The tutorial tool is a tool which allows you to write and run your own tutorials. If you've ever used an online "learn how to program" tool you're likely already familiar with the concept. Where Komodo's tutorial tool sets itself apart is that you are in a full blown IDE environment, so the possibilities of what you could do with the tool are endless.
To run a tutorial open up your toolbox, navigate to the "Tutorials" folder and double click one of the available tutorials. We recommend starting with the "Getting Started" tutorial.
To create a tutorial, start by hitting the "cog" icon at the top right of the toolbox widget, then select "New Tutorial". Alternatively if you wish to edit a tutorial you can right click the tutorial in your toolbox and select "Properties".
Normally you edit a tutorial through the dialog that pops up, but you can also open the tutorial in your main editor by right clicking it and selectin either "Edit Tutorial" or "Edit Tutorial Logic". What do those mean you might ask?
Edit Tutorial: You're editing the main tutorial information, the text, titles, tips, etc. For most people this will be the only thing that they will use. Edit Tutorial Logic: This allows you to provide optional logic for your tutorial, for example you could add validation functionality to ensure that a step is completed before continuing to the next.
Let's have a look at how you actually write the tutorial.
Tutorials are written in YAML, this makes it so that almost anyone can edit a tutorial as the markup is fairly self explanatory and isn't overly picky. Although you'd still need some tech savvy skills to ensure it doesn't break, it won't be anywhere near as bad as using something like JSON.
You might be asking why we didn't create a GUI for this, well quite simply we felt the tutorial tool should be fun to work with, and programmers love their code more than anything else. Wrapping this up in a GUI would likely have made it a frustrating experience both for the user as well as the developer (wherein we, the maintainers of Komodo, are the developers).
So, let's have a look at the anatomy of a tutorial yaml file. Scroll down to see additional information on some of these properties.
Description: A short description of what your tutorial does, currently this isn't used yet but this will eventually show up in the package manager Author: Your Name Version: 1.0 Placement: docked or floating PlacementOptions: Orientation: Vertical Callouts: myCallout: Element: #toolsToolbarGroup Message: Pay attention to this element, it does XYZ! Fail: Make sure you enabled this element! Steps: - Title: First Step Summary: > Markdown summary. Special features include: * [logic callback link][callback:myCallback] - Calls the myCallback method in your tutorial logic * [callout link][callout:myCallout] - See the defined callouts above * Click this button: ![element:#newButton] - Shows an image of the given UI element ![element:#openFilesPaneLabel,chrome://openfiles/content/panel.xul] -- Same as above, but the given UI element is in a specific window Task: > Your Task # The following fields are optional Tips: - tip 1 - tip 2 - tip 3 Validate: checks for this string in the active editor buffer Validate: !!js/regexp /^checks for this regex in the active editor buffer$/ Validate: myValidationFunction # Calls this function in your logic Success: > Shown when the validation succeeds, before continuing to the next step - Title: Second Step Summary: > Your Summary Task: > Your Task
Let's have a closer look at some of these properties, note we'll skip the ones that are self-explanatory.
Defined whether the tutorial opens "docked" or "floating". Docked means it will open as part of the main Komodo window, whereas floating means it will open as a floating window.
Orientation: Defined whether the tutorial will open as a vertical panel or a horizontal panel. Try it out to see the difference.
A callout calls out a certain element in Komodo. For example you could use it to "call out" the debug button. It essentially blacks out the entire window except the chosen element, and shows a chosen message.
Element: The element that should be called out (as a CSS selector). Use the DOM Inspector to find the CSS selector for the element you're interested in. Message: The message to show when the callout is active Fail: This is a warning that shows to the user if the element that was chosen was not found or is not visible.
Fill out a tip per line (starting with the dash). The user will be able to choose to "unlock" one tip at a time. Tips are meant to assist the user when they get stuck, but are otherwise preferred not to be shown as part of the task as you want the user to still have to do some of the work so that they learn the process.
This allows you to specify validation that needs to be met before the user can continue to the next step. Note that the user can choose to force the next step and ignore the validation, but they will be warned that this could break the tutorial (ie. the steps could no longer make sense).
You can enter three types of values:
Note that for the callback method you need to return either "true" (boolean) or you need to return the error message.
This is a simple success message that can be shown before you continue to the next step, or if it's used on the last step in the tutorial it would be shown as the final message before finishing the tutorial.
© 2017 ActiveState Software Inc. All rights reserved. ActiveState®,
Komodo®, ActivePerl®, ActivePython®, and ActiveTcl® are registered
trademarks of ActiveState.
All other marks are property of their respective owners.