Go to https://github.com/gjsjohnmurray/oex-vscode-snippets-template and click the
Use this template button to create a new repository within your GitHub account.
To learn more about this step, visit GitHub Docs.
Clone Repositorybutton there.
src/snippets folder contains a file named
_OEX_John.Murray_exampleInTemplate.code-snippets which you should rename using its context menu so it contains your Developer Community handle in place of mine (
If you're not sure what your handle is, go to your DC profile and look on the upper right panel. Your handle displays after the
@sign, which you shouldn't include in your filename.
This naming convention will allow published snippets from multiple authors to coexist in a VS Code project workspace where they get installed. The
_OEX_ prefix is required for all snippet files being published on Open Exchange using this mechanism.
The repository defines a Docker container for running an IRIS instance where you can try out the snippets you create. Start this now:
Compose Upfrom the context menu of the
Terminal will be reused by tasks, press any key to close it..
_oex-vscode-snippets-template.code-workspacefile and rename it to match your repository name. We recommend keeping the
_prefix so that the file lists next to the dotfiles in Explorer view.
Open Workspacebutton in its lower right corner.
The workspace has two root folders:
Projectcontains the locally-cloned folders and files of the repository you created from the template. You will create your snippets here, but indirectly (see details below).
IRIS Server (test your snippets here)is where you will try your snippets by writing code in the USER namespace of the IRIS instance started above.
Before you can access the IRIS Server you must refresh the connection to it.
ObjectScriptpanel on the status bar.
Refresh Connectionif available, else
After a few seconds the status bar panel should change to report being connected to the USER namespace of a localhost IRIS port, but its hover tip may still report a problem such as "socket hang up". Solve this by running
Developer: Reload Window from Command Palette. When that completes, use
Toggle Connection again from the status bar panel.
To complete the refresh, open your
_XYZ.code-workspace file, change the
"IRIS Server (test your snippets here)" folder label slightly (for example to
"IRIS Server (test my snippets here)"), and save it. This is necessary to make VS Code discover snippet files for that IRIS-hosted folder.
The above refresh steps, including the label edit, will be required each time you subsequently open your _XYZ.code-workspace file in VS Code.
As you saw earlier when renaming the example snippets file, the snippets you write are stored in the
src/snippets folder of the
Project root. However in order for your development changes to be detected by VS Code you should always open these files for editing via the
Snippets: Configure User Snippets command.
That command's quickpick will initially offer you the example snippets file you renamed earlier, for example
_OEX_Jane.Doe_exampleInTemplate.code-snippets. Pick this.
Ultimately you may decide to delete this sample file, or at least change the
exampleInTemplate portion of its name to reflect what its edited contents actually do.
As an alternative to adapting the example file, create a new one. Here's how:
Snippets: Configure User Snippetscommand.
IRISto easily get to the entry beginning
New Snippets file for 'IRIS Server (...)'. .Pick it.
_OEX_prefix. Omit the
_OEX_Jane.Doe_loopsif you are writing a set of snippets for creating loop code.
Snippets: Fill File with Snippet, then choosing
New Snippets File.
To verify how your snippets will behave when used while writing code, create new test classes or routines under the
IRIS Server folder, then trigger snippet insertions using the standard VS Code mechanisms.
IMPORTANT NOTE: The classes and routines you write in this folder are only stored inside the database of the USER namespace in the Docker container instance of IRIS. They will not persist across a container restart.
module.xmlfile in the
nameattribute of its
<Document>tag to become the name of the Open Exchange package you will publish. The recommended convention is
suffixwhere yourid is your Developer Community handle and suffix is whatever you choose to distinguish this published snippets module from others you create. The suffix isn't necessarily the same as the suffix you used in the snippets filename because one package can contain multiple snippet files.
README.mdto remove these template instructions and replace them with your own content. Please retain a reference to the template repository from which you created yours.
LICENSEto credit yourself with the snippets. Please also credit me as the author of the framework.
src/snippets/_OEX_*files. Please do not publish any
Now publish on Open Exchange by pointing to your GitHub repository URL and setting the
Publish in Package Manager checkbox. See this DC article for more details, or consult Open Exchange documentation.
People who want to use your snippets will be able to install the package by issuing the appropriate
zpm command in their IRIS namespace. Your snippets will then be available to them when they are using the InterSystems ObjectScript extension's server-side editing features in that namespace. To use the snippets in client-side editing, locate the directory that the
/_vscode web application of the IRIS server points to. The packaged .code-snippets file(s) will be in a subdirectory whose name matches the namespace into which the package was installed.