TouchDevelop: How to create an Interactive Tutorial
Creating interactive tutorials
How to create 'tap here' tutorials.
TouchDevelop allows to author and distribute interactive tutorials where the user gets help from the system to achieve a particular script.
comments + code = tutorial
Tutorials consist of steps. Every step applies to an action. To create step(s) for an action named foo create an actions in your tutorial named #1 foo, #2 foo, #2.5 foo, etc. Every one of these actions will create one or more steps in the tutorial. (foo by the way is a term used by software designers to illustrate a method or action “pretend” example, it isn’t a name you should really use in a program.)
Let's take a look at an example:
action #1 main ()
## let's get started
We'll first print `hello`.
"hello world" → post to wall
And now we shall print 7.
7 → post to wall
The first two lines are comments (using this syntax <<link). They are the description of the step.
The line that follow is the body of the step. It can one or more lines of code. Then we have description and body of the next step.
TouchDevelop will display the description to the user, and then make them enter exactly the body step as the body of the action main. Steps can be described in nested structures:
action #1 main ()
We start by writing a `for` loop:
for 0 ≤ i < 12 do
In every iteration we'll print `hello world`:
"hello world" → post to wall
A step can not only add, but also replace preceding code. If the description of the step uses macro {stdelete:N} then the steps cancels (removes) N textually preceding steps, therefore we can add {stdelete:1} as the last step to get the desired effect:
action #1 main ()
We start by writing a `for` loop:
for 0 ≤ i < 12 do
In every iteration we'll print **hello world**:
"hello world" → post to wall
{stdelete:1}
And now we change **hello world** to **goodbye**
"goodbye" → post to wall
We can also add code earlier in the action in later steps. Normally steps are followed top-down, but steps with {storder:N} macro in the description are executed after all the steps without such macro, in order of Ns.
{storder} can be combined with {stdelete} to replace code in the middle.
The step order in the following example is:
1. print "good morning"
2. add for loop
3. print "hello world"
4. print i
5. delete the "good morning" line ({stdelete:1} applies to previous line in textual order, not the previous step (which was i)), and replace with 42
action #1 main ()
We start by printing "good morning":
"good morning" → post to wall
{storder:1.5}
{stdelete:1}
And now let's replace "good morning" with `42`!
42 → post to wall
We start by writing a `for` loop:
for 0 ≤ i < 12 do
{storder:1}
Before every iteration we print `i`:
i → post to wall
In every iteration we'll print `hello world`:
"hello world" → post to wall
About adding new actions
In many tutorial, the user will have to create new actions. Let's take a closer look at how to do this.
Let's say we need to create a sqr action that computes the square of a number. In the tutorial, we want to create 2 actions:
· The numbered action that contains the steps, i.e. #2 sqr.
· This action will become a list of steps in the tutorial.
private action #2 sqr (
input : Number)
returns (
output : Number)
do
This code computes the square of ``input``.
output := input * input
The same action with numbering in order to call it, i.e. sqr. This action is used to make calls from other actions.
private action sqr (
input : Number)
returns (
output : Number)
do
output := input * input
An action name and parameter names must be lower case without trailing spaces.
The reason is that the tutorial engine normalizes the names entered by the user during the tutorial.
Including code in description
Use the {stcode} macro to inline the code that will be added in the next step.
{stcode}
You can also use one of the {box:...} macros. In particular, there is {box:block} macro, which doesn't add any border. For example:
action #1 main ()
{box:block}
We start by writing a `for` loop, like this one:
{hide}
var upper bound := 133
{/hide}
for 0 ≤ i < upper bound do
do nothing
{/box}
for 0 ≤ i < 12 do
In every iteration we'll print `hello world`:
"hello world" → post to wall
The entire {box:block} is the description for the first step. Second (and final) step keeps its description.
splash screen and conclusion
The comments on a public main action will be used in the splash screen. The comments on a public final action will be used in the conclusion dialog, after the user publishes.
meta-commands
You can ask the user to run the program with {stcmd:run}. It needs to be included at the end of a step.
Users are automatically asked to publish the script at the end of tutorial.
template and template name
Use the {template:id} macro to specify an initial script to start the tutorial from. TouchDevelop always picks up the latest version of that script.
Use the {templatename:name} to specify a preferred name of the new script created by the user. In name, the token ADJ will be expanded to random adjectives like awesome, great, etc...
{templatename:ADJ game}
checkpoints
The {stcheckpoint} marks a step as a checkpoint and will be rendered specially in the tutorial.
Use the checkpoint to break down tutorials into logical sub-steps where students can get rewarded.
{stcheckpoint}
Controlling the user interface
In tutorial mode, it is possible to closely control the buttons and widgets displayed to the user. TouchDevelop can hide button of advanced features by using the widgets macro. The macro takes a coma separated list of widget identifier from the list below, e.g. {widgets:debugButton,codeSearch} macro.
· debugButton shows the debug button
· undoButton shows the undo button
· updateButton shows the library update button
· exportButton shows the export/help button
· addNewButton shows the add new action, event button
· codeSearch shows the Search code... search box
· librariesSection shows the list of referenced libraries
· promoteRefactoring shows the promote to ◳data, promote to field, demote to var buttons
· gotoNavigation shows the go to button
· uploadArtInSearchButton shows the upload picture and upload sound in the inline art search
· calcApiHelp tapping on the API helps open the help section
Imprecise matching
Normally the tutorial engine requires the code to be entered exactly as in the template. There is however a few exceptions:
The names of art resources are ignored; only the type has to match (i.e., if the tutorial has a picture resource in some place, any picture will do, but TouchDevelop will complain about sound)
Differences in string literals are ignored by default, except for checking that the string is non-empty (if the string in the template is non-empty); we plan to allow switching this off for particular line of code in the future
Differences in concrete colors are ignored (i.e., colors→red is fine even if the tutorials says colors→blue;
What is not fine: colors→random
Any identifier name entered by the user, e.g. action name, parameter name, will be made lower case and white space will be truncated.
Make sure that your tutorial follow these conventions.
Local variables introduced by store in var button are automatically named to match the tutorial; TouchDevelop does not allow any mismatch in variable or action names.
Show me some examples?
You can also learn by looking at our tutorial sources - they are scripts after all! Scroll down to the bottom of the view and select view as script.
How to get started?
You can start modifying this script.
private action sqr (
input : Number)
returns (
output : Number)
do
0
This code computes the square of input.
output := input * input