1.6. MWT APIs
Prev Chapter 1. Mobile Web Toolkit Next

1.6. MWT APIs

Whether you decide to write widgets using taglibs (see Chapter 2) or PHP you have access to a set of APIs. MWT APIs have already been classified in paragraph Widget Body, here we we provide a detailed description.

To find out how to access MWT APIs in PHP scripts and taglibs read these paragraphs:

Through this APIs you can retrieve the list of supported device models and brands, get informations about the current device, perform a device switch to render pages for a specific device.

int width(val=0);
string val=0;

Call this function get the screen width of the current device. If parameter val is omitted the function returns the witdh in pixel, if val is negative then its value is substracted from the current width and the result is returned. Alternatively val can be a percentage, in this case the percentage of the screen width is returned.

array devices(limit=0);
int limit=0;

This function returns a hashtable containing brands, models, and device IDs of the supported devices. If limit is given, then information about only limit number of devices is returned. The returned PHP array is a hashtable whose keys are brand names, for each brand key the corrisponding value is a hashtable whose keys are models names. The value corresponding to a model key is the device ID.

Example 1.5. Getting the device ID of all models in a specific brand

					
$devs = $mwt->$devices();
$nokiaModelsID = array();
$nokiaModels = $devs['Nokia'];				
foreach ($nokiaModels as $model=>$id) {
	$nokiaModelsID[] = $id;
}

array brands();

Returns an array containing the names of all supported brands, the same result can be obtained calling the PHP function array_keys with the value returned by the devices function.

array models(brand);
string brand;

Returns an array containing the names of all the supported models for the brand specified by the brand parameter.

bool useDevice(deviceID);
int deviceID;

Call this function to perform a device switch, the deviceID parameter identifies the device you want to switch to. The function returns true on success and false if an invalid device ID is given.

MWT_DeviceInfo deviceInfo();

Returns a MWT_DeviceInfo object for the current device. MWT_DeviceInfo is a simple PHP class that holds informations about a device. You can access these informations in the following way:

Example 1.6. Getting informations about the current device:

			$devObj = $mwt->deviceInfo();
			$id = $devObj->id;
			$userAgent = $devObj->ua;
			$brand = $devObj->brand;
			$model = $devObj->model;
			$screenWidth = $devObj->screenWidth;

array widthClasses();

Returns an array containing the values of screen widths used when rescaling images and content (see paragraph Image Server).

After reading this paragraph you should read the section describing how to link content with the standard A tag

string urlHome();

Returns the URL for the home of the mobile site.

string urlForContent(pathToContent);
string pathToContent;

This function can be used to link content. The returned URL is in the form of MWT URLs (see paragraph URL rewriting) and contains the current device ID. The leading part of parameter pathToContent identifies the type of content while its trailing part maps the content to link. Possibile cases are summarized in the following table:

pathToContentgenerated URL
post/postIDhttp://127.0.0.1/mwt/index.php/mobile/ua_id/archives/postID
comment/postIDhttp://127.0.0.1/mwt/index.php/mobile/ua_id/archives/comments/postID
page/pagepathhttp://127.0.0.1/mwt/index.php/mobile/ua_id/pages/pagepath
category/catIDhttp://127.0.0.1/mwt/index.php/mobile/ua_id/archives/category/catID
userpage/mypagehttp://127.0.0.1/mwt/index.php/mobile/ua_id/generic/mypage

string config(paraName);
string paraName;

This function lets you retrieve widget configuration (see Widgets configuration). Parameter paraName is the name of the configuration parameter whose value you want to retrieve.

string input(paraName,  
 defaultValue=0); 
string  paraName;
string  defaultValue=0;

This function lets you retrieve the value of input parameters (see Page structure and CMS integration). Parameter paraName is the name of the input parameter whose value you want to retrieve. Sometimes you can place widgets in pages that don't provide them the expected input parameters, in this cases you can call specify a value for the defaultValue parameter when calling input: if paraName it is not found, input returns defaultValue.

string css(optionName);
string optionName;

Use this function to retrieve the value of CSS options defined by the current theme (see paragraph Styles)

string imagesPath(themeName='');
string themeName='';

Returns the relative path of a theme's images directory. Use this function to insert graphics from themes in your widgets. If parameter themeName is not given, the relativa path of current theme's images directory is returned (see paragraph Theme Structure).

string postRequest(url, data);
string url;
array data;

You can use this helper function to perform a HTTP post request. Parameter url is the target URL for the request and data is a PHP hashtable containg key-values pairs of the data to post. The function returns the HTTP response document.

int accessKey();

Returns the internal counter used by the AccessKey tag (see ACCESSKEY tag).

In order to use MWT APIs in your widegts all you need to know is that there is a PHP object, called $mwt, automatically created an put in the widgets scope. Through this object you can access APIs as method calls. This is shown in the example below.

Example 1.7. Accessing MWT APIs from the widgets

								

			
	 <table>
		<tr>
			<td width="20">...</td>
			<td width="<?=$mwt->width(-20)?>">...</td>
		</tr>
	 </table>

For the implementation of widgets, we suggest you to use taglibs instead of plain PHP. When accessing MWT APIs from taglibs you need to write less code in a clearer and more readable syntax that fits perfectly in a XHTML document.

Using MWT APIs in taglibs

Prev Up Next
1.5. Themes Home 1.7. Caches