Datafree Max Developer Reference Guide

This document is provided as a reference for Datafree Max Application developers.

If you are not familiar with Datafree Max Application development, please refer to the Datafree Max - Getting Started Guide which explains the development process and provides example code to get you started.

Sample code can be found here: https://github.com/binuadmin/biNu-sample-1

Index

1. Platform Architecture        4

2. biNu Component Overview        5

Application configuration file - <app> element        5

Application Example Screens        7

Document configuration file - <doc> element        8

Document Example Screens        11

3. Element Descriptions        12

<app>        12

<drawer>        13

<bottom_nav>        13

<menu>        13

<share>        14

<tabs>        15

<style>        15

<doc>        15

<list>        17

<img>        19

<md>        20

<bookmark>        20

<webview>        22

<item>        24

<filter>        25

<option>        25

<menuitem>        26

<msg>        27

4. Markdown and Style Reference        28

Markdown Coding Reference        29

biNu Default Stylesheet        30

Supported Style Properties        32

Markdown Styles - Example Code        33

Supported Fonts        34

Supported Colors        34

5. Design Considerations        35

Using the App Context        36

Handling Different Screen Sizes        37

HTML Support        37

Forms        38

Rules when coding forms        38

Caching        39

Cache Busters        39

Free Data        39

Using filters        40

Registering a new biNu Application        43

Onboarding Screens        43

1. Platform Architecture

The Datafree Max Publishing Platform is comprised of 3 major components:

• The biNu client App which is issued to you as a custom branded app to be published by the developer with their own certificate. The App is not modified by the developer directly; all configuration, layout and content information is supplied from the server-side application and rendered in the client App. biNu development is the creation of the server-side application. biNu supports Android 4.1 and above.

• The Datafree Max Optimisation Server provides optimised content to the smartphone App to reduce bandwidth. The server is developed and managed by biNu and is not configured by the developer .

• The server-side biNu Application which consists of XML files to define the configuration and layout of the client App and provide content to be rendered in the App. This is the only component that needs to be developed to create a biNu Application.

2. biNu Component Overview

A Datafree MAX  Application is built from components which define the menus, style and content rendered in the biNu client App. Components are built from XML files.

Each component is listed in this section with an example however full details for each entity are available in the Element Descriptions section of this document.

Application configuration file - <app> element

This file is the homepage URL specified within the generated client App. There can only be one Application configuration for the biNu Application.

e.g. http://yourhost/yourbinuapplication/app.xml

The Application configuration file is loaded when the App launches and is not changed or reloaded until the App is quit and restarted. It specifies the title, style and main navigation components which are:

• The Navigation Drawer at the top left of the screen - defines by the <drawer> element
• The Menu at the top right of the screen - defined by the <menu> element

Application Configuration Example

This <app> code loads 3 menu items into the Navigation Drawer, 3 menu items into the Menu and a stylesheet.

Notes:

There can be only one <drawer> and one <menu> entity.

If the share menu item is present there must be a <share> element in the code.

Each Menu Item references a Document configuration file <doc> which will be loaded into the page when the item is selected.

Menu Item 2 will be loaded on launch as it has the attribute default set to true.

Application Example Screens 

Example Title

Document configuration file - <doc> element

The Document configuration file specifies what is displayed on the page. It can contain either Navigation or Content type elements but not both:

        Navigation        - either a <list> element  OR a <tabs> element

        Content        - a combination of  <webview>,<md>, <img> elements

                - optionally, one <share> element

Each child element is introduced in the following examples, for a full description refer to the Element Description section later in this document.

If the <doc> file is on the same domain as the <app> file it can be referenced using a relative URL, otherwise it must be a fully qualified path. These examples are static but in practice many <doc> files will be generated dynamically as they would typically extract data from various data sources and wrap it for biNu use.

Document List Example

This <list> example displays a list of 2 items, each item has an image and a line of text specified using Markdown

Document Tab Example

This <tabs> example displays a row of 3 tabs at the top of the page. Each tab is defined by a menuitem which has the same behaviour as a menuitem in the Navigation Drawer.

Document Markdown Example

This <md> example displays 2 blocks of Markdown text on the page.

Note: This Markdown contains special characters so it should be enclosed in CDATA tags to avoid issues when the XML is parsed. If you are not familiar with CDATA tags there is a tutorial here: https://www.tutorialspoint.com/xml/xml_cdata_sections.htm

Document Webview Example

This <webview> example displays an html form.

Note: CDATA tags are required for the webview content.

Document Image Example

This <webview> example displays an image <img> and has the description below in Markdown <md>.

Document Share Example

This <share> example specifies the action to be taken when the document is shared

Document Example Screens

3. Element Descriptions

<app>

Specifies the title, style and main navigation components for the app.

Content: None

Attributes:

Child Elements:

<drawer>

Defines the list of menu items to be displayed in  the Drawer Menu of the Application

Content: None

Attributes: None

Child Elements:

<bottom_nav>

Defines the items to be displayed in  the Bottom Navigation Bar of the  Application

If present then the defaults on these menu items override the ones set in the drawer

Content: None

Attributes: None

Child Elements:

<menu>

Specifies the menu items to be displayed on the (overflow) menu on the right hand side of the screen. The menu is optional.

Content: None

Attributes:

Child Elements:

<share>

Specifies the action to be taken when the enclosing component (either the <app> or <doc>) is shared. The action enables the device to determine which applications can receive the share.

Content: None

Attributes:

Child Elements: None

<tabs>

Specifies a list of tabs to be displayed across the top of the page.

Content: None

Attributes:

Child Elements:

<style>

Provides the stylesheet to be used for this app. The styleurl for the app is ignored if this element is present. This stylesheet is merged with the built-in default stylesheet in the normal CSS behaviour.

Content: Valid CSS file

Attributes: None

Child Elements: None

<doc>

Specifies what is displayed on the page. Can contain either list style content or page style content but not both:

        List Style:        either one <list> element  OR one <tabs> element

        Page Style:        - any combination of  <webview>,<md>, <img> elements

                - optionally, one <share> element

Content: None

Attributes:

Child Elements:

<list>

Specifies a list of items to be displayed on the page.

Content: None

Attributes:

Child Elements:

<img>

An image to be displayed. Can be png, jpg or svg.

Content: None

Attributes:

Child Elements: None

<md>

A block of Markdown text to be displayed on the page. Supported Markdown tags and best practices are defined in the Markdown Coding Reference section.

Content: Markdown code (enclosed in CDATA tags)

Attributes:

Child Elements: None

<bookmark>

Indicates that the doc can be bookmarked. The bookmark icon will be displayed in the status bar for this doc. If selected,  this item will be  listed when the bookmark drawer item is selected. Note that the bookmark drawer item is only present if there is at least on bookmarked document.

Content:  None

Attributes:

Child Elements: None

<webview>

An in-line block of html or url reference to a webpage to be displayed on the page. Note that by default webview uses the Chrome rendering engine and appear as a page within the app. However, this behaviour can be modified by the proxymode parameter.

Content: HTML code (enclosed in CDATA tags) [nb: unless href attribute is present]

Attributes:

Child Elements: None

<item>

A list item.

Content: None

Attributes:

Child Elements:

<filter>

A list filter to enable the selective display of list items. See Using Filters

Content: None

Attributes:

Child Elements:

<option>

A list filter option item. See Using Filters

Content: The text to be displayed for the option

Attributes:

Child Elements: none

<menuitem>

A menu item.

Content: Menu Item Text

Attributes:

Child Elements: None

<msg>

An optional message to be displayed when the app starts.

Content: The message to be displayed as CDATA

Attributes:

Child Elements: none

4. Markdown and Style Reference

Markdown is a simple, lightweight markup for formatting text to be displayed on screen.

Markdown tags have a similarity to HTML tags but there are far fewer Markdown tags. biNu supports most but not all standard markdown tags.

More information on Markdown can be found here 

And here The Ultimate Guide to Writing & Publishing with Markdown

For example:

A Header 1 tag in HTML is:

<h1>Header Text</h1>

A Header 1 tag in Markup is:

## Header Text  

Note 1: there must be a space between the # and the text

Note 2: two spaces at the end of text invoke a new line

Styles can be specified to control how the markdown is displayed. Styles are defined once in the application, in the Application stylesheet defined within the <app> tag. If not specified, biNu default styles are used. Styles in the stylesheet can be applied to Markdown or HTML tags but they are defined in the stylesheet by their HTML tag rather than their Markdown tag.

For example:

                The stylesheet entry: h1 {color:blue;}

                will apply to Header 1 tags in HTML and in Markdown

Note: Markup tags are never used in stylesheets.

There are limitations on the usage of styles in a biNu Application:

1. Nested styles are not supported
2. One style block is allowed per tag
3. The last style definition for the tag will take precedence

Markdown Coding Reference

This table shows the supported Markup tags and their HTML equivalents to be used in the stylesheet.

biNu Default Stylesheet

default {

    color: black;

    background-color: white;

    margin-left: 8;

    margin-right: 8;

    binuImgOpt: c_limit,q_auto:eco;

}

cards {

    background-color: lightgray;

    elevation: 4;

    orientation: vertical;

    columns: 1;

    padding: 2;

}

cards item { corner-radius: 8; text-align: left: margin-left: 8; margin-right: 8; font-size: 24; font-style: italic; font-family: sans-serif; }

list {

    color: black;

    background-color: white;

    divider: black;

    orientation: vertical;

    padding-left: 12;

    padding-right: 12;

    padding-top: 8;

    padding-bottom: 8;

}

list.item { height: 100; text-align: center: padding-top: 0; padding-left: 0; padding-right: 0; padding-bottom: 5; font-size: 12; font-style: italic; }

item { height: 100; text-align: center: padding-top: 0; padding-left: 0; padding-right: 0; padding-bottom: 5; font-size: 12; font-style: italic; }

item.firstitem { height: -2; }

md {

    color:black;

    background-color: white;

    padding:24;

    vertical-align:middle;

}

md.h1 { color:black; font-size: 36; font-style: bold; font-family: sans-serif-thin; line-space:36;}

md.h2 { color:black; font-size: 24; font-style: normal; font-family: sans-serif-condensed; line-space:48;}

md.h3 { color:black; font-size: 12; font-style: italic; font-family: sans-serif-light; line-space:5;}

md.h4 { color:black; }

md.h5 { color:black; }

md.h6 { color:black; font-style: bold-italic; }

md.p { color:black; font-size: 18; font-style: normal; font-family: sans-serif-light; line-space:28;}

md.code { color:black; font-size: 12; font-style: normal; font-family: monospace; }

md.em { color:black; font-size: 18; font-style: italic; }

md.em2 { color:black; font-size: 18; font-style: bold; }

tabs {

    color: black;

    selected-color: #ff0a2062;

    indicator-color: #ff0a2062;

    indicator-height: 4;

}

webview {

    width: 480;

    height:720;

    disable-js: 0;

    internal-only: 0;

    binuImgOpt: c_limit,q_auto:eco;

}

Supported Style Properties

Stylesheets in HTML provide a rich set of properties to align and format text and other elements on the page. biNu supports a subset of standard css properties which are listed in this table.

Note: style names may not the contain hyphen (-) character

Markdown Styles - Example Code

Stylesheet entry

Markdown Code

Supported Fonts

All the fonts supported on android are supported in a biNu Application.

Fonts can be used along with text-style to make them bold and italics.

Supported Colors

The color literal can be used to change color of font, horizontal rule and markown tag element background. Apart from using colour literals, any HEX value is also supported

5. Design Considerations

From our extensive experience developing for high latency network with low capability phones, we have some tips to ensure your users have a great experience:

• Your Application should have a simple design which will work well on a low-end phone and consume less data.
• Design a page structure with good spacing between content and a simple and intuitive layout
• Use standard color styles, this is recommended by Android and helps to make the page more appealing to use read more here
• Images look pretty but consume lots of bandwidth. biNu optimises images for delivery to the client but you should try to minimise the size and number of images on a page as part of the design.
• Use markdown pages as much possible. Markdown is very quick to render and consumes less data
• Avoid complex functionality and page layouts which will usually slow down the apps, add to the mobile cost and quickly alienate end users

Using the App Context

The biNu Android App supplies context data in the request headers (X-Binu:) which may be used to customise the behaviour of the Application. The data is provided in a json string as follows:

Handling Different Screen Sizes

Android provides a number of tools to help & develop apps to run on multiple screen sizes. It scales fonts, images etc to suit the screen size.

Android recognises 4 basic screen sizes; Small, Medium, Large, Extra Large

It is recommended that you design Application for medium screen sizes and test on other screen sizes to verify the design. Occasionally the structure of the page will need to be modified for the different screen sizes which should be done in the Application.

To utilise Android Screen scaling biNu interprets all font size definitions in the stylesheets as Android’s SP. SP sizes (font) are automatically scaled to look similar relative to screen size. However, they can also be scaled by the user through accessibility settings in global device settings e.g user with poor eyesight can set fonts as “Large”. Developer should design their app to work with various font sizes selected by the user to avoid layout issues.

High quality/resolution images should be used irrespective of the screen sizes. biNu will automatically optimize and scale the images to appropriate size in order to minimize data. You are not needed to provide images in multiple formats nor write complex logic to select different images based on screen size etc. The biNu Image Optimiser Guide provides a full description of the optimisation process.

HTML Support

biNu supports content using HTML. In general HTML will use more data and render slower than markdown content, particularly on older phones.

HTML must be displayed within <Webview>. The webview can be in-line as part of a page, as a list item, within a card or appear as a full page. Javascript is supported. Note that all html must be enclosed in CDATA tags e.g. <![CDATA[ html code here ]]> 

The HTML can reference its own Stylesheet defined within the HTML.    

Forms

Forms in biNu are implemented in HTML and must be used from within webview (in-line or otherwise). All HTML Form elements can be used along with JavaScript.

Example form code:

Rules when coding forms

There are some rules that must be obeyed for HTML forms to work with biNu:

1. The form must use the GET method. POST is not supported.
2. The action must always be provided and must use absolute URL, relative URLs are not supported.
3. File Upload is not supported.
4. An HTML form can exist only within one Webview.

Caching

Caching content is important as it helps to reduce bandwidth usage while enabling the user to read content offline. Caching pages can get tricky, you need to ensure content is remains relevant by sending new content to user when requested but also try to avoid sending content that user already has.

You can use TTL (Time To Live) in page headers to control how long a page should be cached. Caching is managed by Picasso and Retrofit. Images consume large amount of data and are therefore set to minimum TTL of 1 hour by the biNu platform to help conserve data.

Cache Busters    

Sometimes content should not be cached and default caching may be a problem. To get around this, cache busting should be used. A Cache buster can be implemented by providing unique key at the end of a URL so each request is unique and therefore forces client to fetch the data from biNu. This can be masked in Analytic / Reporting systems so it doesn’t distort reporting

Cache busting should be used judiciously as it can significantly increase mobile data usage.  

Free Data

Add description here

Using filters

A list may have a filter to enable the user to choose which items are displayed in the list.

The filter has 2 distinct mechanisms for enabling selection and they may be combined in a filter, these are favourites and tags.

1. Favourite Filters

Favourites are  enabled if the list action = “fav”, each item will automatically display a favourite icon. If the user clicks the icon, the item becomes a selected (favourite) item and the item’s id is saved into the application database for the given list id.

If the filter popup  is shown at the top of the list, the user may choose to see all list items or just selected items.

Additionally, if any href in the application contains a list_id parameter, the saved item ids for the parameter’s list id  are automatically added  to the request to enable them to be used in the application logic.

E.g. an href parameter of list_id=myFavList will tell the client to get any saved  item ids in the list with the id=myFavList and add them  to the url as the parameter of  list_val=item1,item2,item3

Here is an example of a favourite filter in a list element

2. Tag Filters

Tag filters determine which items are shown based on selected tags associated with each item. The filter is used to dynamically hide and show items in the list but no data is saved for further use.

Here is an example of a tag filter in a list:

And here is how it looks

Registering a new biNu Application

The Developer Portal is used to manage biNu Applications.  

To register a new Application, log on to the Developer Portal and choose ‘Register New Application’. You will need to provide the following information which is ‘burned’ into the Android apk file when it is generated. Note that you can regenerate the App at any time if changes are required.

You will need to provide:

• the Application name and version;
• the Application package name (e.g. com.mycompany.application);
• a homepage URL pointing to a publicly available <app> XML document ;
• An onboarding URL which optionally provides as set of onboarding screens
• an app icon - a 120x120 pixel PNG file;
• a splash screen image - a 1080x1920 PNG image;

And optionally:

• Style  elements for the action bar  (at the very top of the page):

• Dark action icon colour - set this if the Action bar colour is  white or very light
• Action bar text colour - the colour of the text in the action bar
• Action bar colour - the action bar background colour

• The colour of the status bar

Onboarding Screens

When the user first loads an new or updated apk on their device they can optionally be shown a set of pages that provide information on the use of the application, these are called onboarding screens.

In a biNu application, the onboarding screens are defined as a tabs document and the client code shows them at app launch and allows the user to swipe through the tabs or dismiss them altogether.

The url to the Onboarding tabs document is specified in the application configuration burnt into the apk when it is generated however the tabs page and associated doc pages are maintained as part of the publisher application and can be modified as such.

Here are 2 examples of onboarding screens.

Note that when they are presented to the user in the app , they are overlayed with page position dots and a ’skip’ link.