7 How to install eLML and start working with it?

To be able to create a lesson with eLML you will need to install a XML Editor that supports XML-Schema validating. In this example we use XMLSpy by Altova, one of the best known XML Editors for Windows. But there are other Editors for Windows, Macintosh, Linux etc. available. Just be sure that your XML Editor supports XSLT 2! You should check Google for more information or read some reviews about XML Editors in magazines. We appreciate any comments about using eLML with other XML Editors. Please use our forums to publish your comments.

After you have successfully installed your XML Editor (see chapter 7.2. for a XMLSpy installation guide!), you should get the latest eLML files (read the separate download manual on www.elml.ch). Now you will have a directory called “ELML_ROOT” on your computer. We continue with a short overview about what’s in that eLML folder:

• structure: The eLML XML-Schema XSD files, the “heart” of eLML!
• presentation: Here you will find the XSL files to generate HTML, FO…
• content: This is where the XML files belong. Contains a test lesson.
• logic: Still empty. Put your XSP files for database connections etc. here.
• manual: Documentation about eLML (what you are reading right now).
• config: All configuration files with specific information for your project belong here.
• tmp: Empty. Put your drafts and temporary files here.

7.1 The eLML folder structure and file hierarchy

7.1.1 Folder „structure“: XML-Schema

The structure folder could be called the “heart” of eLML, because here you will find all the XML-Schema XSD files for using eLML. In order to be part of the “eLML community” it is absolutely imperative that everyone is using the same XML-Schema. XML documents that confirm to the standard defined in the eLML XML-Schema will be able to share XSL, XSP etc. files. Please refer to the chapter 4. Description of eLML Structure for more information. In the “structure” folder you will find the following files:

• elml.xsd: This the main eLML XML-Schema XSD file.
• biblio_harvard.xsd: Bibliography elements according to the Harvard standard are defined here. You can create your own bibliography XSD file if you use other standards (see 4.4 Bibliography).
• metadata_elml.xsd: Metadata elements. You can use another set of metadata, e.g. a metadata standard (see eLML XML Schemas).

Since the eLML XML-Schema is used by many authors, it should be as static as possible. If you want to suggest changes or find errors have a look at the eLML Support Page on our eLML Website. The eLML team will try to correct these errors and put the new versions online. Please try to stick to the main elml.xsd and do not change it yourself. As soon as you start using your own modified version of eLML, it will not be a community project anymore.

7.1.2 Folder “presentation”: XSL, CSS and other layout files

• html folder: XSL files needed to convert your XML file to HTML
• fo folder: XSL files needed to convert XML to Formatting Objects (PDF, rtf).
• templates folder: Create your own templates. Includes CSS files, graphics.
• titles.xsl: Contains translations into different languages of important keywords like.

The “html” folder contains all the main XSL files to convert your lesson XML files (that were validated by the eLML XML-Schema) into plain HTML. The elml.xsl is the main file that should be used for transformations. It will transform all the elements defined in the XML-Schema into HTML, but it does not contain any layout tags. It uses different other files, defined in the /config/gitta/config_html.xsl file. The configuration file (config.xsd) contains important parameters and path names that should be adjusted before using eLML. Since the bibliography is interchangeable in the XML-Schema, the XSL files are as well. The biblio_hardvard.xsl file transforms all the elements defined by the biblio_harvard.xsd file. If you plan to use your own bibliography XSD file, then be sure to also create your own bibliography XSL file.

The “fo” folder contains all the XSL files for creating Formatting Objects (FO) out of your lessons, which then can be transformed to PDF or RTF. It is basically built up the same way as the “html” folder. It was created using the Apache FOP engine, but it should also work with other formatting object processors. Please post any comments about the use of eLML with other engines on our website or send us an email! Thank you.

For most of you the only folder of real interest is the “templates” folder. Create here your own layout folder and name it wisely. Use a short name (as the parameter $layout it is part of the URL at some places), do use lowercase, no special characters, only a-z and 0-9 if possible. In this folder you will put all the images and icons (in the according folders) needed for your layout, define how your HTML page looks in the elml.css and define the layout of your HTML page in the layout.xsl file. If you are not familiar with HTML, just use the plain “HTML” layout and adjust the CSS file without touching the layout.xsl file. Please refer to the chapter 7.4 Creating your own layout for more information about adapting eLML to your layout, both with or without knowledge of XSL.

7.1.3 Folder “content”: XML files with your lessons

In these language folders (named e.g. “de” or “en” for German or English) you have to create your lessons folder and name it after the lessons label. The XML file itself should also be named as the lesson label, followed by “.xml”. So if you create a lesson called “Learning eLML” then you would define a label for that lesson (e.g. “learnELML”, create a folder “learnELML” in the /content/en/ directory (if the lesson is in English) and start a new XML file called “learnELML.xml” in there.

Within your lesson folder you are basically free to choose the folder structure as you like. We recommend setting up folders like “images”, “data”, “video”, “audio” etc. to put your different files belonging to your lesson together. Please be sure to reference them correctly in the XML file using relative paths, starting at the place where the XML file is located.

7.1.4 Folder “logic”: XSP, Java, Database connections etc.

7.1.5 Folder “manual”: the eLML documentation

7.1.6 Folder “config”: Configuration files

7.1.7 Folder “tmp”: Temporary files

7.2 Installing eLML

XMLSpy by Altova (http://www.xmlspy.com/) is one of the most common XML Editors for Windows. Since we worked with XMLSpy, we would like to give you a short introduction on how to install eLML using XMLSpy. If you are using another XML Editor, please refer to the next chapter.

A note about XMLSpy 2005: The built-in XSLT Engine of Altova does not yet fully support XSLT 2. Therefore you will have to use the Microsoft XSLT Engine. To change this, open in XMLSpy the Options Window and switch to the XSLT Tab. There you can change the default XSLT engine.

1. Install XMLSpy (or any other XML Editor) on your computer and choose the correct XSLT engine (see above).
2. Get eLML (see download section on eLML Website - http://www.elml.ch)
3. Create a new project using the “New project” command in the “project” menu.
4. Set the preferences of your project using the “Set preferences” command in the “project” menu. Please note that the following paths have their root in the eLML folder that you created by unzipping the eLML.zip file. Set the parameters as follows:

1. Choose “Add External Folder to Project” and select your eLML folder.
2. Open the /config/yourprojectname/config.xsd file and adjust the parameters as described in the XML-Schema part of this documentation.
3. Open the /config/yourprojectname/config_html.xsl file as described in the XSL part of this documentation (see following chapter!).
4. Open the Test Lesson /content/en/TestLesson/TestLesson.xml
5. Click on the XSL button (or use the XSL menu) and you should get your first lesson in HTML using eLML!

Please note that if you enter the path to the XMLSchema in your project properties, XMLSpy will try to validate the config_html.xsl file. Either ignore this error when saving the config_html.xsl file or do not fill out the “Validation” part of the project properties. You can always assign XML-Schemas to a XML file “by hand” using the “DTD/Schema” menu or the interactive menu when creating an empty XML file.

If you are curious how to create your personal layout, jump to chapter 7.4.

7.2.1 Working with eLML and any other XML Editor

If you installed eLML on another operating system (OS) and/or on another XML Editor, please share your experiences in the eLML discussion board on your website www.elml.ch. Thanks.

7.2.2 Working with eLML and Cocoon

• Cocoon can automatically split up your lesson into different pages.
• Generate PDF's on the fly out of your XML files.
• You can generate JPG's or GIF's from SVG graphics on the fly.
• Access databases (e.g. for storing the glossary or bibliography)
• User management
• Content Management functions to facilitate authors the editing of lessons.

These are just some of the advantages using Cocoon (http://cocoon.apache.org/). There is no eLML-Cocoon tutorial available yet, but we plan to implement it. Just subscribe to our newsletter and you will be informed. For more information click on "lists" on our eLML website.

If you have many eLearning lessons created with eLML, it might also be necessary to share glossary and bibliography data in a database. This can also be accomplished with Cocoon. You would then create your lesson.xml file on the fly and replace the glossary and bibliography elements with content from the database.

7.3 Setting the XSL parameters correctly

• $contact: Webmasters email address. Used e.g. in the footer.
• $role: Either tutor or student. Tutors have a detailed view.
• $lang: Language abbreviation as described in ISO 639.
• $layout: Name of the layout used. Same as foldername in templates folder!
• $server: The main URL to your website. Starts with “http://”
• $pathRoot: The path to your eLML folder (including eLML).

The $contact parameter is used to generate the contact-link in the footer and for some error messages, where the user must have a possibility to contact the webmaster.

Authors and tutors will welcome the $role parameter, because when it is set to “tutor”, additional paragraphs, solutions and installation remarks for self assessments and metadata are visible in the final HTML document. If you want to produce your final HTML document for your students, then set this parameter to “student”. This parameter is activated when authors use the role attribute while writing. The attribute is available for certain paragraph types and e.g. for learning objectives.

The $lang parameter sets the correct language for the lesson. It is mainly used within the titles.xsl file, where the most important keywords (like glossary, bibliography, learning objectives etc.) are translated into German, English, French and Italian. Use the ISO 639 two-digit standard (de, en, fr, it etc.) to define your language. If you add more languages, please be sure to update the titles.xsl file. You are very welcome to submit your own translations of these keywords to the eLML server, so that others can use it. Check the chapter about the content folder for more info.

The $layout parameter should be set to the name of your layout. Please note that this name has to be identical with the foldername of your layout folder within the /presentation/templates/ directory. For naming and other issues, check the chapter 7.1.2 about the “presentation” folder. Icons for the “icon” attribute are also referenced using the $layout parameter. The path to these icons is set to:

/presentation/templates/$layout/icons/@icon.gif

(where @icon stands for the type of icon: important, remark, question etc.)

Like the $contact parameter $server is also used to generate a nice footer with a link to your website entry page. Therefore you should always include the “http://” to this parameter. It might also be used for referencing absolute paths.

To reference relative or absolute paths for images, multimedia objects etc. the parameter $rootPath is used. Enter here the path to your eLML directory. If you used our tutorial above for installing eLML, then just leave the path to “..” because the final HTML document is saved in the /tmp directory (so /tmp/.. brings you back to root). Otherwise just use the absolute path without the final slash (c: \bla).

7.4 Creating your own layout

1. No HTML and XSL knowledge: Adapt the CSS file to fulfil your needs.
2. No XSL knowledge: Use (X)HTML and CSS to get the perfect layout.
3. Expert: Dive down into the depths of XSL to get your personal eLML look.

If no are not a “techie” at all, just use eLML as it comes “out of the box”. We tried to avoid any nasty HTML tags that would make your life harder and offer you a basic and clean HTML and PDF output of your lessons. You might want to start with this and while getting more comfortable with eLML start learning CSS or HTML to adapt your layout. The nice thing about XML and XSL is that content and layout are totally separated. So if you created your lessons according to the eLML standard, you are able to change your layout within minutes without touching any content. This means that you could even hire some HTML-guru to design your layout and have your authors working on the content without interfering with each other at all.

Before continuing, please be sure that you copied the config folder as described in chapter 7.1.6. Then go to the templates folder and duplicate the “HTML” folder. Rename the folder to “yourprojectname” and be sure to edit both the parameter $layout and the XSL path in the following file:
/config/yourprojectname/config_html.xsl

Now you can start messing around with these files and still have a working copy of the main HTML layout as a backup.

7.4.1 Modify the layout using CSS

So how is this elml.css file built up? We used both element and class styles (but no ID styles). Element styles are used only for the most basic tags to define the style and size of the font and margins or border widths. Defining element styles should always be done with caution, because you might e.g. use tables as layout elements or as real tables. So defining the TD tag to a certain width and margin might have unwanted effects on your layout. Therefore most of the eLML elements are references using CSS classes.

All styles have a short comment, so please check the CSS file for more information. We tried to give meaningful names so that you should know which style is used where, without digging in the depths of the HTML file. We recommend using a web design software like Adobe GoLive (nice CSS interface!) or Macromedia Dreamweaver with a menu-driven interface to edit the CSS file. With these tools you will not even have to know much about CSS to give your layout a nice touch. Please note that some browser will only show CSS modification if you reload the CSS file itself and not only the HTML document!

7.4.2 Modify the layout using HTML

To start with your own layout, define an XHTML template page in your favorite web design tool (it should support XHTML) and use placeholders where the content, the footer and where the navigation should appear. Store images within the folder:
/presentation/templates/$layout/images/

When you are finished, convert your file to XHTML. This means that all tags must have closing tags. For example the <BR> tag would have to be written either <BR/> or <BR></BR> and nothing else would be accepted. This has to be done, because is XSL confirms to the XML standard, which only allows well formed documents.

Now lets have a look at the main layout template file. It is stored here:
/presentation/templates/$layout/layout.xsl

When you open this file for the first time, it looks like this:

1 <xsl:template name="LayoutBody">
2 <body>
3 <h1><xsl:value-of select="@title"/>h1>
4 <xsl:call-template name="navigation"/>
5 <xsl:apply-templates/>
6 <xsl:call-template name="footer"/>
7 </body>
8 </xsl:template>

The first statement on line 1 starts the definition of the template named “LayoutBody”. Do not edit this name, because else the main XSL file will not detect the layout BODY part and quit with an error. Line 2 is marks the beginning of the BODY tag of your HTML document. We did not use and BODY attributes because everything is defined in the CSS file.

On line 3 we use our first XSL expression: Within a H1 title tag there is a XSL expression that includes the title of the lesson. Use this expression wherever you want the title of your lesson to appear.

Both line 4 and 6 are XSL template calls to import the navigation (line 4) and the footer (line 6) into the HTML document. Note that the navigation is defined and an unordered list (UL) and can only be changed using the “navigation” class in the CSS file. If you don’t like unordered lists, you will have to change the XSL file (see next chapter). This is also valid for the footer part.

But we omitted the main part yet. The XSL apply templates statement on line 5 is where your XSL engine will put all the content of your lesson. Be sure to place this statement at the place where you want your content to appear. Please note that within the content adaptation of the HTML code cannot be done without basic knowledge of XSL (see next chapter). But since most of your design wishes can be realized with CSS, this should not be a problem.

A short note about images and other externally included files. Of course you can use the absolute path to your image files, but to be more flexible and to be able to transfer your files to other users, you should use variables for your paths. In the following explanation, we expect you to store all your images within the folder:
/presentation/templates/$layout/images/

Lets assume you want to include your logo at the beginning of your document. The corresponding HTML tag might look something like this (Please note the slash “/” at the end of the tag, right before the closing “>”! This is correct XHTML!):
<img src="pathtoyourfolder/images/logo.gif" />

HTML purists will argue that you need to put the HEIGHT and WIDTH attribute for faster loading and ALT attribute for better navigation (eg. in text-only browser). We agree, but for simplicity reasons we omitted these and other attributes in this example. Now lets look how this reference should be written correctly:
<img src="$pathRoot/presentation/templates/$layout/images/logo.gif" />

Using the two parameters $pathRoot (obviously for the path to the root folder of your eLML installation) and $layout (the name of your layout as defined in the config_html.xsl and used also as folder name within the templates folders) and using the path as written above, you have now a reference to your logo that is robust to both changes of the root folder location and to renaming of your layout. The disadvantage is of course that your web design software will not display these files anymore. So be sure to first complete your layout and then transfer it to your layout.xsl file.

7.4.3 Modify the layout using XSL

You are welcome to submit your own elml.xsl files to our server, if you think that maybe other people can benefit of it. If you find any bugs or errors, please use the bugtracker on the eLML website to submit them.

Previous "How to create Lessons with eLML"    |   Top   |    TOC    |   Next "References / Additional Resources"