VS Code navigation steps

[alexweininger]

Currently CodeTour is an awesome way to let users interact with files and the text within them.

However, I believe that many projects would benefit from steps that could lead users through the VS Code UI in addition to the project files.

Examples include:

• Directing the user to VS Code's SCM view, and helping the user commit and push code
• Using a CodeTour to create a tutorial for a VS Code extension, a good example might be the Azure Functions extension. Where we could show the user how to create and deploy an Azure Function.

I think that implementing this feature could be as simple as just letting us define custom CodeTour steps, that have a VS Code command associated with them.

[lostintangent]

Hey! 👋 I’ve actually been meaning to add support for steps to include an optional list of commands. That way, authors could automate arbitrarily rich behavior, in addition to being able to easily associate content with a file or directory.

In your case, it sounds like you’d want to be able to define content steps (I.e. steps that aren’t associated with a specific file or folder), that also include a set of commands that would be run when that step is played back?

I wonder if in addition to being able to specify a list of commands, we shouldn’t also add first-class support for a step that focuses a specific view and explains it (e.g. a “view step”). That way, you’d only need to rely on the custom command solution if your step needed to do more than focus a view and provide descriptive text for it. I think it should be possible for CodeTour to contribute a custom title bar action to every view while in record mode, so we might be able to provide a pretty simple UX for creating “view steps”.

[alexweininger]

The "view step" would be exactly what we are looking for.

On top of a bare bones "view step" it might be useful to be able to highlight specific buttons, or text fields of the views. This could definitely be a stretch goal, because just providing a "view step" would be a huge help for us.

As you may know @fiveisprime and I are working on a trial app experience for the Azure App Service VS Code extension. And we think CodeTour could be perfect for a tutorial that could lead users through creating, and editing trial apps in VS Code.

[lostintangent]

@alexweininger Hey! I just pushed experimental support for two things: associating a view with a step, and adding an array of commands to a step. Both of these (currently) require you to hand edit the tour JSON file currently, since I want to get some feedback from you before I try to smooth over the authoring experience :)

To use this, you can create a new tour, add a content step (see image below) with the content you want, and then open up the tour file add a view and/or commands property. The view property simply refers to the ID of the VS Code view (e.g. gistpad.gists). When this property is set, and the user navigates to this step, CodeTour will automatically focus this view.

Additionally, the commands property is an array of strings, which represent the ID of VS Code commands. When the step is navigated to, CodeTour will execute those commands in the order specified. If you need to pass arguments, simply add a query string to the command name, that includes an array of arguments (e.g. codetour.startTour?["Title"]). I'd love to hear any feedback/questions to know if this generally seems like it would work for your scenarios. Thanks!

Note: You can also run the CodeTour: Add Tour Step command in the palette to achieve the same thing.

[alexweininger]

@lostintangent Thanks for making these changes so quickly!

Using the View IDs found here here I'm getting the following error:

Here is the JSON:

[lostintangent]

Apologies! The change I checked in only supported 3rd-party views :/ If you grab v0.0.32, and set the view property to scm, it should work as expected. I added the notion of "well-known" views, that include all of the built-in ones (e.g. debug, explorer, search, scm).

The view property should also now have completion for the well-known views, though the CDN may cache the JSON schema for a bit. In the meantime, here's the list of values you can use. Note that you can also specify the ID of a custom extension-contributed view:

"view": {
  "type": "string",
  "enum": [
    "debug",
    "debug:breakpoints",
    "debug:callstack",
    "debug:variables",
    "debug:watch",
    "explorer",
    "extensions",
    "extensions:disabled",
    "extensions:enabled",
    "output",
    "problems",
    "scm",
    "search",
    "terminal"
  ],
  "description": "The ID (e.g. gistpad.gists) that this step is associated with."
}

[alexweininger]

The view property works really well and is exactly what we need. Thanks!

[lostintangent]

@alexweininger Awesome! 🙌I'll go ahead and close this issue then, since the commands list is also available for you if you need it. Thanks said, please file any other issues/suggestions on how we could unblock your use case.

In the future, I'm going to see how I can add a way to create "view steps" without manually editing the tour file, but I think I'll need some support from VS Code for that 👍