Edit Lesson XML - The 'chunks' Element

Note: The content on these pages that describes the process of creating an XML file will soon be obsolete or, depending on your perspective, perhaps it already is. We've developed a tool that we're calling Lesson Creator which auto-generates the XML file based on your script. This is currently under development but is mostly finished. We use it here at the Language Collaborative and wouldn't dream of writing lesson XML files by hand. If you'd like to be a beta tester for this tool, we invite you to contact us so that we can provide you with a copy.

Overview

This page shows how to edit the chunks element of a lesson XML file.

By the way, this is perhaps the most complex page in our Creating Lessons series. We suggest that you approach it at a time when you are well rested and your mind is fresh. 

Before you begin you should do the steps on the preceding Creating Lessons pages. In particular, you'll need the following:

• You should understand how we define "chunk" (if not, read this).
• You should follow the instructions on the Create a Lesson Folder and XML File page.
• You should follow the instructions on the Edit Lesson XML - First Steps page.

Once you've done these steps your XML file will look something like this, though obviously your file's contents will be different:



In this example the chunks element contains only one chunk element. We'll edit this file so that there are multiple chunk elements - one for each chunk in your lesson.

For example, the lesson XML for a lesson with 10 chunks would look something like this:

You can create these elements by copying the existing chunk element in your file, then pasting it multiple times.

But before you do this you may need to edit the chunk element. In order to know whether any editing is needed and, if so, how to do the editing, you need to understand the logical structure of the lesson XML.


First, Understand the Logic

XML is inherantly logical. Every XML file tells, or at least should tell, a clear and logical story. Let's look at the story that the lesson XML has told us so far.

By now this much is obvious:

• The file describes a lesson.
• The lesson has a lessonName and a level.
• The lesson either isDualLanguage or it isn't.
• The language or languages used in the lesson are identified with their ISO 639-3 codes.

Also, as discussed on the Edit Lesson XML - First Steps page, the defaultTextDisplayType element tells us one of two things:

• The lesson displays ordinary target language text. This is indicated by putting "textTargetLanguage" into this element.
• The lesson displays phonetic target language text. This is indicated by putting "textTargetLanguagePhonetic" into this element.

We assume that you've already made this decision, and that your defaultDisplayType element displays the correct value.


The chunk Element's Children

Each of your chunk elements will contain two child elements:

• A fileNameRoot element.
• Either a textTargetLanguage element or a textTargetLanguagePhonetic element.

For example, like this:



Or this:



If the file's defaultTextDisplayType element contains "textTargetLanguage", then Language Mentor will expect each chunk element to have a textTargetLanguage element.

If the file's defaultTextDisplayType element contains "textTargetLanguagePhonetic", then Language Mentor will expect each chunk element to have a textTargetLanguagePhonetic element.

From a logical perspective this makes sense. If the app is going to display ordinary text, then we need to provide ordinary text for each chunk, which is what a textTargetLanguage element does. If it's going to display phonetic text then we need to provide phonetic text, which is what a textTargetLanguagePhonetic element does.


Okay, now that you understand the logic...

... here's what you'll do next:

• Ensure that you have a single chunk element that you can use as a template for all of the file's chunk elements. If you've been following along with our example you should be all set with regards to this step.
• Ensure that this chunk element has a fileNameRoot element, and either a textTargetLanguage element or a textTargetLanguagePhonetic element, as explained above.
• Copy the chunk element and paste it multiple times, so that you end up with one chunk element for each chunk in your lesson.
• Edit the fileNameRoot element in each chunk element.
• Edit the textTargetLanguage or textTargetLanguagePhonetic element in each chunk element.

For an example of what the end result will look like, go back and take another look at the ten chunk example above.


Editing the fileNameRoot Element

The simplest way to do this is to simply put two-digit or three-digit numerals, in sequence, into these elements.

For example, like this:

     01, 02, 03, etc.

... or this:

     001, 002, 003, etc.

The ten chunk example above uses this approach.

This is a good approach, and we recommend it, but you have other options. Let's examine what these "file name roots" do and how they work, then discuss your options.


How the fileNameRoot Element is Used

As its name suggests, the fileNameRoot element provides the "root" for file names that are associated with a chunk.

Specifically, Language Mentor looks at a chunk's fileNameRoot element when it want to know how its audio file or files are named.

Audio files are named by combining the file name root, an ISO 639-3 language code, and the ".mp3" file extension.

For example, the English audio file for a chunk with a file name root of "001" would have a file name of "001.eng.mp3". If this chunk also uses a Mandarin Chinese audio file it would be named "001.cmn.mp3".

File name roots perform another function - they determine the order in which a lesson's chunks are played. Language Mentor orders chunks alphabetically by their file name roots.

Note that this may be a different order than the order in which the chunk elements are arranged within the lesson XML file.

For example if a lesson has five chunks, and their file name roots are:

     001, 002, 003, 005, 004

Language Mentor will play the first three chunks in order, then the fifth, then the fourth.

Of course, it makes sense to arrange your chunk elements in the order in which they will be played. But we do this to make the order of the chunks clear to human readers of the file - Language Mentor doesn't pay any attention to this.

As long as you bear this principle in mind, you can give your chunks whatever file name roots you like. For example, you could use file name roots like this:

     a, b, c, d, e ...

Or this:

     001_hello, 002_hi_how_are_you, 003_i'm_great_and_you ...

In this example the numeric prefixes ensure that the chunks play in the correct order, while the words that follow describe the contents of the chunks' English audio. We don't particularly recommend this approach - we're just trying to give you a clear sense of your options.


Editing the textTargetLanguage Element Or textTargetLanguagePhonetic Element

This step is simple. If your lessons will show learners ordinary target language text, put it into your textTargetLanguage elements, as shown in the ten chunk example above. If your lessons will show learners phonetic target language text, put it into the textTargetLanguagePhonetic elements, like this:



Congratulations! Your lesson XML is now functionally complete. There are other elements that you can add, for example elements that specify a lesson's credits, but they are optional and we'll explain them later.


Questions?

If you have questions about the lesson creation process, please contact us on our Creating Lessons forum. We're here to help.


What's Next?

Next we'll explain how to create and edit your lesson's audio files.






.