Definition XML file

Sample XML file download
Download a sample dbdefinition.xml file

<definition>
Contains all other tags.

<defversion>
Indicates the version of the definition format to be used, only current option is 1.0
Example: <defversion>1.0</defversion>

<dbtitle>
Sets the title to be displayed in the application when a list of databases is displayed.
Example: <dbtitle>Cities of the World</dbtitle>

<searchtable>
Sets the main table to use in the supplied sqlite database
Example:
<searchtable>city</searchtable> where "city" is the title of the main table.

<searchablefields>
Details a complete list of all fields in the searchtable that can be searched through via the search text bar.
In the app UI these fields will appear as a list of titles followed by switches.

Example:
<searchablefields>
<field> (Define a field)
<name>title</name> (The name of the field, in this case "title")
<title>Title</title> (The title of the field to be shown in the UI, in this case "Title")
<value>1</value> (The initial value of the field, in this case search is switched on by default)
</field>
<field>
<name>country</name>
<title>Country</title>
<value>0</value> (Search is switched off by default, 1 = on, 0 = off)
</field>
<field>
<name>continent</name>
<title>Continent</title>
<value>0</value>
</field>
</searchablefields>

<selectorfields>
Details a complete list of all fields to be shown as selector fields (popup menus).
There can be overlap between the fields listed under searchablefields and selectorfields as these fields are often a data entry convenience.
Another possible use is in cases where there are a small, finite number of possible values for a particular field.

Example:
<selectorfields> <field> (Define a field)
<title>Continent</title> (The title of field to be shown in the UI, in this case "Continent")
<searchfield>continent</searchfield> (The field to search through for the chosen popup value, in this case "continent")
<conjunction>or</conjunction> (The conjunction to use for multiple values in this search field, either "and" or "or")
<option>Africa</option> (The list of predefined options available for this field)
<option>Asia</option>
<option>Australia</option>
<option>Europe</option>
<option>North America</option>
<option>South America</option>
</field>
<field> (Define a field, this time without predefined options. Instead pull options from a database table)
<title>Country</title> (The UI title)
<searchfield>country</searchfield> (The associated field to search)
<conjunction>or</conjunction> (The multi-value conjunction, in this case "or")
<table>country</table> (The table from which to pull values to fill the options for this popup)
<fieldname>title</fieldname> (The table field that contains the option values, in this case "title")
</field>
</selectorfields>

<retrievefields>
A list of fields that will required for displaying search results and individual search result entries.
Usually the fields that can be searched through, information to be displayed on the item screen, or any fields required to construct image urls.

Example:
<retrievefields>
<field>title</field> ("title" is shown in list view and item view)
<field>country</field> ("country" is shown in list view and item view)
<field>continent</field> ("continent" is shown in list view and item view)
<field>imageurl</field>("imageurl" us used to construct a url for an image shown under item view)
</retrievefields>

<listdefinition>
Lists the fields and images displayed in the app UI for each result entry. Every additional field will increase the height of a row accordingly.
Note: the items listed will appear in the order listed in the xml file
Note: listdefinition also supports the use of the <image> tag in a similar way to the <itemdefinition> tag below.

Example 1:
<listdefinition> <field>title</field> (Include the title field in every results list entry)
<field>country</field> (Include the country field in every results list entry)
</listdefinition>
</searchablefields>

Example 2:
<listdefinition>
<image>
<component>https://someserver.com/directorypath/img/</component>(start the url with the common pattern, a server and directory)
<component>field1</component> (the result from field1 is required to construct the url)
<component>/dir2/</component> (another path component)
<component>field2</component> (another field result required to construct the url)
<component>.jpg</component> (the final path component specifies the image file format)
<width>60</width> (the maximum defined width of the image in the table cell)
<height>44</height> (the maximum defined height of the image in the table cell)
</image>
<field>title</field> (show the value of the title field in the results list)
<field>type</field> (show the value of the type field in the results list)
</listdefinition>

<itemdefinition>
Lists the fields displayed in the app UI for each result entry. Every additional field will increase the height of a row accordingly.
Note: listdefinition also supports the use of the <image> tag in a similar way to the <itemdefinition> tag below.

Note: additonal component tags can be used inside the <image> tag if the url for each item follows a proscribed pattern.
Example:
<itemdefinition>
<image> (begin the image tag)
<component>imageurl</component> (the value of the imageurl field specifies the url to load the image from)
<width>350</width> (the maximum defined width of the image)
<height>350</height> (the maximum defined height of the image)
</image>
<field> (begin a field definition tag)
<name>title</name> (the name of the database table field to be used for the field value, must be present in <retrievefields>)
<title>Title</title> (the title of the field displayed in the UI)
</field>
<field>
<name>country</name>
<title>Country</title>
</field>
<field>
<name>continent</name>
<title>Continent</title>
</field>
</itemdefinition>

Building the sqlite database

Main table
The main table of the database is the table that is used to perform searches and must contain all data that will be displayed in the results list or the result item page.
At present HydraDB does not support table joins to keep the complexity of the application and dbdefinition.xml file somewhat simpler. Joins may be supported in some form in a future release.
All main table fields necessary for the results list or individual item view should be listed under <retrievefields>.

Option tables
Selector fields (popup lists) don't necessarily need to be populated by a hardcoded list of options. Instead, they may be populated by the contents of another database table.
The section above on the <selectorfields> tag shows that using the <table> tag and <fieldname> tag can let HydraDB fill a selector field with database-supplied options.

The dbdefinition package

The final package file is a zip compressed archive containing two files, a dbdefinition descriptor file and the actual database file.
The dbdefinition file should be named "dbdefinition.xml" while the database file should be titled "database.sqlite".
These two files must be included in a .zip archive placed in the application's Documents directory.