Skip to content

Latest commit

 

History

History
184 lines (130 loc) · 5.52 KB

README.md

File metadata and controls

184 lines (130 loc) · 5.52 KB
Raw

Agent: An extension to Jens Segers Agent tool for querying user agent data.

Installation

composer require marknotton/agent

Official Documentation

This really is just an extension to Jens Segers Agent utility. Refer to their documentation for all available methods.

Whilst I have tried to keep this plugin as lean as possible, I have extended Jens Segers Agent utility by including a couple of my own methods...

Check

Check to determine the users browser and version type is a match.

Example 1:

true if the users current browser matches either browser name

{{ craft.agent.check('edge', 'firefox') }}
Example 2:

You can use most comparison operators to match against the browsers version.

true if browser version is equal to 100:

{{ craft.agent.check('chrome == 100'}}

true if browser version is not equal to 100:

{{ craft.agent.check('chrome != 100'}}

true if browser version is less than 100:

{{ craft.agent.check('chrome < 100'}}

true if browser version is greater than 100:

{{ craft.agent.check('chrome > 100'}}

true if browser version is less than or equal to 100:

{{ craft.agent.check('chrome <= 100'}}

true if browser version is greater than or equal to 100:

{{ craft.agent.check('chrome >= 100'}}
Example 3:

You can add multiple criteria for your check. true if any criteria is a match:

{{ craft.agent.check('ie 9', 'chrome > 49', 'firefox') }}
Example 5:

You may also negate a check by prefixing a not string. true if the users current browser is not IE version 9 or above.

{{ craft.agent.check('not ie => 9') }}

User agent whitelist:

If the User Agent contains any whitelist exceptions, even with partial matches, then the Check method will always return true. This can be useful for allowing certain bots to pass the Check method.

You can mange the whitelist by creating an agent.php config file in your projects configs directory:

return [
'userAgentWhitelist' => [
	'APIs-Google',
	'Mediapartners-Google',
	'AdsBot-Google',
	'Googlebot-Image',
	'Googlebot',
	'FeedFetcher-Google'
	]
];

or via the CMS plugin settings:

User Agent Whitelist

Version

Jens Segers original version method required a property name (browser, platform, os, etc...); and the return value would resolve to a full schema version:

{{ craft.agent.version(craft.agent.browser) }} // 104.3.0.1

I have found in most cases getting the major browser version would suffice. So instead of the previous example you can return a 'floored' version number where the browser is the assumed default argument.

{{ craft.agent.version() }} // 104

You can still get full version or a floated version number like so:

{{ craft.agent.version('text') }} // 104.3.0.1 
{{ craft.agent.version('float') }} // 104.3

Redirect

Redirect users to a new template/url if the user agent doesn't match any of the check method criteria:

{% set criteria = [
  'chrome > 55',
  'firefox > 44',
  'safari >= 7',
  'edge >= 15',
  'opera > 50'
] %}

{{ craft.agent.redirect(criteria, 'no-support.twig', 302) }}

Data

To set the user agents device name, version and device type directly to an element. Use Crafts attr method to render common data attributes.

<html {{ attr({ data : craft.agent.commonData() })}}>

The end result will look like something like this:

<html data-browser-name="chrome" data-browser-version="103" data-device="desktop">

But why would you want this? This opens up some options for browser specific styling within your CSS; and this server side approach will omit flashes of unstyled content (FOUC) or layout shifts because styling rules aren't dependant on Javascript during page load. This means you can confidently use something like this in your CSS:

html[data-browser-name="safari"] article img { ... }

agent.js

There is a small IIFE agent.min.js (< 0.7k) file that can be injected directly into the <head>. You'll need to enable this via the plugin settings.

Agent CMS Toggle Option

This will define global properties to the window object for the browser name, version, and different device types.
window.browser.name string
window.browser.version int
window.device string
window.isPhone bool
window.isTable bool
window.isDesktop bool

Alternatively you can register the the agent.min.js asset manually:

Twig:

{{ craft.agent.registerAgentJsFile(<useCompressedFile:bool>, <position:string>) }}

Php:

Agent::registerAgentJsFile(<useCompressedFile:bool>, <position:string>);

Change Log & Breaking Changes

There have been many changes since the previous version of Agent 1.2.0. Some for performance, some for sanity. Arguably some practices used in the previous version were over engineered for no obvious gains. These changes could be breaking, that require small syntax tweaks to resolve on older projects. Please review the "4.0.0 - 2022-09-11" change log for suggestions and fixes.