XML files are made up of one or more elements. Each element may itself contain more elements in a nested hierarchy (these are called child elements), and it may contain plain text (called the element content). Each element may also include attributes that inform or alter the element.
A Gloria hymnbook table of contents XML file is made up of a single “hymnbook” element, which in turn contains one or more “title” elements plus a series of “hymn” elements.
Start by adding a hymnbook element. From the Insert menu select Element and click After. On the left hand side (the element name) type:
hymnbook
Leave blank the right hand side (the element value).
With the hymnbook element selected, add some attributes. From the Insert menu select Attribute and click Child. On the left (the attribute name) type:
log
And on the right (the attribute value) type:
true
Add another attribute (Insert / Attribute / After). Set the attribute name to “code” and the value to “Test” (without the quotes). Add another attribute named “maxdemo” with value “100”. And add a final attribute named “version” with value “1”. The document so far will look like this:
Hymnbook Attributes
This is what you have now: a Gloria table of contents XML file with a single hymnbook element. That element has four attributes that define its behaviour. This is what those attributes mean:
log attribute
The “log” attribute is optional. If you include it and set its value to “true”, Gloria will generate a log file with any errors or warnings encountered while importing the hymnbook. The log file is a text file with a series of error messages including the line number in the XML file where the error was encountered. It’s helpful to have a record of errors, especially at the beginning, to troubleshoot problems with a new hymnbook. The log file is stored on the USB memory stick in the same folder as the hymnbook XML file. New entries are added to the end of the log file if the same hymnbook is imported multiple times. The log file won’t be created (or extended) If there are no errors at all while importing the hymnbook.
Any value for the log attribute other than “true” is interpreted as false. A false log attribute, or no log attribute at all, means Gloria will not generate a log file while importing the hymnbook.
The log attribute is only allowed in the hymnbook element, and for maximum benefit should be the first attribute listed.
code attribute
The “code” attribute is required. If you don’t include it Gloria will not import the hymnbook. This is the identification code that represents the hymnbook internally in Gloria, and uniquely differentiates it from other hymnbooks. It’s value must be three or four characters. Upper or lower case ASCII letters (unaccented) and digits are accepted. The code is case sensitive: “Test”, “test” and “TEST” are all different. Typically the code is made up of the initials of the hymnbook. For example, Celebremos Su Gloria is “CSG”. The Celebration Hymnal is “TCH”. Himnos de Fe y Alabanza is “HFyA”.
If you’re creating a collection of songs for your own personal use, you can more or less make up any code you want. If you intend to distribute the hymnbook (say, to a denomination of churches), contact Gloria Music to make sure the code you’ve chosen won’t conflict with another hymnbook. If a user installs a hymnbook with the same code as a hymnbook already on their Gloria, the new hymnbook will overwrite the existing hymnbook.
Hymns within a hymnbook may reference hymns in another hymnbook (more on that later). They use the hymnbook code as part of that reference.
The code attribute is only allowed in the hymnbook element.
maxdemo attribute
The “maxdemo” attribute is optional. Its value is a number in the range 1 to 999. If you don’t include it Gloria will use a default value of 999. This number is the highest-numbered hymn Gloria will play while in Demo mode. In this example the value is set to 100. That means that in Demo mode Gloria will go back to the beginning of the hymnbook after playing hymn #100. If there is no hymn #100 Gloria will only demo hymns below 100. Setting the value to 999 (or using the default) means every hymn in the hymnbook will be included in Demo mode.
It’s useful to set maxdemo to the last official number in the hymnbook and then use higher numbers for utility files such as tuning sequences or musical bridges. That way odd files and musical snippets are not included in the demo.
The maxdemo attribute is only allowed in the hymnbook element.
version attribute
The “version” attribute is optional. Its value is a number in the range 0 to 9999. If you don’t include it Gloria will use a default value of 0 (no version). Start with a version number of 1 and increase the value every time you redistribute the hymnbook with modifications. The hymnbook version appears on the Gloria System Info screen in the setup menu. It’s a useful way for the user to see if they have the latest update for that hymnbook. If you don’t use the version number (or forget to increase it) it may be hard for users to tell if they have the correct version of the hymnbook.
The version attribute is only allowed in the hymnbook element.