Content XML

The content.xmlfile is the starting point for development. It is the first thing that the mobile app accesses to begin self-configuration. Its primary purpose is to identify one or more “sub-apps” called content items to show for user selection after the app starts and to define the “home” entities to show on the home screen of a sub-app. A sub-app is a way to group multiple “apps” onto the start screen of your app. The XML file also provides information about any application servers, content provider programs, help files, etc.

Content Configuration

When building a Mobiliti app, decide how many sub-apps you want and where the content configuration file will reside — either on a web server or stored locally on the mobile device.  The content.xmlconfiguration file will specify that information for Mobiliti to use.  If a sup-app has specific settings to use for passing parameters to the content handler program, then “settings” can also be defined in the XML file to allow the user to store unique data attributes that will be sent to the handler at runtime.

Structure

The XML below shows the general structure of the content file and every element that it can contain. Each element, along with all of its attributes, is documented in the table below the examples:

<?xml version=”1.0″ encoding=”UTF-8″?> <content>

<contentItem >

<homeEntity />

<setting />

</contentItem>

</content>

The structure above has 2 major elements:

  • contentItem — a “sub-app”
  • homeEntity — a data entity  in the sub-app to begin a search or drill-down into its content model

Examples

<?xml version=”1.0″ encoding=”UTF-8″?> <content appServer=”http://mobiltal.appspot.com”&gt;

<contentItem title=”Geocaches” image=”gpx.png” type=”proxy” name=”com.mobiltal.geooh.ContentHandlerGPX” />

<contentItem title=”Waymarks” image=”loc.png” type=”proxy” name=”com.mobiltal.geooh.ContentHandlerLOC” />

<contentItem title=”Placemarks” image=”kml.png” type=”proxy” name=”com.mobiltal.geooh.ContentHandlerKML” />

</content>

Note: This app has 3 content item sub-apps each defined by a contentItem entry. Since the app is using a local content handler the “home” entities are files stored on the mobile device and hence no homeEntity definitions are needed. “Startup Screen”

<?xml version=”1.0″ encoding=”UTF-8″?> <content appServer=”http://mobiltal.appspot.com”&gt;

<contentItem title=”Classic Models Database” image=”mysql-logo.png” type=”database” name=”com.mobiltal.ContentHandlerClassicModels”>

<homeEntity name=’Employees’/>

<homeEntity name=’Customers’/>

<homeEntity name=’Offices’/>

<homeEntity name=’ProductLines’/>

</contentItem>

</content>

Note: This app has only one content item sub-app. Since the app is using a database content handler the “fundamental” database tables are defined with homeEntity entries. “Home Screen”

Content XML

Element Attribute Description Example
content appServer The URL of the application server where the Mobiliti server installation is located. It should end with the context you defined for your server code and the Mobiliti servlets. This is optional if the content handler is found on the mobile device. http://myServer.com/mobiliti
appWebsite The URL of a web site to show information about the application. This will show as a link in the Info screen of the mobile app. This is optional. http://myServer.com
appHelp The URL of web site to show help screens for using the application. This will show as a Help button in the Info screen of the mobile app. This is optional. http://myServer.com/help.html
appHeader The URL of HTML content (or HTML code itself) to show at the top of the first screen when the mobile app starts up. This can be used for any information you want to use to the user such as advertisements, tips, notes, etc. This is optional. http://myServer.com/topbanner.html
appFooter The URL of HTML content (or HTML code itself) to show at the bottom of the first screen when the mobile app starts up. This can be used for any information you want to use to the user such as advertisements, tips, notes, etc. This is optional. http://myServer.com/bottombanner.html
appColor The theme color for the app. This color will be used for the top and bottom bars in a gradient of the color. The value must be in hex format. This is optional. #505050
launcherColumns The number of columns to show in the grid view of content items to select when starting the app. The default is a single column. This is optional. 2
showPreferences A flag to indicate that this content item should display an icon button for opening the preferences dialog. Some apps will not need the user to change preferences so hiding it can reduce confusion. It must be either “true” or “false” (default is true). This is optional. false
contentItem title The title of the content item sub-app that will be displayed to the mobile user. My App Name
image The URL of an image so show for the user to select the content item. This may be an absolute URL for HTTP, FILE, or ASSET locations or just an image name. If the image name doesn’t contain an absolute URL, then Mobiliti will look for the image in an “images” directory relative to the content.xml file. myImage.png
type The type of content handler for this content item. It must be one of the following:

  • proxy
  • database

The default is proxy.

database
handler The fully qualified class name of the content handler to use for the content.  Although handlers are generally created on the server, instances can be created locally on the mobile device.  If a handler class was packaged onto the mobile device, content calls will first be run through the local instance.  Any handler API methods not overridden by the instance will then be forwarded to a server instance of the handler if an app server was specified in the content XML.  This flexibility allows apps to have content handlers that are either server-based, locally stored, or a hybrid where API calls are serviced by both local and server content handlers with the same name. com.myPackage.myClass
footer The URL of content to display at the bottom on the home screen of a content item. The content can be HTML or if the URL is prefixed with widget://, the class name resolved via the URL path will be instantiated with the resulting Android component positioned at the bottom of the screen. This is optional. http://myServer.com/myBanner.html
showLogon A flag to indicate that this sub-app should display a logon screen to obtain a userid and password from the user during start up and pass it on to the server for authentication. It must be either “true” or “false”. The default is false. This is optional. true
homeEntity name The name of this home entity.  The name corresponds to an XML schema that describes the meta-data for that entity. myEntity
image The URL of an image that will show on the left side of the home entity name. This may be an absolute URL for HTTP, FILE, or ASSET locations or just an image name. If the image name doesn’t contain an absolute URL, then Mobiliti will look for the image in an “images” directory relative to the content.xml file. myImage.png
setting name The internal name of a setting field. mySetting
label The external label of the setting field to display to the user. My Setting
type The type of field (see the section below on attribute types). text
length Length of the field contents. Input will be limited to this length. This is optional. 10
decimals The number of decimal places for a number field. This is optional. 2
editable A flag to indicate where the field is editable. It must be either “true” or “false”. The default is true. This is optional. true
required A flag to indicate where the field is required to have a value before saving the settings. It must be either “true” or “false”. The default is false.  This is optional. true
value An initial value specified for the setting which will be the default if the user chooses not to enter a value.  This is optional. my value

Content Schemas

Content schemas define the data model of an app and what the user sees on the mobile device. Building an app therefore is determined by how you decompose your application into component entities with their data attributes, related nodes, and business tasks. Using a UML or ERD tool can be valuable in diagraming your content model. Each discrete content entity will have a schema defined for it.

Structure

The diagram below shows the general structure of a schema file and every element that it can contain. Each element, along with all of its attributes, is documented in the table below the examples.

<?xml version=”1.0″ encoding=”UTF-8″?> <entity>

<permissions>

<permission />

</permissions>

<IDs>

<ID />

</IDs>

<searchAttributes>

<searchAttribute />

</searchAttributes>

<listAttributes>

<listAttribute />

</listAttributes>

<viewAttributes>

<viewAttribute />

</viewAttributes>

<nodes>

<node />

</nodes>

<tasks>

<task>

<taskAttribute />

</task>

</tasks>

<attributes>

<attribute />

</attributes>

</entity>

Examples

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

<searchAttributes>

<searchAttribute name=’CustomerName’ />

<searchAttribute name=’City’ />

<searchAttribute name=’State’ />

<searchAttribute name=’PostalCode’ />

<searchAttribute name=’Country’ />

<searchAttribute name=’CustomerNumber’ />

</searchAttributes>

. . .

</entity>

“Search Screen”

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

. . .

<listAttributes>

<listAttribute name=’CustomerName’ />

<listAttribute name=’Phone’ />

<listAttribute name=’Address’ />

</listAttributes>

. . .

</entity>

“List Screen”

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

. . .

<viewAttributes>

<viewAttribute name=’CustomerName’ />

<viewAttribute name=’ContactLastName’ />

<viewAttribute name=’ContactFirstName’ />

<viewAttribute name=’Phone’ />

<viewAttribute name=’AddressLine1′ />

<viewAttribute name=’AddressLine2′ />

<viewAttribute name=’City’ />

</viewAttributes>

. . .

</entity>

“View Screen”

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

. . .

<nodes>

<node name=’Orders’ />

<node name=’Payments’ />

</nodes>

. . .

</entity>

“Nodes Screen”

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

. . .

<tasks>

<task name=’com.mobiltal.ClassicModels.tasks.Send_overdue_notice’>

<taskAttribute name=’AddressLine1′ />

<taskAttribute name=’AddressLine2′ />

<taskAttribute name=’City’ />

<taskAttribute name=’State’ />

<taskAttribute name=’PostalCode’ />

</task

</tasks>

. . .

</entity>

“Task Screen”

To define the attribute characteristics for the above schema information, there must be an “attributes” definition in the schema.  For example:

<?xml version=’1.0′ encoding=’UTF-8′?> <entity name=’Customers’>

<IDs><ID name=’CustomerNumber’ /></IDs>

. . .

<attributes>

<attribute name=’CustomerName’ type=’Text’ length=’50’ required=’true’ label=”Name” />

<attribute name=’ContactLastName’ type=’Text’ length=’50’ required=’true’ />

<attribute name=’ContactFirstName’ type=’Text’ length=’50’ required=’true’ />

<attribute name=’Phone’ type=’Phone’ length=’50’ required=’true’ />

<attribute name=’AddressLine1′ type=’Text’ length=’50’ required=’true’ />

<attribute name=’AddressLine2′ type=’Text’ length=’50’ />

<attribute name=’City’ type=’Text’ length=’50’ required=’true’ />

<attribute name=’State’ type=’Text’ length=’50’ />

<attribute name=’PostalCode’ type=’Text’ length=’15’ />

<attribute name=’Country’ type=’Text’ length=’50’ required=’true’ />

<attribute name=’SalesRepEmployeeNumber’ type=’Textnumeric’ length=’11’ />

<attribute name=’CreditLimit’ type=’Currency’ length=’22’ />

<attribute name=’CustomerNumber’ type=’Textnumeric’ length=’11’ />

<attribute name=’Address’ type=’Address’ length=’50’ />

</attributes>

. . .

</entity>

Schema XML showTasksOnListA flag to indicate whether to show any tasks defined for an entity below the displayed list of the nodes for that entity. Instead of showing those tasks in the popup task list dialog, they will show as permanent buttons on the list of nodes shown. The value must be either “true” or “false”. The default is false. This is optional.true

Element Attribute Description Example
entity label The external label for the entity to display to the user. This is optional. Customer
image The URL of an image so show to the left of an entity displayed on a List screen. This may be an absolute URL for HTTP, FILE, or ASSET locations or just an image name. If the image name doesn’t contain an absolute URL, then Mobiliti will look for the image in an “images” directory relative to the content.xml file. This is optional. customer.png
useImageOnMap A flag to indicate that entity images will be used when displaying “points” on a Google map.  If there is no image defined or this value is false, a default map pin will be used. The default is true. This is optional. false
insertTask A task module to run when creating (inserting) records instead of the built-in “view” screen’s add function. This module must be a fully qualified class name from a parent entity which will be used to insert a new row. This is optional. com.mobiltal.myEntity.myInsertTask
clone This option will clone another entity schema. This provides an inheritance capability between schemas. Once a clone is defined any meta-data XML following it will add to the schema specification. The value must be the name of another entity schema to clone. This is optional. myEntityClone
permissions This is optional.
permission name The name of a CRUD permission for the entity. It must be one of the following:

  • create
  • read
  • update
  • delete
  • execute
update
value A flag to indicate whether the permission is on for the entity. It must be either “true” or “false”. The default is true for all permission types. false
Note: Schema permissions can also be dynamically determined by the server content handler by either overriding the “getSecurity()” method or one of the following: “createAllowed()”, “readAllowed()”, “updateAllowed()”, “deleteAllowed()”, or “executeAllowed()” methods.
IDs This is required.
ID name The name of a data attribute that is part of the unique identifier for a particular instance of the entity. For a database, this is a primary key identifier. customer_id
Note: The items listed here must also be included in the XML “attribute” element described later.
searchAttributes This is optional.
instructions A set of instructions to display at the bottom of the Search screen to give the user information on how to fill out the search form. This is optional. Please enter the customer name to search for.
showSearch A flag to indicate whether a search dialog is always shown even if search fields have been populated from a previous search. It must be either “true” or “false”. The default is false. This is optional. true
searchAttribute name The name of an entity’s data attribute used for searching and finding records. customer_name
Note: The items listed here must also be included in the XML “attribute” element described later.
listAttributes This is optional.
sortable A flag to indicate whether the list can be used for sorting the entity. It must be either “true” or “false”. The default is true. This is optional. true
rowLimit The number of records to retrieve from the content handler during a list request. The number of records could result in the screen to display “Get more records” if the total records exceed the limit. The default is 25. This is optional. 15
showImageHeader A flag to indicate that a column header for the entity image column on the far left was be visible. This header can be used to sort and filter the rows based on the image. This feature is valuable if there is a small number on entity images where it can make sense to filter individual groups of images. The default is false. This is optional. true
imageWidth The number of pixels to scale entity images to that will display on the left side of a list row. This can be used to force all images to be the same size or to rescale them for better display on the screen. This is optional. 64
listAttribute name The name of an entity’s data attribute used when displaying a list of records. This attribute will show up as one of the List screen’s “columns”. customer_name
Note: The items listed here must also be included in the XML “attribute” element described later.
viewAttributes This is optional.
viewAttribute name The name of an entity’s data attribute used for viewing a particular entity record. This attribute will show up as one of the View screen’s “fields”. customer_name
Note: The items listed here must also be included in the XML “attribute” element described later.
nodes This is optional.
sort A flag to indicate whether to sort the nodes when displaying them in a list on the screen list. If the value is false, the order of the nodes are determined by the order specified in the schema. The value must be either “true” or “false”. The default is false. This is optional. true
showTasksOnList A flag to indicate that task buttons will be shown below the list of nodes for an entity.  Instead of showing those task buttons in the task popup dialog displayed for an entity, they will show in the node list. This feature is valuable if you want to make tasks more visible and accessible to the user. The value must be either “true” or “false”. The default is false. This is optional. true
node name The name of an entity that is a child node of this entity. For a database, this is a foreign table related to this data entity. Nodes will be used to automatically build relationships between entities and allow a drill-down navigation capability. The framework uses ID attributes for each of the entities in a relationship to display instances of records in one entity related to the other. customer_invoice
link A list of matched pairs of “node:parent” IDs used to relate this node with the enclosing parent entity with the specified IDs. Multiple pairs are separated by commas “,” or spaces ” “, and the link names separated by a colon “:”. If no link is specified, then an attempt will be made to link the entities using matching ID names. This is optional. invCustomer_id : customer_id
image The URL of an image so show to the left of an entity displayed on a Node screen. This may be an absolute URL for HTTP, FILE, or ASSET locations or just an image name. If the image name doesn’t contain an absolute URL, then Mobiliti will look for the image in an “images” directory relative to the content.xml file. This is optional. customerInvoice.png
Note: The items listed here must also be included in other XML schema definitions.
tasks This is optional.
task name The fully qualified class name of the task. This task may run on the server or the mobile device depending on where the class is found. Mobiliti checks the mobile class packages first to see if the before trying to run the task on the server.If the name is prefixed with “intent://”, Mobiliti will run the task as an Android activity intent.  It will also pass a Message object and an Entity object in the intent’s ‘extra’ bundle using keys of ‘message’ and ‘entity’.  These objects will contain all message and selected entity data to be used by the intent.  On return from the activity, you should update these objects with any changes so Mobiliti can apply the updates internally. Be sure to update Message.returnCode with the appropriate Message.ReturnCode value to indicate whether the task completed successfully or had an error. com.mobiltal.tasks.Send_overdue_notice
title The title of the task that will be displayed to the mobile user. If no title is specified, then Mobiliti will try to derive one from the task class name. This is optional. Send Overdue Notice
showDialog A flag to indicate whether a task dialog should show when running the task. If a task doesn’t require any user input or confirmation to run the task, then there is no need to display a dialog. In that case the task will run immediately. The default is “true”. This is optional. false
instructions A set of instructions to display at the bottom of the Task screen to give the user information on how to perform the task. This is optional. Please enter overdue information.
taskAttributes This is optional.
taskAttribute name The name of an entity’s data attribute used when displaying a task dialog. This attribute will show up as one of the Task screen’s “fields”. overdue_amount
Note: The items listed here must also be included in the XML “attribute” element described later.
attributes showLabels A flag to indicate whether the view fields will display their labels on the screen for the entity. It must be either “true” or “false”. The default is true. This is optional. true
orientation An indicator how a view field’s label will be positioned in relation to the field itself. Specify “horizontal” to put the label on the same horizontal line to the left of the field. Specify “vertical” to position the label vertically about the field. The default is “vertical”. This is optional. horizontal
This is required.
attribute name The name of an entity’s data attribute. For database content, this name must match the column name in the entity’s database table. customer_name
label The external label for the entity to display to the user. If not found, Mobiliti will derive a label from the name. This is optional. Customer Name
type The data type for the attribute. This type controls what features Mobiliti will enable for the attribute. See the table below for a list of types. The default is “Text”. Integer
length Length of the field contents. Input will be limited to this length. This is optional. 10
decimals The number of decimal places for a number field. This is optional. 2
editable A flag to indicate where the field is editable. It must be either “true” or “false”. The default is true. This is optional. true
required A flag to indicate whether the field is required to have a value before saving a change. It must be either “true” or “false”. The default is false. This is optional. true
visible A flag to indicate whether the field is initially visible to the user. It must be either “true” or “false”. The default is true. This is optional. true
monitored A flag to indicate whether the field will be monitored for changes by the content handler program. If true, any changes to the field will cause the onFieldValueChange method of the program to be called. It will also trigger a call to onFieldFocusChange when the field loses or gains focus. The value must be either “true” or “false”. The default is false. This is optional. true
value An initial value specified for the setting which will be the default if the user chooses not to enter a value. This is optional. my value
choices A list of choice values for either a CHOICE, CHOICEIMAGE, or RANGE type. Values must be separated by tab characters. For CHOICEIMAGE, the values are URIs to the image. For RANGE, only one value should be supplied to specify the maximum for the range. This is optional. choice1 (tab) choice2 (tab) choice3
instructions A set of instructions for someone to use when changing or viewing the attribute. These instructions will be displayed below the attribute field on a screen. This is optional. “Please enter your phone number above”

Attribute types

Type Description
ADDRESS Street address
AUDIO Audio file (the value is a URI to the audio file)
BARCODE A widget to scan barcodes
BINARY Binary value of any data (not yet implemented)
BOOLEAN Checkbox indicating true or false values
CHOICE Drop down list of single selectable string values — the choices must be tab-delimited (or separated by a ‘|’ character) to indicate the separation of choices
CHOICEIMAGE Drop down list of single selectable images — the choices must be image URLs that are tab-delimited (or separated by a ‘|’ character) to indicate the separation of choices
CURRENCY Currency value (for the locale)
DATE Date widget
EMAIL Email address
FILE File location (not yet implemented)
HREF URL that will not show the value on screen. Note: an HREF attribute will not show up in a List screen until you long press the row to show a popup to open the referenced value in a browser;  on a View screen, the value will show as “Touch to view” instead to open the browser.
HTML HTML text
IMAGE Image (photo or graphic) 
INTEGER Single line of digit numbers with formatting (no decimals) that returns an integer value
LISTMULTIPLE Drop down list of multi selectable values
LOCATION Geo-coordinate in latitude/longitude format
LOOKUP Perform a mini-search to display a list of selectable values  — the choices must be attribute names that are tab-delimited (or separated by a ‘|’ character) to be used as search fields during the lookup process
NUMBER Single line of digit numbers with formatting (and optional decimals) that returns a number value
NUMERIC Single line of digit numbers with no formatting that returns an integer value
PASSWORD Password (value will be masked)
PHONE Phone number
PHOTO Camera widget to take photos
RANGE Slider type widget with a minimum and maximum value (currently, only a maximum is supported with the minimum starting at 0)
RATING Five star rating
SIGNATURE Displays a widget for entering handwritten signatures
TEXT Single line of alphanumeric text
TEXTAREA Five lines of alphanumeric text
TEXTNUMERIC Single line of digit numbers with no formatting that returns a numeric string value
TIME Time widget
TIMESTAMP Timestamp (includes date and time)
URL URL link
WGS84 Geo-coordinate in the WGS84 standard format

Schema Locations

Content schemas can be static XML files stored on a server or the mobile device… or built and retrieved dynamically from the content handler. Mobiliti will first check for a file with the name entityname.XML (entitynameis the name of a content entity). This file must be in a “/schemas” directory where your content.xml file was retrieved from (as specified by the contentURL in the Android manifest).

If no file exists, then Mobiliti will issue a remote method call, getSchema(entityname), to the content handler program. Your program must then return the XML schema when the method returns back to the mobile device.

Advertisements

%d bloggers like this: