Skip to content

Commit bce1ac2

Browse files
rajrsinghrajrsingh
authored
Merge pull request intersystems-community#322 from gjsjohnmurray/enh-gettingStarted
Implement intersystems-community#321 - Contribute to empty Explorer content
2 parents c802cdb + c1092b3 commit bce1ac2

File tree

8 files changed

+400
-198
lines changed

8 files changed

+400
-198
lines changed

‎README.md

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -87,33 +87,19 @@ To edit code directly in one or more namespaces on one or more servers (local or
8787

8888
1. Start VS Code.
8989
2. If your last-used folder opens, use 'Close Folder' on the 'File' menu ('Code' menu on macOS). Or if what opened was your last-used workspace, use 'Close Workspace'.
90-
3. Use 'Save Workspace As...' to create an empty file with a .code-workspace extension.
91-
4. Use the Command Palette to run 'Preferences: Open Workspace Settings (JSON)'.
92-
5. Add a `folders` array that defines one or more root folders for your workspace. The `uri` property of each folder specifies whether to use `isfs` or `isfs-readonly`, and which entry within `intersystems.servers` to get the connection definition from. All example here reference one named `local`. Add a `ns` query parameter to specify which namespace to access. Optionally add a `label` property to set the display name of the folder in Explorer. Optionally add a workspace-specific `settings` object to hide the ObjectScript Explorer view, which is not usually needed when working server-side in this way.
90+
3. On VS Code's Explorer view, click the 'Choose Server and Namespace' button. Respond to the sequence of quickpicks.
91+
4. Use 'Save Workspace As...' to store your workspace definition in a file with a .code-workspace extension.
9392

94-
```json
95-
{
96-
"folders": [
97-
{
98-
"name": "local:USER",
99-
"uri": "isfs://local/?ns=USER"
100-
},
101-
{
102-
"name": "local:USER (readonly)",
103-
"uri": "isfs-readonly://local/?ns=USER"
104-
}
105-
],
106-
"settings": {
107-
"objectscript.showExplorer": false
108-
}
109-
}
110-
```
93+
Optionally, customize your workspace settings to remove the ObjectScript Explorer icon from the Action Bar. The ObjectScript Explorer view is not usually needed when working server-side in this way.
94+
95+
5. Use the Command Palette to run 'Preferences: Open Workspace Settings'.
96+
6. Search for `objectscript.showExplorer` and clear the checkbox of this setting.
11197

112-
To access the server-side files of a web application, format your `uri` property like this:
98+
To access the server-side files of a web application, edit the JSON of your workspace definition. Get there by running the 'Preferences: Open Workspace Settings (JSON)' command. Format your `uri` property like this example for the `/csp/user` web application:
11399

114100
```json
115101
{
116-
"uri": "isfs://local/csp/user/?&csp&ns=USER"
102+
"uri": "isfs://local/csp/user?csp&ns=USER"
117103
}
118104
```
119105
The `csp` query parameter indicates web application files are to be shown. The uri path specifies which application. The `ns` parameter must specify the same namespace the application is configured to use.

‎docs/Configuration.md

Lines changed: 121 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,121 @@
1-
---
2-
layout: default
3-
title: Configuration
4-
permalink: /configuration/
5-
nav_order: 5
6-
---
7-
# Configuration
8-
9-
The settings that define an InterSystems IRIS server and the connection to the server are crucial to the functioning of VS Code in developing in ObjectScript.
10-
11-
## Configuring a Server
12-
13-
First, configure one or more servers. Open the settings editor by selecting **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **User** or **Workspace** settings level by selecting it at the top of the settings window. For example, the following screen shot shows Workspace selected:
14-
15-
![Workspace selected.](../assets/images/ClickWorkspace.png "workspace selected")
16-
17-
Find Extensions in the list in the left pane of the editor window, click to open, then select InterSystems Server Manager from the list to find the correct place in the settings UI. The following screen shot shows InterSystems Server Manager selected:
18-
19-
![Select server manager.](../assets/images/ServerManagerSelect.png "select server manager")
20-
21-
And this screen shot shows Server Manager area of the edit pane:
22-
23-
![Server manager settings.](../assets/images/ServerManagerSettings.png "server manager settings")
24-
25-
You need to edit the server configuration in the settings.json file, so your only option is to click *Edit in settings.json*.
26-
27-
To configure a server, enter code something like this:
28-
29-
```js
30-
"intersystems.servers": {
31-
"test": {
32-
"webServer": {
33-
"scheme": "http",
34-
"host": "localhost",
35-
"port": 52774,
36-
},
37-
"username": "_SYSTEM",
38-
},
39-
},
40-
```
41-
42-
The components of this server definition are:
43-
44-
- **test** - an arbitrary name to identify this server
45-
- **webServer** - The collection of properties that define the web server.
46-
- **scheme** - The protocol used for connections.
47-
- **host** - the host for this server
48-
- **port** - the WebServer port number for this server
49-
- **username** - the username to use in logging in to this server.
50-
- **password** - password for the specified username. Entering the password in this file is acceptable only in limited situations with very low need for security.
51-
52-
If you do not add a password to the server definition, anyone using the server needs to supply the password. Or, you can store the password securely in the system Keychain. The InterSystems Server Manager adds the following commands for managing stored passwords to the Command Palette:
53-
54-
- **InterSystems Server Manager: Clear Password from Keychain** - remove password for selected server
55-
- **InterSystems Server Manager: Store Password in Keychain** - select a server and enter a password
56-
57-
## Configuring a Server Connection
58-
59-
Select InterSystems ObjectScript from the settings editor extensions list. You need to edit the server configuration in the settings.json file, so your click *Edit in settings.json* under the heading **Objectscript: conn**.
60-
61-
You should enter code something like this:
62-
63-
```js
64-
"objectscript.conn": {
65-
"ns": "USER",
66-
"server": "tst",
67-
"active": true,
68-
},
69-
```
70-
The components of this server definition are:
71-
72-
- **ns** - namespace to use on the server
73-
- **server** - server name as specified in the server configuration
74-
- **active** - specifies whether the connection is active.
75-
76-
## Configuring Export from Server
77-
78-
Select InterSystems ObjectScript from the settings editor extensions list. Find the section labeled **Objectscript: conn**. You can edit many of the export settings in the settings editor. For others you need to edit the settings.json file.
79-
80-
You export configuration looks something like this:
81-
82-
```js
83-
"objectscript.export": {
84-
"folder": "",
85-
"addCategory": true,
86-
"atelier": true,
87-
"generated": false,
88-
"filter": "",
89-
"category": "*",
90-
"noStorage": false,
91-
"dontExportIfNoChanges": false,
92-
"maxConcurrentConnections": 0
93-
},
94-
```
95-
The components of this export definition are:
96-
97-
- **folder** - Folder for source code.
98-
- **addCategory** - Add a category folder to the export path.
99-
- **atelier** - Export source code as Atelier does, with packages placed in subfolders.
100-
- **generated** - Export generated source code files.
101-
- **filter** -
102-
- **category** - Specifies a category of source code to export: CLS = classes; RTN = routines; CSP = csp files; OTH = other. The default is *, export everything.
103-
- ****noStorage** - Strip the storage XML on export. This is useful for multiple systems.
104-
- **dontExportIfNoChanges** - Don't update the local file if the content is identical to what is on the server.
105-
- **maxConcurrentConnections** - The maximum number of export connections. (0 = Unlimited)
1+
---
2+
layout: default
3+
title: Configuration
4+
permalink: /configuration/
5+
nav_order: 5
6+
---
7+
# Configuration
8+
9+
The settings that define an InterSystems IRIS server and the connection to the server are crucial to the functioning of VS Code in developing in ObjectScript.
10+
11+
Open the VS Code Settings Editor by selecting **File > Preferences > Settings** (**Code > Preferences > Settings** on macOS) from the menu, or by pressing <kbd>Ctrl/Cmd</kbd>+<kbd>,</kbd> (comma).
12+
13+
> Pro tip: If you know the name of the setting you want to change, or a phrase that occurs in its descrition, start typing this into the 'Search settings' field, for example `intersystems` or `objectscript` or `udl`.
14+
15+
## Configuring a Server
16+
17+
First, configure one or more servers. Open the settings editor by selecting **File > Preferences > Settings** (**Code > Preferences > Settings** on macOS) from the menu, or by pressing <kbd>Ctrl/Cmd</kbd>+<kbd>,</kbd> (comma).
18+
19+
Select the **User** or **Workspace** settings level by selecting it at the top of the settings window. **User** level is normally selected by default, and where to put your server definitions so they can be used by any of your workspaces. You can learn more about the difference between these levels in the [Settings](../settings) section of this documentation.
20+
21+
The following screen shot shows **Workspace** selected:
22+
23+
![Workspace selected.](../assets/images/ClickWorkspace.png "workspace selected")
24+
25+
Find **Extensions** in the list in the left pane of the editor window, click to open, then select **InterSystems Server Manager** from the list to find the correct place in the settings UI.
26+
27+
If you don't see this entry, check that you have [installed](../installation) that extension and that it has not been disabled.
28+
29+
The following screen shot shows InterSystems Server Manager selected:
30+
31+
![Select server manager.](../assets/images/ServerManagerSelect.png "select server manager")
32+
33+
And this screen shot shows the Server Manager area of the edit pane:
34+
35+
![Server manager settings.](../assets/images/ServerManagerSettings.png "server manager settings")
36+
37+
The **InterSystems: Servers** setting is a structured object that is too complex to be edited in the settings UI, so your only option is to click *Edit in settings.json*.
38+
39+
If you are defining this setting for the first time, a default settings object will be offered for you to amend. A completion list may also appear. Press <kbd>Esc</kbd> to dismiss this.
40+
41+
To configure a server, enter something like this:
42+
43+
```json
44+
"intersystems.servers": {
45+
"test": {
46+
"webServer": {
47+
"scheme": "http",
48+
"host": "localhost",
49+
"port": 52774,
50+
},
51+
"username": "_SYSTEM",
52+
},
53+
},
54+
```
55+
56+
The components of this server definition are:
57+
58+
- **test** - your choice of name to identify this InterSystems server in your settings. The name can only contain lowercase 'a' to 'z', digits 0 to 9, and limited punctuation (`-._~`).
59+
- **webServer** - a collection of properties that define its associated web server, as follows:
60+
- **scheme** - protocol used for connections (http or https).
61+
- **host** - hostname or IP address of the web server server.
62+
- **port** - port number of this web server. This is the same port as you connect to when using the InterSystems Management Portal from your browser. If you already use InterSystems Studio do not confuse the web server port number with the port number Studio connects to (sometimes called the superserver).
63+
- **username** - username to use when logging in to this server. This is optional. If omitted the user will be prompted for it at connection time, then cached for the session.
64+
- **password** - password for the specified username. This is optional, and the example above omits it. Storing the password in a settings file should only be done in limited situations where there is very low need for security or where default credentials are being used (e.g. `_SYSTEM`/`SYS`).
65+
66+
If you do not add a password to the server definition, the user will need to enter the password when connecting. It will then then be cached for the session. Alternatively you can store the password securely in keychain of your local workstation. The InterSystems Server Manager extension adds the following commands to the Command Palette for managing stored passwords:
67+
68+
- **InterSystems Server Manager: Store Password in Keychain** - select a server and enter a password.
69+
- **InterSystems Server Manager: Clear Password from Keychain** - remove password for selected server.
70+
71+
## Configuring a Server Connection
72+
73+
Select **InterSystems ObjectScript** from the settings editor's **Extensions** list. You need to edit the connection configuration in the settings.json file, so click *Edit in settings.json* under the heading **Objectscript: conn**.
74+
75+
You should enter code something like this:
76+
77+
```json
78+
"objectscript.conn": {
79+
"server": "test",
80+
"ns": "USER",
81+
"active": true,
82+
},
83+
```
84+
The components of this connection definition are:
85+
86+
- **server** - server name as specified in the `intersystems.servers` configuration described in the previous section of these instructions.
87+
- **ns** - namespace to use on the server.
88+
- **active** - specifies whether the connection is active.
89+
90+
## Configuring Export from Server
91+
92+
Default settings for export are suitable for many situations, but if you need to adjust them here's how.
93+
94+
Select **InterSystems ObjectScript** from the settings editor **Extensions** list. Find the section labeled **Objectscript: export**. You can change many of the export settings directly in the settings editor. For others you need to edit the settings.json file.
95+
96+
When viewed in JSON format your export configuration looks something like this:
97+
98+
```json
99+
"objectscript.export": {
100+
"folder": "",
101+
"addCategory": true,
102+
"atelier": true,
103+
"generated": false,
104+
"filter": "",
105+
"category": "*",
106+
"noStorage": false,
107+
"dontExportIfNoChanges": false,
108+
"maxConcurrentConnections": 0
109+
},
110+
```
111+
The components of this export definition are:
112+
113+
- **folder** - Folder for source code within workspace.
114+
- **addCategory** - Add a category folder to the beginning of the export path.
115+
- **atelier** - Export source code as Atelier did it, with packages as subfolders.
116+
- **generated** - Export generated source code files, such as INTs generated from classes.
117+
- **filter** - SQL filter to limit what to export.
118+
- **category** - Category of source code to export: `CLS` = classes; `RTN` = routines; `CSP` = csp files; `OTH` = other. The default is `*` which exports everything.
119+
- **noStorage** - Strip the storage definition on export. Can be useful when working across multiple systems.
120+
- **dontExportIfNoChanges** - Do not rewrite the local file if the content is identical to what came from the server.
121+
- **maxConcurrentConnections** - The maximum number of concurrent export connections. (0 = unlimited)

‎docs/RunDebug.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ If no launch configurations are available, you are prompted to create one:
1414

1515
Clicking the link creates and opens a `launch.json` file containing the following default information:
1616

17-
```js
17+
```json
1818
{
1919
"version": "0.2.0",
2020
"configurations": [
@@ -35,7 +35,7 @@ These attributes are mandatory for any launch configuration:
3535

3636
In addition, for an **objectscript** configuration, you need to supply the attribute **program**, which specifies the executable or file to run when launching the debugger, as shown in the following example:
3737

38-
```js
38+
```json
3939
"launch": {
4040
"version": "0.2.0",
4141
"configurations": [

0 commit comments

Comments
 (0)