Detector Family Tutorial

Detector Families allow developers to organize browsers that share certain traits into groupings. With families a developer can test for the group a browser belongs to rather than each individual feature that browser may support when displaying content.

Default Families

The default install of Detector will categorize browsers into one of three families. They are: mobile-advanced, mobile-basic, and desktop. families.json, which stores the family configuration, can be found in the config/ directory. The only difference between mobile-advanced and mobile-basic is that the former checks for support of cssanimations. The default set of groupings is not overly detailed and you may want to tweak it.

Creating Your Own Families

Let's use the default config as our base. It's fairly straightforward. The keys (e.g. mobile-advanced) will be the names of our families and the attributes (e.g. isMobile) are what's going to be tested by Detector.

{
"mobile-advanced": { 
         "isMobile": true,
         "features": [ "cssanimations" ]
},
"mobile-basic": { 
         "isMobile": true
},
"desktop": {
         "isComputer": true
}
}

Two important points:

• each attribute that is tested for a family must return true for Detector to classify a browser as belonging to that family. So think of each comma (,) as an && when separating attributes.
• families should be ordered from your most specific set of tests to the most general set of tests.

So to create your own family simply add a key and object that will hold the attributes you want to test.

{
"mobile-ios": {

    }
    "mobile-advanced": { 
         "isMobile": true,
         "features": [ "cssanimations" ]
},
"mobile-basic": { 
         "isMobile": true
},
"desktop": {
         "isComputer": true
}
}

But obviously you'll need to add attributes...

Attributes That Can Tested

Any item that appears in either the core profile or extended profile can be tested in families. For the most part, any attribute that is generated by ua-parser-php and is related to the user-agent will be tested like the isMobile test. Some other examples:

"os": "iOS"
"browserFull": "Chrome 16.0.912"
"device": "Palm Pixi"

For those attributes that you want to test that are features that come out of Modernizr should be tested in the features array. Simply separate each feature you want to test with a comma. Again, each comma should be treated as an &&. An example:

"features": ["cssanimations","indexeddb","deviceorientation"]

So in our example we could have expanded to be:

{
"mobile-ios": {
         "os": "iOS",
    }
    "mobile-advanced": { 
         "isMobile": true,
         "features": [ "cssanimations" ]
},
"mobile-basic": { 
         "isMobile": true
},
"desktop": {
         "isComputer": true
}
}

But using && all the time doesn't provide the most flexibility...

Operators

Their are three simple operators that can be used when building families. They are:

• ! to test if a value is false and thus return true for the test
• || to test if at least one of the options in the list is available
• = to test if a feature matches a certain value

These operators can be used for attributes or the feature tests. Some examples:

"os": "!iOS" // will return `true` for any OS result that _doesn't_ match iOS
"os":  "iOS||Blackberry" // will return `true` for any OS result that matches _either_ iOS or Blackberry
"features": [ "cssgradients||cssanimations", "!indexeddb"] // will return `true` if _either_ cssgradients and cssanimations are available _and_ indexeddb _isn't_ available

At the moment their aren't any features in the default install of Detector that would require the = operator but it is available just in case.

So for our final example maybe we want to rename the family to mobile-ios-bb and test for the availability of either OS:

{
"mobile-ios-bb": {
         "os": "iOS||Blackberry",
    }
    "mobile-advanced": { 
         "isMobile": true,
         "features": [ "cssanimations" ]
},
"mobile-basic": { 
         "isMobile": true
},
"desktop": {
         "isComputer": true
}
}

And that's how you can go about building a family for Detector.