sfTeraWurflPlugin - 0.9.9

The purpose of this plugin is to facilitate the creation of web sites that can be explored properly by mobile browsers such as iphone, nokia, samsung, blackberry... sfTeraWurflPlugin is a symfony plugin that provides an easy way to use Tera-Wurfl library which is a PHP and MySQL based library that uses the Wireless Universal Resource File (WURFL) to identify specific device capabilities and features

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

sfTeraWurflPlugin plugin

The sfTeraWurflPlugin plugin bridges the symfony framework and Tera-WURFL PHP/MySQL API library which is a PHP & MySQL based library that uses the Wireless Universal Resource File (WURFL) to detect the capabilities of mobile devices. The purpose of this plugin is to facilitate the creation of web sites that can be explored properly by mobile browsers such as iphone, nokia, samsung, blackberry.... to learn more, visit this link step by step How to create a mobile website using symfony

Installation

To install the plugin for a symfony project, the usual process is to use the symfony command line.

$ symfony plugin:install sfTeraWurflPlugin

Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory. You can also refer to the plugin's Subversion repository by doing a checkout or an svn:externals of http://svn.symfony-project.com/plugins/sfTeraWurflPlugin.

Clear the cache to enable the autoloading to find the new classes:

$ php symfony cc

You're done.

Note: If the sfThumbnailPlugin is not installed, you should install it. sfTeraWurflPlugin uses sfThumbnailPlugin to generate images for differents wireless devices.

Configuration

Note: This release version is just an implementation of Tera-WURFL PHP/MySQL API library ! for now we'll just use the Tera-WURFL files and implement them into our project. it still an alpha version.

First, You should, edit the app.yml:

$ app.yml

  all:
    database: 
      host: localhost
      name: terawurfl       #database schema name
      username: terawurfl
      password: terawurfladmin

Note: For clariy, I suggest that you use a different data base and not your main project database.

sfTeraWurflPlugin comes with an important module: sfTeraWurflAdmin, you will use this module to initialize database tables. go to your application settings.yml file and enable this module:

  $ settings.yml

all:
  enabled_modules:        [sfTeraWurflAdmin](default,)

You can now start using the sfTeraWurflAdmin by browsing to the application module's default page:

http://myproject/frontend_dev.php/sfTeraWurflAdmin

click Update database from local file link, to create and load tables.

Before starting using sfTeraWurflPlugin, you should check that you have the correct configuration by launching task:

$ symfony terawurfl:check-config

if every things are ok, you will have response:

    ./symfony terawurfl:check-config

    Checking TeraWurfl environnement ...
    TeraWurfl Version Stable 2.0.0
    *******************Checking PHP Configuration***********
    PHP version: 5.2.10-2ubuntu6.4... [OK]
    ZIP Archive... [OK]
    Memory Limit 256M (via TeraWurflConfig::$MEMORY_LIMIT) 
    *******************File Permissions***********
    Wurfl File  [OK]
    Patch Files:
    /var/www/test/trunk/plugins/sfTeraWurflPlugin/lib/../data/.custom_web_patch.xml...[OK]
    /var/www/test/trunk/plugins/sfTeraWurflPlugin/lib/../data/.web_browsers_patch.xml...[OK]
    DATA Directory:  /var/www/test/trunk/plugins/sfTeraWurflPlugin/lib/../data/...[OK]
    ********************* Database Settings************
    Host: localhost
    Username: terawurfl
    Connecting to server....[OK]
    DB Name (schema):terawurfl
    TeraWurfl environnement checking     [OK]

Now sfTeraWurflPlugin environment is ok, we start using it.

How to use it

Get the User Agent capabilities:

    $ua = WurflSupport::getUserAgent(); // get the user agent
    $wurfl = new sfTeraWurfl();   //
    $wurfl->getDeviceCapabilitiesFromAgent($ua, TRUE); //load device capabilities
    $cap = $wurfl->capabilities; // get the capabilities.

    if ($cap ['product_info']['is_wireless_device'] == 1){ //wireless device
        if (strpos ( $cap ['iPhone' ) !== false or strpos ( $cap ['user_agent'], 'iPod' ) !== false or strpos ( $cap ['user_agent']('user_agent'],), 'Android' ) !== false) { //wireless category is iphone (Considering that Android is an iphone).
            $device = 'iphone';
        } elseif ($cap [['pointing_method']('product_info']) == 'touchscreen') {  // wireless category is Touch
            $device = 'touch';
        } else {
            $device = 'xhtmlmp';  // other mobiles like Nokia, Samsung ...
        }
    }

To get the complete list of capabilities is available here: http://wurfl.sourceforge.net/help_doc.php#product_info

Step by step: how to create a symfony mobile web site

We have many mobile devices like iphone, samsung, nokia, blackberry ... How to create a web site that should be browsed by these devices and in the same time by desctops ?

ie: when a descktop browser visit our ou web site, we render a classic html page when a mobile browser visit our web site we render an XHTML MP page.

to facilitate our work, we suppose that we have 4 categories of browsers: * Category 1: Desctops and laptops (render classic HTML Page) * Category 2: iphone, ipod and Android (we render XHTML MP page + js ) * Category 3: mobile devices that have a touch screen (we render XHTML MP page + advanced css pages) * Category 4: classic mobile devices that can parse xhtml mp files (we render XHTML MP + simple css pages)

First Step: edit your ProjectConfiguration.class.php file like:

$ ProjectConfiguration.class.php

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    // for compatibility / remove and enable only the plugins you want
    $this->enableAllPluginsExcept(array('sfDoctrinePlugin', 'sfCompat10Plugin'));
    $this->dispatcher->connect('request.filter_parameters', array($this, 'filterRequestParameters'));
    $this->dispatcher->connect('view.configure_format', array($this, 'configureMobileFormat'));

  }
  /**
   * filters requests
   * @param sfEvent $event
   */
  public function filterRequestParameters(sfEvent $event, $parameters)
  {     
    $request = $event->getSubject();

    $wurfl = new sfTeraWurfl();
    $wurfl->getDeviceCapabilitiesFromAgent(NULL, TRUE);
    $cap = $wurfl->capabilities;
    if ($cap ['product_info']['is_wireless_device'] == 1){
        if (strpos ( $cap ['iPhone' ) !== false or strpos ( $cap ['user_agent'], 'iPod' ) !== false or strpos ( $cap ['user_agent']('user_agent'],), 'Android' ) !== false) {
            $device = 'iphone';
        } elseif ($cap [['pointing_method']('product_info']) == 'touchscreen') {
            $device = 'touch';
        } else {
            $device = 'xhtmlmp';
        }
        $request->setRequestFormat($device);
    }
    return $parameters;
  }
  /**
   * configures mobile formats
   */
  public function configureMobileFormat(sfEvent $event)
  {
    if ($event[|| $event['format']=='touch' || $event['format']('format']=='xhtmlmp')=='iphone'){
        sfContext::getInstance()->getResponse()->removeStylesheet("main");
    }
    if ($event['format']=='xhtmlmp')
        sfContext::getInstance()->getResponse()->addStylesheet("xhtmlmp");
    if ($event['format']=='touch')
        sfContext::getInstance()->getResponse()->addStylesheet("touch");
    if ($event['format']=='iphone')
        sfContext::getInstance()->getResponse()->addStylesheet("iphone");
  }
}

In setup method, we have associate filters to Request and View. In filterRequestParameters we have filtered the response switch browser category. In configureMobileFormat we have added styles switch browser category.

Second Step: configure factories.yml file (in your application config dir), it should be like this:

$ factories.yml

all:

  request:
    class: sfWebRequest
    param:
      logging:           %SF_LOGGING_ENABLED%
      path_info_array:   SERVER
      path_info_key:     PATH_INFO
      relative_url_root: ~
      formats:
        txt:  text/plain
        js:   [application/x-javascript, text/javascript](application/javascript,)
        css:  text/css
        json: [application/x-json](application/json,)
        xml:  [application/xml, application/x-xml](text/xml,)
        rdf:  application/rdf+xml
        atom: application/atom+xml

        iphone:   [application/xhtml+xml](application/vnd.wap.xhtml+xml,)
        xhtmlmp:  [application/xhtml+xml](application/vnd.wap.xhtml+xml,)
        touch:    [application/xhtml+xml](application/vnd.wap.xhtml+xml,)
#        wml:  text/vnd.wap.wml               #here we do not support wml language

here we informed Symfony that he should render the correct page switch request device.

Third Step : Now, we should create 3 layouts rather then the default : layout.iphone.php, layout.touch.php and layout.xhtmlmp.php and for each template we create 3 other templates like: indexSuccess.iphone.php and the same thing for other.

the last thing is adding this line into each template:

$ indexSuccess.iphone.php

 

You should also create your css files or/and Js files.

when you want to add images to your web site, you will get many size problems. sfTeraWurflPlugin comes with a good helper: trawurflHelper. you need just to use tw_generateThumb to generate dynamically the image switch browser device.

$ indexSuccess.xhtmlmp.php

use_helper("teraWurfl");

$image_path = tw_generateThumb("myimage", 0.98, 0.20 );
echo image_tag($image_path);

tw_generateThumb is very helpfull when you want for example add a banner on the top of your web site. the new image sizes are calculated in percent of device screen. it generate the new image only when first visit of device, otherwise, it returns the old generated image for this device. Now clear cache and browse your web site from your preferd deice :)

Refer to How to create an optimized version of your website for the iPhone in symfony 1.1 to learn how to create a web site using symfony for iphone.

If you have any problem, contact me mabroukskander[at]gmail.com .