Merge pull request #653 from intersystems-community/server-manager2

Document new features for ServerManager 2.0

Author: isc-rsingh

docs/.vscode/settings.json

@@ -1,7 +0,0 @@
-{
-    "objectscript.conn": {
-        "server": "default~iris",
-        "ns": "USER",
-        "active": true
-    }
-}

docs/Configuration.md

@@ -2,15 +2,28 @@
 layout: default
 title: Configuration
 permalink: /configuration/
-nav_order: 3
+nav_order: 4
 ---
-# Configuration
+# Configuration 
 
 VS Code settings enable you to customize various aspects of its function. The InterSystems extensions provide settings used to configure VS Code for ObjectScript development.
 
+{: #code-workspaces}
+## VS Code Workspaces 
+
+To work with VS Code, you need to open a workspace. In the simplest setup, a VS Code workspace is just the root folder of your project. Workspace settings and task configurations are stored in the root folder in the `settings.json` file in a folder called `.vscode`. Debugging launch configurations are stored in `launch.json`, also in `.vscode`.
+
+If you need to have more than one root folder in a VS Code workspace, use a feature called multi-root workspaces. See [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the VS Code documentation.
+
+A multi-root workspace is defined by a `*.code-workspace` file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The `*.code-workspace` file stores information about what folders are in the workspace, and may also store other settings that would otherwise be stored in the settings.json or launch.json files. Settings in a folder's `.vscode/settings.json` or `.vscode/launch.json` will override those in the `*.code-workspace` file, so be careful to use one or the other unless you truly need to leverage this flexibility. You can have a workspace file even if you are only working with a single root folder. Indeed. if you are [working server-side](../serverside/) you will always be using a workspace file.
+
+To edit **InterSystems ObjectScript** extension settings in a `*.code-workspace` file in VS Code, open the workspace using **File > Open Workspace...**, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace tab. Search for **objectscript: conn**, and click on *Edit in settings.json*. VS Code opens the `*.code-workspace` file for that workspace.
+
+The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development directly in namespaces on InterSystems servers.
+
 ## Settings
 
-Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager and InterSystems ObjectScript extensions supply additional settings you can use to define InterSystems IRIS servers and connections to those servers.
+Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager, InterSystems ObjectScript and InterSystems Language Server extensions supply additional settings you can use to define InterSystems IRIS servers and the behavior of connections to those servers.
 
 There are several levels on which settings are stored and used:
 
@@ -24,6 +37,7 @@ For example, the following screen shot shows the Workspace level selected:
 
 See the VS Code documentation section [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
 
+{: #config-server}
 ## Configuring a Server
 
 First, configure one or more servers. Select **View > Command Palette > InterSystems Server Manager: Store Password in Keychain**. This command lets you define a new server and securely store a password in the system keychain. Click the plus sign in the upper right corner of the dialog, as shown:
@@ -40,6 +54,8 @@ Provide the following values when prompted:
 
 Once you have entered these values, the server definition is stored in your user settings. At that point another prompt appears, asking for a password to store in the system keychain. Enter the password for the username supplied earlier to complete the process. Storing a password is optional. You can terminate the process and store the server configuration by pressing either **Escape** or **Return**. If you do not store a password, users are prompted for a password each time they connect to the server.
 
+To remove a password from the keychain, Select **View > Command Palette > InterSystems Server Manager: Clear Password from Keychain**. The commands to both store and clear passwords are also available from the server context menu in the InterSystems Tools view.
+
 You can create a configuration for a server that is not currently running.
 
 ## Editing a Server Configuration
@@ -50,6 +66,10 @@ If you need to modify a server configuration select **File > Preferences > Setti
 
 Click *Edit in settings.json*.
 
+The InterSystems Tools view provides an alternate path to this `settings.json` file. Click the `...` button and select **Edit Settings**. 
+
+![Edit settings.](../assets/images/edit-settings.png "edit settings")
+
 The server configuration in *settings.json* looks similar to the following, with the values you entered when you configured the server:
 
 ```json
@@ -111,4 +131,4 @@ The components of this configuration are:
 
 - **ns** - namespace to use on the server
 - **server** - server name as specified in the server configuration
-- **active** - specifies whether the connection is active.
+- **active** - specifies whether the connection is active.

docs/ExtensionUI.md

@@ -0,0 +1,129 @@
+---
+layout: default
+title: InterSystems Extensions UI
+permalink: /extensionui/
+nav_order: 3
+---
+# InterSystems Extensions User Interface
+
+The InterSystems extensions add additional capability to the VS Code user interface to support development in ObjectScript. These additions are based on the standard VS Code UI, which is described in the section [User Interface](https://code.visualstudio.com/docs/getstarted/userinterface) in the VS Code documentation.
+
+## Explorer View
+
+Select the Explorer view button in the Activity Bar to open the view.
+
+![Explorer view button.](../assets/images/explorer.png "explorer view button")
+
+The Explorer view is a standard VS Code view. InterSystems extensions add the following items to context menus in the this view:
+
+- **Add Server Namespace to Workspace...** - in context menu of folders
+- **Import and Compile** - in context menu of folders and files when you are connected to an InterSystems server
+- **Import Without Compilation** - in context menu of folders and files when you are connected to an InterSystems server
+
+## InterSystems Tools View
+
+The InterSystems Server Manager extension supplies an InterSystems Tools view. Select the InterSystems Tools view button in the Activity Bar to open the view.
+
+![InterSystems Tools button.](../assets/images/intersystems-tools.png "intersystems tools button")
+
+### Viewing Server Resources
+
+This view shows server resources in a tree format.
+
+![Server tree view.](../assets/images/server-tree-view.png "server tree view")
+
+As you can see, the view groups servers into a variety of folders, such as currently in use, favorites, and recently used. Within the view, you can perform operations on the servers. When you move the cursor over a server listing, command buttons appear which let you mark the server as a favorite, or open the Management Portal for the server in either the simple browser in a VS Code tab or in an external browser:
+
+- ![Add to starred.](../assets/images/add-to-starred.png "add to starred")
+- ![Open Management Portal in tab.](../assets/images/management-portal-tab.png "open management portal in the simple browser in VS Code")
+- ![Open Management Portal in browser.](../assets/images/management-portal-browser.png "open management portal in browser")
+
+#### Notes About the VS Code Simple Browser
+
+Only one Simple Browser tab can be open at a time, so launching a second server's Management Portal replaces the previous one.
+
+If the server version is InterSystems IRIS 2020.1.1 or later you need to change a setting on the suite of web applications that implement Management Portal. The Simple Browser is not be permitted to store the Portal's session management cookies, so the Portal must be willing to fall back to using the CSPCHD query parameter mechanism.
+
+In Management Portal, select **System Administration > Security > Applications > Web Applications**. Enter `/csp/sys` in the **filter** field to find the five web applications whose path begins with `/csp/sys`.
+
+![Portal web app list.](../assets/images/five-web-apps.png "portal web app list")
+
+For each application, select the link in the **name** column to edit the application definition. In the section labeled **Session Settings**, change the the value of **Use Cookie for Session** from **Always** to **Autodetect**. 
+
+![Edit session setting.](../assets/images/edit-webapp.png "edit session setting")
+
+Save the change. This change is not thought to have any adverse effects on the usage of Portal from ordinary browsers, which continue to use session cookies.
+
+### Viewing and Editing Source Code on the Server
+
+Expand the target server, then expand its **Namespaces**  folder. Hover over the target namespace to reveal its command buttons:
+
+![Namespace edit buttons.](../assets/images/namespace-buttons.png "namespace edit buttons")
+
+- Click the **edit pencil** button to add an *isfs://server:namespace/* folder to your VS Code workspace.
+- Click the **viewing eye** button to add an *isfs-readonly://server:namespace/* folder to your VS Code workspace.
+- Hold the **alt** or **option** key while clicking the edit or view button if you want to add a folder that gives you access to server-side web application files (for example, CSP files).
+
+Once you have added a server-side namespace to the workspace, VS Code opens the Explorer view showing the added namespace. The following screen shot shows the **Sample** and **User** packages in the **src** folder on the client, and the **Sample** and **User** packages in the **USER** namespace on the server, with read-only access.
+
+![Client-side and server-side namespaces.](../assets/images/client-server.png "client-side and server-side namespaces")
+
+Learn more about isfs and isfs-readonly folders in the section [Configuration for Server-side Editing](../serverside).
+
+If you are already doing client-side editing of your code, for example, managing it with Git, be sure you understand the consequences of also doing server-side editing using isfs. The ObjectScript extension's README outlines the differences between client-side and server-side editing. If in doubt, limit yourself to isfs-readonly by only using the eye icon.
+
+### Adding a Server
+
+You can use the plus sign (`+`) at the top of the view to add a server. This control provides an additional entry point to the process described in the section [Configuring a Server](../configuration/#config-server).
+
+![Add server.](../assets/images/add-server.png "add server")
+
+The server definition is added to your user-level *settings.json* file and also appears at the top of the 'Recent' folder.
+
+### Server Context Menu
+
+Servers listed in the InterSystems Tools view provide a context menu which provides access to several commands, including storing and clearing passwords in the keychain.
+
+![Server context menu.](../assets/images/server-context-menu.png "server context menu")
+
+A submenu enables you to set the color of the icon to the left of the server name. The following screen shot shows this menu, and the icon color set to red.
+
+![Set icon color.](../assets/images/set-icon-color.png "set icon color")
+
+### Import Server Connections
+
+On Windows, the Server Manager can create connection entries for all connections you previously defined with the original Windows app called InterSystems Server Manager. This action is available from the '...' menu at the top right corner of Server Manager's tree, as shown in the following screen shot.
+
+![Import servers from registry.](../assets/images/import-servers.png "import servers from registry")
+
+## ObjectScript View
+
+The InterSystems ObjectScript extension supplies an ObjectScript view container. The button to select this appears in the Activity Bar only when a folder or a workspace that includes a client-side folder is open:
+
+![ObjectScript button.](../assets/images/objectscript.png "objectscript button")
+
+When a VS Code workspace is not connected to an InterSystems IRIS server, the ObjectScript view provides a button that lets you select a server and namespace. Once the workspace is connected to an InterSystems IRIS server, the ObjectScript view shows files on the server, grouped by type of file.
+
+If the workspace is configured for server-side editing, the ObjectScript view is not available. In this configuration, the Explorer view lists files on the server, not on the local machine, making the ObjectScript view irrelevant.
+
+The ObjectScript view provides the following items:
+
+- **Compile** - Compiles files on the server.
+- **Delete** - Deletes files from the server.
+- **Export** - Exports files to the workspace on the client.
+- **Server Command Menu...** - Pick a command from menus configured on the server.
+- **Server Source Control...** - Pick a command from menus configured on the server.
+
+The InterSystems IRIS documentation section [Extending Studio](https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ASC#ASC_Hooks_extending_studio ) describes how to configure menus for source code control and other purposes. Entries from menus named **%SourceMenu** and **%SourceContext** appear in the **Server Source Control...** quickpick provided the source control class doesn't disable the entry, for example, disabling checkout if it knows that the file is already checked out.
+
+Entries from menus with any other name appear in the **Server Command Menu...**.
+
+## Views and View Containers
+
+Technically the 'InterSystems Tools' and 'Explorer' entities described above are what VS Code calls [view containers](https://code.visualstudio.com/api/extension-capabilities/extending-workbench#view-container). Each contains a single view:
+- in container **InterSystems Tools** is view **Servers**
+- in container **ObjectScript** is view **Explorer**
+
+When a VS Code container has only a single view in it the view header merges with the container header, with the two names separated by a colon.
+
+Views can be dragged between containers, so for example you could move Explorer off its ObjectScript container and onto the InterSystems Tools container. Or move Servers onto the ObjectScript container. Or move either of them onto VS Code's main Explorer container.

docs/Installation.md

@@ -8,11 +8,11 @@ nav_order: 2
 
 ## Install VS Code
 
-Your first step is to install VS Code: 
+Your first step is to install VS Code:
 
 1. Go to the [Visual Studio Code download page](https://code.visualstudio.com/).
-2. Download an appropriate build for your platform.
-3. Open the downloaded file and follow the installation instructions.
+1. Download an appropriate build for your platform.
+1. Open the downloaded file and follow the installation instructions.
 
 ## Install the InterSystems ObjectScript Extensions
 
@@ -30,6 +30,4 @@ Type `intersystems` in the search field to find these extensions in the Marketpl
 
 ![Search in Marketplace.](../assets/images/marketplace.png "search in marketplace")
 
-You can install all the required extensions in one step by clicking on the **Install** button for the InterSystems ObjectScript Extension Pack. You can also install each extension separately by clicking the **install** button for the required extension. Note that the InterSystems ObjectScript extension supplies an ObjectScript button which appears in the Activity Bar when a workspace or folder is open:
-
-![ObjectScript button.](../assets/images/objectscript.png "objectscript button")
+You can install all the required extensions in one step by clicking on the **Install** button for the InterSystems ObjectScript Extension Pack. You can also install each extension separately by clicking the **install** button for the required extension. 

docs/RunDebug.md

@@ -2,7 +2,7 @@
 layout: default
 title: Running and Debugging
 permalink: /rundebug/
-nav_order: 4
+nav_order: 5
 ---
 # Running and Debugging