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
+57-13Lines changed: 57 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@
12
12
13
13
- Documentation on [GitHub Pages](https://intersystems-community.github.io/vscode-objectscript/).
14
14
15
-
- Guidance on [reporting issues](https://community.intersystems.com/post/using-intersystems-objectscript-vs-code-how-report-issues).
15
+
- Guidance on [reporting issues](https://community.intersystems.com/post/using-intersystems-objectscript-vs-code-how-report-issues). This guidance also appears in a later section of this document.
16
16
17
17
## Features
18
18
@@ -38,10 +38,11 @@
38
38
39
39
Install [Visual Studio Code](https://code.visualstudio.com/) first.
40
40
41
-
Open VS Code. Go to Extensions view (<kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd>), search for "vscode-objectscript" and install it.
42
-
Or install direct from the ObjectScript extension page on [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=intersystems-community.vscode-objectscript).
41
+
Then to get a set of extensions that collaborate to bring you a great ObjectScript development experience, install the [InterSystems ObjectScript Extension Pack](https://marketplace.visualstudio.com/items?itemName=intersystems-community.objectscript-pack).
When you install an extension pack VS Code installs any of its members that you don't already have. Then if you ever need to switch off all of those extensions (for example, in a VS Code workspace on a non-ObjectScript project) simply disable the extension pack at the desired level. Member extensions can still be managed individually.
44
+
45
+
Open VS Code. Go to Extensions view (<kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd>), use the search string **@id:intersystems-community.objectscript-pack** and install it.
45
46
46
47
## Enable Proposed APIs
47
48
@@ -50,14 +51,13 @@ This extension is able to to take advantage of some VS Code APIs that have not y
50
51
The additional features (and the APIs used) are:
51
52
- Server-side [searching across files](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) being accessed using isfs (_TextSearchProvider_)
52
53
-[Quick Open](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_quick-open) of isfs files (_FileSearchProvider_).
1. Download and install a beta version from GitHub. This is necessary because Marketplace does not allow publication of extensions that use proposed APIs.
58
58
- Go to https://github.com/intersystems-community/vscode-objectscript/releases
59
-
- Locate the beta immediately above the release you installed from Marketplace. For instance, if you installed `1.0.6`, look for `1.0.7-beta.1`. This will be functionally identical to the Marketplace version apart from being able to use proposed APIs.
60
-
- Download the VSIX file (for example `vscode-objectscript-1.0.7-beta.1.vsix`) and install it. One way to install a VSIX is to drag it from your download folder and drop it onto the list of extensions in the Extensions view of VS Code.
59
+
- Locate the beta immediately above the release you installed from Marketplace. For instance, if you installed `1.0.12`, look for `1.0.13-beta.1`. This will be functionally identical to the Marketplace version apart from being able to use proposed APIs.
60
+
- Download the VSIX file (for example `vscode-objectscript-1.0.13-beta.1.vsix`) and install it. One way to install a VSIX is to drag it from your download folder and drop it onto the list of extensions in the Extensions view of VS Code.
61
61
62
62
2. From [Command Palette](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_command-palette) choose `Preferences: Configure Runtime Arguments`.
63
63
3. In the argv.json file that opens, add this line:
@@ -78,7 +78,7 @@ To be able to use many features you first need to configure the connection to yo
78
78
79
79
We recommend you define server connections in the `intersystems.servers` object whose structure is defined by the [InterSystems Server Manager](https://marketplace.visualstudio.com/items?itemName=intersystems-community.servermanager) helper extension.
80
80
81
-
Install that extension and consult its documentation about commands for easy setup of connections, plus assistance when editing the JSON definition directly.
81
+
Install that extension and consult its documentation about its UI and commands for easy setup of connections, plus assistance when editing the JSON definition directly.
82
82
83
83
For more tips about the `intersystems.servers` object, see the [Notes](#Notes) section below.
84
84
@@ -101,14 +101,57 @@ To edit code directly in one or more namespaces on one or more servers (local or
101
101
102
102
1. Start VS Code.
103
103
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'.
104
-
3. On VS Code's Explorer view (<kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd>), click the 'Choose Server and Namespace' button. Respond to the sequence of quickpicks. You can also define a new server connection during this process.
105
-
4. Use 'Save Workspace As...' to store your workspace definition in a file with a `.code-workspace` extension.
104
+
3. On VS Code's Explorer view (<kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd>), click the 'Manage Servers' button which is contributed by the Server Manager extension.
105
+
4. Find your target server in the tree, or use the '+' button to add a new server.
106
+
5. Expand the server and its 'Namespaces' folder, then click on the 'pencil' icon for editing access to the namespace or the 'eye' icon for viewing access. If you want to work with web application files rather than classes and routines, hold down the <kbd>Alt</kbd>/<kbd>Option</kbd> key when clicking the button.
107
+
6. Use 'Save Workspace As...' to store your workspace definition in a file with a `.code-workspace` extension.
106
108
107
109
For more about `isfs` and `isfs-readonly` folder specifications see the [Notes](#Notes) section below.
108
110
111
+
## Reporting Issues
112
+
113
+
[InterSystems ObjectScript for VS Code](https://intersystems-community.github.io/vscode-objectscript/) consists of three collaborating VS Code extensions. This modular architecture also means there are three different GitHub repositories where issues can be created. Fortunately VS Code itself helps with the task. You will need a GitHub account. Here's how:
114
+
115
+
1. From the Help menu in VS Code choose 'Report Issue'. Alternatively, open the Command Palette and run `Help: Report Issue...`.
116
+
117
+
2. When the dialog appears, use the first dropdown to classify your issue:
118
+
- Bug Report
119
+
- Feature Request
120
+
- Performance Issue
121
+
122
+
3. In the second dropdown pick 'An extension'
123
+
124
+
4. The third dropdown lets you pick one of your installed extensions. You can type a few characters to find the right entry. For example, `isls` quickly selects "InterSystems Language Server".
125
+
126
+
Which one to choose? Here's a guide:
127
+
- InterSystems Language Server
128
+
- code coloring
129
+
- Intellisense
130
+
- InterSystems ObjectScript
131
+
- export, import and compile
132
+
- ObjectScript Explorer (browsing namespace contents)
133
+
- direct server-side editing using `isfs://` folders in a workspace
134
+
- integration with server-side source control etc
135
+
- InterSystems Server Manager
136
+
- Server Browser on the InterSystems Tools view
137
+
- password management in local keychain
138
+
- definition and selection of entries in `intersystems.servers`
139
+
140
+
If unsure, pick InterSystems ObjectScript.
141
+
142
+
5. Type a descriptive one-line summary of your issue. The dialog may offer a list of existing issues which could be duplicates. If you don't find one that covers yours, proceed.
143
+
144
+
6. Enter details. If your VS Code is authenticated to GitHub the dialog's button is captioned "Create on GitHub" and clicking it will open the issue, then load it in your browser so you can edit it. Otherwise it reads "Preview on GitHub" and launches a browser page where you must complete and submit your report.
145
+
146
+
Tips for use on the GitHub page:
147
+
148
+
- Paste images from your clipboard directly into the report field. For hard-to-describe issues an animated GIF or a short MP4 gets bonus points. The `Developer: Toggle Screencast Mode` in VS Code can help your recording make more sense.
149
+
- Link to other issues by prefixing the target number with #
150
+
- Remember that whatever you post here is visible to anyone on the Internet. Mask/remove confidential information. Be polite.
151
+
109
152
## Notes
110
153
111
-
- Connection-related output appears in the "Output" view while switched to the "ObjectScript" channel using the drop-down menu on the view titlebar.
154
+
- Connection-related output appears in the 'Output' view while switched to the 'ObjectScript' channel using the drop-down menu on the view titlebar.
112
155
113
156
- The `/api/atelier/` web application used by this extension usually requires the authenticated user to have Use permission on the %Development resource ([read more](https://community.intersystems.com/post/using-atelier-rest-api)). One way is to assign the %Developer role to the user.
114
157
@@ -163,15 +206,15 @@ This settings object is primarily relevant when doing client-side development.
163
206
### More about `isfs` and `isfs-readonly` workspace folders
164
207
Server-side development is best done using `isfs` folders. The read-only variant `isfs-readonly` is also useful when doing client-side development, since it enables server-side searching of your codebase.
165
208
166
-
To modify how your folder behaves, edit the JSON of your workspace definition (_XYZ.code-workspace_ file). Get there by running the 'Preferences: Open Workspace Settings (JSON)' command. Edit your `uri` property.
209
+
To modify how your folder behaves, edit the JSON of your workspace definition (_XYZ.code-workspace_ file). Get there by using the 'Edit Settings' option from the context menu of Server Manager's 'Servers' view, or by running the 'Preferences: Open Workspace Settings (JSON)' command from the Command Palette. Edit your `uri` property.
167
210
168
211
- The `csp` query parameter indicates web application files are to be shown. The uri path optionally specifies which application. The namespace suffix on the server name (preferred syntax) or the `ns` query parameter (deprecated) must specify the same namespace the application is configured to use. In the following example the first folder is for the `/csp/user` web application in the USER namespace of the server named 'local' and the second gives read-only access to all web applications that reside in the %SYS namespace. The second folder also uses the optional `name` property:
169
212
```json
170
213
{
171
214
"uri": "isfs://local:user/csp/user?csp"
172
215
},
173
216
{
174
-
"name": "local:%SYS web files (read-only)",
217
+
"name": "local:%SYS web files (read-only)",
175
218
"uri": "isfs-readonly://local/?ns=%SYS&csp"
176
219
}
177
220
```
@@ -188,6 +231,7 @@ To modify how your folder behaves, edit the JSON of your workspace definition (_
188
231
-`type=cls` to show only classes, or `type=rtn` to show only routines.
189
232
-`flat=1` to flatten the hierarchy.
190
233
-`generated=1` to show generated items.
234
+
-`system=1` to show system (%) items. Without this parameter these are only shown for the %SYS namespace.
191
235
-`filter=filterspec` to use a filter specification formatted in the same way as used in InterSystems Studio's File Open dialog (e.g. `filter=Ensem*.inc`).
0 commit comments