GM Toolkit eXchange Format Specification

The file format is not proprietary - merely a way to refer to an XML file formatted so that GM Toolkit can consume it. Described below are the supported tags and attributes that will be processed by GM Toolkit when an XML file with the extension ".gmx" is opened on your Android device.

 

All of the tags below must be contained between a "gmx-data" tag to be processed. The "gmx-data" tag is the root tag, of which there can only be one opening (<gmx-data>) and closing (</gmx-data>) pair.

Importing Systems

Tag: "system"

The system tag is the simplest of the tags with just two attributes. It does not need a closing tag.

 Attributes

  • "name": The name attribute is the name of the system as it is displayed in the list.
  • "key": The key is a human-friendly identifier. Up until now, those in GM Toolkit have been automatically generated as Globally Unique IDentifiers (GUIDs), though some will be displayed as product codes. When you want to associate something, for instance a template, with the system, reference it using the value specified here.

<system name="Sample System" key="sampleSystem" />

Note: If you are importing to a system you have already created on your device, you''ll need to make sure you reference the system with the same key attribute as the one already on your device, otherwise a new system will be created. You can find out what this key is by long-pressing the system and choosing Properties.

Importing Templates

Tag: "template"

A template is defined by both it''s own tag and must enclose the tags defining its fields. A template must be associated with a system or it cannot be used. The system-xref attribute must contain the same value as the "key" attribute of the system tag specified elsewhere in the GMX file (or match a pre-existing key value that is currently stored on your Android device).

Attributes

  • "name": The name of the template that is displayed in the tab bar after choosing a system.
  • "key": The key is a human-friendly identifier, usually a GUID or similar unique string of characters. When you want to specify an entry will use a template, make sure the entry uses this key.
  • "system-xref": This value identifies the system a template will be associated with. It must match a the key property of a system already created in GM Toolkit or one that has been specified in the import document.

<template name="Sample Template" key="sampleSystemSampleTemplate" system-xref="sampleSystem">
    <attributes>
         <attribute name="Attribute 1" key="sampleSystemSampleTemplateAttribute1" data-type="text" sortValue="0" />
         <attribute name="Attribute 2" key="sampleSystemSampleTemplateAttribute2" data-type="numeric" sortValue="1" />
         <attribute name="Attribute 3" key="sampleSystemSampleTemplateAttribute3" data-type="link" sortValue="2" />
    </attributes>
</template>

Note: If you are importing to a template that has already been created on your device, you''ll need to reference the template by it''s unique key. You can find that key by choosing it from the tabs along the top of the entry listing, then tapping the menu, and choosing Properties.

Defining Fields
Tag: "attributes"

A template, in order to define the fields a template provides, you must provide one or more "attribute" tags. If you do not specify any fields, the template may still be imported, but cannot store any data. You should have at least one fields (attribute tag) per template and all attribute tags should be contained between an open and closing "attributes" tags.

Attributes
  • "name": The name of the field (such as "Race", "Level", or "Class").
  • "key": A unique identifier of the attribute. This is used by entry data to determine where to set values.
  • "data-type": This is the type of information stored by the field. By default, it will be set to "text". Valid values are: "text", "numeric", "linked".
  • "sort-value": This is a numeric value indicating the ordering of the fields. If all set to the same value (i.e. zero), the fields will be sorted alphabetically.

Importing Entries

Tag: "entry"

An entry, like a template, is defined by both it''s own tag and must enclose the tags defining its field values. An entry must be associated with a templateor it cannot be used. The template-xref attribute must contain the same value as the "key" attribute of the template tag specified elsewhere in the GMX file (or match a pre-existing key value that is currently stored on your Android device).

<entry name="Sample Entry" key="sampleSystemSampleTemplateSampleEntry" template-xref="sampleSystemSampleTemplate">
    <attributes>
         <attribute attribute-xref="sampleSystemSampleTemplateAttribute1" value="Example Value" />
         <attribute attribute-xref="sampleSystemSampleTemplateAttribute2" value="3" />
         <attribute attribute-xref="sampleSystemSampleTemplateAttribute3">
              <linked-entry entry-xref="sampleSystemSampleTemplateSampleEntry2" />
         </attribute>
<attribute attribute-xref="sampleSystemSampleTemplateAttribute4" value="Long text value. Use {CRLF} to signify a new line."/>
    </attributes>
</entry>

Defining Values
Tag: "attributes"

An entry, because it uses a template, may set the values of any one or more fields. Using the key of the field defined on the template data payload, you can set the value of a field for the entry. If the field is used to link to other entries, you can provide a list of other entries by the entry key ("entry-xref") and the links will be created as long as the entry either already exists in GM Toolkit or was previously processed from the GMX data.

Attributes
  • "attribute-xref": The unique identifier for the field specified by the template.
  • "value": The value of the field. This is not used for a linked field. Instead, the "attribute" tag will enclose (with an opening and closing tag) one or more "linked-entry" tags (see below). If you have a long entry and need to break it up into paragraphs, use "{CRLF}" in the text. This will be replaced on import with a single line break.

Note: To find out the reference key for any attribute so that it can have a value imported to it, long press the attribute name when viewing an entry and it will be displayed.

Defining Linked Entries
Tag: "linked-entry"

Each of these tags specifies the unique identifier for some other entry to link to the one being imported.

Attributes
  • "entry-xref": The unique identifier for the entry that will be linked to this attribute and entry set.

The GM Toolkit eXchange Format is the term we use to describe the custom XML layout for importing data into GM Toolkit. GM Toolkit eXchange (GMX) files can be modified with any text editor, such as Notepad, or an XML editor.