AskPythia - Overview

A few useful terms

The Device description Simple API standard defines a Service interface that provides read-only functionality to retrieve the properties of a device. The device is uniquely identified by some evidence, typically extracted from the HTTP request header.

Properties are defined in vocabularies. A DDR may contain properties that belong to various vocabularies. The DDR Simple API recommends that implementations of the DDR Simple API support the Device Description Repository Core Vocabulary that identifies properties that are considered essential for adaptation of content in the Mobile Web.

The terms service, evidence, property and vocabulary, defined in the standard, are used throughout the description of AskPythia. Interfaces and classes are named after them.

Code example

Without further ado, let's have a look at a working code example that uses the included implementation on top of the WURFL database.


	  // Prerequisite: Include the serviceFactory class defined in the DDR Simple API

	  require_once(dirname(__FILE__).'[path to AskPythia]/interface/serviceFactory.php');

	  

	  // Step 1: Create the service that will be used to retrieve device properties

	  $service = ServiceFactory::newService(

	      'WURFL',

	      'http://www.w3.org/2008/01/ddr-core-vocabulary',

	      array('wurfl_path'=>'[path to WURFL]'));

	  

	  // Step 2: Create the evidence that identifies the requesting device

	  $evidence = $service->newHTTPEvidenceM($_SERVER);

	  

	  // Step 3: Retrieve and display a property in the default core vocabulary

	  $property = $service->getPropertyValueES($evidence, 'vendor');

	  echo $property->getString();

For this code to work properly, the local path to the AskPythia and WURFL folders must be correctly set. The WURFL database must have been downloaded and prepared as well, please refer to the description of the implementation on top of WURFL for more details.

The code displays the name of the maker of the requesting browser.

Let's have a closer look at each of the three steps.

Step 1: Create a Service

First step to access a DDR through the DDR Simple API is to create an instance of the Service interface bound to the underlying DDR. That is the role of the generic ServiceFactory class through a call to its newService method. Three parameters must be precised:

clazz: the name of the DDR wrapper that needs to be instantiated. In AskPythia, the ServiceFactory factory will instantiate the class clazzService and will call its initialize method. ServiceFactory will also try to include the file "[path to AskPythia]/implementation/clazz/clazzService.php" if it exists. This file should contain the definition of the clazzService. It is recommended to follow this rule although it is not an error to do otherwise.
defaultVocabulary: the IRI of the vocabulary by default. When not precised, properties returned by subsequent calls to one of the getPropertyValues methods of the returned instance will be searched for in the default vocabulary. In our example, the IRI is that of the DDR Core Vocabulary.
configuration: an array of configuration settings that will be passed to the initialize method of the created instance before it is returned. In the implementation on top of WURFL, this array must define the wurfl_path setting with the location of the folder that contains the prepared WURFL files. Thus this parameter completely depends on the underlying DDR wrapping implementation.

Step 2: Create an Evidence

All the methods of the Service interface that return one or more properties expect an Evidence as argument. Basically, an evidence is a set of name and value pairs that describes a given device. The evidence is used to uniquely identify the device in the underlying repository. The set of HTTP request header fields is typically used in practice. The HTTP User-Agent header field is the most commonly used evidence, but it may be completed with other HTTP header fields such as Accept or Accept-Charset.

The Service that was created during step 1 should be used to create the evidence from the set of HTTP header fields.

Step 3: Request device properties

Once the Service and the Evidence have been created, the DDR can be easily accessed through one of the Service query methods. Please note that these query methods do not return the value of the corresponding device property, but rather an instance of a class that implements the PropertyValue interface. The returned object contains the actual property value.

What properties can be queried? It all depends on the DDR Service implementation. For instance, the included implementation on top of WURFL supports most of the properties in the DDR Core Vocabulary as well as a couple of properties taken from the WURFL vocabulary. It is recommended both to AskPythia users and developers to stick to the DDR Core Vocabulary where possible and to re-use existing vocabularies where needed.

Note on methods naming convention

The DDR Simple API uses methods overloading (e.g. it defines multiple Service::getPropertyValues methods). Methods overloading is forbidden in PHP. The AskPythia library uses the same naming conventions as the WSDL representation mentioned in the DDR Simple API (see Other Representations of the DDR Simple API).

Contact: François Daoust <fd@w3.org>, Sylvain Lequeux <lequeux@polytech.unice.fr>