Add support for project-based workflows (intersystems-community#927)

Author: isc-bsaviano

docs/ExtensionUI.md

@@ -58,14 +58,21 @@ Save the change. This change is not thought to have any adverse effects on the u
 
 ### 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:
+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 to add a folder that gives you access to server-side web application files (for example, CSP files).
 
+If you want to add a folder that shows only a single project's contents, expand the target namespace and the **Projects** folder to reveal the projects in the target namespace. Hover over the target project to reveal its command buttons:
+
+![Project edit buttons.](../assets/images/project-buttons.png "project edit buttons")
+
+- Click the **edit pencil** button to add an *isfs://server:namespace/?project=prjname* folder to your VS Code workspace.
+- Click the **viewing eye** button to add an *isfs-readonly://server:namespace/?project=prjname* folder to your VS Code workspace.
+
 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")
@@ -97,32 +104,31 @@ On Windows, the Server Manager can create connection entries for all connections
 
 ## 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:
+The InterSystems ObjectScript extension supplies an ObjectScript view container. The button to select this appears in the Activity Bar:
 
 ![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.
+This view container contains two views: the ObjectScript Explorer and the Projects Explorer. For more information about the Projects Explorer, see the [Working with Projects](../projects/#explorer) page.
 
-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.
+When a VS Code workspace is not connected to an InterSystems IRIS server, the ObjectScript Explorer provides a button that lets you select a server and namespace. Once the workspace is connected to an InterSystems IRIS server, the ObjectScript Explorer shows files on the server, grouped by type of file.
 
-The ObjectScript view provides the following items:
+If the workspace is configured for server-side editing, the ObjectScript Explorer 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 Explorer 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.
+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 **ObjectScript** 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**
+Technically the **InterSystems Tools** and **ObjectScript** entities described above are what VS Code calls [view containers](https://code.visualstudio.com/api/extension-capabilities/extending-workbench#view-container). The **InterSystems Tools** view container has a single view called **Servers**. The **ObjectScript** view container has two views: **Explorer** and **Projects**.
 
 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.
 

docs/Projects.md

@@ -0,0 +1,117 @@
+---
+layout: default
+title: Working with Projects
+permalink: /projects/
+nav_order: 9
+---
+
+# Working with Projects
+
+A project is a named set of class definitions, routines, include files, web application files or custom documents. All files in a project must be in the same namespace on the same InterSystems server. Each document can be associated with any number of projects. Each namespace can contain any number of projects.
+
+## Why Projects?
+
+You are not required to use projects in VS Code, but you should consider using them if:
+
+* You work [server-side](../serverside) and the `type` and `filter` [query parameters](../serverside/#filters-and-display-options) are not granular enough.
+* You work server-side and want to edit CSP and non-CSP files in the same workspace folder.
+* You work client-side and want to group together many files to export with a single click.
+* You are migrating from InterSystems Studio and want to keep using an existing project.
+
+{: #explorer}
+## Projects Explorer
+
+The easiest way to manage projects is using the Projects Explorer, which is in the [ObjectScript view](../extensionui/#objectscript-view):
+
+![Projects Explorer](../assets/images/projects-explorer.png "projects explorer")
+
+Initally, the Projects explorer contains a root node for each server and namespace connection that exists for the current workspace. It can be expanded to show all projects in that namespace on the server, and expanding the project node will show its contents:
+
+![Projects Explorer Expanded](../assets/images/projects-explorer-expanded.png "projects explorer expanded")
+
+You can also add root nodes for namespaces on any server configured using the InterSystems Server Manager extension. To do so, click on the plus (`+`) button at the top of the view.
+
+The following sections will describe how to use the Projects Explorer and other tools to work with projects.
+
+{: #creating}
+## Creating Projects
+
+There are two ways to create projects in VS Code:
+
+* Right-click on a server-namespace node in the Projects Explorer and select the `Create Project` menu option.
+* Open the command palette and run the `ObjectScript: Create Project` command.
+
+Project names are required to be unique per server-namespace and may optionally have a description. The description is shown when hovering over the project's node in the Projects Explorer or below its name when selecting one in a dropdown menu.
+
+{: #modifying}
+## Modifying Projects
+
+There are three ways to add or remove items from a project:
+
+* Using the Projects Explorer:
+  * To add items, right-click on the project node or one of the document type nodes (i.e. `Classes` or `Routines`) and select the `Add Items to Project...` menu option. If you clicked on a document type node, you will only be shown documents of that type to add.
+  * To remove an item, right-click on its node and select the `Remove from Project` menu option. If you remove a package or directory node, all of its children will also be removed from the project. You may also right-click on the project node and select the `Remove Items from Project...` menu option to be presented with a multi-select dropdown that allows you to remove multiple items at once.
+* Within a workspace folder configured to view or edit documents in a project directly on the server:
+  * To add items, right-click a root `isfs(-readonly)` folder that has the `project` query parameter in its URI and select the `Add Items to Project...` menu option.
+  * To remove an item, right-click on its node and select the `Remove from Project` menu option. If you remove a package or directory node, all of its children will also be removed from the project. You may also right-click on a root `isfs(-readonly)` folder that has the `project` query parameter in its URI and select the `Remove Items from Project...` menu option to be presented with a multi-select dropdown that allows you to remove multiple items at once.
+* Using commands:
+
+  Open the command palette and select the `ObjectScript: Add Items to Project...` or `ObjectScript: Remove Items from Project...` command.
+
+### Add to Project UI
+
+The `Add to Project` command implements a custom multi-select dropdown that is shown regardless of how it is invoked. Items that are in the namespace and not already in the project are shown. The elements of this UI are described in more detail below:
+
+![Add to Project UI](../assets/images/add-to-project.png "add to project UI")
+
+* Title bar row:
+  * Click the icons to show or hide system and generated items, respectively.
+* Input box row:
+  * Click the check box to select all items that are currently shown.
+  * Type in the input box to filter the items that are shown.
+  * Click the **OK** button to add the selected items to the project.
+* Item rows:
+  * Click the check box to select the item. If the item is a package or CSP directory, all of its contents will be selected as well, even though the check boxes for those items don't appear selected.
+  * The icon preceding the name represents its type. It corresponds to the icons in the Projects Explorer and [ObjectScript Explorer](../extensionui/#objectscript-view).
+  * The more prominent text is the short name of the item, as it would appear in a file system.
+  * The less prominent text is the full name of the item, including its package or CSP directory.
+  * Click the arrow icon at the far right of the row to show or hide its contents.
+
+{: #deleting}
+## Deleting Projects
+
+There are two ways to delete projects in VS Code:
+
+* Right-click on a project node in the Projects Explorer and select the `Delete Project` menu option.
+* Open the command palette and run the `ObjectScript: Delete Project` command.
+
+{: #server-side}
+## Editing Project Contents Server-Side
+
+There are a few methods to create a workspace folder to view or edit documents in a project directly on the server:
+
+* Follow the steps [here](../serverside/#config-server-side) and select the project.
+* Right-click in the [Explorer view](../extensionui/#explorer-view) and select the `Add Server Namespace to Workspace` menu option.
+* Use the InterSystems Tools view, as described [here](../extensionui/#viewing-and-editing-source-code-on-the-server).
+* Right-click on a project node in the [Projects Explorer](../projects/#explorer) and select the `Add Workspace Folder For Project` menu option.
+* Add a folder to your `.code-workspace` file directly:
+```json
+{
+  "uri": "isfs://myserver:user/?project=prjname",
+  "name": "prjname"
+}
+```
+
+{: #client-side}
+## Editing Project Contents Client-Side
+
+The entire contents of the project can be easily exported to your local file system for client-side editing. To do so, simply right-click on the project you'd like to export and select the `Export Project Contents` menu option.
+
+## Notes
+
+If you are getting `ERROR #5540: SQLCODE: -99 Message: User abc is not privileged for the operation` when you try to expand the Projects Explorer or view a project's contents in a virtual folder, then grant user abc (or a SQL role they hold) the following SQL permissions:
+
+```SQL
+GRANT SELECT, INSERT, UPDATE, DELETE ON %Studio.Project, %Studio.ProjectItem TO abc
+GRANT EXECUTE ON %Studio.Project_ProjectItemsList TO abc
+```

docs/ServerSide.md

@@ -28,12 +28,24 @@ Next create a workspace for editing code directly on the server:
 1. Pick a namespace from the list retrieved from the target server:
 
    ![Choose a namespace.](../assets/images/ss-choose-namespace.png "choose a namespace")
+1. Pick if this folder should show a project's contents:
+
+   ![Choose if project.](../assets/images/ss-is-project.png "choose if project")
+1. If yes, pick the project from the list, or click the **+** sign to create a new one:
+
+   ![Choose project.](../assets/images/ss-pick-project.png "choose project")
 1. Pick an access mode from the list:
 
+  If no project was selected:
+
    ![Choose an access type.](../assets/images/ss-access-type.png "choose an access type")
+
+  If a project was selected:
+  
+   ![Choose an access type (project).](../assets/images/ss-access-type-project.png "choose an access type (project")
 1. If you want to reopen this workspace in the future, use the command **File > Save Workspace As...** to save it as a `.code-workspace` file.
 
-Note that the ObjectScript button is not visible in the Activity Bar. Because the files listed in the Explorer view are all on the server, it is not needed for this configuration.
+Note that the ObjectScript Explorer view is not visible in the ObjectScript view container. Because the files listed in the Explorer view are all on the server, the ObjectScript Explorer is not needed for this configuration.
 
 The `.code-workspace` file is a JSON file which you can edit directly, as described in the section  [VS Code Workspaces](../configuration/#code-workspaces). A simple example looks like this:
 ```json
@@ -136,10 +148,11 @@ Changes you make to files opened from this root folder of your VS Code workspace
 The query string of the `uri` property accepts several parameters that control filtering and display of the server-side entities. The examples below access the USER namespace on the server whose definition is named 'myserver'.
 
 - `isfs://myserver:user?type=cls`, shows only classes
-- `isfs://myserver:user?type=rtn`, shows only routines, mac, int and inc files
+- `isfs://myserver:user?type=rtn`, shows only mac, int and inc files
 - `isfs://myserver:user?generated=1`, shows generated files as well as not generated
 - `isfs://myserver:user?filter=%Z*.mac,%z*.mac`, comma-delimited list of search options, ignores `type`. The default is `*.cls,*.inc,*.mac,*.int`. To see all files, use `*`.
-- `isfs://myserver:user?flat=1`, a flat list of files does not split packages as folders.
+- `isfs://myserver:user?flat=1`, a flat list of files. Does not split packages as folders. Cannot be combined with `csp`.
+- `isfs://myserver:user?project=prjname`, shows only files in project `prjname`. Cannot be combined with any other parameter.
 
 The options `flat` and `generated` can be combined with each other, and with `type` or `filter`. If `filter` is specified, `type` is ignored.
 

docs/SettingsReference.md

@@ -59,6 +59,7 @@ The extensions in the InterSystems ObjectScript Extension Pack provide many sett
 | `"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. |
 | `"objectscript.openClassContracted"` | Automatically collapse all class member folding ranges when a class is opened for the first time. | `boolean` | `false` | |
 | `"objectscript.overwriteServerChanges"` | Overwrite a changed server version without confirmation when importing the local file. | `boolean` | `false` | |
+| `"objectscript.projects.webAppFileExtensions"` | When browsing a virtual workspace folder that has a project query parameter, all files with these extensions will be automatically treated as web application files. Extensions added here will be appended to the default list and should **NOT** include a dot. | `string[]` | `[]` | Default extensions: `["csp","csr","ts","js","css","scss","sass","less","html","json","md","markdown","png","svg","jpeg","jpg","ico","xml","txt"]` |
 | `"objectscript.serverSideEditing"` | Allow editing code directly on the server after opening it from ObjectScript Explorer. | `boolean` | `false` | |
 | `"objectscript.serverSourceControl.disableOtherActionTriggers"` | Prevent server-side source control 'other action' triggers from firing. | `boolean` | `false` | |
 | `"objectscript.showExplorer"` | Show the ObjectScript Explorer view. | `boolean` | `true` | |