MUPE Client Script Reference Manual

DOCUMENT HISTORY

Version	Date	Who	Description
1.00	30.10.2003	ER	Release version.
1.01	13.11.2003	ER	Added “initialise” and “finalise” parameters to starttimer and g_starttimer messages. Fixed g_starttimer documentation, which was not correct. Added g_starttimer and g_stoptimer messages to Form UI
1.02	20.11.2003	ER	Changed “group” parameter for “template” message to “uigroup” (it was overlapping with canvas “group” parameter). Fixed some chapter references.
1.03	5.12.2003	ER	Added <nbsp /> tag into form UI.
1.04	16.01.2004	ER	Minor Bug fixes
1.10	23.04.2004	ER	Added section Common Script Language and changed the whole document structure accordingly. Introduced concept of common item reference, <identifiers>. Added event handlers: on_activation and on_deactivation. In addition some small bug fixes.
1.21	09.12.2004	ER	Script reference for MIDP 2.0 clients v2.21 and later.
1.26	12.01.2006	ER	Update for 2.26rc version of Mupe client.
1.26b	09.02.2006	ER	Created Wiki version of the document.
1.30a	15.03.2006	ER	Updated for 2.30a release of client.
1.31g	30.10.2006	ER	Updated for 2.31g client. Almost all XML Widgets documented.

Note: Changed parts since the previous version of the document are marked with (updated) in the corresponding chapter header. New sections/chapters are marked with (new).

XML SCRIPT LANGUAGE

MUPE is an application platform for multi-user mobile applications. MUPE applications are client-server applications, where the client device has a MIDP client that is constantly connected to the MUPE server. Due to the limited bandwidth of the current mobile devices, and the latency of the HTTP or even TCP protocol, real time communications with the server is not easy. To make the system more responsive for user interaction, functionality should be uploaded to the terminals itself so they can quickly respond to the user input. The data transmission should be kept minimal, yet the user should feel that the system is responsive. Especially keeping in mind that each request to the server can take several seconds regardless of amount of data transferred. Because of this the it is good to minimize the times client has to interact with the server.

The XML script language is a method of creating UIs and client side functionality with simple scripts. The scripts allows the MUPE MIDP client to change its behavior and UI dynamically while the user is connected to the MUPE server. A part of the MUPE script language is based on MIDP 2.0 LCD-UI specification (to some extent downwards compatible with old MIDP 1.0 client) supporting most of the features defined in the MIDP 2.0 UI specific feature set.

The MUPE script language supports dynamical changes to the client device behavior. The new functionality can be uploaded to the terminal either by specifying a new template or uploading individual objects. The template defines all previous components and creates a new container for client functionality. The template contains any number of other objects. The objects can be changed dynamically using the script language and there is no need to change the template to change the behavior of the client device. The client is constantly connected to the MUPE server and the actions the user does can either be handled in the client or they can be sent to the server. Application designers need to decide how they want the MUPE applications to work. The bandwidth is usually scarce, and it should in most cases be preserved. The client supports the following features:

• Messages between the client and server. These are used for communications between he MUPE client and server.
• Form Uis. These create standard form Uis. The user can input text, create lists, choice groups etc.
• Canvas Uis. Graphical user interfaces are created with this.
• Event hooks. User input, timers, messages and UI events can be caught and handled with the scripts.
• Resources that can be loaded and then reused several times in the content.
• Support for third party plugins.

A typical MUPE application has only one server and a larger number of MIDP clients. This should be taken into account when designing applications. As much of the functionality as possible should be uploaded to the client terminal and the data traffic should be kept minimal.

CLIENT-TO-SERVER REQUESTS

The client sends information regarding its state to the server. When the client needs response from the server, such as new objects or new information, it sends a request to the server. When the client does not need a response from the server, the client sends a notification. System messages are internal messages. The client can also send standard XML-RPC requests. These can be used to extend the use of the MUPE client to get information from other sources.

 

message types

The client can send four types of messages to the server. These are: · requests · notifications · XML-RPC messages

 

request

Request is a message that waits a response from the server. The message is sent to the server and the client waits a response until it comes, it is timed out, or the server closes the connection. In addition to the client the server should also be aware that it is required to respond to the message.

Example(s)

<msg from="clientid">
message here
</msg>

 

---

notify

Unlike request, a notification does not wait response from a server. This type of interaction with the server is used when the client does not need an update from the server for each message it sends. Client can “front-load” information to the server using notifications and then send a request to download the update.

This method of interaction with the server is considerable faster than using multiple requests. The server does not have to acknowledge notifications, since client will close connection immediately after sending the message to the server.

Example(s)

<msg r="0" c="1" from="clientid">
message here
</msg>

 

---

xml-rpc

XML-RPC calls are messages that follow the xml-rpc specification. They are not wrapped with msg tags but methodCall tags according to the specification. The content of the message is not checked for validity and is assumed that the server party checks the message validity and responds accordingly.

Example(s)

<?xml version=”1.0”?>
<methodCall>
xml-rpc call here
</methodCall>

Common requests

These messages are independent from the service and UI types.

 

clientSubscribe

clientSubscribe is an internal request from client to server. It asks the server to invoke the subscription phase for the client. The purpose of this is to register the client to the service. The server should respond to the client with either a UI or a serviceinfo message, if the client does not need to provide information from the user.

After the client has been registered the clientSubscribe message is no longer needed for that server. Instead the client can inform the service with clientActivate and disable messages if it wants to momentarily enable or disable the service. The client is known to the service until the client sends a clientUnsubsribe message to it.

Example(s)

<msg>
clientSubscribe
</msg>

 

---

clientUnsubscribe

clientUnsubscribe is an internal request from client to server. It asks the server to remove the client information from the service and disable the service for the client. In other words after sending unsubscribe message to the service the service should clean all the client related data of the client. In addition the client removes all service related data, which includes the service bookmark in the client main menu.

Parameters

Param	Type	Default	Meaning
from	string	none	The client id
v	string	none	Client version.
c	int	0	Set to 1 if client can handle compressed xml.
r	int	0	Set to 0 if client does not want reply to its message.

Example(s)

<msg from="23" v="2.25" c="0" r="0'>
23::clientUnsubscribe {servicepassword} {servicename}
</msg>

 

---

clientActivate

Client sends clientActivate message to the server when the client account has been disabled earlier, or when the client activates the account first time after the subscription phase. Along with clientDisable and clientUnsubscribe messages the client password is required to be given with the message, to authenticate changes in the server account.

clientActivate message is sent to server each time the client software is started and is connecting to a subscribed service.

Parameters Param Type Default Meaning from string none The client id v string none Client version. c int 0 Set to 1 if client can handle compressed xml. r int 1 Set to 0 if client does not want reply to its message.

Example(s)

<msg from="23" v="2.25" c="1" r="1">
23::clientActivate {servicepassword}
</msg>

 

---

clientPoll

clientPoll is a general way to request an UI update from the server. It is a default functionality to pull updates from server. The server should respond with up-to-date version of the current UI.

Parameters

Param	Type	Default	Meaning
from	string	none	The service name
v	string	none	Client version.
c	int	0	Set to 1 if client can handle compressed xml.
r	int	1	Set to 0 if client does not want reply to its message.

Example(s)

<msg from="23" v="2.25" c="1" r="1">
clientPoll
</msg>

 

---

SERVER-TO-CLIENT RESPONSES (CLIENT CONTENT)

Server-to-client messages are responses to client-to-server requests. The common format for server-to-client message are as follows:

<msg>
xml message here
</msg>

The message follows a certain XML format thought the whole system. Each XML section can have a series of parameters that is given to it. The parameters can be given in two ways. Either they are given in the header of the XML section (xmlsection and subsection1 in the example) or they are given inside a special purpose tag called parms. There can be only one parms section for each tag. The parameter values are given inside the variable tag, as PCData.

<xmlsection var1="value1" var2="value2">
<parms>
<var3>value3</var3>
<var4>value4</var4>
</parms>
<subsection1 var1="value1" var2="value2" var3="value3" />
<subsection2 var1="value1">
<parms><var2>value2</var2></parms>
</subsection2>
</xmlsection>

The next XML section is equal to the previous example:

<xmlsection var1="value1" var2="value2" var3="value3" var4="value4">
<subsection1 var1="value1" var2="value2" var3="value3" />
<subsection1 var1="value1" var2="value2" />
</xmlsection>

 

Common messages

There is a set of common messages that are independent from UI type. They provide the basic functionality to:

• store service specific information into client service database.
• and create UI templates.

All the other functions are UI dependent.

 

---

 

serviceinfo

Service info messages works as a “cookies” in script language. They are used for storing service specific information on the client device. The information is bound to service name, which is a free form text string defined by the service. In addition to the service specific information there are three information tags that are used internally by the client. These tags are:

 

url || The server URL username || Client login name for the service password || Client password for the service

Parameters

Param	Type	Default	Meaning
service	string	none	The service name
<variable>	string	none	The information tags are strings that stores service specific data. The data can be accessed by the UI-script using $(service.<variable>) notation.

Example(s)

<serviceinfo service="myservice">
<parms>
<username>test1</username>
<password>testpass</password>
</parms>
</serviceinfo>

 

---

template

Template message creates a new user-interface (UI) for the client. The look-and-feel and functionality of the user-interface is defined by the client implementation and the given UI type parameter. Currently MUPE client supports two different kinds of UIs: forms and canvases. The client is implemented in such way that the template message can create other kinds of Uis in the future, if so needed. The smallest common nominator between the UIs is the “form” type UI, which is a requirement for all MUPE clients. The client also supports multiple simultaneous UIs, i.e. the client can load a set of UIs called UI group. There can only be one UI group at a time. The UI group is identified by an ID (group parameter). If either the group ID changes or a UI without group ID is downloaded the current UI group is discarded. If one needs to replace only one UI in the UI group, it can be achieved by specifying the same group and id parameters for the template message.

Note: Basically the client tries to create an instance of a class defined by the given type parameter with a prefix “UI”. So in case of “form” type UI the client creates a UI from class “UIForm” and sends the content of the template XML message to the newly created UI module.

Parameters

Param	Type	Default	Meaning
id	string	none	User-interface Id.
type	string	none	User-interface type.
uigroup	string	none	UI group this template belongs to.
active	boolean	true	Is user-interface set as the current visible UI.

Example(s)

<template id="canvas_ui" type="canvas">
</template>

<template id="form_ui" type="form">
</template>

<template id="test" type="my_own_ui_type">
</template>

 

---

XML-RPC responses

XML-RPC responses are automatically handled by the client and it parses the response to a serviceinfo call. The response type is ignored (string, i4, int, etc) and the value is placed under service attribute rpc_response.

In case of an error-response there is another attribute called rpc_error (it is cleared before each XML-RPC call) and the error message is placed in the attribute.

Each UI type can handle the XML-RPC responses differently. Currently, Canvas UI has more possibilities in reacting to XML-RPC responses than Form UI. In Canvas UI one can “hook” each message to different events, which makes it easy to notify the content about received XML-RPC messages.

 

---

 

COMMON SCRIPT LANGUAGE

Common Script Language defines a set of messages and conventions available for all UI type, i.e. in canvas and form UI styles. They define a basic functionality of MUPE UI independent of the UI style used.

 

UI templates

UI template is the basic element of MUPE script language. All the functionality happens through UI templates. Currently the client supports two kinds of UI templates, Canvas and Form. They can be created with template message.

The UI templates are dynamic since the content can be changed on-the-fly without recreating the whole screen each time. These changes can be done by the server or by the content itself (triggered by user interaction or various events). The content consists of UI items that be replaced by other UI items. In addition the UI items have attributes and functionalities that can be used to manipulate them. All the UI manipulation is done via messages that are UI dependent. Each UI type defines a set of messages (message API).

The benefit of this is that the UIs don"t have to be recreated each time when interacting with the server (unlike when using HTML). This makes it possible to transfer less data between the client and the server. In addition it is possible to manipulate individual UI items at the same time for instance when user is writing to an edit field, without losing the partly written text in the edit field.

 

UI Groups

One can download multiple UIs in the client by using UI groups. The idea is that the client can hold one UI group at a time. If the UI group changes or the UI group is not specified in the downloaded UI template the current UI and UI group is discarded and replaced by new UI or group of UIs.

Like the UI items the UI group has an ID that is given with group parameter in the template message. The UIs in UI group don"t have to be the same type but one can mix different types of UIs there as well. The communication between the UIs is also possible and using the messaging they can also share data. For instance, there can be a Canvas UI that defined the actual application and then a Form UI to configure the application. Another example would be to use the Canvas UI as the content viewer and then Form UI to interact with the server.

When downloading UIs in the UI group there is another parameter, called active, that is used for notifying the client, which UI in the group is the current active (read: visible) UI. This is done by setting the active flag to true for one UI and false for the rest.

As a summary, the UI template can contain one UI template or a collection of templates inside a UI group. The possibilities are seen in figure 1.

Image:Image.jpg Figure 1. The possibilities of creating a UI.

 

UI items

Each UI template contains a set of UI items. The set of UI items can be and in most cases is different for each UI type; Form type UI has a different set of UI items than Canvas type UI. The UI items can be created in a UI template by writing an XML section that describes the UI item. Each UI item has id parameter that is given as parameter in the XML section. The id parameter can be used to refer to the UI item later on. If additional information is needed to make an UI item unique, that can be implemented by the UI. For instance canvas UI needs group parameter in addition to id parameter to make a UI item unique in the name space.

The UI items can be manipulated using global messages of item specific messages. Global messages are starting with “g_” prefix and item specific messages with “i_” prefix. The item specific message API can differ between UI items but the global message API is common for all UI items.

In addition to manipulating UI items with messages from server or by user interaction, there can be also message sequences triggered by so called events. For instance when user is writing to an edit field that creates an on_change event for the edit field item. The script language can “hook” these items and trigger a sequence of UI messages when the event takes place. The events, which can be triggered for each UI item are defined by the UI type.

 

Inheritance

One can also reduce the size of XML script by using inherits="itemid" parameters within the UI item creation. The inheritance is only allowed inside an item group. Inheritance also reduces the memory requirements of the content, since the script is shared between UI items instead of copying it for each UI item. The inheritance only shares the event hooks. Anything outside the event hooks is considered as item specific extended properties. The inheritance is not restricted to using same UI item types but it also works between different UI item types.

In the example below, we have two image items image1 and image2. The "image1" implements the base class for the other image (image2) to inherit. Image1 does not have to be visible UI item. It only implements the script. When image2 is created it inherits the on_create event hook from image1, but not the extended_attibute attribute. After creation of image2 the on_create event is triggered and it also downloads the "image1.png" data as the content.

Example(s)

<image id='image1' visible='false'>
<i_attribute name='extended_attribute' value='not_shared' />

   <i_hook name='on_create'>
<i_setimage url='http://www.images.com/image1.png' />
<i_attribute name='foo' value='bar' />
</i_hook>
</image>

<image id='image2' visible='true' x='50' y='60' inherits='image1' />

Sending messages to UI items

The server sends information to a single UI item in the same way as new items are created. The object is referred to with its group and id parameters and in case such object already exists, its content is changed.

In Form UI the UI items are referenced with id parameter. Canvas UI has different referencing method, since the UI items are in item groups (analogy: window). In Canvas UI the referencing is done via id and group parameters.

However, in both cases one does not have to specify id and group parameters for each message. This is because the script language is running in an item context and the message is pointed to the same UI item, such as when an event has been triggered for a UI item. In such cases if the id and group parameters are not specified it can be assumed that the information can be extracted from the UI item context.

IMPORTANT: The content creator must understand that each tag is in fact a message sent to the UI and it needs a target UI item information to know to which UI item is meant to be handling the message. In the following (Canvas UI) example there is several different ways of referencing items. There is two event hooks implemented for image1 and it is assumed that there is also another image image2 inside same item group with image1 and also another item group other_group that includes image image3.

There are four i_hide messages in the on_select event hook that behaves differently because of the UI item context (which is image1).

• The 1st one hides the image1 itself since the id and group information is left unspecified.
• The 2nd one hides image2 UI item in the same item group, since the group parameter is left unspecified.
• The 3rd one hides image3 from another item group called other_group.
• The 4th one hides the item group other_group

Note: If item group is referenced outside it"s context (from other UI items) the group and id are both set as the item group"s ID.

Example(s)

<image id="image1">
<i_hook name="on_select">
<i_hide />
<i_hide id="image2" />
<i_hide id="image3" group="other_group" />
<i_hide id="other_group" group="other_group" />
</i_hook>    
</image>

Sending message to an item in another UI

When using UI groups, a UI can send a message to another UI using ui parameter. The ui parameter is the ID of the UI that was given in the template message at creation. This feature makes is also possible to share data between UIs. Instead of just sending a message to another UI the message parameters are evaluated in the source UI"s context. The message can contain several parameters, which are not constant but references to (see next chapter for details) to different attributes of the source UI, which are then evaluated to constant values before sending the message to another UI. The destination UI can then take the parameter and store/use the value for its own purposes.

Example(s)

<i_settext ui="form1" id="string1" text="$(canvas1.group1.text1)" />

<i_settext target='form1:string1' text="$(canvas1.group1.text1)" />

Definition of <identifiers>

Almost all messages take item identifiers as parameters. As mentioned before, depending on the script context, some of the parameters can be left unspecified. In addition to that the item identifier can vary depending on the used UI type. I.e. in Canvas type UI the items belong to item groups which adds one parameter (group) into the messages when defining the reference to a UI item. The following tables show how <identifiers> is defined in each available UI type.

 

Identifier	UI types	Refers to
ui	All	User-interface Id.
id	All	Item Id.
group	Canvas	Item group
item	All	Alternative way of referring to ui items with syntax: ui:group/id

Resources

Resources are special items that do not have visual representation on the screen but are used as data stores for UI items. The data, downloadable media, can be images, sound, and binary data. In case of image resources the resource is referenced with "resource:" prefix in the url parameter. In case of sounds the data always has to be downloaded to a resource before using them. The sound resources are referenced using id parameter with the g_playsound message.

The resources are downloaded using http protocol and the downloadind process creates events for the default item group (the canvas ui itself). The events are on_resource_loaded and on_resource_load_error.

 

Event	Meaning
on_resource_loaded	resource was successfully loaded
on_resource_load_error	resource loading failed

The event hooks can be captured and the special resource_id attribute can be used to define which resource has been loaded or which has failed. This makes it possible to visualize the process of loading resources and activating things, like user input, when the downloading process has ended.

 

creation

Param	Type	Default	Meaning
id	string	none	Resource id
type	string	none	wave = Waveform audio tone = Ringing tone image = Image (at least PNG |supported) midi = Midi tune xml = Xml script
url	string	none	URL to the actual data
global	bool	false	Set to true if the created resource is a global resource. Global resources are freed only when the service is changed of quit.
cache	string	“true”	Set to “false” if you want the resource to be downloaded each time when created. Handy for dynamic content that can change any time in the web. Set to “update” if you want the resource object to be updated in the cache.

Example(s)

<resource id="explo1" type="wave">
<parms>
<url>http://audio.com/explosion.wav</url>
</parms>
</resource>

<resource id="playerchar" type="image">
<parms>
<url></url>
</parms>
</resource>

 

---

Image subresource

You can split image resources into sub resources. After the image has been split into sub resources, you can use the sub resources with a “resource.subresource” notation. The sub resources are created at once when the image resource is created and its not possible to create more sub resources later. The original image is discarded from memory after the sub resources are create for saving up memory, thus the original image resource cannot be used as it is, only the sub resources.

Parameters

Param	Type	Default	Meaning
name	string	none	Sub resource id
cropx	int	0	Top left x-coordinate of the sub resource inside the main image resource.
cropy	int	0	Top left y-coordinate of the sub resource inside the main image resource.
cropwidth	int	none	Width of the sub resource.
cropheight	int	none	Height of the sub resource.
mirror	bool	false	Set to true if the sub image should be mirrored horizontally.
rotate	string	“deg0”	“deg0” = sub image is not rotated “deg90” = sub image is rotated 90 degrees “deg180” = sub image is rotated 180 degrees “deg270” = sub image is rotated 270 degrees

Example(s)

<resource id="playerchars" type="image">
<parms>
<url></url>
</parms>
<subresource name="hero1" cropx="0" cropy="0" cropwidth="64" cropheight="64" />
<subresource name="hero2" cropx="64" cropy="0" cropwidth="64" cropheight="64" mirror="true" />
</resource>

 

---

 

XML script as resource

In addition to media files the client can also store XML scripts as resources. These scripts stays in the client even if the client is restarted or updated. The script resource system also implements a simple version control, which can be used to update the scripts with newer version from the server.

Example script resource:

<resource id="script1" type="xml" version="1.0">
<g_debug text="Hello world!" />
</resource>

When the script is defined as resource its automatically loaded and is ready for use. However if the client is restarted the script must be loaded in order to run it. However loading a script every time before its being run does not cause any errors. One can load scripts using the g_load method implemented for the plugin interface.

Example script loading:

<g_load script="script1" version="1.0" />

The script can be then run as follows:

<g_call script="script1" /> 

If loading fails following events are created at the global level of the template:

Event	Reason
on_no_such_script	No such script is stored in the client
on_script_need_update	Version does not match with the version of script stored in the client.

If running fails following events are created at the global level of the template:

Event	Reason
on_script_not_loaded	The script tried to be run is not currently loaded as resource.

 

Attributes and references

Each UI item can hold information, so called attributes. This information can be extracted from the UI items and for instance sent to server. There are two kinds attributes; read-only attributed and user-defined attributes. The difference between these two is that read-only attributes cannot be directly changed, but they change according to UI item initialization and when interacting with the UI item. Unlike the read-only attributes the user-defined attributes are not directly used by UI items, but they exist only to store information. The user-defined attributes can only be used by the XML script.

 

Read-only attributes

Each UI item has a set of read-only attributes. Again what attributes is defined for each UI item is defined by the UI type. The only common read-only attribute that is defined for every UI item is id. The values of read-only attributes cannot be directly set using i_attribute message in Canvas UI, but they can be changed indirectly with the UI specific message API. As an example in Canvas UI each item has x and y attributes that determines the placement of the UI item. One cannot move an UI item by changing the x attribute with i_attribute message, but the moving is done via g_move message that changes the x and y attributes according to the parameters and along with many other required procedures when the UI item is moved on screen.

 

System and service attributes (updated)

There are a set of static attributes stores in the MIDP system. They can either be set compile time using JAD extensions or defined by the platform itself. The developer can access this information by using "client" keyword as the attribute container. In addition the there are a few special attributes:

Attribute	Meaning
cachetotal	Maximum cache size.
cacheused	Used cache size.
cachefree	Available cache space.
cachefiles	Number of files cached.
memorytotal	Total memory.
memoryfree	Available memory. (Java can allocate more memory if needed, so this usually does not tell how much memory is really available, but how much is free from the current allocated chunk of memory.)

The client can also store service specific information using "serviceinfo" message. This type of information can be accessed by using "service" keyword as the container. See "serviceinfo" section for more details.

 

---

User-defined attributes

User-defined attributes are used for storing information in the UI items. Currently only Canvas UI supports this feature with its more advanced script language support. The user-defined attributes are created for an UI item using i_attribute message, with given initial value. When an attribute value is changed the change can be done with the same message using different value parameter.

The benefit of user defined attributes is to create more logic in the client-side by making it possible to do simple calculations with the attributes and also sharing common data between the UI items, without asking the remote server to do these things. This makes the client content less dependent on the server and more effective as user-interface.

 

---

 

Referencing UI item attributes

To use the UI item attributes one must refer to them using a certain notation. Both read-only and user-defined attributes can be referred with same kind of notation. The syntax for the notation is as follows:

$(ui_item_identifier.ui_item_attibute)

where the ui_item_identifier tells the client which UI item has the attribute and ui_item_attibute is the attribute identifier. For instance, when referring to a x coordinate of an image item image1 in Canvas UI the reference would look like this:

$(image1.x)

The previous example assumes that the message is sent from the same item group with the image1 item. In Canvas UI the ui_item_identifier can consist of two parts, item group and item id. The item group can be left unspecified if the message was sent from same item group. The general notation for UI items in Canvas type UI would look like this:

$(ui_item_group.ui_item_identifier.item_attribute)

And the previous example in general format:

$(itemgroup1.image1.x)

Referencing item group itself in Canvas UI:

$(itemgroup1.itemgroup1.x)

Referencing attribute of Canvas UI itself.

$(canvasid. canvasid.width)

Referencing attribute of Form UI. Form UI only has one level notation.

$(formid.width)

 

---

 

Referencing attributes from another UI

Since version 2.23a of the client it has been possible to reference attributes from another UI. In the previous versions of the API it was needed to transfer data between the UIs using messages such as i_attribute, i_settext, etc. This is not necessary anymore, but one can access attributes in more straightforward way, just by including the UI ID in the attribute reference in a following way: $(ui_id:<item_id>)

The ui_id is the identifier of the UI where the attribute is defined, and the <item_id> is an attribute reference as defined in chapter Referencing UI item attributes. The ui_id and <item_id> are separated with a colon. As an example, lets say we have two Uis in a UI group: ui1 and ui2. The ui1 has editfield item edit1 and the ui2 has string item str1. its now possible to write following hook in ui2 for displaying the contents of the edit1 in ui2.

<i_hook name="on_activation"> <i_settext id="str1" text="$(ui1:edit1.text)" /> </i_hook>

 

 

Dynamic references and attributes (updated)

In addition to identifying the UI items with ui_item_identifier there is also a set of reserved words that can be used for referring attributes in special contexts. They can be used to replace the ui_item_identifier in the attribute reference. One cannot create UI Items using these as item id. Here is a list of the reserved keywords:

 

Keyword	UI types	Refers to
this	All	Current UI item context in script.
service	All	Information stored with service info.
resources	All	Use resource id as the attribute name. Returns base64 encoded data of a snaphot taken by camera or recorded audio clip. Returns empty string for downloaded content.
reference#	All	UI item set by g_setreference message. # can be [0..7] or left unspecified for index 0. Note: This keyword also has alias "ref", so $(reference2.var) is equal to $(ref2.var).
global	All	Referring to attributes of the UI itself.
client	All	Referring to MIDP property values.
group	Canvas	item group of an UI item.
random	All	Accesses random number generator. For instance $(random.integer) returns 32bit random integer.
selected	Canvas	Referencing to currently selected item in Canvas UI.

Arithmetic statements as parameters

Since version 2.26a it has been possible to use arithmetic statements as parameters. This makes it considerably easier to make calculations in the script language. In the previous versions of the script language one had to use the methods from common script language when manipulating the integer values. This created a large amount of temporary variables and stressed the script engine by handing each arithmetic operation separately.

The usage of arithmetic statements is pretty straightforward with only one exception. When using arithmetic statement as value parameter of i_attribute method, one must remember to specify the type="int" parameter. Otherwise the parameter will be evaluates as a string. Also, when using parentheses within the arithmetic statements one must use [ ] characters instead of normal ( ). The parentheses can be nested.

Here is couple of examples for using arithmetic statements:

<g_move id="img" deltax="$(global.movestep)+4" />

<g_move id="img2" deltay="[$(global.movestep) – 5] *  3" />

<g_move id="img3" x="[[$(a.b) – $(c.d)] * 5 ] / 3" />

 

Event hooks (updated)

Event hooks allow the client device to respond to user input, timers and client created events. These features allow great flexibility and customizability for the client. The system contains a number of predefined hooks and the programmer can also define new hooks.

Event hooks are like subroutines that can be called anytime by the content or by the system. The predefined event hooks define a set of basic events that can happen for each UI item, such as adding more functionality when a UI item is shown, hidden or created.

Common Script Language defines a large set of event hooks available for all UI types and the different UI types can extend the set of events with their own events. In addition there can be also custom event hooks that are not called by the system but by the script itself (via i_event message).

It is also possible to define an event hook another way (since 2.30b). The client assumes that every tag starting with characters "on_" are event hooks. For example:

<on_create>
<scripthere /> 
</on_create>

The Following list of events are available for all UI types:

 

on_create

This event takes place when a UI item is initialized and added to the UI but not yet shown. It only happens once for an UI item. It can be used to initializing UI item attributes or configuring the UI for the item.

Example(s)

<i_hook name="on_create">
<g_debug text="UI item $(this.id) was just created." />
</i_hook>

 

on_delete

This event takes place when a UI item is destroyed with g_delete message, just before the item attributes and event hooks are removed from the system. If the UI item is not explicitly removed with g_delete message but the UI template is changed, the UI item does not receive this event.

Example(s)

<i_hook name="on_delete">
<g_debug text="UI item $(this.id) was just deleted." />
</i_hook>

 

on_change

This event takes place when the UI item is changed item specific messages. It"s a general way of noticing that the UI item has been changed somehow and other UI items related to the item needs to be updated as well.

Note: This event might become obsolete at later time. It can be replaced with a set of events that describes different ways of manipulating the UI items better.

Example(s)

<i_hook name="on_change">
<g_debug text="UI item $(this.id) was changed." />
</i_hook>

 

on_resource_loaded

This event takes place when a resource data has been successfully loaded. Only the UI template can hook this event. In addition to the event there is an attribute named resource_id that is dedicated to tell the ID of the resource that was just loaded. The attribute ‘is set as the property of the default group.

Example(s)

<i_hook name="on_resource_loaded">
<g_debug text="Resource $(this.resource_id) was just loaded." />
</i_hook>

on_resource_loading

These events are created for the UI during resource loading. There is an attribute named resource_id that is dedicated to tell the ID of the resource that was just loaded. The attribute ‘is set as the property of the UI template. In addition to the id there is also another parameter called resource_status which tells how many percent the resource has been downloaded so far.

Example(s)

<i_hook name="on_resource_loaded">
<g_debug text="Downloading $(this.resource_id), $(this.resource_status)% complete." />
</i_hook>

on_resource_load_error

This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. In addition to the event there is attribute named resource_id that is dedicated to tell the ID of the resource of which loading failed. The attribute is set as the property of the default group.

Example(s)

<i_hook name="on_resource_load_error">
<g_debug text="Error loading $(this.resource_id)." />
</i_hook>

 

on_net_request

This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when the content sends a request to a server. It can be used to control the general state of the content when it is interacting with the server.

Example(s)

<i_hook name="on_http_request">
<g_allowuserinput value="false" />
</i_hook>

 

on_net_response

This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when the client receives a message from the server. It can be used to control the general state of the content when it is interacting with the server.

Example(s)

<i_hook name="on_http_response">
<g_allowuserinput value="true" />
</i_hook>

 

on_net_error

This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when an HTTP request to the server has failed. It can be used to control the general state of the content when it is interacting with the server.

Example(s)

<i_hook name="on_http_error">
<g_allowuserinput value="true" />
</i_hook>

 

on_activation

There can be several UIs in so called UI group, where one UI is visible on the screen at a time. UI receives this event when it is shown on screen via setactive message.

Example(s)

<i_hook name="on_activation">
<i_settext id="str1" text="Hello again!" />
</i_hook>

 

on_deactivation

There can be several UIs in so called UI group, where one UI is visible on the screen at a time. UI receives this event when it is no longer visible on screen, when setactive message has been received by another UI.

Example(s)

<i_hook name="on_deactivation">
<g_stoptimer id="very_heavy_animation" />
</i_hook>

 

Custom event hooks

User defined hooks are like subroutines that can be called by the content using i_event message . They can be defined as the internal even hooks using i_hook message, by choosing a different name for the hook, not one of the system specific event hooks. Custom event hooks helps creating applications a great deal. Instead of copying a subroutine into several places in the UI item script one can create just one event hook and then call it from several places in the script.

Like the built-in event hooks, the custom event hooks does not have parameters. However, instead of using parameters one can use a set of attributes as parameters for the event hook. The event hook uses those attributes and so can behave differently according to the attribute values.

Example(s)

<i_hook name="myownevent">
<g_debug text="a=$(this.a)" />
</i_hook>
<i_hook name="on_show">
<i_attribute name="a" value="1" />
<i_event hook="myownevent" />
</i_hook>
<i_hook name="on_hide">
<i_attribute name="a" value="2" />
<i_event hook="myownevent" />
</i_hook>

Global messages

Global messages are a set of messages that can be used in a global context of the script language. The difference between the global messages and item messages is that the global messages cannot be used within the creation of the UI item.

 

command

Command message adds a new menu command for a UI. Menu commands are part of the UI template, but still they are independent of the UI type.

Menu commands are pretty much like timers but instead of being triggered in given time they are triggered by the user.

As UI element the menu command follows the MIDP UI API specification, with the exception of supporting “empty” menu commands that can be used for separating groups of menu commands.

 

creation

Param	Type	Default	Meaning
id	string	none	Menu command ID
type	string	“screen”	Available menu command type: “ok”, “cancel”, “back”, “screen”, “exit”, help”, “item”, “stop” and “empty”
priority	int	1	Priority of the placement of menu command. The values are positive integers, where 1 = highest priority.
text	string	“”	Caption text for the menu command.

Example(s)

<command id="mycommand" text="toggle item1">
<g_show id="item1" />
<break />
<g_hide id="item1" />
</command>

submenu

Creates a menu command with a sub menu. You can use it for creating 2-level menus. This is very recommended since the menus tend to crow very large in Mupe applications. The submenu consists of command statements, which have the same syntax as the command message. Submenus cannot contain other submenus.

 

creation

Param	Type	Default	Meaning
id	string	none	Menu command ID
type	string	“screen”	Available menu command type: “ok”, “cancel”, “back”, “screen”, “exit”, help”, “item”, “stop” and “empty”
priority	int	1	Priority of the placement of menu command. The values are positive integers, where 1 = highest priority.
text	string	“<unnamed>”	Caption text for the menu command.

Example(s)

<submenu id="mysubmenu" text="submenutest">
<command id="sub1" text="choice1">
<g_debug text="choice1 chosen"/>
<command>
<command id="sub2" text="choice2">
<g_debug text="choice2 chosen"/>
</command>
</submenu>

quit

By default, quits from the current content and returns the client to the main menu, where the user can connect to a new MUPE server by specifying the address or choosing a service from the favorites list. If the exitmupe parameter is set to true the quit message exits mupe client.

Parameters

Param	Type	Default	Meaning
exitmupe	boolean	false	Set to true for quitting mupe client.

Example(s)

<command text="quit service">
<quit />
</command>

<command text="quit mupe">
<quit exitmupe="true" />
</command>

 

setactive

Makes this UI the current displayed UI. Activation message can be sent from the server or by another UI. Works with UI group that contains multiple Uis.

Parameters

Param	Type	Default	Meaning
ui	string	current	UI Id. If not specified the message is sent to this UI.

---

changeservice

Changes the currently active service. Stops handling any more messages from the current message stream and shows the user a dialog, which asks if it is ok to change to the new service. If the user gives a positive answer the service is changed, otherwise the client stays connected to the current service.

The client sends subscribe message to the newly connected service if the service has not been subscribed yet. Otherwise the client sends a activation message. if the service has already been subscribed the url parameter is not necessary. In addition, if the service has not been subscribed yet service parameter is not necessary.

Parameters

Param	Type	Default	Meaning
service	string	none	Name of the service.
url	string	none	URL to the service.

Example(s)

<changeservice service="Mupe Master Server" url="mupe.net:8780" />

 

g_removecommand

Removes a command, submenu or submenu item from a UI.

Parameters

Param	Type	Default	Meaning
id	string	none	Id of the menu command or submenu..
sub	string	none	Specified in case of removing a single sub menu item instead of removing the whole submenu.

 

 

g_setreference or g_ref (updated)

Sets a UI item as the referenced item. This has no implications to the visible UI by it is a handy way of putting one item into a “register” and then reference to it"s attributes from another item. The item attributes can be referenced using reference keyword. For instance referencing the Id of the referenced item would be like this:

<g_debug text="referenced item is $(reference.id)" />

Note: <g_setreference /> has alias <g_ref />, which is faster to write.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
index	int	0	Reference number. Values 0-7 are valid.

Example(s)

<g_setreference id="sprite1" />

<g_ref id="sprite1" />

g_foreach

This message runs a script for each item in an item group that has ID that matches the given pattern. The pattern consist of three possible filters:

• contains
• begins
• ends

They all can be speficied or left unspecified. Unspecified filter means that the script is run for all items according to that filter. As implication from that if all three filters are left unspecified the script is run for all items in that group. Inside the script the item context temporarily is changed to the item the script is run for.

The script is run sequentially for each item instead of running one clause at at time for each item that matches the pattern.

Note: If the item context is left unspecified when using this message with canvas UI, the script is run for each item group, instead of items in an item group.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item container identifiers.
contains	string	none	Item Id must contain this text
begins	string	none	Item Id must begin with this text
ends	string	none	item Id must end with this text

Example(s)

<g_foreach begins="icon_">
<g_hide />
</g_foreach>

 

g_debug (updated)

Writes debug text with System.err.println method. In real environment most probably this message does nothing (depending on the implementation again). With emulated environment this message can be used to debug the script by tracing it by placing g_debug calls to appropriate places in the script. Since version 2.31g the client has special debug cpnsole that remember last 20 debug messages.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
text	string	“”	debug text
onscreen	bool	false	Set to true for showing the debug text on device screen instead of default console.

Example(s)

<g_debug group="group1" item="image1">
<parms>
<text>coords: $(this.x) , $(this.y)</text>
</parms>
</g_debug>

 

g_showdebug (new)

Shows the client debug console and pauses the client while the user is examining the debug texts.

Example(s)

<g_showdebug />

g_alert

Alert message displays an alert box for user containing the given text string and title. The alert box is either disposed after a given time or it waits for user input. If the time is in not specified the alert box waits for user input. There are several different types of alert boxes, which are documented in detail in the “Alert” MID Profile specification [J2MESPEC]. The valid types are:

• alarm
• confirmation
• error
• warning
• info

The “info” alert type is used as default if the type parameter is not specified.

Parameters

Param	Type	Default	Meaning
title	string	none	Title text of alert box
text	string	none	Text content of the alert
type	string	“info”	Alert type: “info”, “alarm”,”confirmation”,”error”,”warning”
time	int	forever	How long the alert is displayed until discarded (ms)

Example(s)

<g_alert title="test" text="hello world" type="info" time="5000" />

 

g_send

Sends a message to the server. Uses the specified UI item as the context for referencing attributes with "this.attribute_name" notation. The message type can be either

• request
• notify
• internal
• xmlrpc

The content defines which message type it wants to use.

The message is an xml section inside the g_send tag. If can be free-form text or an xml section, with the exception that the attribute references are evaluated to appropriate attribute values before the text is sent to the server.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
Type	string	“tcp”	“tcp” = Send a tcp message to the server. “http” = Send a http request to the server. “xmlrpc” = message is an XML-RPC call Note: Default value can be overridden with default_network_protocol service info.
url	string	current service	Alternative HTTP address that receives the message.
Event	string	“on_net_response”	Event that is created for the UI when the request is responded.
Error	string	“on_net_error”	Event that is created for the UI in case for HTTP error.
port	int	8080	Server port for TCP messages. Note: Default value can be overridden by using default_tcp_port service info.
notifyonly	bool	false	Set to true for notification messages. Client does not wait for reply, nor does server send one.
encode	bool	true	Set to false if the message should not be iso8859-1 encoded before sending.

Example(s)

<g_send type="http">
clientPoll
</g_send>

<g_send type="tcp" notifyonly="true">
clientSetX $(item1.x)
</g_send>

 

g_delete

Deletes an UI item or item group with given group and Id information. If the referred item is not found the message does nothing.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.

Example(s)

<g_delete id="sprite1" />

 

g_starttimer

Adds a new timer task for the client. Timers can be used to delay actions, repeat actions and create background task that does not block the UI from user. A timer waits for certain period of time and then invokes the action given to it. After the action has been done it can be repeated with given number of times. The action can actually be multiple sequences of messages, which are separated by <break /> statement. Each time the timer is triggered next sequence of message is run until next break. if the end of message sequence is met before the timer is disposed the message sequence is started from beginning.

Parameters

Param	Type	Default	Meaning
id	string	none	timer id
ui	string	current	UI Id. If not specified, timer uses current UI.
time	int	1000	Timer delay in milliseconds
times	int	-1	Amount of times the timer activates. –1 = forever
initialise	bool	false	The 1st message sequence is run only once at timer creation.
finalise	bool	false	The last message sequence is run only once at timer disposal.

Example(s)

<g_starttimer id="newtimer" time="500" times="10">
<g_move id="sprite1" deltax="10" />
</g_starttimer>

<g_starttimer id="newtimer" time="10000" times="1">
<g_send>poll_ui $(sprite1.x)</g_send>
</g_starttimer>

 

g_pausetimer (new)

Pauses a timer with given id. If the timer is already paused calling g_pausetimer resumes it. If the timer is still active it will be paused after it has completed the current action.

Parameters

Param	Type	Default	Meaning
id	String	none	Timer Id

Example(s)

<g_pausetimer id="newtimer" />

g_stoptimer

Stops a timer with given id. If the timer is still active it will be stopped after it has completed the current action. If the timer is waiting for the next trigger it is stopped. Stoptimer not only stops the timer but also destroys it, so the timer cannot be resumed other way than with the g_starttimer statement.

Parameters

Param	Type	Default	Meaning
id	String	none	Timer Id

Example(s)

<g_stoptimer id="newtimer" />

g_input

Implements a generic text input method for canvas UI (and possible other UIs) that does not otherwise have a text input feature. The g_input message opens an edit box, where the use can input text. The visual representation of the edit box depends on the MIDP implementation.

When the edit box is closed an event occurs for the item in which context g_input was called. If the user cancelled editing the cancel event is send for the item, and if the result was accepted accept event is sent. The cancel and accept events can be given as parameters or the g_input uses default events on_textinput_ok and on_textinput_cancel.

If the user accepts the edited text input, the text can be read from $(this.textinput) attribute.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
title	string	“”	Title of the edit box.
text	sring	“”	Current text of the edit box.
max	int	128	Maximum characters allowed.
event	string	“on_textinput_ok”	Event created on the item if the user accepts the text input.
cancel	string	“on_textinput_cancel”	Event created on the item if the user cancels the text input.
input_any	bool	true	All kinds of input is allowed
input_numeric	bool	false	Input contains of numeric characters
input_url	bool	false	Input is an URL
input_password	bool	false	Input is a password
input_phonenumber	bool	false	Input is a phone number

Example(s)

<template type="canvas">
<string id='namestatic' text='name:' bold='true' x='5' y='5' />
<string id='nameedit' text='anonymous' anchor='top_right' anchorid='namestatic' x='5' selectable='true'>
<i_hook name='on_select'>
<g_input title='Your name?' text='$(this.text)' />
</i_hook>
<i_hook name='on_textinput_ok'>
<i_settext text='$(this.textinput)' />
</i_hook>
</string>
<g_allowuserinput value='true' />
</template>

g_in

Runs a script with given item context only if the item exists. If the item does not exist it tries to run the script under the <else></else> section. This command can be used for two different purposes:

1. Making writing xml faster since one does not need to specify the group and id parameters in certain situations.
2. Can be used for testing if an ui item exists or not.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.

Example(s)

<g_in id='item1' group='group1'>
<g_debug text='The item context on $(this.id) in this xml section' />
</g_in>

g_sendsms

This command is used for either sending plain sms messages to any user or sending sms invites to offline users. The sms invite invokes the client in the recipient phone and asks the user if he/she wants to connect the mupe server where the sender is connected to at the moment.

Parameters

Param	Type	Default	Meaning
type	string	"message"	"message" = Message is plain sms message "invite" = Message is an sms invite
messsage	string	none	The message that is sent to the recipient
number	string	none	The phone number of the recipient
sender	string	none	(for sms invites only) Sender avatar name
param	string	none	(for sms invites only) Server state where the recipient is invited to
phone	string	none	(for sms invites only) Phone number of the sender (optional)

Example(s)

  <g_sendsms number='+5550000' message='Hello there!' />

  <g_sendsms number='+5550000' message='Come talk with me!' sender='Jack' param='chatroom' />

 

g_reporterrors (new)

With parameter "value='true'" enables error reporting to server. Every error taking place in the client's end is sent to the server. The default implementation in the server writes these error reports into log file. Handy for field testing MUPE service.

Parameters

Param	Type	Default	Meaning
value	bool	true	Set to true for enabling error reporting.

Example(s)

<g_reporterrors />

Item messages: Basic script functionality

 

i_hook (updated)

This message (re)defines an event hook handler for a UI item. The event handlers can be one of the build-in handlers (for intance on_show) or defined by the content. The event hooks works as subroutines and they can be either invoked with a i_event message or by the system (in case of predefined event hooks). The script that is run for each event hook is inside the corresponding i_hook tag.

One can define event hooks for both UI items and item groups. If the event hook is defined in the global level in the template it is defined for the default group.

It is also possible to define an event hook another way (since 2.30b). The client assumes that every tag starting with characters "on_" are event hooks. For example:

<on_create>
<scripthere /> 
</on_create>

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
name	string	none	Name of the event hook

Example(s)

<i_hook name="on_show">
<g_move id="sprite1" x="10" />
</i_hook>

 

i_event

Invokes an event for a UI item. Events are like calls to subroutines defined for a UI item. The events can be "hooked" using the i_hook message. If the given event is hooked the subroutine under the appropriate the i_hook tag is run.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current	item	Item reference.
hook	string	none	Name of the hook that handles the event
<parameters>	params	None	Extra parameters for the event. Set of attributes that are set for the item before calling the event.

Example(s)

<i_event hook="on_show" />

<i_event hook="my_own_event_hook" myparam="foo" />

 

i_loop (updated)

Runs a script in a loop for given number of times. If the times parameter is zero the message does nothing.

While the loop is run other messages are not handled. In addition, there is no functionality to time or delay the actions. If the content creator wants to implement animations or timed events he/she should use a timer instead of loop.

Note: By default the index of the current iteration loop can be found from attribute "loop_index".

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
times	int	0	Number of times the loop is run
attr	string	"loop_index"	Alternative attribute name for loop_index. Needed for nested loops.

Example(s)

<i_loop times="5">
<g_show id="image_$(global.loop_index)" />
</i_loop>

Item messages: Attribute manipulation

These messages are used for defining custom attributes for UI items and manipulating them in different ways.

 

i_attribute

Defines an attribute for an UI item. There are three basic types that the attribute may use by default

• int
• bool
• string

The "int" type is used for initializing an integer attribute, "bool" type is used for boolean values and the "string" for strings. If the type parameter is not specified the "string" type is used by default.

Attributes are properties of an UI item. The use of attributes is comparable to conventional object-oriented languages, with the exception that the attributes are not protected by any way. Any UI item can change or refer to an attribute of another UI item.

Parameters

type ||string||“string”||“int” = value is initialized as integer “string” = value is initialised as string“bool” = value is initialized as Boolean

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
name	string	none	Attribute name
value	any	none	The initial attribute value.
<var>	string	None	Sets attribute <var> to given value.

Example(s)

<i_attribute name="str_test" value="foobar" />

<i_attribute name="int_text" type="int" value="5" />

<i_attribute name="bool_test" type="bool" value="true" />

<i_attribute str_test2="test 1 2 3" />

 

i_inc

Increases the value of an integer attribute. The attribute is referred with group, id and attr parameters, where the group and id define the item and the attr defines the attribute in question. The value is increased by the amount of value parameter. If the value parameter is not specified the value is increased by 1.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value	int	1	The amount how much attribute value is changed

Example(s)

<i_inc attr="amount" value="10" />

 

i_dec

Decreases the value of an integer attribute. The attribute is referred with group, id and attr parameters, where the group and id define the item and the attr defines the attribute in question. The attribute value is decreased by the amount of value parameter. If the value parameter is not specified the value is decreased by 1.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value	int	1	The amount how much attribute value is changed

Example(s)

<i_dec attr="amount" value="10" />

 

i_multiply

Multiplies the value of an integer attribute with a given value. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. The value is multiplied by the amount of value parameter and the result is stored in the attribute. If the value parameter is not specified the message does nothing.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value	int	1	The multiplier

Example(s)

<i_multiply attr="amount" value="2" />

 

i_divide

Divides the value of an integer attribute with a given value. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. The value is divided with the value parameter. If the value parameter is not specified the message does nothing.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value	int	1	The divider

Example(s)

<i_divide attr="amount" value="2" />

 

i_modulo

Calculates modulo for an integer attribute and the given value and stores the result back to the attribute. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. If the value parameter is not specified the message does nothing.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value	int	1	The divider

Example(s)

<i_modulo attr="amount" value="100" />

 

i_absolute

Calculates absolute value for an integer attribute and stores the result back to the attribute. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. If the value parameter is not specified the message does nothing.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name

Example(s)

<i_absolute attr="negative_int" />

 

i_substring

Cuts a sub string from a given string. The result will be set as the value of given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but u need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the specified sub string cannot be extracted from the source string the resulting string will be an empty string.

If the end attribute is left unspecified the sub string will be the end of the string starting from the given start index.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be cut.
start	int	0	Start index of the sub string (zero based).
end	int	none	End index of the sub string.

Example(s)

<i_substring attr="title1" text="$(edit1.text)" start="5" end="10" />

i_stringlength

Calculates length of a given string argument. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but u need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String which length is calculated.

Example(s)

<i_stringlength attr="title1" text="hello world" />

 

i_stringtoken

Extracts a string token from a given string using given delimiter (space character by default). The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be tokenized.
delimiter	string	“ “	Delimiter string that is used for tokenizing the original string.
Index	int	none	Index of the token.
allowmultiple	bool	false	Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.

Example(s)

<i_stringtoken attr="title1" text="hellofooworld" delimiter="foo" index="1" />

 

i_findtoken (new)

Returns index of a given token. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be tokenized.
delimiter	string	“ “	Delimiter string that is used for tokenizing the original string.
allowmultiple	bool	false	Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.
value	string	""	Token that is searched in the string.

Example(s)

<i_findtoken attr="tokenindex" value="world" text="hellofooworld" delimiter="foo" />

 

i_settoken (new)

Sets a new value for token with given index. The modified string will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be tokenized.
delimiter	string	“ “	Delimiter string that is used for tokenizing the original string.
Index	int	none	Index of the token.
allowmultiple	bool	false	Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.
value	string	""	New value of the token.

Example(s)

<i_settoken attr="title1" value="bar" text="hellofooworld" delimiter="foo" index="1" />

 

i_removetoken (new)

Removes given token completely and also removes the delimiters around the token. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be tokenized.
delimiter	string	“ “	Delimiter string that is used for tokenizing the original string.
Index	int	none	Index of the token.
allowmultiple	bool	false	Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.

Example(s)

<i_removetoken attr="worldremoved" text="hellofooworld" delimiter="foo" index="1" />

i_numberoftokens

Calculates how many string tokens a given string has using given delimiter (space character by default). The result will be set as the value of given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but u need to use new attribute and reset the read-only attribute using appropriate set-message (such as i_settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute where the result is stored.
text	string	none	String that is to be examined.
delimiter	string	“ “	Delimiter string that is used for tokenizing the original string.
allowmultiple	bool	false	Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.

Example(s)

<i_numberoftokens attr="title1" text="hello foo world" delimiter="foo" />

item messages: Conditional statements

Conditional statements are statements that tests a certain attribute value or item and if the test is successful script defined inside the conditional statement is run. However, its also possible to define a special else branch inside the conditional statement, which is run if the test fails. The structure of conditional statement is as follows:

<condition>
“this script is run if the test is successful”
<else>
“this script is run if the test fails”
</else>
“this script is run if the test is successful”
</condition>

 

i_equal (updated)

Conditional statement that tests if two attribute values are equal. The attribute is referred with group, id and attr parameters, where the group and id defines the item of which property the attribute is and the attr parameter is the attribute name.

In addition the method can used to test to integer values instead of testing an attribute. This can be done by specifying parameter value0 instead of attr. Parameter value0 represents the left side of the conditional statement (value0 == value).

If the referred attribute value is equal to the given value parameter the script under the tag is run.

Parameters

Param	Type	Default	Meaning
<identifiers>	params	current item	Item reference.
attr	string	none	Attribute name
value0	int/string	none	Optional value that is tested instead of attribute.
value	int/string	"true"	Compared value. Default value has changed to "true" for easier boolean value tests.
numeric	bool	false	Set to true for forcing numeric comparison.
nocase	bool	false	Set to true if comparison of two strings should be case insensitive.