RSS

Navigation





Search the wiki
»

PoweredBy

itrezzo Technical Support Wiki

How to Make an IPA Guide

RSS
Modified on 2014-01-15 07:16 by Lalaine F. Categorized as HowTo

How to Make an IPA Guide




1. Main structure

Basically, IPA consists of five .xml files: *_actions.xml, *_app.xml, *_def.xml, *_screens.xml and *_trans.xml. Substitute '*' with the name of the IPA. There are additional files that may be required for your application. For example: *_evtgens.xml

*_app.xml is system file of IPA. It contains information about other files and platform type etc.

*_actions.xml is functional file that contains information about actions in future application (e.g. Refresh screen, ShowDialog etc.).

*_def.xml is a functional file that contains information about data items of IPA which can be String or Table.

*_screens.xml describes the way of interaction between actions, data items and view component of IPA (screens).

*_trans.xml is used for transferring html or transferring with email

All files are case insensitive, except setting path to HTML tag.

Articles given below illustrate how to use tags to make IPA for each file.



2. *_app.xml

At the beginning tag "xml" with attribute "version"

<?xml version="1"?>

*_app.xml has 3 main tags: Application, Documents, and Document. Application and Documents should have both start-tags and end-tags. Document is empty-element tag.

"Application" has parameters:
  • Name - name of application
  • Type - xml file type. In this case, value should be "Application"
  • Version - IPA version
  • Platform - platform type. Value should always be "RIMJ2ME"
  • Persist saves all data to device memory. Value can be: Yes or No
  • Priority Value should be 1.

"Documents" tag that contains group of tags "Document".

"Document" has following parameters:
  • DocAlias - alias of each other document of IPA
  • Type - type of other documents in IPA; values can be Definitions, Actions, Screens, Transport, correspondingly.
  • Version - version of each file

For example, ebay search IPA:

<?xml version="1.0"?>
<Application Name="itrezzo Web Search" Type="Application"  Version="1.0" Platform="RIMJ2ME" Persist="Yes" Priority="1">
   <Documents>
		<Document DocAlias="ebayDef" Type="Definitions" Version="1"/>
   		<Document DocAlias="ebayScreens" Type="Screens" Version="1"/>
   		<Document DocAlias="ebayActions" Type="Actions" Version="1"/>
   		<Document DocAlias="ebayTransport" Type="Transport" Version="1"/>
   </Documents>
</Application>

Back to Top

3. *_actions.xml

At the beginning tag "xml" with attribute "version"

<?xml version="1"?>

Actions is container tag for group of tags Action.

Action is empty-element tag. Has next attributes:
  • Name - name of action
  • Type - type of action. According to each value there is additional necessary attributes of tag Action . Values can be:
    • Transport - action is taken from Transport.xml
      • TransportName - name of action in *_transport.xml
    • ScreenPusher opens new screen with specified in ScreenName parameter name
      • ScreenName - Screen name to open (from *_screens.xml)
      • PopCurrent - Closes current screen before opening new one; values can be Yes/True or No/False. If current screen is first, IPA will be closed.
    • ScreenCacher - was used in old version of APE, and is not using after version 4.5.x.x.
      • ScreenName
    • ScreenPusherFilterData - was used in old version of APE, and is not using after version 4.5.x.x.
      • ScreenName
    • ResetScreen resets screen values to their initial state.
      • ScreenName
    • RefreshScreen refreshes data on specified screen
      • ScreenName
    • CloseScreen action with this type closes specified screen
      • ScreenName
    • ShowAlert alert will be shown
      • Message - Dataitem name, that contains message
      • Fatal - yes (true)\no (false) values. Means if alert reports fatal error. If alert reports fatal error, then APE About screen is displayed
      • Sync - yes (true)\no (false) values. Modal alert, stops the execution of APE until button is pressed
    • ShowBrowserURL Shows URL in BlackBerry default browser.
      • URL_DataItem - DataItem name that contains URL
    • SetDataItem sets DataItem; for DataItems that are changed under some conditions
      • DataItemName
      • Source - Source of DataItem. Possible values: "static" (e.g. value="2"), "DataItem"
      • Value - for DataItem. Values can be numeric or source DataItem name
    • ShowDialog shows pop-up dialog (set in screens.xml) that
      • DialogName - name of pop-up from screens.xml
    • ShowPendingBox shows pop-up with loading progress
      • Message - message to be shown in loading pop-up
      • GaugeOn - specifies either to show progress bar; values can be Yes/True or No/False.
      • ProviderType - Value should be "Transport" if progress provider is a transport or "Action" if progress provider is an action
      • Provider - Transport name from *_trans.xml or Action name from *_action.xml
    • Launch launches other IPA from current IPA. For IPA which is used as main screen of application
      • DataItemName - name of DataItem, that contains IPA name
      • Hide - hides current IPA
    • LaunchMultiple Launches several IPA(s)
      • dataitem - DataItem that contains IPAs names separated by comma (',') or single IPA name
      • hide - values can be Yes/True or No/False. if FALSE - current IPA will remain shown during and after launch(s)
    • StartEventGen starts event generator
      • EGName - event generator name from *_evtgens.xml
    • StopEventGen stops event generator
      • EGName - event generator name from *_evtgens.xml
    • ResetEventGen restarts event generator
      • EGName - event generator name from *_evtgens.xml
    • Transport launches transport action from trans.xml; transport won't work without action with transport type
      • TransportName - name of transport action to launch
    • TransformTable performs transformation one table into another. See example 1.
    • ClearTable - Clears table (delete all rows)
      • tableDIN - name of Table DataItem
    • AddTableNode Action for adding node into Tables.
      • path - path "where" to add
      • node - node description; see example 2.
    • CopyTableNode copies node(s) of one table to other table
      • Source - path what node(s) to add. (usign \ character)
      • Dest - path where to copy.
    • deletetablenode - deletes table node
      • expression - path "which" node(s) to delete
    • getImageGroup loads images, set in Imagelist attribute
      • ImageList - names of dataitems with Image type, separated by coma
    • getimage loads image
      • URLDI - image URL
      • ResultDI - dataitem name where image should be put
      • RespCodeDI - for exception handling; http code, value must be "200"
      • RespDescDI - for exception handling; http description
    • Playtune - action that plays tune.
      • Tune - tune contains tune sequence separated by comma
      • Vol - specifies volume to play tune;
    • playmidi plays midi
      • streamDI - DataItem name
      • PlayUntilDI - DataItem name, if it's value = 1 - play until StopAllMidi action is performed
      • VolumeDI - volume DataItem name
    • GetMidi - loads MIDI file
      • urlDataItem - url for midi
      • respDataItem DataItem name to write result to
      • respCodeDI name of DataItem for result code
      • respDescDI name of DataItem for description
    • vibrate for enabling device vibration
      • Duration - string that contains int or DataItem name
    • Test - was used in old version of APE, and is not using after version 4.5.x.x.
      • Test
      • Result
    • BringToForeground - Brings APE to foreground.
    • Bootstrap - not usually used by user. used for APE bootstrap
    • performer Block of actions. Starts actions one after another. Corresponds to <Perform> ... </Perform> block in Action.xml or to "Performer" action type
    • if Performs "if" based on condition. See example 3.
    • ControlStatement doesn't need additional parameter; has subtag Switch (with attribute Type and Target), which contains Case tage and Perform where actions are placed. See example 4

example 1
<Action Type="TransformTable" Name="CL_ImportEmailToDevice">
   <DataSet Set="CL_EmailTable::Email/Body/Line">
    <AddNode Path="CL_ChecklistsOnDevice::checkLists/checkList[@id=CL_GeneratedUID] "
                Node="item(@id='[%CL_itemUUID%]' @name='1' @sequence='0' lastChangedBy='[%UserEmail%] deleted='false' checkStatus='0')" />
   </DataSet>
  </Action>

example 2
item(@id='100500' @name='pupkindata' @sequence='0' @lastChangedBy=[%UserEmail%] @deleted='false' @checkStatus='0')

example 3
<Action Name="..."  Type="If" >
  <If Condition="....">
   <Perform Mode="Serial">
    <Action Name="..."/>
   </Perform>   <Else>
    <Perform Mode="Serial">
     <Action Name="..."/>
    </Perform>
   </Else>
  </If>
 </Action>

example 4
<Action Name="ALERTS2"  Type="ControlStatement" >
   <Switch Type="dataitem" Target="ALERTS2">
     <Case Value="0">
       <Perform Mode="Serial">	
          <Action Name="ALERTS_setSMTP1_Off2"/>
          <Action Name="ALERTS_setSMTP2_Off2"/>
          <Action Name="ALERTS_setSUB1_Off2"/>
          <Action Name="ALERTS_setSUB2_Off2"/>
       </Perform>
     </Case>
     <Case Value="1">
        <Perform Mode="Serial">
          <Action Name="ALERTS_setSMTP1_On2"/>
          <Action Name="ALERTS_setSMTP2_On2"/>
          <Action Name="ALERTS_setSUB1_On2"/>
          <Action Name="ALERTS_setSUB2_On2"/>
        </Perform>
      </Case>
    </Switch>
  </Action>

Back to Top

4. *_def.xml

At the beginning tag "xml" with attribute "version" and "encoding"

<?xml version='1.0' encoding='UTF-8'?>

Definitions tag is container tag for all other tags of def.xml; Definitions tag has both start-tags and end-tags.

Definitions tag has following attributes:
  • Type - value should be "Definitions"
  • Version - version of file
  • Platform - version of platform; value should be "RIMJ2ME"
  • Persist - verifies if changes are saved in device memory; value can be Yes\No.
  • priority - sets priority

FQN tag has both start-tags and end-tags. ?????

FirstScreen tag has both start-tags and end-tags. Contains name of main screen. Loads the screen with set name from screens.xml as first screen

OnInit tag has both start-tags and end-tags and attribute InitPolicy with numeric value (e.g. "0"). Sets actions that will be performed on initialization. OnInit tag is container for Perform tag.

Perform tag has both start-tags and end-tags and attribute Mode with value "Serial" (to implement actions in a serial way). Perform is container for Action tag.

Action tag has both start-tags and end-tags and attribute Name that contains name of action to perform from action.xml. There can be several actions for OnInit event.

Styles tag has both start-tags and end-tags and is targeting to set the parameters to display all the controls (something close CSS). Styles is container for all Style tag.

Style tag has both start-tags and end-tags and attribute Name where name of tag StyleClass should be. Style tag is container for Default tag.

Default has both start-tags and end-tags and is used for setting parameters for Style. Default tag is container for all "Property" tags (there can be several Property tags).

Property is empty-element tag. It has attributes Name (any parameter name that is using to describe control, such as Width, Height etc.) and Value (value of Name parameter, e.g. if Name=Height, Value=50 - height of control will be 50px).

DataItems tag has both start-tags and end-tags and is container for DataItem tags.

DataItem tag has both start-tags and end-tags and info about all dataitems. Container for Template tag if it's necessary. Has next attributes:

  • Name - name of dataitem
  • Type - type of dataitem; may be string, table, long\int (for numeric)
  • Initial - sets default value
  • Persist - to save in device memory

    Template tag has both start-tags and end-tags; can display xml. If dataitem name is displayed within square brackets and % sign - its value will be taken. For example:


&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;soap:Body&gt; [%SomeDataitemName%]
&lt;/soap:Body&gt;

Back to Top

5. *_screens.xml

Screens tag has both start-tags and end-tags; Screens tag is container tag for all other tags of screens.xml.
It contains tags Dialogs and Screen

Dialogs tag has both start-tags and end-tags and container for Dialog tag. Dialogs tag describes pop-up dialogs; all action that calls dialog must have dialogs described here (in screens.xml); otherwise error is occurred (except action "ShowPendingBox"). Each dialog is described in separated Dialog tag container

Dialog tag has both start-tags and end-tags. Dialog tag has attribute "Name" and is container for Caption and Controls tags.

Caption tag has both start-tags and end-tags. Specifies title of the dialog.

Controls tag has both start-tags and end-tags and is container for all Control tag.

Control tag can be empty-element or have tag both start-tags and end-tags (to be container). It has the following attributes:

    • Type - type of control; can be Button, EditField, datefield, button, gridfield, inputcheckbox, outputcheckbox, labelfield, richtextfield, dirconneditfield, phoneeditfield, emaileditfield, editfield, urleditfield, realnumeditfield, bpineditfield, lowercaseeditfield, uppercaseeditfield, integereditfield, hexeditfield, passwordeditfield, autotexteditfield, activeautotexteditfield, emailaddresseditfield, basiceditfield, choicefield, custombutton, tablemappedlist
    • Label - static text; value means text that is displayed on control
    • DataItemName - data that is taken from specific dataitem (def.xml);
    • NB! If DataItem type is table and html should be put to this table, then in DataItemName attribute value after actual name of DataItem two colons and html path to necessary data. In this case Control type should be "labelfield" (information more for Screens than Dialogs)


      For example, how temperature is shown in weather informer:
      	<Control Type="labelfield" StaticText="Current t: " DataItemName="Weather_htmlInfo::html/body/div[@class='content']/tr/td[0]/span" />
      In def.xml we have DataItem with name "Weather_htmlInfo" and Type="table"
      And there is other DataItem with Initial where URL of the site is prescribed
      	<DataItem Name="WDP_get_url" Type="String" Initial="http://pogoda.yandex.ru/34504/" Persist="No"/>

    • Actions - specifies action of control; e.g. value can be "CloseOnClick" for Cancel button
    • Max - for edit fields maximum size of field
    • Style - name of style from *_def.xml

Events tag has both start-tags and end-tags and describes of control; container for events tags; they can be: OnClick, OnDataItemChange, GotFocus, LostFocus, ScreenPush, ScreenPop.

OnClick tag (or other event tag from above) has both start-tags and end-tags and is container for Perform tag

Names sub-tag only for OnDataItemChange event. Names tag has both start-tags and end-tags and is container for Name tag.

Perform tag has both start-tags and end-tags and is container for Action tag. Perform tag has attribute "Mode" with value serial.

Action tag has both start-tags and end-tags and specifies action to do at this event. The tag has attribute "Name" - name of action from actions.xml.

<Events>
	<ScreenPush>
		<Perform Mode="Serial">
			<Action Name="SentSOAPGetInfo"/>
		</Perform>
	</ScreenPush>
</Events>

Screen tag has both start-tags and end-tags. It contains tags to determine screens of IPA.

Caption tag has both start-tags and end-tags. Specifies title of the screen.

Input file name for content of the screen, that is set in *_app.xml

SidePanel has both start-tags and end-tags. Adds a side pane (vertical) on the screen. SidePanel is container for Background and Controls

Background has both start-tags and end-tags. Specifies background parameters for side panel. Has attributes Type (with value SolidColor) and Color (sets color).

Controls has both start-tags and end-tags and container for Control tag. Specifies elements on side panel.

Control has both start-tags and end-tags and is container for Events tag. Control has attributes:

  • Type - value can be "CustomButton"-specifies type of control on side panel
  • Label - specifies label of control
  • FocusedImage - value is name of Dataitem that has URL of image to display control when it's on focus.
  • UnfocusedImage - value is name of Dataitem that has URL of image to display control when it's not on focus
  • StyleClass - value is name of Style from def.xml.

    Events is has both start-tags and end-tags and has container for OnClick tag. Onclick tag is container for Perform tag. Perform has attribute Mode with value = "Serial"


Events tag has the same meaning and possible functionality as Events of Dialogs (see above).

Controls tag of the Screen has has the same meaning and possible functionality as Controls of Dialogs (see above).

Menu can be empty-element tag (basic menu) or can have both start-tags and end-tags (to add more menu items). Menu is container for tag MenuItem

MenuItem tag has both start-tags and end-tags and attribute "Name"; attribute Name specifies the name of menu item. MenuItem tag is container for tag Perform

Perform tag has both start-tags and end-tags and attribute "Mode" with value "Serial". This tag specifies the action to perform for the MenuItem.

Action is sub-tag of Perform tag; Action is empty-element tag; has attribute "Name" - name of action to perform from actions.xml

For example:
<Menu>
	<MenuItem Name="Refresh">
		<Perform Mode="Serial">
			<Action Name="Weather_Loadprogress"/>
			<Action Name="getWeather_weatherInfo"/>
		</Perform>
	</MenuItem>
</Menu>

Back to Top

6. *_trans.xml

Transports is container tag for group of all Transport tags.

Transport has both start-tags and end-tags and is container tag for all other tags. All the tags below are sub-tags for Transport tag.
This tag has next parameters:
  • Name - name of transport
  • Encoding - sets encoding for received data
  • RequestDIN - URL
  • ResponseDIN - Dataitem name where result will be written
  • ResultCodeName - http code
  • ResultDescName - http description
  • URI="[%TURIGetInfo%]" - duplicate of RequestDIN; for support of old versions of IPAs
  • Timeout - required attribute; values are integers
  • Type - type of transport; value can be:
    • itrezzo-http-get for http get request (file, image etc.)
    • itrezzo-http-post http post request
    • itrezzo-http-post-zip same with post, but with zip archive
    • RIM-Email sends email to user
    • HTTP-SOAP Method="getPropertyInformation" "GetWhoIS" transport for sending SOAP queries; is not usually used; its functionality can be reached with http-post\get
    • KSOAP Method="GetWhoIS" transport for sending SOAP queries; is not usually used; its functionality can be reached with http-post\get

HTTP_HEADER has both start-tags and end-tags and is container tag for Property tag. HTTP_HEADER is also sub-tag of Transport tag and is for setting http head fields (content-length etc.) See http headers

Property tag is empty-element tag. Has next parameters:

  • Name - name of header
  • Value - value of header

Content tag is empty-element tag. Has parameter "DataItemName". Contains e.g. DataItem name with Template tag where SOAP query is presented to connect to web-services.

Input and Output tags have both start-tags and end-tags and is container tag for Parameters tag. Output has attribute Type with values e.g. String.

Parameters has both start-tags and end-tags and is container tag for Parameter tag

Parameter is empty-element tag.

Example of Transport.xml
<Transports>
	<Transport Type="itrezzo-http-get" Encoding="UTF-8" Name="updateWDP_WeatherInfo"	
				RequestDIN="WDP_get_url"
				ResponseDIN="WDP_htmlInfo"
				ResultCodeName="WDP_weather_info_result"
				ResultDescName="WDP_weather_info_desc">
		<HTTP_HEADER>
			<Property Name="Connection" Value="Keep-Alive"/>
		</HTTP_HEADER>
	</Transport>
</Transports>

Back to Top

itrezzo Support Wiki version 3.0.5.619. See the itrezzo web site or the itrezzo blog site to learn about contact management on your smartphone.

The Trademark RIM® BlackBerry® Smartphone and BlackBerry® Enterprise Solution is owned by Research In Motion Limited and is registered in the United States and may be pending or registered in other countries. The owner of this wiki site is not endorsed, sponsored, affiliated with or otherwise authorized by Research In Motion Limited.

Microsoft Outlook, Microsoft Exchange Server, Microsoft Active Directory, Microsoft Windows Mobile are trademarks of Microsoft.