brauser

Gem Version Dependency Status Build Status Code Climate Coverage Status

A framework agnostic browser detection and querying helper.

http://sw.cow.tc/brauser

http://rdoc.info/gems/brauser

Description

Brauser is a framework agnostic helper that helps you in targeting your applications against most diffused browsers.

Installation

Brauser comes with a Ruby on Rails hooks (more framework to follow), so for Rails you have just to add this to your Gemfile:

ruby gem "brauser"

Once done that, every controller in your application will have a browser method (also extended to views/layout via helper_method).

If you don’t use Rails, you can instantiate a new browser by including the gem in your code and by doing something like this:

ruby browser = Brauser::Browser.new(USER_AGENT_HEADER, ACCEPT_LANGUAGE_HEADER)

where the first argument is the HTTP header User-Agent, and the second is the HTTP header Accept-Language.

For the rest of this document, let’s assume you use Chrome 1.2.3 on Mac OS X.

Getting browser information

Once you instantiate the browser, you can query the browser about name, version and platform. You can also get readable name and platforms via readable_name and platform_name.

The version is returned as a String, and you can use Brauser::Browser.compare_versions to compare against another version.

The name and the platform are returned as Symbol and can be in the range of names and engines registered via register_browser, register_default_browsers, register_platform and register_default_platforms.

Also, you can get global information using browser.to_s or browser.classes. This will return an array or a string already formatted to be used in your views to scope your CSS.

For example, if you do this in a ERB view:

html <body class="<%= browser.classes %>"> ...

The view will get compiled to this:

html <body class="chrome version-1 version-1_2 version-1_2_3 platform-osx"> ...

And thus scoping your CSS will be trivial.

Querying the browser

Brauser supports querying about name (method is), version (method v), platform (method on) and language (method accepts).

The is method queries about a browser name (or a list of names) and optionally by version and platform:

ruby # We talk about the ending ? later. browser.is?(:chrome) # => true browser.is?([:msie, :firefox]) # => false browser.is?(:chrome, {lt: "2"}, :osx) # => true browser.is?(:chrome, ">= 3", :windows) # => false

The method is is the only which supports direct internal propagation to version and platform.

The v method queries about the browser version. You can specify the comparison with an hash or a little expression.

In the case of hash, the syntax is {:operator => value}, where :operator is one of [:lt, :lte, :eq, :gte, :gt] and value can be a Float or a String.

In the case of expression, the syntax is OPERATOR VALUE && .., where OPERATOR is one of ["<", "<=", "=", "==", ">=", ">"] and value specifies the version.

Examples:

ruby # Those two methods are equivalent. browser.v?({lt: "2", gt: 1}) # => true browser.is?("< 2 && > 1") # => true

The method on check is the current browser in one of the specified platform. The platform should be passed as Symbol.

ruby browser.on?(:osx) # => true browser.on?([:windows, :ios]) # => false

At the end, the method accepts checks if the browser accepts one of the specified languages. Languages should be passed as language codes in String.

ruby browser.accepts?("en") # => true browser.accepts?(["de", "es"]) # => false

Every query method exists in two forms: the concatenation one (the method name doesn’t end with a ?.

The former return a Query object, which supports the same query method of the browser and thus enables concatenation.

The latter return a boolean object, and it’s equivalent to calling result on the query after concatenation.

Ideally, you should use the ? version to end the query and fetch the result.

ruby # These expressions are equivalent. browser.is?(:chrome, {lt: "2"}, :osx) browser.is(:chrome, {lt: "2"}, :osx).result browser.is(:chrome).v({lt: "2"}).on?(:osx) browser.is(:chrome).v({lt: "2"}).on(:osx).result

Finally, Brauser support dynamic query operator to write simple queries without using concatenation.

You construct the method just using operator specified above, separating method name and method arguments with a _.

For the version, use the expression form but use symbol operators and replace . with _ and && with and.

Example:

```ruby # These expressions are equivalent. browser.is(:chrome).v(“< 2 && > 1.2”).on(:osx).result browser.is_chrome_v_lt_2_and_gt_1_2_on_osx.result

These expressions are equivalent.

browser.is(:chrome).v(“< 2 && > 1.2”).on?(:osx) browser.is_chrome_v_lt_2_and_gt_1_2_on_osx? ```

Adding new browsers

To add new browsers, simply call ::Brauser::Browser.add(:browsers, ...).

This methods accepts a single instance or an array of instances of the ::Brauser::Definition class.

For example, for Google Chrome the call should be:

ruby Brauser::Browsers.add(:browsers, ::Brauser::Definition.new(:chrome, "Chrome", /((chrome)|(chromium))/i, /(.+Chrom[a-z]+\/)([a-z0-9.]+)/i))

Adding new platforms

To add new platforms, simply call ::Brauser::Browser.add(:platforms, ...).

This methods accepts a single instance or an array of instances of the ::Brauser::Definition class.

For example, for Mac OS X the call should be:

ruby Brauser::Browsers.add(:platforms, ::Brauser::Definition.new(:osx, /mac|macintosh|mac os x/i, "Apple MacOS X"))

Adding new languages

To add new languages, simply call ::Brauser::Browser.add(:languages, ...).

This methods accepts a single instance or an array of instances of the ::Brauser::Definition class.

For example, for Italian the call should be:

ruby Brauser::Browsers.add(:languages, ::Brauser::Definition.new(:it, "Italian"))

Contributing to brauser

Copyright (C) 2013 and above Shogun (shogun_panda@me.com).

Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.