Help - Text - Browse

JTLanguage help browser.

Creating a Markup Template

Introduction

In this help page, we will look at creating and using markup templates.

A markup template is an object in JTLanguage with multiple uses. It's main purpose is to store a block of text that is coded in a markup language that is a superset of HTML (a superset of XHTML to be exact, which is a case of the XML format), extended with additional elements for substitution, conditionals, and control flow.

When used in a textual content item, a markup template can be used to override the visual layout of the page. When used in lesson, group, course, or plan main page, it will layout the content of those pages. When used in the "Generate" page of an audio media content item, a markup template can be used as a script to generate the actual audio file by the teacher, substituting pre-recorded audio from the study items or defined strings, or using speech synthesis. Finally, when used in an automated content or study item, the markup template will be used as the source for a script that runs in real time, managing the visual and audio output for the automated item. We'll look at each of these cases in terms of creating and referencing a markup template.

The markup language implements string and token substitution mechanisms that allow the script to be used for multiple languages. You can define these language strings in the markup template itself, and can also associate audio files with them (for the case of audio generation). Substitution tokens can represent strings pulled from fields in the content or lesson nodes, and for referencing study items from a study list content item.

An "Insert" element lets you insert content from a text content it, either the whole item, an indexed subset, individual study items, or study item components, as well as insert a player for a media item. Conditional and control flow elements lets you do conditional output, or various forms of iteration

We'll given an example of a script in creating a markup template, but we won't go into much detail about the markup/scripting language itself here, as it's described in the following two help pages:

Markup Text Reference
Generate/Automated Markup Reference

Some knowledge of HTML and XML would be useful in understanding the markup language.

In this page we will mainly look at the creating and mangagement of these markup template objects. We'll do so by walking through the creation of a simple markup template for a lesson summary page, and setting up a markup template for a lesson page, generating an audio media file, setting the markup template used as a script for both an automated media item defined in a lesson as well as one used in the automated study mechanism.

The Markups List

Selecting the "Teacher->Markups" menu path will cause the markups list page to be displayed. This page displays the markup templates you've created, and can also display other teachers' markup templates as well, selectable via the "Show markup templates for teacher" drop-down menu.

Markups list page.

The buttons to the right of the listed markup templates can be used to operate on individual markup templates, such as navigating to it, editing its profile, editing its markup text, editing its strings, copying from another markup template, moving it up or down, and deleting it.

The button links at the bottom are for navigation and various operations on the whole markups list.

Creating the Markup Template Profile - Lesson Summary

To add a new stand-along markup template, we'll click the "Add markup" button link at the bottom of the "Markups" page. This brings up a page for setting up the profile for the markup template.

Add markup profile page.

For our example, I'll call my markup template "Lesson Summary", with a description string of "Layout for a lesson summary page."

By default, the language fields are set to the languages of the current profile. These fields specify which languages the markup template currently supports. If you will be using the markup template with additional languages, you can set up those languages there. The special "Target Languages" and "Host Languages" placeholder items in the language fields specify that when the markup template is used, it will just get the languages from the current profile.

The "Public" flag indicates whether the markup template can be seen by other users in the markups list.

Click "Save" to save the markup template profile. The main page for the markup template will be displayed, showing that no markup text or strings have been created yet.

Empty markup page.

Adding Markup Text

To add or edit the markup template script text, click the "Edit markup text" button link. This takes you to the Markup Text page, with a big text edit control for editing the markup text in the "Markup Text" fieldset, a "Markup" fieldset that will display render the markup as a preview, and a list of the defined language strings for the current languages in your user profile.

Edit markup text.

I'll input the following script, which will display two titled tables that display the Words and Sentences study lists of the associated lesson:

<Markup>
    <h2>
        {Words}
    </h2>
    <table style="width:100%;">
        <tr>
            <th>$(Target)</th>
            <th>$(Host)</th>
        </tr>
        <for name="value" limit="$(Words.Count)">
            <tr>
                <td>$(Words[{value}].Target)</td>
                <td>$(Words[{value}].Host)</td>
            </tr>
        </for>
    </table>
    <p />
    <h2>
        {Sentences}
    </h2>
    <table style="width:100%;">
      <tr>
        <th>$(Target)</th>
        <th>$(Host)</th>
      </tr>
      <for name="value" limit="$(Sentences.Count)">
        <tr>
          <td>$(Sentences[{value}].Target)</td>
          <td>$(Sentences[{value}].Host)</td>
        </tr>
      </for>
    </table>
    <p />
</Markup>

I'll explain this a bit.

The items bracketed in "<" and ">" denote an "element" start tag. The items bracketed in "</" and ">" denote an element end tag. Stuff between the start and end tags are the content of an element, which can be other nested elements or text. The items bracketed in "<" and "/>" denote a self-closing element that stands alone. Otherwise a start element must always be matched with a closing element for proper nesting. The name after the "<" or "</" is the element name. Optional "(name)=(value)" pairs denote additional attributes for the element. All of these element and attribute names will be given and explained in the markup template reference help page. Note that I use indentation to help make the hierarchy of elements clear. It is not actually required.

The markup text consists of a single "<Markup>...</Markup>" element. A requirement of XML is that there can only be one top-level element. The contents of the Markup element consist of some HTML elements, some special substitution text and tokens, and some special extension elements.

However, note that if your markup template is for generating audio files or for using as an automated study script, the outer-most element will be a "<generate>...</generate>" element. Note that the element and attribute names are not case-dependent.

Text marked by "{" and "}" constitute a string substitution. The text inside the braces is written in the teacher's host language, but could be replaced by a translation when the markup is rendered for a user with a different host language. These string can be pre-translated in the string list associated with the markup template. Even if you won't be supporting multiple host languages yourself, this would make it easier for others to add translations later. The substitution could also be a reference to a variable named in an enclosing element attribute, such as is the case for an iteration index, which we will look at shortly.

Note the first occurance of a string substitution in the first h2 element, used as a title for the table of words following it.

Text marked by a "$(" and ")" denote a substitution token. The contents refer to some named field expression of the content or lesson referencing the markup template, or the current user profile. Note, for example, the "$(Target)" token. It will be replaced by the name of the target language in the user profile. Note the "$(Words.Count)" token in the "limit" attribute of the first "for" element. This token will be replaced by the number of study items in the "Words" study list.

The token expression can also use "[" and "]" to do subscripting, such as for the case of referncing study list items. For example, a "$(Words[0].Target)" token would be replaced by a the first study list item's target language item. From our example above, "$(Words[{value}].Target)", note the use of a variable substitution for the "value" variable named in the "name="value"" attribute of the "for" element, described next.

The "for" element is an example of a flow control element. It will iterate based on its attribute values, basically rendering the markup inside it for each iteration. In this case, it iterates over the study items in a study list, outputting a table row for each iteration. It defines a temporary variable named in its "name="value"" attribute, which can be referenced in its content by a "{value}" string substitution, even inside a substitution token, as we saw above.

Note that this markup could be much simpler using the "insert" element, which would render an entire content item as a substitution for itself. It's attributes provide some control over the format. However, I wanted to show an example with substitution at a lower level.

Please see the reference documentation linked above for in-depth descriptions of the markup language, and the Example Course for examples of different markup templates, including page layout, audio generation, and automated study.

After inputting the text, I'll click "Save". Note that if I made a mistake, such as forgetting a closing element, I'd get an error message referring to the line.

The "Markup" fieldset displayed on the markup text edit page will render the markup for your testing purposes. However, note that it can't actually reference content yet, so it's more for previewing surrounding text and such.

The "String" fieldset lists the strings list. We'll look at this next.

Markup Strings

A markup template can store a strings list, which is a set of pre-translated versions of the string substitutions described previously. This mechanism is for the case where your markup template might be used for multiple host languages. If this is not the case, you don't need to create a strings list or use the string substitution tokens.

To create or manage the strings list, click the "Edit markup strings" button link at the bottom of the markup main page, or in the "Markup Strings" fieldset of the markup text page. This will bring up the Edit Markup Strings page, which is a little similar to the study list text edit page.

Edit markup strings page.

The list is initially empty. We can populate it manually by adding individual strings using the buttons provided, but we can simplify this by clicking the (Collect strings) button, which will pull out all the strings found in string substitutions in the current markup text, albeit in just the host language. Then we could add translations manually, editing individual strings or language groups of them, or we could start with automated transation via the (Add translations) button, and then fix any errors manually.

Edit markup strings page after collecting strings and translating them.

If we then click the "Back to markup" button link at the bottom, our markup main page looks like the following.

Finished markup page.

Referencing Markup Templates in Documents and Study Lists

For document or study list content items, if you go to the "Edit" page, you can set the "Select display" drop-down menu to "Edit document" to see a page where you can specify a markup template to use for laying out the content item.

Edit document page - no markup template used.

For no markup template, the "Select markup template" field is set to "(none)".

To select a markup template from your own collection from the "Teacher->Markups" page, click the "Select markup template" drop-down menu. The pop-up menu will list your markup templates. If you select one, the page will be re-displayed with a "Preview:" section, showing how the content item will be rendered with respect to the markup template.

Edit document page - markup template selected.

Note that the "Select markup template" drop-down menu also displays a "(local)" item. If selected, this informs the content item that a local markup template will be created and embedded in the content item. If "(local)" is selected, the page will be redisplayed showing controls for editing the markup template text just like for editing independent markup templates. A "Preview:" is also displayed, although until we fill in the markup text, it will be empty.

Edit document page - local markup template selected.

Then you can go in and fill in the markup text, clicking "Save" when complete.

However, note the added "Copy Markup Template" drop-down menu field. This control allows you to select one of your saved templates and copy it to the local template as a starting point.

Note for all these cases the "Select Markup Use" drop-down menu field, which controls how the markup template is rendered. The choices are: "Normal" for where the markup template takes over the content item display, "Top Notes" where the markup template is rendered above the normal content display, and "Bottom Notes" where the markup template is rendered below the content normal content display.

Using Markup Templates for Lesson, Group, Course, or Plan Pages

In creating a Lesson, Group, Course, or Plan, when filling in the profile page, you will find a "Markup Template" drop-down menu field. This field can be used to choose one of your markup templates to use to layout the main page for your Lesson, Group, Course, or Plan.

For example, in a lesson profile, if we referenced the "Lesson Summary" markup template from the previous sections, our main page would display the summary on the main page for the lesson.

Using Markup Templates for Generating Audio or Automated Study

Note that if your markup template is for generating audio or automated study, you will be typically be using the "generate" element as the outer-most element instead of "markup" in your markup text script, though it could be embedded inside a "markup" element as well.

Naturally, the element content inside the "generate" element will be somewhat different than for a displayed layout. The following help page describes the available elements:

Generate/Automated Markup Reference

Generating Audio Media Items from a Markup Template

For generating audio media items, there is a "Generate" page for the media item, accessible via the "Generate media" button link.

Audio media item generate page.

The "Select markup template" field lets you select the markup template to use. If set to "Don't use a template, use raw source text", a markup template will not be used. Instead, the items from the referenced study lists will be rendered in order, with a delay between them specified by the "Default pause between items (seconds)" field.

If the "Select markup template" field is set to one of your markup templates, the page will be redisplayed showing the markup text, allowing you to edit it. It will also show something of a textual preview of what will be spoken.

If the "Select markup template" field is set to "(local)", a local markup template will be created in the content item and the page will be redisplayed showing the markup text, allowing you to edit it, and a preview, much like as it was for the textual content items edit page.

The "Select default voice" field lets you select the voice names for different languages and voices to be associated with named items, for the cases where pre-recorded audio is not present and speech synthesis is used. Note, however, that JTLanguage might only have one voice per language, depending on the speech synthesis languages installed on the JTLanguage server. If the language is not installed, Google Speech will be used, which only supports one voice per language. Note that the JTLanguage server has three English voices, an American male and female, and a British female.

The "Generate" button will run the process of generating the audio file.

Automated Media Items

Automated media content items use the content type of "Automated". Similar to generating audio media items, there is an "Edit" page for the automated media item, accessible via the "Edit automated template" button link.

Edit automated template page.

This page is used pretty much just like the generate audio edit page described previously, so please refer to that description.

Automated Study Items

If there is no automated media items in a lesson, JTLanguage will insert a "Lesson Study" item in the lesson node in the course or plan tree control. By default, a markup template called "Default Automated Study" provided by the "JTLanguage" account is used for the automated lesson study. Note, however, that students can override this by setting up their own markup template and referencing it in their "Home->Settings" page.

Note that if you set up an automated media item in your lessons, then you have control over the markup template used for the automated study, and the "Lesson Study" item is not automatically appended to the tree control lesson node.

Importing and Exporting Markup Templates

The "Import" and "Export" button links at the bottom of the markup page or the markups list page let you import or export lesson markup templates. You can use this to backup or restore markup templates. It's probably a good idea to backup your markup templates.

Conclusion

We looked at the process for creating and filling in a markup template. Using this mechanism for page layout, audio generation, or automated study, you have unprecedented control over your lesson material's presentation.

Help menu Back