You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+8-22Lines changed: 8 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -87,33 +87,19 @@ To edit code directly in one or more namespaces on one or more servers (local or
87
87
88
88
1. Start VS Code.
89
89
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.
93
92
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.
111
97
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:
113
99
114
100
```json
115
101
{
116
-
"uri": "isfs://local/csp/user/?&csp&ns=USER"
102
+
"uri": "isfs://local/csp/user?csp&ns=USER"
117
103
}
118
104
```
119
105
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.
Copy file name to clipboardExpand all lines: docs/Configuration.md
+42-26Lines changed: 42 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,21 +8,35 @@ nav_order: 5
8
8
9
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
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
+
11
15
## Configuring a Server
12
16
13
-
First, configure one or more servers. Open the settings editor by selecting **File > Preferences > Settings** (**Code > Preferences > Settings** on macOS) 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:
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:
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:
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:
18
30
19
31
![Select server manager.](../assets/images/ServerManagerSelect.png"select server manager")
20
32
21
-
And this screen shot shows Server Manager area of the edit pane:
33
+
And this screen shot shows the Server Manager area of the edit pane:
You need to edit the server configuration in the settings.json file, so your only option is to click *Edit in settings.json*.
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.
26
40
27
41
To configure a server, enter something like this:
28
42
@@ -41,22 +55,22 @@ To configure a server, enter something like this:
41
55
42
56
The components of this server definition are:
43
57
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.
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`).
51
65
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 extension adds to the Command Palette the following commands for managing stored passwords:
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:
53
67
54
68
-**InterSystems Server Manager: Store Password in Keychain** - select a server and enter a password.
55
69
-**InterSystems Server Manager: Clear Password from Keychain** - remove password for selected server.
56
70
57
71
## Configuring a Server Connection
58
72
59
-
Select InterSystems ObjectScript from the settings editor's 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**.
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**.
60
74
61
75
You should enter code something like this:
62
76
@@ -67,17 +81,19 @@ You should enter code something like this:
67
81
"active": true,
68
82
},
69
83
```
70
-
The components of this server definition are:
84
+
The components of this connection definition are:
71
85
72
-
-**server** - server name as specified in the server configuration.
86
+
-**server** - server name as specified in the `intersystems.servers` configuration described in the previous section of these instructions.
73
87
-**ns** - namespace to use on the server.
74
88
-**active** - specifies whether the connection is active.
75
89
76
90
## Configuring Export from Server
77
91
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.
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.
79
95
80
-
You export configuration looks something like this:
96
+
When viewed in JSON format your export configuration looks something like this:
81
97
82
98
```json
83
99
"objectscript.export": {
@@ -94,12 +110,12 @@ You export configuration looks something like this:
94
110
```
95
111
The components of this export definition are:
96
112
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.
Copy file name to clipboardExpand all lines: docs/ServerSide.md
+86-26Lines changed: 86 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,94 @@ nav_order: 7
6
6
---
7
7
# Server-side Editing
8
8
9
-
You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Version Control System (VCS) as XML, and you are using source control in Studio using Studio extensions, as provided by `%Studio.Extension.Base`.
9
+
You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Source Code Management (SCM) product interfaced to the server. For example you might already be using the Source Control menu in InterSystems Studio or Portal, implemented by a source control class that extends `%Studio.SourceControl.Base`.
10
10
11
-
First configure the connection to InterSystems as described in [Configuration](../configuration).
11
+
First configure the `intersystems.servers` entry for your server, as described in [Configuration](../configuration).
12
12
13
-
Use **File > New File** to create a new file. Add content similar to the following example. Note that `my-project` in the `isfs://` uri, should be the same as the name of any folder where there are settings for the connection.
13
+
Next create a workspace for editing code direct on the server:
14
+
15
+
1. Open VS Code. If a folder or workspace is already open, close it, for example by pressing <kbd>Ctrl/Cmd</kbd>+<kbd>K</kbd>, releasing that keypair, then pressing <kbd>F</kbd>.
16
+
17
+
2. Open the Explorer view (<kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd>) if it is not already visible.
18
+
19
+
3. When the button labeled "Choose Server and Namespace" appears, click it.
20
+
21
+
4. Pick a server from your `intersystems.servers` settings object.
22
+
23
+
5. Enter credentials if prompted.
24
+
25
+
6. Pick a namespace from the list retrieved from the target server.
26
+
27
+
7. Pick an access mode (Editable or Read-only).
28
+
29
+
8. If you want to reopen this workspace in future, save it as a `.code-workspace` file.
30
+
31
+
> Pro tip: The .code-workspace file you just created is a JSON file which can be edited directly. The Command Palette command `Preferences: Open Workspace Settings (JSON)` gets you there quickly. A simple example looks like this:
32
+
```json
33
+
{
34
+
"folders": [
35
+
{
36
+
"name": "test:USER",
37
+
"uri": "isfs://test/?ns=USER"
38
+
}
39
+
],
40
+
"settings": {}
41
+
}
42
+
```
43
+
> The `name` property sets how the root folder is labeled and can be edited to suit your needs.
44
+
45
+
To add more root folders to your workspace, giving you access to code in a different namespace, or on a different server, use the context menu on your existing root folder to invoke the `Add Server Namespace to Workspace...` command. This command is also available on the Command Palette.
46
+
47
+
An example of a two-folder workspace in which the second folder gives read-only access to the %SYS namespace:
48
+
```json
49
+
{
50
+
"folders": [
51
+
{
52
+
"name": "test:USER",
53
+
"uri": "isfs://test/?ns=USER"
54
+
},
55
+
{
56
+
"name": "test:%SYS (read-only)",
57
+
"uri": "isfs-readonly://test/?ns=%SYS"
58
+
}
59
+
],
60
+
"settings": {}
61
+
}
62
+
```
63
+
64
+
Workspaces can also consist of a mixture of server-side folders and local folders. Use the context menu's `Add Folder to Workspace...` option to add a local folder.
65
+
66
+
Root folders can be re-sequenced using drag/drop in the Explorer view, or by editing the order their definition objects appear within the `folders` array in the JSON.
67
+
68
+
## Web Application (CSP) Files
69
+
70
+
To edit web application files (also known as CSP files) on a server, configure the uri as `isfs://myserver{csp_application}?ns=XXX&csp`
71
+
72
+
For example, the following uri gives you access to the server-side files of the `/csp/user` application. The `csp` query parameter is mandatory and the `ns` parameter must specify the correct namespace for the web application.
73
+
74
+
```
75
+
"uri": "isfs://myserver/csp/user?ns=USER&csp"
76
+
```
77
+
78
+
Changes you make to files opened from this root folder of your VS Code workspace will be saved onto the server.
79
+
80
+
## Filters and Display Options
81
+
82
+
The query string of the `uri` property accepts several parameters that control filtering and display of the server-side entities.
83
+
84
+
-`isfs://myserver?ns=USER&type=cls`, shows only classes
85
+
-`isfs://myserver?ns=USER&type=rtn`, shows only routines, mac, int and inc files
86
+
-`isfs://myserver?ns=USER&generated=1`, shows generated files as well as not generated
87
+
-`isfs://myserver?ns=USER&filter=%Z*.cls,%z*.cls,%Z*.mac`, comma-delimited list of search options, ignores `type`
88
+
-`isfs://myserver?ns=USER&flat=1`, a flat list of files does not split packages as folders.
89
+
90
+
The options `flat` and `generated` can be combined with each other, and with `type` or `filter`. If `filter` is specified, `type` is ignored.
91
+
92
+
## Advanced Workspace Configurations
93
+
94
+
This section gives examples of some more complex workspace definitions for server-side editing.
95
+
96
+
Use **File > New File** to create a new file. Add content similar to the following example. Note that `my-project` in the `isfs://` uri, should be the same as the `name` property (i.e. the root display name) of any local folder where specialized settings for the connection are being stored in a `.vscode/settings.json` file.
14
97
15
98
```json
16
99
{
@@ -72,26 +155,3 @@ Example with connection to different namespaces on the same server.
72
155
}
73
156
}
74
157
```
75
-
76
-
## CSP support
77
-
78
-
To get access to edit CSP files on a server, you can configure uri in format `isfs://myapp{csp_application}?csp`
79
-
For example, the following URI gives you access to the content of `/csp/user` CSP application, where flag `csp` is mandatory.
80
-
81
-
```
82
-
"uri": "isfs://myapp/csp/user?csp"
83
-
```
84
-
85
-
Any changes in this virtual folder are saved on the server.
86
-
87
-
## Filters
88
-
89
-
There are some more filtering options.
90
-
91
-
-`isfs://myapp?type=cls`, shows only classes
92
-
-`isfs://myapp?type=rtn`, shows only routines, mac, int and inc files
93
-
-`isfs://myapp?generated=1`, shows generated files as well as not generated
94
-
-`isfs://myapp?filter=%Z*.cls,%z*.cls,%Z*.mac`, comma-delimited list of search options, ignores `type`
95
-
-`isfs://myapp?flat=1`, a flat list of files does not split packages as folders.
96
-
97
-
The options `flat` and `generated` can be combined with each other, and with `type` or `filter`. When `filter` is specified `type` is ignored.
0 commit comments