Callbacks

To make use of dynamic information the content of certain elements and attributes are evaluated in order to translate special callback expressions. They have the form $(name) or $(name:arg) and are dynamically replaced by their return values.

Things to consider when writing callbacks:

• Callbacks argument: necessity of an argument, limitations on the argument.
• Extra white space on callbacks name and argument: see Common errors.
• Character case of the callback and its argument
• There are 2 types of callback placeholders, $(...) and $[...]. The difference between them is shown below
• Callbacks can be stacked on top of each other, for example: $(callback2:$(callback1:param))

Common errors

Here are some examples of common errors:

Correct syntax:

$(max_registrations)
$(set:vol_speakers)

Examples of errors:

Available callbacks

Differences between placeholders

Callback can be used with two different placeholders, $(...) and $[...]. The main difference between them is the time when the value will be fetched.

In the following example:

<?xml version="1.0" encoding="UTF-8"?>
<SnomIPPhoneBatch>
    <SnomIPPhoneMenu id="menu">
        <MenuItem name="mi1" id="mi1">
            <Url>http://link_to_this_example.xml#sub=*[@id="text"]&amp;var:text=$[sel]</Url>
        </MenuItem>
        <MenuItem name="mi2" id="mi2">
            <Url>http://link_to_this_example.xml#sub=*[@id="text"]&amp;var:text=$[sel]</Url>
        </MenuItem>
        <MenuItem name="mi3" id="mi3">
            <Url>http://link_to_this_example.xml#sub=*[@id="text"]&amp;var:text=$[sel]</Url>
        </MenuItem>
    </SnomIPPhoneMenu>
    <SnomIPPhoneText id="text">
        <Text>selected id = $(var:text)</Text>
    </SnomIPPhoneText>
</SnomIPPhoneBatch>

In the first page the sel callback is not yet replaced. But after one of the MenuItem is selected, the sel callback will be replaced with the selected MenuItem id and it will be printed on second page through the var callback.

Result:

Encoding and callbacks

It is important to understand how encoding and callbacks interact. This behavior is relevant for cases when the returned value of the callback would break the URL format or the value might/will change but we still wish to hand over the changed value (for example, when using translation or templates).

We will illustrate this behavior with an example. In this example, we have a callback result that, when used in an URL, would break the URL format. Let's assume that we would like to display a MenuItem which takes its name using the lang callback. The name of the MenuItem should be the translated name of the country"Trinidad & Tobago". The name of this country contains space and '&', which are both not allowed in a URL.

Here is the example code:

<?xml version="1.0" encoding="UTF-8"?>
<SnomIPPhoneMenu>
        <MenuItem name="First example $(var:b)">
		<url>phone://mb_nop#var:b=%24(lang:lang_cntry_TTB)</url>
	</MenuItem>
       <MenuItem name="Second example $(var:b)">
		<url>phone://mb_nop#var:b=$(lang:lang_cntry_TTB)</url>
	</MenuItem>
</SnomIPPhoneMenu>

The code contains two MenuItem examples. The only difference between them is the usage of the dollar sign:

• In the First example, the dollar sign is URL-encoded, which causes the Minibrowser to store the callback in the variable b
• In the Second example, the dollar sign is not encoded, which causes the Minibrowser to store the result of the callback in the variable b

To see the effect of this difference, open first this Minibrowser page, choose the First example and press OK. The phone will show:

Then open the State page and look at the end of the page. You will see:

Selection list: 2
-----------------
## First example Trinidad & Tobago
data: _xpath:/*
_url:phone://mb_nop#var:b=%24(lang:lang_cntry_TTB)
_track:
_id_attr:name
_id:First example $(var:b)
## Second example Trinidad & Tobago
data: _xpath:/*
_url:phone://mb_nop#var:b=Trinidad & Tobago
_track:
_id_attr:name
_id:Second example $(var:b)

Callbacks: 2
-------------
$.current_path
$.module_id_of_current_line

Minibrowser vars: 2
---------------------
cur_pkey: 
b: $(lang:lang_cntry_TTB)

Look at line 24 above, at the value of variable b. Because we chose the first example, the phone shows the full name of the country, "Trinidad & Tobago". Because the dollar sign for the lang callback is URL-encoded using '%24' (%24(lang:lang_cntry_TTB)), the callback was stored in the variable b, and the callback was parsed later, when the URL was called.

Close the Minibrowser page. Then open it again, choose the Second example and press OK. The phone will show:

Then open again (or refresh) the State page and look at the of the page. You will see:

Selection list: 2
-----------------
## First example Trinidad
data: _xpath:/*
_url:phone://mb_nop#var:b=%24(lang:lang_cntry_TTB)
_track:
_id_attr:name
_id:First example $(var:b)
## Second example Trinidad
data: _xpath:/*
_url:phone://mb_nop#var:b=Trinidad & Tobago
_track:
_id_attr:name
_id:Second example $(var:b)

Callbacks: 2
-------------
$.current_path
$.module_id_of_current_line

Minibrowser vars: 2
---------------------
cur_pkey: 
b: Trinidad

• Look at line 24 above, at the value of variable b. Because we chose the second example, the phone shows only the first part of the country name, "Trinidad".
• Because the dollar sign for the lang callback is not URL-encoded ($(lang:lang_cntry_TTB)), the result of the callback was stored in the variable b, which was "Trinidad & Tobago".
• And then, when the URL was built using the value of b, the URL was "phone://mb_nop#var:b=Trinidad & Tobago", which was an incorrect URL (broken by the un-encoded space).
• As a result, the URL became "phone://mb_nop#var:b=Trinidad".

• Page:
  Boolean Callbacks
• Page:
  Callback arch_series
• Page:
  Callback bool_eval
• Page:
  Callback checkbox_property
• Page:
  Callback condition
• Page:
  Callback create_url
• Page:
  Callback current_input
• Page:
  Callback current_line
• Page:
  Callback date
• Page:
  Callback display_type
• Page:
  Callback empty
• Page:
  Callback enum
• Page:
  Callback fragment
• Page:
  Callback get_cmd
• Page:
  Callback lang
• Page:
  Callback lines
• Page:
  Callback list_size
• Page:
  Callback math_eval
• Page:
  Callback max_registrations
• Page:
  Callback mod_ifc
• Page:
  Callback on_off
• Page:
  Callback phone_state
• Page:
  Callback remove_cmd
• Page:
  Callback set
• Page:
  Callback setcache
• Page:
  Callback show_feature
• Page:
  Callback status_message
• Page:
  Callback time
• Page:
  Callback urlencode
• Page:
  Callback user_displayname
• Page:
  Callback var
• Page:
  Callback var_ifc
• Page:
  Callback wifiscan
• Page:
  Callback wlang
• Page:
  Callbacks
• Page:
  Callbacks edit_mode and next_edit_mode
• Page:
  Callbacks for function keys
• Page:
  Callbacks sel and lastsel