Agent plugin for Craft CMS 3.x
Query the server-side information from the users agent data.
Table of Contents
- Credit
- Installation
- Check
- Redirect
- Data
- Full
- Browser/platform version
- Magic is-method
- Mobile Detection
- Match User Agent
- Accept Languages
- Device Name
- Desktop Detection
- Phone Detection
- Robot Detection
- Robot Name
- Extra
- Agent.js
Credit
Installation
Via compsoer:
composer require marknotton/agent
Or manually in your compsoer.json:
"require": {
"marknotton/agent": "^1.1.4"
}
Check
Perform a number of checks to determine wether the users browser type is a match. Returns boolean
.
Example 1:
Returns true if current browser is either 'IE, Edge, or Firefox'
{{ craft.agent.check('ie', 'edge', 'firefox') }}
Example 2:
Returns true if current browser is greater than IE 9
{{ craft.agent.check('ie > 9') }}
Example 3:
Returns true if current browser is greater or equal to IE 9
{{ craft.agent.check('ie => 9') }}
Example 4:
Returns true if current browser is either, IE version 9, Chrome version 50 or above, or any version of Firefox
{{ craft.agent.check('ie 9', 'chrome > 49', 'firefox') }}
Redirect
Redirect users if their current agent doesn't meet any of these conditions. Following the same syntax as the 'check' function, this will redirect users to a specific template. You can also pass in a status code too.
{% set criteria = [
'ie 11',
'chrome > 55',
'firefox > 44',
'safari >= 7',
'edge >= 15',
'opera > 50'
] %}
{{ craft.agent.redirect(criteria, 'no-support.twig', 302) }}
Data
Returns a string in the format of data attributes containing the browser name and version number, platform and device type. Ideal for querying via Javascript or CSS. See the included agent.js file for more information.
Example:
{{ craft.agent.data }}
Example Output:
data-browser="chrome 52"
Example Output: jQuery Usage
if ( $('html[data-browser^=chrome]').length ) {...}
Example Output: CSS Usage
html[data-browser^=chrome] {...}
Full
Simply returns the name and version of the users browser.
Returns browser name and version number in an array
{{ craft.agent.full }}
Returns browser name
{{ craft.agent.full.name }}
Returns version number
{{ craft.agent.full.version }}
Browser/platform version
MobileDetect recently added a version
method that can get the version number for components. To get the browser or platform version you can use:
{% set browser = craft.agent.browser() }}
{% set version = craft.agent.version($browser) }}
{% set platform = craft.agent.platform() }}
{% set version = craft.agent.version($platform) }}
Note, the version method is still in beta, so it might not return the correct result.
Magic is-method
Magic method that does the same as the previous is()
method:
{{ craft.agent.isAndroidOS() }}
{{ craft.agent.isNexus() }}
{{ craft.agent.isSafari() }}
Mobile detection
Check for mobile device:
{{ craft.agent.isMobile() }}
{{ craft.agent.isTablet() }}
Match user agent
Search the user agent with a regular expression:
{{ craft.agent.match('regexp') }}
Accept languages
Get the browser's accept languages. Example:
{% set languages = craft.agent.languages() %}
// ['nl-nl', 'nl', 'en-us', 'en']
Device name
Get the device name, if mobile. (iPhone, Nexus, AsusTablet, ...)
{{ craft.agent.device() }}
Operating system name
Get the operating system. (Ubuntu, Windows, OS X, ...)
{{ craft.agent.platform() }}
Browser name
Get the browser name. (Chrome, IE, Safari, Firefox, ...)
{{ craft.agent.browser() }}
Desktop detection
Check if the user is using a desktop device.
{{ craft.agent.isDesktop() }}
This checks if a user is not a mobile device, tablet or robot.
Phone detection
Check if the user is using a phone device.
{{ craft.agent.isPhone() }}
Robot detection
Check if the user is a robot. This uses jaybizzle/crawler-detect to do the actual robot detection.
{{ craft.agent.isRobot() }}
Robot name
Get the robot name.
{{ craft.agent.robot() }}
Extra
All Agent service methods are accessible without the need to define 'craft.'. So all of the functions above can be called like this too:
{{ agent.browser() }}
Agent.js
Agent comes complete with a Javascript class to help make it easier to query some of the user agent data.
You can include the agent.js like this:
{% do view.registerJsFile(
craft.app.assetManager.getPublishedUrl('@agent/assets/scripts/agent.js', true),
{'position' : constant('\\yii\\web\\View::POS_HEAD')}
)%}
You can initialise it like this:
let agent = new Agent();
By default, we assume the Twig data function is defined in your HTML tag via Twig:
<html {{ craft.agent.data|default }}>
If you're using it on another tag, you'll need to define the element like this:
let agent = new Agent($('body')[0]);
Now you have access to these methods:
Function | Return Example | Description |
---|---|---|
agent.browser | {name: "chrome", version: "66"} |
Gets the users browser name and version number |
agent.viewport | {width: 1345, height: 1321} |
Gets the users viewport width and height |
agent.screen | {pixelWidth: 2560, pixelHeight: 1440} |
Gets the users device resolution. This takes into account condensed pixels |
agent.platform | osx |
Gets the users platform type |
agent.mobile | true |
Checks if the user is on a mobile device |
agent.tablet | true |
Checks if the user is on a tablet device |
agent.desktop | true |
Checks if the user is on a desktop |
agent.touch | true |
Checks if the users device supports touch input |
agent.orientation | landscape |
Checks the orientation of the users display/device |
agent.notch | left |
Checks if the users device has a notch, and tells you what side it's on |
Orientation, Touch, and Notch data is stored in the DOM window as device
. Referring to this will return something like this:
[orientation: "landscape", touch: true, type: "iphoneX", notched: true, notch: "left"]
All of the above methods are auto loaded when the Agent Class is initialised. Each method stores data to the DOM window. So rather than actioning each method when you need it, you can refer to the cached data in your Window. Meaning you can simply call browser
in your script to get the data. You can disable this by passing in false
as argument: new Agent(false)
.