Data Suitcases (MOJO)

A Journey Object (MOJO) or now known as Data Suitcase is an XML file stored on the Blinkmobile server. When a MOJO has been transferred to a mobile device it is a Mobile Journey object (MoJO). XSLT code interactions check currency of any required MoJOs It then processes interactions without going beyond the users mobile device. This essentially caches all the required data on the mobile device increasing speed and decreasing data transmission delays.

Data Suitcase General Overview

A Data Suitcase (or Mojo) is simply an XML document. Sometimes, for advanced situations, you may choose to use JSON. For now we'll focus on XML.

Currently, the BMP provides two main automated methods for using Data Suitcase data - to pre populate a single List within a Form, or to pre-populate an entire Blink Form.

The basic steps to using Data Suitcases are:

1. Generate your XML file (manually, or through a webservice).
2. Setup a trigger point in your Blink App to download the XML and store it as a Data Suitcase.
3. Configure your List or Form to use the Data Suitcase as a source.

Questions to ask when designing your Data Suitcase:

1. How frequently will this data change - daily, weekly, monthly?
2. How should updates be sent to users? Automatically or manually?

Data Suitcase Currency

Basic-Mode Devices
 Basic-mode devices are not assumed to have sufficient device-side storage. When these devices access an XSLT interaction, only the result of the XSLT is transmitted to the device. As the XSLT is performed entirely on our server, the very latest version of the Data Suitcases is always available.

Advanced-Mode Devices
 Advanced-Mode Devices (and native applications) typically have mechanisms available to store data on the device.
Our platform is designed to allow these devices to function with intermittent or absent network connections.

XML Caveats
Typical Data Suitcases will contain information arranged within a well-formed pre-validated XML string. Here are some tips to avoid unnecessary headaches when working with XML:

• XML (element) names consist of letters, numbers, underscores (_) and colons ( : ), and should never start with a number. Colons are used to represent namespaces (like the “xsl” namespace we use with XSL), so it is a good idea to avoid colons too.
• Ampersands & have special meaning at all times in XML documents, so if you wish to include them anywhere in your XML document then you need to encode them as HTML entities (&entityname;). *Angle brackets <> have special meaning at all times in XML documents, so if you wish to include them in your content then you need to encode them as HTML entities.
• Single-quotes ‘ and double-quotes “ have special meaning depending on where they are used (ie enclosing attribute values). You need to be careful, and you may need to encode them as HTML entities.
• XML (and therefore XSL and XHTML) never contains tags that are left open. Always remember to close every single tag that you open (<p>text</p>), or use self-closing tags (<br />).
• You may have to resort to CDATA Sections in order to store unstructured or poorly-formed HTML within an XML document.

Partitioning XML Data

XSLT marries a single XML document with a single XSL document. For the duration of the execution of the XSLT interaction, it is only able to take into account a single XML document and a single XSL document. In practical terms, all information that needs to be queried (via XPath) and displayed in the same Interaction result needs to co-exist in the same XML document.

Taken in reverse, if 2 pieces of information never need to be displayed / queried together, then they do not need to occupy the same XML document. For optimal device performance, we recommend partitioning data into separate XML documents where possible. You can use record IDs to facilitate navigating from one XML document to the relevant section in the next. 

For more technical documentation for Data Suitcases for BIC v2:

Go to https://github.com/blinkmobile/bic-v2/blob/develop/docs/datasuitcases.md

Server-hosted Data Suitcases

This type of Data Suitcase is stored in the BMP database as it is considered ancillary answerSpace configuration material. 
Server-Hosted Data Suitcases are uniquely addressable by combination of answerspace and suitcase name.

Security
It is not currently our design to go to any lengths to protect this Data Suitcase, any device is able to request this data.

Further, this data is provided via an unprotected web service to our advanced-mode client, therefore any person with knowledge of the URL, answerSpace and Suitcase name can access it.

mADL Commands include

• setJourneyObject
• getJourneyObject
• deleteJourneyObject

These commands allow mADL Interactions to perform operations on Server-Hosted Data Suitcases. All commands will return a Boolean “false” if they fail. “set...” and “delete...” will return a Boolean “true” upon success, while “get...” will return the requested Suitcase contents if successfully located.

Usage Notes

• The most common and supported use case is for the $data string to contain well-formed (pre-validated) XML, to serve as input data for a separate XSLT Interaction.
• If you are not planning to use XSLT Interactions, you may still find these commands useful for a form of persistent (insecure) storage.
• One answerspace uses these mechanisms to cache the results of fetches, so that content requests do not trigger our server to contact the customer’s website too often (or at all). You could use one Suitcase to store the time of the last fetch, and have Interactions only trigger a fresh fetch once per day, for example.

Personal Data Suitcases

You can populate a personal data suitcase from an interaction see Code example section.

active-forms Data Suitcases

The Active Forms List (formerly known as the Pending Queue) is a special-purpose Interaction or view that displays any form records that have not yet been submitted to the server. 

See Active Forms List section for more information.

Stars Data Suitcases

They use a combination of a stored XML file and Blink-starrable style sheet 

To create a "Starred" list, article or form, you must add the Blink-starrable style sheet to your interaction. 

This can be achieved by adding it to your code either as part of of some HTML or in the second parameter of your fetch rows command.

The Blink-starrable style sheet allows you to add a link reference of your interaction result to a stored XML document held locally.

When an item is "Starred" a record is entered into the XML document. Besides the primary reference you can also add additional variables for storage and use in your favourites page. This page usually will display all the "Starred" items within the answerspace for easy retrieval and if required "de-Starring".

$t->rows("|<h2><a href=\"/{URL}\" title=\"{TITLE}\">~*<div class=\"field-item odd\">{TEASER}</div>~*<img src=\"{THUMB}\" |U",
"My output and containers built from the body in the code builder....
<span class=\"blink-starrable\"
data-type=\"OBJECTITEM\"
data-DATYPE=\"PLACES\"
data-id=\"{URL}\"
data-NAME=\"{TITLE}\"
data-URL=\"../visitor_details/?\"
data-ARGS0=\"{URL}\"
data-ARGS1=\"{TITLE}\"
data-ARGS2=\"{IMAGE}\"
</span>");

Blink-starrable style sheet

The Blink-starrable style sheet consists of several parameters.

For more information on "Starring" download the Data Suitcases - Step by Step.pdf

mADL Commands.

These mADL commands can help you setting stars on or off or clearing all starred items in your data suitcase.

There are tree types, "On", "Off", "Clear".

$t->addControlMessage(array(
'startype' => 'session',
'staron' => array(1,2,3,4),
));
return $t->result;


$t->addControlMessage(array(
'startype' => 'session',
'staroff' => array(5,6),
));
return $t->result;


$t->addControlMessage(array(
'startype' => 'session',
'clearstars' => ''
));
return $t->result;

Data Suitcases and mADL

Data Suitcases can be created, modified and deleted using mADL Functions. They include

• $t->addControlMessage()
• $t->setjourneyobject( )
• $t->getjourneyobject( )
• $t->DeleteJourneyObject( )
• $t->listJourneyObjects( )

Data Suitcases and Javascript

 @returns {jQueryPromise}

 @returns {jQueryPromise}

Data Suitcases Populating A BlinkForm

As most uses of this involve XPath queries under your control, the precise tag used for the root element is not important, although valid XML specifies exactly 1 root element. This format is used for network transmission, and data suitcase (MoJO) storage.

Glossary #

• field type: BlinkForms2 types are not the same as the HTML Input Type.
• field name: unique identifier (within the form) for the field, matches a DB column, restricted characters (\w+)
• field label: not necessarily the same as the name, fewer restrictions on characters
• form object name: unique identifier (within an answerSpace) for the form, matches a DB table, restricted characters (\w+).
• tuple: Database-speak for a particular row / record in a DB table

Example 1

Here are 2 tuples (records) for the formObject1Name form. 
Note that the 2nd tuple omits several fields, simulating non-mandatory fields or an incomplete state. 
Values that contain multiple values, such as “multi” select fields and “checkboxes” fields, should list the values in EOL-delimited plain-text.

<root>
	<formObject1Name>
		<fieldName1>value</fieldName1>
		<fieldName2>value</fieldName2>
		<fieldName3>value</fieldName3>
		<fieldName4> 
<!-- sub_form type -->
	<formObject2Name>
		<fieldName1>value</fieldName1>
		<fieldName2>value</fieldName2>
	</formObject2Name>
	<formObject2Name>
		<fieldName1>value</fieldName1>
		<fieldName2>value</fieldName2>
	</formObject2Name>
		</fieldName4>
		<fieldName5> 
<!-- multi(-select) or checkboxes type -->
valueA
valueB
</fieldName5>
	</formObject1Name>
	<formObject1Name>
		<fieldName3>value</fieldName3>
		<fieldName4> 
<!-- sub_form type -->
	<formObject2Name>
		<fieldName2>value</fieldName2>
	</formObject2Name>
		</fieldName4>
	</formObject1Name>
</root>

Example 2

Here are some examples including correct field formats.

<yourtext>
Sample TextBlink Forms is now saving your Blink Form Object and generating
 Blink Forms Definitions which should allow you to view
 and use the form once this process has completed successfully.</yourtextarea>
<yourselectbox>2</yourselectbox>
<yourdate>2012-07-27T00:00:00+10:00</yourdate>
<yourtime>12:38:55+10:00</yourtime>
<yourdatetime>2012-10-30T00:09:30+10:00</yourdatetime>
<yourradio>Option A</yourradio>
<yourlocation>{"altitude":null,"latitude":-33.868901,"altitudeAccuracy"
:null,"heading":null,"accuracy":25000,"longitude":151.207091,"speed":null}</yourlocation>
<yourmulti>Option A
Option D</yourmulti>
<yourimage>data:image/png;base64,YourBase 64 encoded string</yourimage>
<yoursignature>data:image/png;base64,Your Base 64 encoded string
</yoursignature>

You can download the sample XML code and an answerspace example in the attachments section below.

JSON 

This format is used for local storage in the submission queue, and loosely describes the non-JSON data structure used in the HTTP POST transaction for form submissions.

Note that this has been formatted with additional non-compliant white-space for educational purposes. We recommend working with JSON as it is generated by software, which will not contain this additional white-space.

Example 3

Here is 1 tuples (records) for the formObject1Name form.

{
“fieldName1”: “value”,
“fieldName2”: “value”,
“fieldName3”: “value”,
“fieldName4”:
[
{ // field values for a new subForm tuple
“fieldName1”: “value”
“fieldName2”: “value”
},
{
“fieldName1”: “value”
“fieldName2”: “value”
},
“subTuple3” // primary key for existing subForm tuple
],
“fieldName5”:
[ // multi(-select) or checkboxes type
“value”,
“value”,
“value”
]
}