This sample can be used as a reference to:

• display a list of data (the amount of data being variable)
• manage navigation in a list (current item index display, item selection, pages number display, current page index display and change...)
• delete an item from a list
• filter data from a list (here: show all messages, show only read messages, show only unread messages)
• sort data from a list (here: sort be email (asc or desc), sort by date (asc of desc))

Screenshots

This sample service offers simple layout adaptation to targeted screen size: all top and bottom elements have fixed height, others in the central area occupy all available vertical space (number of displayed mails on one page of the mailbox will be automatically computed), all elements have their width automatically adapted to fill in all available horizontal space.
This is a simple version of layout adaptation that is intended not to complexify the understanding of the present sample focused on InstantScript usage for list management; for an accurate solution for managing adaptation for your application we strongly recommend to rely on the Adaptation Framework we provide.

Interactions

In order to interact with this service, it is possible to use keypad and/or touchscreen.

General

• quit application: click on bottom right part of the footer on screen or press right softkey ([CTRL]+[RIGHT] when using Workbench Developer emulator)

Mailbox

• select previous/next mail: click up/down arrow on screen or press [LEFT]/[RIGHT] key
• access currently selected mail details: click the area corresponding to the currently selected mail on screen or press [FIRE]
• reload mailbox data from server: select reload action in options menu

Mail details

• select previous/next mail: click left/right arrow on screen or press [UP]/[DOWN] key
• go back to mailbox: select back action in the options menu

Options menu

• show/hide options menu: click on bottom left part of the footer on screen or press left softkey ([CTRL]+[LEFT] when using Workbench Developer emulator)
• select previous/next option (when options menu is displayed): press [UP]/[DOWN] key
• trigger action (if active): click option area on screen or press [FIRE]

Initially (i.e. at first launch) the list of mails is empty ("no message") and you will have to trigger the reload action in the options menu in order to retrieve the mails data from the server. When the application will be launched again, the lastly reloaded data from server will be displayed by default (and you will still be able to retrieve up-to-date mails data from server, triggering the reload action in the options menu.

Structure of the Project

• ant: the necessary Ant tasks to build the InstantScript lib (note: you will have to set the JDK path in file local.properties in case you want to use this task to rebuild the lib)
• doc: the present HTML documentation
• is: the client-side InstantScript lib subproject files (note: you can use the Ant task to build the library bin)
• java: the server-side Java lib subproject files (note: you can package the library jar proceeding as usual)
• res: the resources files (bitmaps)
• src: the rich media scenes (RSP)

Conception

Basically the overall conception for managing a list of data client-side (i.e. the mailbox display screen) consists in:

• Defining the presentation layer (visual) for one page (only!):
  • number of messages
  • current page index / total number of pages
  • given number of mails information (here we put as much as possible to fill in the available place in the central area)
  • up / down arrows
• Providing the (raw) data of the list as media elements (i.e. Text, Bitmap...):
  • number of items of the list
  • 1 Text node for each data (i.e. each attribute of each entity of the list)
• Implementing the necessary operations (logic) for managing all data and pages (especially inject the (raw) data in the defined presentation):
  • load / ingest mails data as object representation
  • display a given page (show appropriate data and provide appropriate interactions)
  • navigate among pages
  • select and display a given mail details
  • navigate among mails
  • delete a mail from the list (and update the current page display accordingly)
  • sort the mails in the list (and update the current page display accordingly)
  • filter the mails in the list (and update the current page display accordingly)

Scenes conception

The sample project is composed of 4 scenes:

• start.rsp (first scene of the service): defines the common and non dynamic UI elements of the application (i.e. header + footer + options menu + loading animation) and also all InstantScript code (library, variables and functions) to manage the list (see logic operations mentioned above)
• mailbox.rsp: simply defines the UI elements corresponding to the display of one single page of the mailbox
• mail.rsp: simply defines the UI elements corresponding to the display of the details of one mail
• data.rsp (the only server-side scene of the service): simply transmits the up-to-date mails data (retrieved by a Java library from a XML file) from server to client

The most "complex" scene of the service is definitely start.rsp as it contains all InstantScript code necessary for the application (and also all non dynamic elements that are common to all scenes, i.e. reused taking advantage of the append mode usage (see Workbench Developer help for more information on this feature)).
Other scenes simply get appended to it, by replacing the central area with the appropriate content (i.e. mailbox display or mail details display or mails data).

Server-side conception (Java library)

As usual this set of Java classes packaged as a library (JAR) has been developed and validated completely out of Streamezzo environment.
It consists in 3 classes:

• Message: the class representing a mail, with the appropriate getters and setters to manipulate the related information
• MessagesList: the class representing a list of mails (i.e. the mailbox content), with the appropriate constructors to populate this list, especially ingesting an XML document containing all mails data; the XML file is a simple representation of what a real back-end would be and enables to update this set of mails data without requiring to republish the application on server
• MessagesLoader: the class only responsible for loading a list of mails (MessagesList)) based on a the path to an XML document

Client-side conception (InstantScript library)

This Java class packaged as an InstantScript library (bin) has also been developed and validated completely out of Streamezzo environment (it is almost exactly the Message class from the server-side library). The only thing we have to take care of is to respect the limitations related to InstantScript compared to pure Java coding (refer to Workbench Developer help for more information on this).

The generation of the library bin is operated thanks to the Ant task called generateLibs provided with the sample project.

Data loading (reload action)

The server mails data loading simply consists in:

• implementing a server-side scene (data.rsp) that will:
  • retrieve all data from backend (defined in messages.xml and accessed using MessagesLoader Java class)
  • send (rwa) data to the client as media nodes (Text).
• invoking an InstantScript function that will:
  • retrieve the (raw) data from the media nodes (Text) using DomApi.get...() methods
  • instanciate objects (Message InstantScript class) using this (raw) data
  • remove the (now useless) data from the scene graph

The server mails data loading process consists in the following steps:

1. Clean data container scene from client cache (see Data restoration section below)
2. Access data container scene on server (data.rsp)
3. Deliver data as scene graph update containing the appropriate media (Text) from server to client
4. Instantiate objects in client memory, using the provided data
5. Clean useless data from scene graph
6. Use the objects to update data presented on screen and enable appropriate interactions

Data restoration (on application launch)

As previously mentioned transferring (raw) data from server to client simply consists in implementing a RSP containing media nodes (Text, Bitmap...) carrying this data to the client. Then the logic implemented in InstantScript will ingest this data (here populate a Vector of InstantScript Message instances) and manage the presentation and related interactivity.
Here we have implemented a rather simple context restoration: when the application is launched we will restore (without any server connection) the last update of the mails data as provided by the server (which means it allows offline browsing but the list of mails may not be up-to-date and we will need to trigger the reload action in the options menu if we want to get an up-to-date list).
Note: A more relevant mechanism would counsist in restoring the latest local context (i.e. not display deleted mails and display appropriate read status according to what has been operated by the end-user during his last session). However this is not what this sample does, so it doesn not make the current implementation understanding more complex.

As a consequence to implement such mechanism, we simply:

• store in client-side permanent cache the scene data.rsp: set the appropriate attributes for this in the <header> tag
• load this cached data when launching the application: when accessing start.rsp (which is accessed only once) look for data.rsp in the cache, if there is a hit access data.rsp in cache
• (note that as consequence when the reload action is triggered we have first to clear data.rsp from the cache before accessing it server-side)

Debugging

Server-side debugging

This is the most easy part to debug as you can:

• debug your Java libraries separately from the application itself (and from Streamezzo Workbench Developer environment)
• use the provided ServiceLogger to log debug information while processing a RSP (including calls to your Java libraries)
• simply disable the logs according to their level by configuring the logs level in Streamezzo Rich Media Server administration interface (i.e. with no impact on the RSP code itself and without requiring to republish the server-side part of your application); remember to finally tune the logs level appropriately when you will put your application in production

Client-side debugging

Although debugging on client (and even more a script) is usually not that easy, you can take advantage of the logs mechanism provided with the InstantScript Virtual Machine:

• use an InstantScript variable (like LOGS_ON) to enable/disable logs; remember to finally disable logs when you will put your application in production
• use VM.log() function to log any useful information

 

We encourage you to use this sample extensively as a reference for similar developments.

Attachment	Size
Mailbox.swz	175.51 KB