-
Notifications
You must be signed in to change notification settings - Fork 7
Recipe how to create a tutorial
There are three major syntax gotchas to watch out for when editing JSON content!
-
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
]
-
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 orspan
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\"
-
Backslashes are treated as an escape character, so to include a literal backslash character you must escape it. For example,
C:\\temp
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' />
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.
- Install NodeJS
- Install Git
- Open a command window and run the following command:
> npm install -g harp
- Create your own fork of the iib-tutorials repository to work from. This contains the src directory where the Harp templates live.
- Clone the fork to your local machine.
-
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
-
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.
- Create a copy of the tutorialExample directory and change the name.
- Edit the first line of details.ejs and steps.ejs to replace tutorialExample with your directory name
<% var thisTutorial = public.tutorialExample.en._data %>
- Edit _data.json with all the text content for your tutorial.
- You can check the rendering of your tutorial pages on the Harp server http://localhost:9000/\<yourTutorial>/en/steps
- From the command line, run
> harp compile [src-dir] [out-dir]
For example:
> harp compile . ../static20150327
[Draft - advice, required structure?]
- Export a PI file with your message flow, resources, and BAR file.
[Draft]
- [Create new repository - or get someone with access to do so - on ot4i with your tutorial HTML pages and PI file.]
- 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.