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 .
Skander Mabrouk 