Live Tutorials Add-on
An add-on is available that contributes a view that provides the ability to create, run, and check progress for tutorials directly in Oxygen XML Editor. Once the add-on is installed, a Tutorials view is available that shows the available tutorials and allows missions to be followed.
The add-on comes bundled with a set of tutorials for learning to work with the DITA XML standard and you also have the ability to create your own tutorials. Each tutorial contains one or more missions. A mission consists of initial file content that is opened in the application and a set of steps and hints for guidance. The mission is considered complete when the initial content is changed by the end user to match an expected result.
Quick Installation
You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:
Manual Installation
-
Go to to open an add-on selection dialog box.
Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file. - Select the Live Tutorials add-on and click Next.
- Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
- Restart the application.
Result: The Tutorials view is now available. To open the view, select Tutorials from the menu.
Loading Tutorials
The add-on comes bundled with a set of tutorials for learning to work with the DITA XML standard. For example, there are tutorials that contain various missions for learning some basic DITA editing tasks, learning how to work with tables, learning how to edit and insert images, reuse content, and more. Additional tutorials can be loaded from a specified location in the page.
Extra tutorials files (with the fixed name tutorial.xml) that are located within various folders in the Project view will also be loaded automatically.
You can also create your own tutorials and use them with the add-on.
Tutorials View
Once the Live Tutorials add-on is installed, the Tutorials view is available by selecting it from the menu.
The Roadmap is the main interface of the add-on, where all the available tutorials are presented along with the actions that can be triggered regarding the tutorials.
- Tutorials list
-
This is a list of all the available tutorials. Each tutorial is an entry, with its own progress icon displayed on the left side. The following actions are available in the Tutorials list:
- Start mission
- Double-click, press ENTER, or right-click and choose Start mission on any selected mission to begin a new mission. Missions can be started in any order.
- Reset mission progress
- Right-click on a mission and choose Reset progress to reset its current progress.
- Learn how to create your own tutorials help link
- Opens the user guide help pages of the add-on in the preferred browser.
- Learn how to create your own tutorials link
- Opens the user guide of the add-on in the preferred browser.
Once a mission is opened from the Roadmap, the Tutorials view changes to display the selected mission.
Back- Navigates back to the Roadmap missions list.
Hints-
Opens the collapsible/expandable Hints pane that gives you access to various hints to help you complete the current mission.
Figure 3. Hints Pane 
The Hints pane has the following features:- Compare with expected result link
- Opens a visual file comparison tool with the current mission's edited file on the left side and the expected file content from the finished tutorial on the right side.
- Hint details section
- Presents details about the current hint.
- Previous/Next hint buttons
- Navigates between available hints.
- Mission details
- Details are displayed in the mission panel about what the mission consists of and the steps needed to complete it.
Completing a Mission
Once a mission is started, details about how to complete the mission and hints are available. The initial mission file is opened and the add-on will automatically check it to check when it matches the expected content. Upon completing a mission, the Mission Accomplished dialog box is shown and the Next Mission button becomes available to progress to the next mission.
Creating New Tutorials
Once the add-on is installed, you can create new tutorials that can later be loaded from the page. Each tutorial loaded by the add-on must have an associated configuration file named tutorial.xml, where details about the tutorial and the corresponding missions, as well as activity files and hints, are defined.
First, you should create a folder that will contain both the tutorial.xml file and other resources necessary for the tutorial.
Then use the New Document Wizard and search for the tutorial template. Select Live Tutorials/tutorial and save it as tutorial.xml in the custom tutorial folder. A small sample tutorial folder can be downloaded from here.
The tutorial.xml file can be edited in the Author visual mode, which contains inline actions to add new missions, hints, or to browse for referenced resources.
<tutorial>- The root element of the tutorial XML configuration file.
<title>- The title of a tutorial.
<goal>- An overall goal description for the tutorial (can contain escaped HTML content). It is displayed when hovering over the tutorial in the Roadmap.
<mission>- A tutorial has one or more missions. A mission is one of the many objectives that
may appear in a tutorial. There has to be at least one mission in a every tutorial. A
mission requires the following elements and attributes:
@id- An attribute of the mission element that is unique to a mission.
<title>- The title of the mission.
<activity>- The activity of the mission describes the steps to follow and contains the
initial and expected files.
<description>- Describes the steps required to complete the activity. May contain escaped HTML content.
<files>- An activity requires two of file paths that are used to test if the
user completed the steps of the activity.
@projectFolder- An optional reference to a folder where the resources for the mission are located. It can contain an Oxygen Project File (.xpr) that will automatically be opened when the mission starts. The folder needs to be created and referenced relative to the tutorial.xml file.
@editPath- Represents the path of a file that will serve as a starting point for the user to complete the mission. The edited file needs to be created and referenced relative to the tutorial.xml file.
@expectedPath- A reference to a file with expected content that is compared with the changes the end user performs in the edit file. The expected file needs to be created and referenced relative to the tutorial.xml file.
@ignoreXPath- An XPath expression that can be set to ignore certain
elements or attributes when comparing the original and the
user-modified file. For example, you can set it to
@idto ignore all automatically generated IDs.
<hint>- A hint helps the user with more information when trying to complete an activity. The hint may contain embedded escaped HTML content. An activity can have zero or more hints.
Customizing the Default Tutorials
- Copy the default tutorials from the installation directory of the
add-on to a project and edit them as desired. Oxygen XML Editor automatically loads
the tutorials found inside the current project.Tip: To find the location where the add-on is installed, go to , select Live Tutorials from the list of add-ons and look at the value of the Location property. In that location, there is a tutorials folder that contains all the default tutorials.
- Once you have copied the tutorials to your project, you need to disable the loading of the default tutorials by going to and de-selecting the Load default tutorials option. You should also save the options from the Live Tutorials preferences page at the project level so that whenever someone opens your project, the custom tutorials will be loaded from it instead of the default tutorials.
- If applicable, you can share your custom tutorials with others.
Resources
To see a visual demonstration of the Live Tutorials add-on, watch our webinar: Interactive Tutorials in Oxygen.