-
Notifications
You must be signed in to change notification settings - Fork 24
Available Commands in Didact and Elsewhere
The VS Code environment provides many different commands that can be called, but they may require some additional work to see what needs to be passed to them. Most will take a vscode.Uri indicating the resource they are operating on, but you may have to actually look at some code in the Microsoft VS Code GitHub repo to divine those details.
What follows is a list of commands provided by the Didact extension and any details to be passed, along with one or more examples of use.
Creates a folder/file structure in the user's workspace based on the structure defined in the JSON file provided.
- Inputs: Pass the path to the JSON file specifying the file/folder structure. With no input, it creates a sample folder/file structure.
- Example:
didact://?commandId=vscode.didact.scaffoldProject&extFilePath=redhat.vscode-didact/create_extension/md-tutorial.project.didact.json&completion=Created%20starting%20Didact%20file. - See [Didact Scaffolding(https://github.com/redhat-developer/vscode-didact/wiki/Didact-Scaffolding) for details about the JSON file structure.
"folders": [
{
"name": "root",
"folders": [
{
"name": "resources",
"folders": [
{
"name": "text"
},
{
"name": "images"
}
]
},
{
"name": "src",
"files": [
{
"name": "simple.groovy",
"content": "from('timer:groovy?period=1s')\n\t.routeId('groovy')\n\t.setBody()\n\t.simple('Hello Camel K from ${routeId}')\n\t.to('log:info?showAll=false')\n"
}
]
}
]
}
]
Opens the default Didact file as specified by the preference Didact: Default Url.
- Inputs: None
- Example:
didact://?commandId=vscode.didact.openTutorial
Opens a Didact window with the Markdown or AsciiDoc file passed in as a vscode.Uri reference. If no Uri is provided, it will attempt to get the currently selected file and assume it is a Didact file.
- Inputs: vscode.Uri
- Example:
didact://?commandId=vscode.didact.startDidact
Note: This can also be done by simply specifying a valid Uri to a Didact file in a vscode://redhat.vscode-didact? link. (See Constructing Didact Links for details on specifying https/http, extension, and workspace paths.
- Example 1:
vscode://redhat.vscode-didact?https=raw.githubusercontent.com/redhat-developer/vscode-didact/master/example/tutorial2.didact.md - Example 2:
vscode://redhat.vscode-didact?extension=example/tutorial.didact.md
The VS Code Link Handler that is registered uses the startDidact command to handle incoming links specified in this manner.
Creates and shows a terminal with the given name in the VS Code window. The name can be omitted.
- Inputs: name (string, optional)
- Example:
didact://?commandId=vscode.didact.startTerminalWithName&text=file-copy-term&completion=Opened%20the%20file-copy-term%20terminal.
Sends text to a named terminal, which is then executed in the terminal. If the named terminal doesn't exist, it is created.
- Inputs: name (string) and text (string) to send in the format
text=name$$command-to-execute - Example:
didact://?commandId=vscode.didact.sendNamedTerminalAString&text=file-copy-term$$cd%20file-copy%20%26%26%20mvn%20exec:java&completion=Sent%20commands%20to%20terminal%20window.(Changes to the directory calledfile-copyand executesmvn exec:java)
Note: In order to send multiple commands spread out across multiple links in the same terminal window, ensure that the name passed is consistent.
Send a Ctrl+C key combination to a named terminal to stop a long-running process. Terminal with the given name must be accessible.
- Inputs: name (string) in the format
text=name - Example:
didact://?commandId=vscode.didact.sendNamedTerminalCtrlC&text=file-copy-term&completion=Sent%20Ctrl+C%20to%20terminal%20window.(Sends Ctrl+C to Terminal window calledfile-copy-term)
Closes and dispooses a named terminal. Terminal with the given name must be accessible.
- Inputs: name (string) in the format
text=name - Example:
didact://?commandId=vscode.didact.closeNamedTerminal&text=file-copy-term&completion=Closed%20terminal%20window.(Closes the named Terminal window calledfile-copy-term)
Creates and opens a named output channel. If you don't provide a name then the Didact Activity output channel will be used instead.
Access to output channels is very limited in VS Code and you can only access output channels which were created by yourself.
- Inputs: name (string, optional) in the format
text=name - Example:
didact://?commandId=vscode.didact.openNamedOutputChannel&text=newOutputChannel&completion=Opened%20a%20new%20output%20channel.(Opens a new output channel namednewOutputChannel)
Sends a text to the output channel with the given name. If you don't provide a name then the Didact Activity output channel will be used instead.
Access to output channels is very limited in VS Code and you can only access output channels which were created by yourself.
- Inputs: message (string), channelName (string, optional) in the format
text=message$$channelName - Example:
didact://?commandId=vscode.didact.sendTextToNamedOutputChannel&text=Hello%20Didact!&completion=Sent%20a%20text%20to%20Didact%20Activity%20channel.(SendsHello Didact!to the Didact Activity output channel)
Simple command-line check for system capabilities. Takes three parameters - the id of the HTML element to update with the results, the test command (such as mvn --version, and a string to search for in the resulting text, such as Apache Maven if the mvn command works successfully).
- Inputs: text anchor name to update, command to execute, and expected text (partial matches are ok)
- Example:
didact://?commandId=vscode.didact.requirementCheck&text=maven-requirements-status$$mvn%20--version$$Apache%20Maven&completion=Apache%20Maven%20is%20available%20on%20this%20system.(in this case the command will look to update themaven-requirements-statustext (formatted like*Status: unknown*{#maven-requirements-status}) with success or failure after executingmvn --versionand looking for the stringApache Mavenin the text that comes back)
Even simpler command-line check for system capabilities. Takes two parameters - the id of the HTML element to update with the results and the test command (such as mvn --version. If command executes with no errors (return code 0), it returns true. If not, false.
- Inputs: text anchor name to update, command to execute
- Example:
didact://?commandId=vscode.didact.cliCommandSuccessful&text=maven-requirements-status$$mvn%20--version&completion=Apache%20Maven%20is%20available%20on%20this%20system.(in this case the command will look to update themaven-requirements-statustext (formatted like*Status: unknown*{#maven-requirements-status}) with success or failure after executingmvn --versionand checking for the return code zero that comes back)
Simple check to see if the extension Id is installed in the user workspace. Takes two parameters: the id of the HTML element to update with the results and the extension Id to check for.
- Inputs: text anchor name to update, and expected extension ID to be available in the VS Code environment
- Example:
didact://?commandId=vscode.didact.extensionRequirementCheck&text=extension-requirement-status$$redhat.apache-camel-extension-pack&completion=Camel%20extension%20pack%20available.
Simple check to see if the workspace has at least one root folder. Takes one parameter: the id of the HTML element to update with the results.
- Inputs: text anchor name to update
- Example:
didact://?commandId=vscode.didact.workspaceFolderExistsCheck&text=workspace-folder-status&completion=A%20valid%20folder%20exists%20in%20the%20workspace.
Creates a folder in the user's temp directory and adds it to the workspace as a makeshift root directory.
- Inputs: None
- Example:
didact://?commandId=vscode.didact.createWorkspaceFolder&completion=Created%20temporary%20folder%20in%20the%20workspace.
Forces the Didact window to reload with the default Didact file specified in VS Code settings.
- Inputs: None
- Example:
didact://?commandId=vscode.didact.reload&completion=Reloaded%20Didact%20window%20with%20default%20link%20specified%20in%20preferences.
Gathers all requirements in the Didact file and invokes the requirement checks one at a time. Useful if you have a long list of requirements to check.
- Inputs: None (assumes that there are Requirements checks specified in the Didact file)
- Example:
<a href='didact://?commandId=vscode.didact.validateAllRequirements' title='Validate all requirements!'><button>Validate all Requirements at Once!</button></a>(creates a button that can be clicked to walk through all the requirements validations one at a time)
Gathers a list of all requirements in the Didact file. Used internally as part of the vscode.didact.validateAllRequirements execution.
Gathers a list of all commands used in the Didact file. Used for testing purposes only.
Menu command used when the user right-clicks on a tutorial in the Didact Tutorials view to Start Didact Tutorial.
Command used to register a new Didact tutorial so that it appears in the Didact Tutorials view. This command is invoked by VS Code Extension code to register tutorials they provide.
- Inputs: name of tutorial, path to the tutorial, and tutorial category
- Example:
// command ID: vscode.didact.register
const commandId = 'vscode.didact.register';
// then pass name, uri, and category
const tutorialName = 'My First Tutorial';
const tutorialPath = path.join(context.extensionPath, './path/to/tutorial.didact.md');
const tutorialUri = vscode.Uri.parse(`file://${tutorialPath}`);
const tutorialCategory = 'My Tutorials';
await vscode.commands.executeCommand(commandId, tutorialName, tutorialUri,tutorialCategory);
Toolbar command used when the user clicks the Refresh button on the toolbar of the Didact Tutorials view.
Command to copy text from a file onto the clipboard. Handy for longer examples or examples with formatting.
- Input: path to file - can use 'extension', 'workspace', 'http', 'https' like with the
startDidactcommand - Example:
didact://?commandId=vscode.didact.copyFileTextToClipboardCommand&extFilePath=redhat.vscode-didact/examples/clipboardTextToTerminal.txt
Command to copy text directly from the URL to the clipboard. Handy for short strings you can URL encode easily.
- Input: URL encoded text to copy onto the clipboard
- Example:
didact://?commandId=vscode.didact.copyToClipboardCommand&text=The%20fox%20jumped%20over%20the%20lazy%20dog.
VS Code has a rich set of commands and every extension may have its own commands to mine for Didact links. Some common commands include:
-
java.projectConfiguration.update: Updates a Mavenized Java project, essentially attempting to get it ready to run (See vscode-java) -
vscode.openFolder: See Commands in the VS Code API docs -
vscode.open: See Commands in the VS Code API docs
New in 0.1.18! Passing JSON to commands that accept it
Some commands allow passing settings via JSON. We now support that in the Didact URL!
didact://?commandId=workbench.action.terminal.renameWithArg&json={"name":"aNewName"}didact://?commandId=type&vscode.open={"viewColumn":-2}
Note that in the
vscode.opencase, you must pass the enum value for the vscode.ViewColumn enum entry itself. -2 corresponds toBesideand is a useful command to keep in mind!