Recipe how to create a tutorial

How to create a tutorial

HTML documentation pages

Notes

JSON tips

There are three major syntax gotchas to watch out for when editing JSON content!

1. The last item in a list must not have a trailing comma. This is a fatal validation error. This is easy to get wrong when copying/pasting/removing sections or objects in a list.

   "topicList":
[
{
"title":"Transformation using Java"
}, # comma
{
"title":"Working with files"
}, # comma
{
"title":"Splitting a large message"
} # no comma
]

2. JSON strings use double quote marks " as delimiters. That means you cannot use unescaped double quote marks within the strings. This will mostly affect you if you want to include HTML in the instructions - e.g. images or span elements with CSS classes. See the examples further down the page - attributes are quoted with single quote marks. You could also use an escaped double quote mark \"

3. Backslashes are treated as an escape character, so to include a literal backslash character you must escape it. For example, C:\\temp

Images

In the section, steps, and substeps text, you can insert images that are hosted on ot4i. For example:

• Start Flow exerciser icon:
  <span class='icon'>Start Flow exerciser</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/startFlowExerciser.png' alt='Start Flow exerciser' />
• Return flow to edit mode icon:
  <span class='icon'>Return flow to edit mode</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/stopFlowExerciser.png' alt='Return flow to edit mode' />
• Send Message icon:
  <span class='icon'>Send Message</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/sendMessage.png' alt='Send message' />
• View path icon:
  <span class='icon'>View path</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/viewPath.png' alt='View path' />
• Change perspective icon:
  <span class='icon'>Change perspective</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/changePerspective.png' alt='Change perspective' />
• DFDL test 'play' icon:
  <span class='icon'>DFDL test</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/dfdlTestPlay.png' alt='DFDL test play' />
• DFDL inherited property icon:
  <span class='icon'>DFDL inherited property</span> icon <img src='http://ot4i.github.io/iib-tutorials/images/icons/iib/dfdlInheritedProperty.png' alt='DFDL inherited property' />

CSS classes

Use CSS classes to highlight or mark pieces of inline text in the tutorial instructions. Some styles currently have the same visual presentation, but marking content semantically gives us forward flexibility to highlight things as appropriate.

The following CSS classes have been defined and align with the styles used in IBM Knowledge Center documentation:

For all user interface controls (use this to mark up the names of buttons, icons, entry fields, menu items, tab names, radio buttons, check boxes, items in drop-down menu, etc.): .uicontrol { font-weight: bold; }
Click <span class='uicontrol'>View details</span>

For library names: .library { font-weight: bold; }
Open the <span class='library'>EDIFACT</span> library

For project names: .project { font-weight: bold; }
The <span class='project'>Large Messaging</span> project is imported into your workspace.

For application names: .application { font-weight: bold; }
Deploy the <span class='application'>HTTP Input</span> application to the integration server.

For message flow names: .msgflow { font-weight: bold; }
Open the <span class='msgflow'>TCPIPProvider.msgflow</span> message flow.

For other IIB resources: .resource { font-weight: bold; }
This points to a configurable service <span class='resource'>TCPIPTutorialServerCF</span>.

For a file name or directory path: .filepath { font-family: monospace, monospace; }
Create the input directory <span class='filepath'>C:\\temp_in</span>

For command names: .cmdname { font-weight: bold; font-family: monospace, monospace; }
You can stop the integration node by using the command <span class='cmdname'>mqsistop</span>.

For a property name: .property { font-family: monospace, monospace; }
Set the <span class='property'>Connection details</span> property.

For a parameter option: .option { font-family: monospace, monospace; }
Set this property to <span class='option'>Whole File</span>

For a variable: .varname { font-style : italic;}
<span class='varname'>ToolkitWorkspace</span>/LargeMessaging/LargeMessaging.xml where ToolkitWorkspace is the local path to your Integration Toolkit workspace.

For a parameter name: .parmname { font-weight: bold; font-family: monospace, monospace; white-space: nowrap; }
Ensure that <span class='parmname'>Input directory</span> is set

For code samples, use the <code> element: code { font-family: monospace, monospace; }
The name of the repeating element is set by the following declaration: <code>final String REPEATING_ELEMENT = "SaleList";</code>

For anything the user has to type in: .userinput { font-family: monospace, monospace; }
Type <span class='userinput'>exit</span> and press Enter.

For message text produced by the application: .msgph { font-family: monospace, monospace; }
The following message is shown: <span class='msgph'>BIP8071I: Successful command completion</span>

For an icon label: .icon{ font-variant: italic; }
Click the <span class='icon'>View path</span> icon.

Manual process using Harp

Setting up your environment

1. Install NodeJS
2. Install Git
3. Open a command window and run the following command:
   > npm install -g harp

Create a fork

1. Create your own fork of the iib-tutorials repository to work from. This contains the src directory where the Harp templates live.
2. Clone the fork to your local machine.

Run Harp

1. Open a command window within the src/tutorials directory and type the following (you can change the port by specifying -port xxxx):
   > harp server
   You should see the following text:
   ------------
Harp v0.14.0 – Chloi Inc. 2012–2014
Your server is listening at http://localhost:9000/
Press Ctl+C to stop the server

2. Point your browser at http://localhost:9000/tutorialExample/en/details
   This corresponds to the details.ejs template file in the tutorialExample directory, and http://localhost:9000/tutorialExample/en/steps corresponds to steps.ejs.
   In general, you can point your browser at a URL that corresponds to a .ejs file beneath that point. Harp compiles the HTML on the fly for rendering without restarting the server.

Start creating your tutorial

1. Create a copy of the tutorialExample directory and change the name.
2. Edit the first line of details.ejs and steps.ejs to replace tutorialExample with your directory name
   <% var thisTutorial = public.tutorialExample.en._data %>
3. Edit _data.json with all the text content for your tutorial.
4. You can check the rendering of your tutorial pages on the Harp server http://localhost:9000/\<yourTutorial>/en/steps

Generate the HTML pages

1. From the command line, run
   > harp compile [src-dir] [out-dir]
   For example:
   > harp compile . ../static20150327

PI file

[Draft - advice, required structure?]

1. Export a PI file with your message flow, resources, and BAR file.

Next steps

[Draft]

1. [Create new repository - or get someone with access to do so - on ot4i with your tutorial HTML pages and PI file.]
2. Update repo_metadata.json by creating a fork of ot4i.github.io, making your changes to include your tutorial, and then issuing a pull request.