Check out the latest documentation.

Configuration

Quick setup

The 51Degrees Switcher can be used to control if a particular kind of device will use a particular Joomla theme or redirects to a different url. The plugin can have multiple rules set up at once so a different theme can be setup for mobile, tablets, input methods or any other data provided by the 51Degrees Provider.

After installing the Joomla plugin open the plugin menu by clicking the 51Degrees link from the admin area.

You will see the following screen:

Start by creating your first rule by going pressing the 'Add New Rule' button. This will refresh the page showing a screen with a single tab. A tab represents a single rule, each one with options to specify activation conditions and their action.

Let's create a rule that will switch to a mobile domain for all mobile devices:

1. Check the 'Mobile' mobile checkbox in basic properties. Additional basic properties from the yellow box can be enabled by using premium data. See our premium data page for more details.

2. Advanced properties can be used to go into more detail about what devices should be switched, such as the manufacturer or input methods. We don't this for now so we can ignore it.

3. Finally, set which URL mobile devices should be redirected to. We recommend a seperate mobile domain.

4. You can now visit the site from a mobile device or emulator to see your site responding to a mobile device.

Multiple Rules

An unlimited amount of rules can be created allowing for different device and property combinations being sent to different themes or sites.

You can create new rules by pressing the 'Add New Rule' button. A new tab will be added to the right of the tabs and will be given a unique name. The rule name can be changed by overwriting the textbox in the tab and pressing 'Save Rule'.

Rules must have unique name. If a Rule's name is changed to be the same as an older Rule, the older Rule will be overwritten and take the properties of the new Rule.

The positioning of the tabs affect their priority. If two Rules clash over a device the Rule encountered first (ie, the left most tab) will be used. You should have your most specific Rules on the left going to least specific Rule on the right.

The order of the tabs can be changed using the '<' and '>' buttons on the selected tab. These options are only available when the tab is allowed to move in that particular direction.

If no matches are found the default theme is requesting URL is used.

Advanced Properties

Properties in the 'Basic Properties' section are chosen because they are frequently used and would be an aid to developers to be collected in one place. Also, unlike the 'Advanced Properties' section they are evaluated on an OR basis. If the following properties were marked:

Mobile

Tablet

Console

Any device that was true for at least one of those properties would satisfy that Rule. This allows developers to quickly make Rules that cover a lot of devices, rather than having multiple Rules with the same action.

However, if more detail is required then the Advanced Properties can be used. These properties are evaulated on an AND basis. First, they must be enabled via the checkbox, then their desired value set in the drop down box. By having the seperate enabling step a Rule can check if the property should be false.

Note that if basic and advanced properties are mixed in the same Rule, only a single Basic Property needs to match for the Rule to be satisfied, even if none of the Advanced Properties match.

Settings

You may enable this to contribute data to 51Degrees to help us create better detection data. Data is anonymous and not shared with any other party. See our Share Usage FAQ for more info.

Upgrade Device Detection Data

After purchasing a license key you can update your detection data by copying the key into the box and pressing 'Update Data'. If a newer version is available the data will be download installed. Note that your server needs to support outbound HTTP connections and be given file writing permission for this process to work.

For Developers

Preventing redirection

Redirection can be prevented using the session variable 'NO_SWITCH':

$_SESSION['NO_SWITCH'] = true; // redirection will no longer occur
Note that detection occurs in the onAfterRoute event, so you will need to use an earlier event to prevent the first redirection.

Accessing 51Degrees.mobi Properties

The 51Degrees Detector is a system plugin that detects incoming devices, but its data can also be accessed from any other page in Joomla using the JDispatcher. The following two snippets show how to get properties and data using these functions: 

										
										<?php
										
										
										function
										
										
										get_fiftyone_degrees_properties
										
									() {
  
										
										$dispatcher
										
										
										=
										
									 JDispatcher
										
										::
										
										
										getInstance
										
									();
  
										
										// gets results from all plugins implementing 'getFiftyOneDegreesProperties'.
										
										
										$results
										
										
										=
										
										
										$dispatcher
										
										
										->
										
										
										trigger
										
									(
										
										'getFiftyOneDegreesProperties'
										
									, 
										
										null
										
									);
  
										
										if
										
									(
										
										empty
										
									(
										
										$results
										
									))
    
										
										return
										
										
										null
										
									;
  
										
										else
										
										
										return
										
										
										$results
										
									[
										
										0
										
									];
}


										
										?>
										
									

										
										<?php
										
										
										function
										
										
										get_fiftyone_degrees_meta_data
										
									() {
  
										
										$dispatcher
										
										
										=
										
									 JDispatcher
										
										::
										
										
										getInstance
										
									();
  
										
										// gets results from all plugins implementing 'getFiftyOneDegreesMetaData'.
										
										
										$results
										
										
										=
										
										
										$dispatcher
										
										
										->
										
										
										trigger
										
									(
										
										'getFiftyOneDegreesMetaData'
										
									, 
										
										null
										
									);
  
										
										if
										
									(
										
										empty
										
									(
										
										$results
										
									))
    
										
										return
										
										
										null
										
									;
  
										
										else
										
										
										return
										
										
										$results
										
									[
										
										0
										
									];
}


										
										?>

See the 51Degrees PHP page for more info.