docs/file.README.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
File: README
— Documentation by YARD 0.8.7.6
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
hasFrames = window.top.frames.main ? true : false;
relpath = '';
framesUrl = "frames.html#!file.README.html";
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
Class List
</a>
<a class="full_list_link" id="method_list_link"
href="method_list.html">
Method List
</a>
<a class="full_list_link" id="file_list_link"
href="file_list.html">
File List
</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'><h1 id="brauser">brauser</h1>
<p><a href="http://badge.fury.io/rb/brauser"><img src="https://badge.fury.io/rb/brauser.png" alt="Gem Version" /></a>
<a href="https://gemnasium.com/ShogunPanda/brauser"><img src="https://gemnasium.com/ShogunPanda/brauser.png?travis" alt="Dependency Status" /></a>
<a href="http://travis-ci.org/ShogunPanda/brauser"><img src="https://secure.travis-ci.org/ShogunPanda/brauser.png?branch=master" alt="Build Status" /></a>
<a href="https://codeclimate.com/github/ShogunPanda/brauser"><img src="https://codeclimate.com/github/ShogunPanda/brauser.png" alt="Code Climate" /></a>
<a href="https://coveralls.io/github/ShogunPanda/brauser?branch=master"><img src="https://coveralls.io/repos/github/ShogunPanda/brauser/badge.svg?branch=master" alt="Coverage Status" /></a></p>
<p>A framework agnostic browser detection and querying helper.</p>
<p>https://sw.cowtech.it/brauser</p>
<h2 id="description">Description</h2>
<p>Brauser is a framework agnostic helper that helps you in targeting your applications against most diffused browsers.</p>
<h3 id="installation">Installation</h3>
<p>Brauser comes with a Ruby on Rails hooks (more frameworks to follow), so for Rails you have just to add this to your Gemfile:</p>
<p><code>ruby
gem "brauser"
</code></p>
<p>Once done that, every controller in your application will have a <code>browser</code> method (also extended to views/layout via <code>helper_method</code>).</p>
<p>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:</p>
<p><code>ruby
browser = Brauser::Browser.new(USER_AGENT_HEADER, ACCEPT_LANGUAGE_HEADER)
</code></p>
<p>where the first argument is the HTTP header <code>User-Agent</code>, and the second is the HTTP header <code>Accept-Language</code>.</p>
<p>For the rest of this document, let’s assume you use Chrome 1.2.3 on Mac OS X.</p>
<h3 id="getting-browser-information">Getting browser information</h3>
<p>Once you instantiate the browser, you can query the browser about <code>name</code>, <code>version</code>, <code>platform</code>, <code>languages</code>.</p>
<p>You can also get readable name and platforms via <code>human_name</code>, <code>human_platform</code>, <code>human_languages</code>.</p>
<p>The version is handle via the <a href="http://dazuma.github.io/versionomy/">versionomy</a> gem.</p>
<p>The name and the platform are returned as <code>Symbol</code> and can be in the range of names and engines registered via <code>Brauser::Definitions.register</code>.</p>
<p>The languages are returned as an hash where values are the priorities.</p>
<p>Also, you can get global information using <code>browser.to_s</code> or <code>browser.classes</code>. This will return an array or a string already formatted to be used in your views to scope your CSS.</p>
<p>For example, if you do this in a ERB view:</p>
<p>```html</p>
<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, version, platform, language.
Name and platform support querying via the `==` operator, which supports a single value or a list of values.
```ruby
# We'll talk about the ending "?" later.
browser.name == :chrome
# => true
browser.name == [:msie, :firefox]
# => false
```
The version is delegated to the versionomy gem. You can use comparison operator. The right hand part must be either a `String` or a `Versionomy::Value`.
```ruby
browser.version == "3"
# => false
browser.version >= "2"
# => true
```
The language support querying via the `accepts?` method, which supports a single value or a list of values.
```ruby
browser.accepts?(:it)
# => true
browser.accepts?(:it, :en)
# => true
```
All the querying can be combined in the single method `is?`:
```ruby
browser.is?(name: :chrome, version: ">= 4", platform: [:osx, :windows], languages: :it)
# => false
```
Name, platform and languages can be either symbols or array of symbols. Version must be a query in the form is `OPERATOR VALUE && ..`,
where `OPERATOR` is one of `["<", "<=", "=", "==", ">=", ">"]` and value specifies the version.
### Prevent old browsers to access the Rails application.
If you want to easily prevent a legacy browser to open your application, create a file `supported-browsers.yml` in the `config` folder with a similar content:
```yaml
---
chrome: 29
firefox: 28
safari: 6.1
msie: 11
```
then create a filter in the `ApplicationController`:
```ruby
class ApplicationController < ActionController::Base
# ...
before_filter do
redirect_to(URL) unless browser.supported?(Rails.root + "config/supported-browsers.yml")
end
# ...
end
```
and you are set.
### Adding new browsers, platform and languages.
To add new browsers, simply call `::Brauser::Definitions.register(:browser, :id, ...)`.
The first argument can be `:browser`, `:platform` or `:language`.
The second argument is the id of the definition.
The remaining argument will be passed to the definition constructor.
For example, for Google Chrome the call should be:
```ruby
Brauser::Definitions.register(:browsers, :chrome, "Chrome", /((chrome)|(chromium))/i, /(.+Chrom[a-z]+\/)([a-z0-9.]+)/i)
```
## API Documentation
The API documentation can be found [here](https://sw.cowtech.it/brauser/docs).
## Contributing to brauser
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
* Fork the project.
* Start a feature/bugfix branch.
* Commit and push until you are happy with your contribution.
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
## Copyright
Copyright (C) 2013 and above Shogun (shogun@cowtech.it).
Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
</body></body>
</div></div>
<div id="footer">
Generated on Thu Aug 18 15:49:54 2016 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.3.0).
</div>
</body>
</html>