Skip to content

Commit 1f08ddd

Browse files
isc-bsavianoisc-bsaviano
authored
Merge pull request #758 from isc-bsaviano/docs
Documentation Improvements
2 parents b5ba419 + b02b55d commit 1f08ddd

File tree

6 files changed

+154
-21
lines changed

6 files changed

+154
-21
lines changed

‎docs/Configuration.md

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ For example, the following screen shot shows the Workspace level selected:
3737

3838
See the VS Code documentation section [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
3939

40+
See the [Settings Reference page](../settings/) for a list of all settings contributed by the extensions in the pack.
41+
4042
{: #config-server}
4143
## Configuring a Server
4244

@@ -102,6 +104,7 @@ If you do not store the password securely in the system Keychain or add it to th
102104
- **InterSystems Server Manager: Clear Password from Keychain** - remove the password for a selected server
103105
- **InterSystems Server Manager: Store Password in Keychain** - select a server or create a new one and enter a password
104106

107+
{: #config-server-conn}
105108
## Configuring a Server Connection
106109

107110
Open the folder where you want client-side files to be located. Select the **ObjectScript Explorer** button on the Activity Bar. Select the **Choose Server and Namespace** button. This action opens a dialog that lets you select a server, or create a new one. Once you have selected a server and namespace, connection configuration is complete. VS Code adds the server and namespace to the status bar, as shown in the following screen shot.
@@ -110,10 +113,6 @@ Open the folder where you want client-side files to be located. Select the **Obj
110113

111114
You cannot create a connection to a server that is not running.
112115

113-
Click on the server and namespace in the status bar to open a list of actions you can take for this server:
114-
115-
![Select action for server.](../assets/images/action-for-server.png "select action for server")
116-
117116
## Editing a Server Connection
118117

119118
If you need to modify a server connection select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **Workspace** settings level. Search for **objectscript: conn**, and click on *Edit in settings.json*.
@@ -133,3 +132,35 @@ The components of this configuration are:
133132
- **ns** - namespace to use on the server
134133
- **server** - server name as specified in the server configuration
135134
- **active** - specifies whether the connection is active.
135+
136+
{: #server-actions-menu}
137+
## Add Custom Entries to the Server Actions Menu
138+
139+
Click on the server and namespace in the status bar to open a list of actions you can take for this server:
140+
141+
![Select action for server.](../assets/images/action-for-server.png "select action for server")
142+
143+
You can add custom entries to this list using the `objectscript.conn.links` configuration object, which contains key-value pairs where the key is the label displayed in the menu and the value is the uri to open. The following variables are available for substitution in the uri:
144+
145+
- **${host}** - The hostname of the connected server. For example, `localhost`
146+
- **${port}** - The port of the connected server. For example, `52773`
147+
- **${serverUrl}** - The full connection string for the server. For example, `http://localhost:52773/pathPrefix`
148+
- **${ns}** - The namespace that we are connected to, URL encoded. For example, `%25SYS` or `USER`
149+
- **${namespace}** - The raw `ns` parameter of the connection. For example, `sys` or `user`
150+
- **${classname}** - The name of the currently opened class, or the empty string if the currently opened document is not a class.
151+
- **${classnameEncoded}** - URL encoded version of **\${classname}**.
152+
153+
An example links configuration looks like this:
154+
155+
```json
156+
"objectscript.conn": {
157+
"links": {
158+
"Portal Explorer": "${serverUrl}/csp/sys/exp/%25CSP.UI.Portal.ClassList.zen?$NAMESPACE=${ns}",
159+
"SOAP Wizard": "${serverUrl}/isc/studio/templates/%25ZEN.Template.AddInWizard.SOAPWizard.cls?$NAMESPACE=${ns}"
160+
},
161+
}
162+
```
163+
164+
And the resulting Server Actions Menu looks like this:
165+
166+
![Server actions with custom links.](../assets/images/server-actions-with-links.png "server actions menu with custom links")

‎docs/RunDebug.md

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,20 @@ nav_order: 5
88

99
The InterSystems ObjectScript Extension provides support for ObjectScript debugging. It takes advantage of the debugging capabilities built into VS Code, so you may find these VS Code documentation resources useful:
1010

11-
- [Node.js debugging in VS Code](https://code.visualstudio.com/docs/editor/debugging)
12-
- [Debugging](https://code.visualstudio.com/docs/editor/debugging)
11+
- [Debugging Intro Video](https://code.visualstudio.com/docs/introvideos/debugging)
12+
- [Debugging User Guide](https://code.visualstudio.com/docs/editor/debugging)
1313

14-
## Launch Configurations
14+
## Debug Configurations
1515

16-
In order to run or debug an ObjectScript class or routine, you must create a launch configuration. Some other languages default to running the currently active file, but to run ObjectScript, you must specify the routine or ClassMethod to use.
16+
In order to run or debug an ObjectScript class or routine or attach to a running process, you must create a debug configuration. Some other languages default to running the currently active file, but to run ObjectScript, you must specify the routine or ClassMethod to use or the running process to attach to.
1717

1818
Click the run button in the Activity Bar:
1919

2020
![Run button.](../assets/images/run.png "run button")
2121

22-
If no launch configurations are available, you are prompted to create one:
22+
If no debug configurations are available, you are prompted to create one:
2323

24-
![Create launch configuration.](../assets/images/CreateLaunchConfig.png "create launch configuration")
24+
![Create debug configuration.](../assets/images/CreateLaunchConfig.png "create debug configuration")
2525

2626
Clicking the link opens a dialog containing a list of debug environments. Select **ObjectScript Debug**.
2727

@@ -42,13 +42,13 @@ Once you have chosen a debug environment, VS Code creates and opens a `launch.js
4242
}
4343
```
4444

45-
These attributes are mandatory for any launch configuration:
45+
These attributes are mandatory for any debug configuration:
4646

4747
- **type** - Identifies the type of debugger to use. In this case, `objectscript`, supplied by the InterSystems ObjectScript extension.
4848
- **request** - Identifies the type of action for this launch configuration. Possible values are `launch` and `attach`.
4949
- **name** - An arbitrary name to identify the configuration. This name appears in the Start Debugging drop down list.
5050

51-
In addition, for an **objectscript** configuration, you need to supply the attribute **program**, which specifies the routine or ClassMethod to run when launching the debugger, as shown in the following example:
51+
In addition, for an **objectscript launch** configuration, you need to supply the attribute **program**, which specifies the routine or ClassMethod to run when launching the debugger, as shown in the following example:
5252

5353
```json
5454
"launch": {
@@ -68,15 +68,44 @@ In addition, for an **objectscript** configuration, you need to supply the attri
6868
"program": "##class(Test.MyOtherClass).GoodbyeWorld()",
6969
},
7070
]
71-
}
71+
}
7272
```
7373

74-
## Launching a ClassMethod or Routine
74+
For an **objectscript attach** configuration, you may supply the following attributes:
75+
76+
- **processId** - Specifies the ID of process to attach to as a `string` or `number`. Defaults to `"${command:PickProcess}"`, which provides a dropdown list of process ID's to attach to at runtime.
77+
- **system** - Specifies whether to allow attaching to system process. Defaults to `false`.
78+
79+
The following example shows multiple valid **objectscript attach** configurations:
80+
81+
```json
82+
"launch": {
83+
"version": "0.2.0",
84+
"configurations": [
85+
{
86+
"type": "objectscript",
87+
"request": "attach",
88+
"name": "Attach 1",
89+
"processId": 5678
90+
},
91+
{
92+
"type": "objectscript",
93+
"request": "attach",
94+
"name": "Attach 2",
95+
"system": true
96+
},
97+
]
98+
}
99+
```
100+
101+
## Starting a Debugging Session
102+
103+
You can select a debug configuration from the list VS Code provides in the Run and Debug field at the top of the debug side bar:
75104

76-
You can select a launch configuration from the list VS Code provides in the Run and Debug field at the top of the debug side bar:
105+
![Select debug configuration.](../assets/images/select-config.png "select debug configuration")
77106

78-
![Select launch configuration.](../assets/images/select-config.png "select launch configuration")
107+
Clicking on the green arrow runs the currently selected debug configuration.
79108

80-
Clicking on the green arrow runs the currently selected launch configuration.
109+
When starting **objectscript launch** debug session, make sure that the file containing the **program** that you are debugging is open in your editor and is the active tab. VS Code will start a debug session with the server of the file in the active editor (the tab that the user is focused on).
81110

82111
Debugging commands and items on the **Run** menu function much as they do for other languages supported by VS Code. For information on VS Code debugging, see the documentation resources listed at the start of this section.

‎docs/SettingsReference.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
layout: default
3+
title: Settings Reference
4+
permalink: /settings/
5+
nav_order: 7
6+
---
7+
8+
# Settings Reference
9+
10+
The extensions in the InterSystems ObjectScript Extension Pack provide many settings that allow you to configure their behavior. Below you will find a table containing all settings for each extension in the pack, as well as a short description, the type of value they accept, the default value and any other notes that may be useful to you. Please see [this VS Code documentation page](https://code.visualstudio.com/docs/getstarted/settings) for more information about settings and how to change them.
11+
12+
{: #language-server}
13+
## InterSystems Language Server
14+
15+
| Setting | Description | Type | Default | Notes |
16+
| ------- | ----------- | ---- | ------- | ----- |
17+
| `"intersystems.language-server.diagnostics.classes"` | Controls whether error diagnostics are provided when a class that is being referred to doesn't exist in the database. | `boolean` | `true` | |
18+
| `"intersystems.language-server.diagnostics.deprecation"` | Controls whether strikethrough warning diagnostics are provided when a class or class member that is being referred to is deprecated. | `boolean` | `true` | |
19+
| `"intersystems.language-server.diagnostics.parameters"` | Controls whether warning diagnostics are provided when a class Parameter has an invalid type or the assigned value of the Parameter doesn't match the declared type. | `boolean` | `true` | |
20+
| `"intersystems.language-server.diagnostics.routines"` | Controls whether error diagnostics are provided when a routine or include file that is being referred to doesn't exist in the database. | `boolean` | `false` | |
21+
| `"intersystems.language-server.formatting.commands.case"` | Controls the case that ObjectScript commands will be changed to during a document formatting request. | `"upper"`, `"lower"` or `"word"` | `"word"` | |
22+
| `"intersystems.language-server.formatting.commands.length"` | Controls the length that ObjectScript commands will be changed to during a document formatting request. | `"short"` or `"long"` | `"long"` | |
23+
| `"intersystems.language-server.formatting.system.case"` | Controls the case that ObjectScript system functions and variables will be changed to during a document formatting request. | `"upper"`, `"lower"` or `"word"` | `"upper"` | |
24+
| `"intersystems.language-server.formatting.system.length"` | Controls the length that ObjectScript system functions and variables will be changed to during a document formatting request. | `"short"` or `"long"` | `"long"` | |
25+
| `"intersystems.language-server.hover.commands"` | Controls whether hover information is provided for ObjectScript commands. | `boolean` | `true` | |
26+
| `"intersystems.language-server.hover.preprocessor"` | Controls whether hover information is provided for ObjectScript preprocessor directives. | `boolean` | `true` | |
27+
| `"intersystems.language-server.hover.system"` | Controls whether hover information is provided for ObjectScript system functions and variables. | `boolean` | `true` | |
28+
| `"intersystems.language-server.refactor.exceptionVariable"` | The name of the exception variable inserted in a 'Wrap in Try/Catch' refactor. | `string` | `"ex"` | |
29+
| `"intersystems.language-server.signaturehelp.documentation"` | Controls whether documentation for a method is shown when a SignatureHelp is active. | `boolean` | `true` | This setting does not affect documentation for macro SignatureHelp views, which is always shown. |
30+
| `"intersystems.language-server.suggestTheme"` | Controls whether the extension will suggest that one of the InterSystems default themes be used if neither one is active upon extension activation. | `boolean` | `true` | |
31+
| `"intersystems.language-server.trace.server"` | Traces the communication between VS Code and the language server. | `"off"`, `"messages"` or `"verbose"` | `"off"` | Any trace information will be logged to the `InterSystems Language Server` Output channel. |
32+
33+
{: #vscode-objectscript}
34+
## InterSystems ObjectScript
35+
36+
| Setting | Description | Type | Default | Notes |
37+
| ------- | ----------- | ---- | ------- | ----- |
38+
| `"objectscript.autoPreviewXML"` | Automatically preview XML export files in UDL format. | `boolean` | `false` | |
39+
| `"objectscript.autoShowTerminal"` | Automatically show terminal when connected to docker-compose. | `boolean` | `false` | |
40+
| `"objectscript.compileFlags"` | Compilation flags. | `string` | `"cuk"` | Common compilation flags are ***b*** (compile dependent classes), ***k*** (keep generated source code) and ***u*** (skip related up-to-date documents). For descriptions of all available flags and qualifiers, click [here](https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=RCOS_vsystem#RCOS_vsystem_flags_qualifiers). |
41+
| `"objectscript.compileOnSave"` | Automatically compile an InterSystems file when saved in the editor. | `boolean` | `true` | |
42+
| `"objectscript.conn"` | Configures the active server connection. | `object` | `undefined` | See the [Configuration page](../configuration/#config-server-conn) for more details on configuring server connections. |
43+
| `"objectscript.debug.debugThisMethod"` | Show inline `Debug this method` CodeLens action for ClassMethods. | `boolean` | `true` | |
44+
| `"objectscript.export.addCategory"` | Add a category folder to the beginning of the export path. | `boolean` or `object` | `false` | |
45+
| `"objectscript.export.atelier"` | Export source code as Atelier did it, with packages as subfolders. | `boolean` | `true` | |
46+
| `"objectscript.export.category"` | Category of source code to export: `CLS` = classes; `RTN` = routines; `CSP` = csp files; `OTH` = other. Default is `*` = all. | `string` or `object` | `"*"` | |
47+
| `"objectscript.export.dontExportIfNoChanges"` | Do not rewrite the local file if the content is identical to what came from the server. | `boolean` | `false` | |
48+
| `"objectscript.export.filter"` | SQL filter to limit what to export. | `string` | `""` | |
49+
| `"objectscript.export.folder"` | Folder for exported source code within workspace. | `string` | `"src"` | |
50+
| `"objectscript.export.generated"` | Export generated source code files, such as INTs generated from classes. | `boolean` | `false` | |
51+
| `"objectscript.export.map"` | Map file names before export, with regexp pattern as a key and replacement as a value. | `object` | `{}` | For example, `{ \"%(.*)\": \"_$1\" }` to make % classes or routines use underscore prefix instead. |
52+
| `"objectscript.export.maxConcurrentConnections"` | Maximum number of concurrent export connections. | `number` | `0` | 0 = unlimited |
53+
| `"objectscript.export.noStorage"` | Strip the storage definition on export. | `boolean` | `false` | Can be useful when working across multiple systems. |
54+
| `"objectscript.format.commandCase"` | Case for commands. | `"upper"`, `"lower"` or `"word"` | `"word"` | Has no effect if the `InterSystems Language Server` extension is installed and enabled. |
55+
| `"objectscript.format.functionCase"` | Case for system functions and system variables. | `"upper"`, `"lower"` or `"word"` | `"word"` | Has no effect if the `InterSystems Language Server` extension is installed and enabled. |
56+
| `"objectscript.ignoreInstallServerManager"` | Do not offer to install the [intersystems-community.servermanager](https://marketplace.visualstudio.com/items?itemName=intersystems-community.servermanager) extension. | `boolean` | `false` | |
57+
| `"objectscript.multilineMethodArgs"` | List method arguments on multiple lines, if the server supports it. | `boolean` | `false` | Only supported on IRIS 2019.1.2, 2020.1.1+, 2021.1.0+ and subsequent versions! On all other versions, this setting will have no effect. |
58+
| `"objectscript.overwriteServerChanges"` | Overwrite a changed server version without confirmation when importing the local file. | `boolean` | `false` | |
59+
| `"objectscript.searchAllDocTypes"` | Whether [Quick Open](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_quick-open) should search across all Studio Document types. Default is to only search classes, routines and include files. | `boolean` | `false` | |
60+
| `"objectscript.serverSideEditing"` | Allow editing code directly on the server after opening it from ObjectScript Explorer. | `boolean` | `false` | |
61+
| `"objectscript.serverSourceControl.disableOtherActionTriggers"` | Prevent server-side source control 'other action' triggers from firing. | `boolean` | `false` | |
62+
| `"objectscript.showExplorer"` | Show the ObjectScript Explorer view. | `boolean` | `true` | |
63+
| `"objectscript.studioActionDebugOutput"` | Log in JSON format the action that VS Code should perform as requested by the server. | `boolean` | `false` | Actions will be logged to the `ObjectScript` Output channel. |
64+
| `"objectscript.suppressCompileErrorMessages"` | Suppress popup messages about errors during compile, but still focus on Output view. | `boolean` | `false` | |
65+
| `"objectscript.suppressCompileMessages"` | Suppress popup messages about successful compile. | `boolean` | `true` | |
66+
67+
{: #intersystems-servermanager}
68+
## InterSystems Server Manager
69+
70+
| Setting | Description | Type | Default | Notes |
71+
| ------- | ----------- | ---- | ------- | ----- |
72+
| `"intersystems.servers"` | InterSystems servers that other extensions connect to. Each property of this object names a server and holds nested properties specifying how to connect to it. | `object` | `undefined` | See the [Configuration page](../configuration/#config-server) for more details on configuring servers. |

‎docs/assets/images/server-actions-with-links.png

57.6 KB
Loading

‎docs/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ nav_exclude: true
1111
* [Configuration](./configuration)
1212
* [Running and Debugging](./rundebug)
1313
* [Server-side Editing](./serverside)
14+
* [Settings Reference](./settings)

0 commit comments

Comments
 (0)