Plugin User Manual

Getting Started

Requirements

Restive Plugin requires JQuery 1.7 or higher.

Versions

There are two versions of Restive Plugin:

  1. Basic: this is the basic version available on Github
  2. Pro: this is the advanced version containing additional features like 'Modularity' and 'Analytics'

License

The two versions previously mentioned are governed by the respective licenses:

  1. Basic License Agreement
  2. Pro License Agreement

Changelog

Version 1.0.0 (October 22, 2013)

  • First Commit

Script Reference Warnings

Please be mindful to disable the following Javascript libraries from your Web pages before using Restive Plugin (i.e. if you have them enabled):

These libraries are already embedded within Restive Plugin.

Installation

To install Restive Plugin, simply include the plugin script after the JQuery Library:

<link rel="stylesheet" type="text/css" href="your.css" />
<script type="text/javascript" src="jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="restive.min.js"></script>

Where your.css is the CSS file containing all your stylesheet definitions (It is possible this could be more than one file). See CSS Reference for more information.

Usage

The basic format for using Restive Plugin is as follows:

<script>
    $(document).ready(function () {
        $('selector').restive(options);
    });
</script>

NOTE: Please ensure that you always wrap your code with $(document).ready().

So considering a simple usage scenario, let's say we have designed a HTML5 Web site and we want to make it Responsive to a specific set of breakpoints: 240, 320, 480, 640, 960, 1024, and 1280 pixels wide. Our code will look something like this:

<script>
$(document).ready(function () {
    $('body').restive({
        breakpoints: ['240', '320', '480', '640', '960', '1024', '1280'],
        classes: ['css-240', 'css-320', 'css-480', 'css-640', 'css-960', 'css-1024', 'css-1280']
    });
});
</script>

So what does the above setup mean?! The Plugin will actively monitor the viewport of any devices that visit your web site for the following width ranges: 0 to 240 pixels, 241 to 320 pixels, 321 to 480 pixels, 481 to 640 pixels, 641 to 960 pixels, 961 to 1024 pixels, and 1025 to 1280 pixels. If the viewport of the device is between 0 and 240 pixels wide, the plugin will add the class css-240 to the <body> tag; if the viewport is between 241 and 320 pixels wide, it will add the class css-320, and so on.

So if I have a Google Nexus 4 (768 pixels wide by 1280 pixels high when in portrait orientation) and I visited a Web site with the above Restive Plugin configuration, the plugin would add the class css-960 to the body tag, because the viewport falls within 640 pixels and 960 pixels wide. You could then tweak your CSS file and add any required rules required to customize your layout.

NOTE: We strongly advise that you use either 'html' or 'body' as your preferred selector always.

API Reference

Concepts

Restive Web Design

Restive Web Design is a function-based approach to designing Web sites. Using the concept of "Incremental Zen", the goal of Restive Web Design is to constantly evolve a Web site until it is ultimately adaptive to every Web-enabled Device.

Follow the link for more information on Restive Web Design.

Responsive Web Design vs. Adaptive Web Design

Responsive Web Design (often abbreviated to RWD) is an approach to web design in which a site is crafted to provide an optimal viewing experience—easy reading and navigation with a minimum of resizing, panning, and scrolling—across a wide range of devices (from desktop computer monitors to mobile phones)1.

Adaptive Web Design (often abbreviated to AWD) is an approach to web design that is similar to Responsive Web Design. Whereas RWD is usually concerned with changing the layout of your Web site as the device's screen size changes, AWD will also consider changes in other device properties e.g. platform (iOS, Android, etc.) and form-factor (phone, tablet, etc.).

For example, a Responsive web site may be designed to cater to various device screen sizes between 240px to 1024px wide. However, it will not be able to distinguish much else beyond screen size (intuitively so that is). On the other hand, an Adaptive web site may consider screen size in addition to other device properties; so you can provide, say, a different experience for two devices with identical screen sizes simply because one is a tablet and the other is a phone.

Adaptive Web Design usually provides more options than Responsive Web Design. However, you need to do a lot more work to tailor your Web site to more scenarios.

1 Source: Wikipedia

Modular Web Design

Modular Web Design is an approach to web design in which a web site is first broken into components, and then these components are designed, developed, tested, and finally assembled to create a finished Web site. A key advantage of this approach is encapsulation. For example, if you design a web site widget, and you need to improve it, you can simply update the widget without tampering with any of the other component modules that make up the whole web site.

Responsiveness

Responsiveness is your Web site's capability to manage different device screen sizes, and modify its layout in response to those differences.

Adaptiveness

Adaptiveness is your Web site's capability to manage different device screen sizes and device features e.g. platform (iOS, Android, etc.), form-factor (phone, tablet, etc.), et al. and modify its layout in response to those differences.

Modular Responsiveness

This is the ability of your web site to modify the layout of a web page component [which is housed within a container] as the size of its container changes. There are specific situations where certain UI elements are built in a modular fashion. Traditional Responsive + Adaptive Web Design techniques are usually only concerned with the viewport. Enabling modular responsiveness will allow these components to adapt to changes in their immediate layouts [not just the overall viewport] e.g. a calendar widget that automatically displays its 'mini' version when it is put in a smaller sidebar container as opposed to its usual wider main page container.

Modular Adaptiveness

This is the ability of your web site to modify the layout of a web page component as the size of its container changes, and according to specific device features e.g. platform (iOS, Android, etc.), form-factor (phone, tablet, etc.), et al.

Viewport

The viewport is the portion of the web page that the user can currently see. So if on a web page, there is a picture but you have to scroll down to see it, this image is said to be outside the viewport. Viewport width and viewport height refer to the width and height, respectively, of the viewable portion of the web page.

Container

The container is a HTML element (nested under the <body> tag) that encapsulates another HTML element. For example, if you have the following code: <div id="container-1"><div id="component-1"></div></div>, the element with id 'container-1' is a container to the element with id 'component-1'.

Orientation

Orientation is the way a rectangular viewing area e.g. a monitor, a mobile device, etc. is oriented for viewing. The two most common types of orientation are portrait and landscape. When the viewing area is taller than it is wider, this is referred to as portrait orientation mode. When the viewing area is wider than it taller, this is referred to as landscape orientation mode.

Breakpoints

Break points in Responsive Web Design are browser widths that have a declaration – media query or otherwise – to change the layout once the browser is within the declared range2.

Restive Plugin uses Breakpoints to find and match viewports of mobile devices. So if you define the following breakpoints: 240, 360, 480; the plugin will target the following viewports 0 to 240 pixels, 241 to 360 pixels, and 361 to 480 pixels.

There are two types of breakpoints in Restive Plugin

  • Pixel Breakpoints: This is when the breakpoints are defined by widths in pixels
  • Resolution Breakpoints: This is when the breakpoints are defined by standard graphic display resolutions e.g. nHD, SVGA, XGA, 1080p, etc. Click here to view all Resolution Shortcodes that are allowed for use when defining such breakpoints.

    Every device has its own specific viewport width and height e.g. XGA is 768 by 1024 pixels. When you use resolution breakpoints, Restive searches for the specific graphic display resolution and obtains its viewport width. It then sorts everything in order and creates a viewport range that will match all the resolutions you have listed.

    For example, let's say nHD, qHD, and UXGA are listed as your resolution breakpoints. These resolution definitions have a viewport width of 360px, 540px, and 1200px respectively. Restive Plugin will then sort the widths in order and create the proper viewport range. So in this case, our breakpoint range will be 0 to 360px, 361 to 540px, and 541 to 1200px. Restive Plugin does this automatically.

NOTE: Breakpoint ranges are calculated automatically by Restive Plugin, you only need to define the actual widths you want to target, and the plugin will do the rest.

2 Source: Web Site - 1stwebdesigner.com

Special Features

Breakpoint Orientation Markers

Orientation markers are a special feature of Restive Plugin that allows you to define breakpoints that target viewport width ranges in specific orientation modes. For example, if you define the following breakpoints: 240, 360-l, 480-p; the Plugin will target the following viewports: 0 to 240 pixels, 241 to 360 pixels only if the device is in landscape orientation, and 361 to 480 pixels only if the device is in portrait orientation. You can append an orientation marker to any breakpoint that you have defined.

Supported Orientation Markers are:

  • -p for portrait orientation
  • -l for landscape orientation

NOTE: Orientation markers always take precedence if duplicate breakpoints are defined. For example, let's say you have defined breakpoints that include 640 and 640-p, with corresponding classes 640-c and 640-pc respectively. If the device viewport width falls within 0 and 640 pixels, the class 640-pc will be applied even though the two breakpoints are both technically an exact match.

NOTE: Orientation markers work a little differently when using Resolution Breakpoints. When using resolution breakpoints with orientation markers, Restive Plugin uses the width component of the resolution when in portrait, and the height component of the resolution when in landscape. For example, let's say you define the following: hvga, hvga-l; this resolution is 320px by 480px. The Plugin will target 0 to 320 pixels, and 321 to 480 pixels only if the device is in landscape orientation.

NOTE: If you define two identical breakpoints with two identical orientation markers, the one that appears first in your definition will take precedence.

Multiple Constructors

Restive Plugin lets you call its constructor multiple times. The primary reason for doing this is when you want to segment your breakpoints e.g. when you want to target multiple platforms or form-factors.

The syntax for using multiple constructors is as below:

$.restive.startMulti();

$('selector').restive(options_1);
$('selector').restive(options_2);

$.restive.endMulti();

So considering a real example, let's say we need to define multiple breakpoints for two different form-factors. We can do this as follows:

$.restive.startMulti();

$('selector').restive({breakpoints: ['240', '360', '480', '640'], platform: 'ios'});
$('selector').restive({breakpoints: ['240', '360', '480', '640'], platform: 'android'});

$.restive.endMulti();

NOTE: You must always call the method $.restive.startMulti() before you define multiple constructors, and $.restive.endMulti() at the end. If you don't, you'll get errors.

NOTE: Ensure that you use the same selector for each constructor i.e. if you’re using ‘body’ for the tag make sure you use it for all your constructor calls. This is best practice advice.

NOTE: You should only use this feature when you want to segment breakpoints along platform or form-factors i.e. you want to define different breakpoints for different platforms or form-factors. You shouldn't use it as a way of adding more breakpoints (if you want to add more breakpoints, just add them to your existing breakpoints). We've built Restive Plugin to work even if you use multiple constructors without specifying segmentation options like platform and formfactor, but you really shouldn't use it that way

Modularity

This enables Responsiveness and/or Adaptiveness at the container-level. Using modularity, the components on your Web page can respond and adapt to changes in the dimensions of its container.

The syntax for using modularity is as below:

$('#element-id').restive({
    breakpoints: ['640', '3000'],
    classes: ['640-ce', '3000-ce'],
    anchor: 'element'
})

So considering a real example, let's say we had a <div> container with id 'container-1', and we wanted to enable modularity, we could do this as follows:

$('#container-1').restive({
   breakpoints: ['320', '768', '5000'],
   classes: ['320-ce', '768-ce', '5000-ce'],
   anchor: 'element'
})

EXPLANATION: When a resize of the viewport or change in orientation causes the width of the HTML element identified by div tag and id 'container-1' to drop below 320 pixels in width, the class 320-ce will be added to said element i.e. <div id="container-1" class="320-ce"></div>. If the width of this element is between 321 and 768 pixels wide, the class 768-ce will be added to the tag representing this element, and so on.

NOTE: When using this feature, it is advised that you always define a very high value for your final breakpoint item [i.e. a value you do not expect your container element to ever attain e.g. 5,000] to properly close out the range.

NOTE: This feature is only available with Restive Plugin Pro.

Options

breakpoints

An itemized list of dimensions that define a specific range within which an adaptive action should take place. Restive Plugin allows for 2 distinct types of breakpoints:

  • Pixel: This is defined by widths as pixels e.g. 320.
  • Resolution: This is defined by graphical device resolution shortcodes e.g. HVGA, VGA, etc. See list of all allowable graphical device resolution shortcodes here.

NOTE: Restive Plugin also allows for additional orientation markers e.g. 320-p, 480-p, hvga-l, xga-p, etc. -l signifies landscape, and -p signifies portrait. This enables you define multiple CSS classes for multiple orientation states per resolution breakpoint.

Breakpoints are defined as an array:

breakpoints: ['240', '320', '480', '640'];

The above setting means that the plugin will monitor the viewport for the following width ranges: 0 to 240px, 241 to 320 pixels, 321 to 480 pixels, and 481 to 640 pixels. It will then apply classes (see next option) to the DOM based on which range the viewport width matches.

NOTE: Do not start from zero when defining breakpoints. Always start from the upper limit of the implied range. For example, if you specify 240 as the first item in the breakpoints option, the plugin will enable a range of 0 to 240; if 480 is the next item, the plugin will enable a range of 241 to 480 and so on.

NOTE: Do NOT use commas when defining breakpoints that are in the thousands e.g. never do '1,000'; do '1000' instead.

NOTE: Ensure that you define your breakpoints based on device pixels [and not css pixels]. For example, if you want to match a device width of 720 pixels, use 720 even when you know the Device-Independent Pixel Width is 360. You can override this behavior by using the force_dip option.

classes

An itemized and corresponding list of CSS classes that will be set to the matched element defined in the Restive Plugin selector, in lock-step with the corresponding breakpoints.

Classes are defined as an array:

classes: ['240-c', '320-c', '480-c', '640-c'];

The above setting will add the class 320-c to the selected DOM element when the viewport is between 241 and 320 pixels (considering the breakpoints options defined earlier)

NOTE: The number of classes defined here must be identical to the number of breakpoint items defined in the breakpoints option.

NOTE: You can also add multiple classes to the matched element defined in the Restive Plugin selector. Simply space-separate your classes e.g. myclass1 myclass2

force_dip

This option provides an override capability that forces the breakpoints option to consider device-independent pixels instead of device pixels (which is the default behavior). Setting this option to true enables the override.

For example, say you have an iPad 2 and an iPad Air (which has a retina display), and your Restive Plugin settings are as set up below:

$('body').restive({
    breakpoints: ['768', '1280'],
    classes: ['768-c', '1280-c']
});

If a user uses the iPad 2 to visit your web site (in portrait orientation), the class 768-c will be added to the class attribute of the <body> tag. However, if the iPad Air is used, nothing gets added to the <body> tag because the iPad Air viewport width is 1536 pixels (i.e. considering device pixels). This is the default behavior for breakpoints.

However, using the force_dip option [and setting it to true], you can force breakpoints to consider device-independent pixels instead of device pixels. This way, Restive Plugin will see the ranges 0 to 768 pixels [for a non-retina device] and 0 to 1536 pixels [for a retina device] as the same. See revised settings below:

$('body').restive({
    breakpoints: ['768', '1280'],
    classes: ['768-c', '1280-c'],
    force_dip: true
});

NOTE: This option also works if you are using the Modularity feature (i.e. you have set anchor to element).

anchor

This defines the basis by which responsiveness is applied i.e. how classes will be applied according to changes to either the viewport or DOM element. There are two possible options:

  • window: This will anchor responsiveness to the viewport i.e. classes will be applied as the viewport changes in width, and as those widths match the breakpoints provided
  • element: This will anchor the responsiveness to the element's container i.e. classes will be applied as the element's container changes in width, and as those widths match the breakpoints provided

Anchor selection is automatic and functions according to the following conditions:

  • If you use the html or body tag in your Restive constructor e.g. $('body').restive(), the anchor option defaults to window. You cannot force element when either one of these two specific selectors are used.
  • If you use any tag that is determined to be within the body tag e.g. $('div#someid').restive(), the anchor option defaults to element, otherwise it defaults to window. You may force window instead of element if you so desire.

NOTE: This option is only available in the Pro version of Restive Plugin

NOTE: When using anchor option with element value, you must use a valid JQuery ID selector in your Restive plugin constructor e.g. $('#myid').restive()

NOTE: Do not define callbacks in any Restive Constructors that have anchor option set to e or element

anchor_e_df

This is a special option that determines what method should be used to retrieve the width of the element container when the basis for responsiveness/adaptiveness (‘anchor’ option) is ‘element’. This width is used by Restive Plugin to enable modular responsiveness + adaptiveness.

There are three possible values that you may use:

  • 'w' to use $().width(). This is the default value
  • 'i' to use $().innerWidth()
  • 'o' to use $().outerWidth()

NOTE: This option is only used when anchor option is e or element

NOTE: This option is only available in the Pro version of Restive Plugin

platform

This defines the specific mobile platform that you want to target. The following values are available for use:

  • all: target all platforms (and by inference all devices). This is the default setting.
  • ios: target only devices based on the iOS platform e.g. iPad, iPod, etc.
  • android: target only devices based on the Android platform e.g. Samsung Galaxy S4, Google Nexus 7, etc.
  • symbian: target only devices based on the Symbian platform e.g. Nokia Asha 311
  • blackberry: target only devices based on the Blackberry platform e.g. Blackberry Q10
  • windows: target only devices based on the Windows platform e.g. Nokia Lumia, Microsoft Surface, etc.

formfactor

This defines the specific form factor that you want to target. The following values are available for use:

  • all: target all form-factors (and by inference all devices). This is the default setting.
  • desktop: target all desktop devices e.g. notebooks, desktop
  • tv: target smart TVs and Game Consoles
  • tablet: target tablets
  • phone: target phones

turbo_classes

There are certain instances when you need to define a class that will be added to your selected DOM element alongside any other classes you may have defined in classes.

For example, let's say you want to add a class mobi if the device is a mobile device alongside the selected class previously defined in the classes option. You can do this quite easily using turbo_classes.

Using turbo_classes, you can specify one or more conditions and a corresponding class for each condition that will be added to your DOM selector when said condition is met.

You define your turbo-class (or classes) in the following format: {condition}={class}.

Where {condition} is the specific circumstance that will trigger the {class} to be added. The following {condition} definitions are available for use:

  • is_mobile: will add a {class} if device is mobile e.g. phone or tablet
  • is_non_mobile: will add a {class} if device is non-mobile e.g. pc or tv
  • is_retina: will add a {class} if device has a retina display
  • is_phone: will add a {class} if device is a phone
  • is_tablet: will add a {class} if device is a tablet
  • is_tv: will add a {class} if device is a TV
  • is_desktop: will add a {class} if device is a Personal computer (or similar)
  • is_portrait: will add a {class} if device is in portrait orientation
  • is_landscape: will add a {class} if device is in landscape orientation

So let's further clarify with an illustration:

$('body').restive({
    breakpoints: ['320', '480', '640', '720', '960', '1280'],
    classes: ['320-c', '480-c', '640-c', '720-c', '960-c', '1280-c'],
    turbo_classes: 'is_mobile=mobi,is_portrait=view-p'
});

EXPLANATION: The class in the classes option will be added to the <body> tag depending on which breakpoint range matches the device viewport. However, since the turbo_classes option is defined with two conditions, the following will also happen:

  • If the device is a mobile device, mobi will be added to the <body> tag class attribute
  • If the device is in portrait orientation, view-p will be added to the <body> tag class attribute

So if the device is in portrait, and is 640 pixels wide, 'mobi view-p 640-c' will be added to the class attribute of the <body> tag.

NOTE: You can use turbo_classes to add only one class per condition i.e. multiple class definitions per condition are not possible. So that means you can't do something like this: turbo_classes: 'is_mobile=mobi,is_mobile=mobi_plus'

pro_key

This is your Pro License Key and must be defined when using Restive Plugin Pro. It is assigned to you automatically when you purchase the Pro version of Restive Plugin.

You can get your pro_key by logging into your Restive Cloud Account: It's prominently displayed on your Dashboard.

NOTE: You only need to define this if you are using the Pro version of Restive Plugin.

ba

This setting determines if Breakpoint Analytics feature will be enabled or not. Set this value to true or false.

NOTE: This feature works exclusively with Restive Analytics which is still under development.

ba_key

This is the unique access key to enable you use the Breakpoint Analytics feature. It is assigned to you automatically when you purchase the Pro version of Restive Plugin.

You can get your ba_key by logging into your Restive Cloud Account: It's prominently displayed on your Dashboard.

NOTE: If ba is set to true, you must provide your ba_key or the Breakpoint Analytics feature will not work.

NOTE: This feature works exclusively with Restive Analytics which is still under development.

ba_tag

This is an identifier that is used to segment Breakpoint Analytics data when using Restive Plugin on multiple web sites.

NOTE: You must have a Multi-user Pro License (5-user, 10-user, or Unlimited) for this feature to work.

NOTE: This feature works exclusively with Restive Analytics which is still under development.

Event Callbacks

These are technically also Options. However, just for better categorization, we have separated them from Options above.

The following Callbacks are available for use in Restive Plugin

onReady

This callback is triggered on Plugin initialization i.e when the web page is loaded.

$('body').restive({
    onReady: function(){alert("I'M READY WHEN YOU ARE!");}
});

onResize

This callback is triggered after there is a change in the size of the Viewport.

$('body').restive({
    onResize: function(){alert("I JUST GOT RESIZED!");}
});

NOTE: This callback does not work on mobile devices i.e. phone and tablet

onRotate

This callback is triggered just after the Device Orientation changes i.e. from Portrait to Landscape and vice versa.

$('body').restive({
    onRotate: function(){alert("I JUST GOT ROTATED!");}
});

onRotateToP

This callback is triggered just after the Device Orientation changes from Landscape to Portrait.

$('body').restive({
    onRotateToP: function(){alert("I JUST GOT ROTATED TO PORTRAIT!");}
});

onRotateToL

This callback is triggered just after the Device Orientation changes from Portrait to Landscape.

$('body').restive({
    onRotateToL: function(){alert("I JUST GOT ROTATED TO LANDSCAPE!");}
});

onRetina

This callback is triggered if the Device has a pixel ratio of 2 or higher.

$('body').restive({
    onRetina: function(){alert("I CANNOT BE MORE CLEAR-EYED!");}
});

onPortait

This callback is triggered if the Device is in Portrait Orientation on initialization i.e. when the web page is loaded.

$('body').restive({
    onPortrait: function(){alert("I AM TALLER THAN I AM WIDE!");}
});

onLandscape

This callback is triggered if the Device is in Landscape Orientation on initialization i.e. when the web page is loaded.

$('body').restive({
    onLandscape: function(){alert("I AM WIDER THAN I AM TALL!");}
});

onPhone

This callback is triggered if the Device is a Phone.

$('body').restive({
    onPhone: function(){alert("I AM A PHONE!");}
});

onTablet

This callback is triggered if the Device is a Tablet.

$('body').restive({
    onTablet: function(){alert("I AM A TABLET!");}
});

onTV

This callback is triggered if the Device is a TV or TV-enabled e.g. game console.

$('body').restive({
    onTV: function(){alert("I AM A TELEVISION!");}
});

onPC

This callback is triggered if the Device is a Personal Computer i.e. not a phone, tablet, or tv.

$('body').restive({
    onPC: function(){alert("I AM NOT A PHONE, TABLET, OR TV!");}
});

onMobile

This callback is triggered if the Device is a Mobile Device i.e. phone or tablet.

$('body').restive({
    onMobile: function(){alert("I AM MOBILE!");}
});

onNonMobile

This callback is triggered if the Device is a Non-Mobile Device i.e. tv or pc.

$('body').restive({
    onNonMobile: function(){alert("I AM NOT MOBILE!");}
});

onAddClass

This callback is triggered when the Restive Plugin adds a class to the DOM element identified by selector e.g. when a breakpoint range is matched. The name of the class added is passed as the only argument of this function.

$('body').restive({
    onAddClass: function(name){alert("PLUGIN JUST ADDED A CLASS CALLED '"+name+"'!");}
});

onRemoveClass

This callback is triggered when the Restive Plugin removes a class from the DOM element identified in selector e.g. when there is no breakpoint match. The name of the class removed is passed as the only argument of this function.

$('body').restive({
    onRemoveClass: function(name){alert("PLUGIN JUST REMOVED A CLASS CALLED '"+name+"'!");}
});

Methods

These are the methods available within Restive Plugin. A usage example is also provided after each method description.

getPlatform

This determines the operating platform of the device. The following are the possible results when using this method: ios, android, symbian, blackberry, windows. If the device is not recognized as one of these platforms, other will be returned.

//example
var platform = $.restive.getPlatform();

getFormFactor

This determines the form-factor of the device. There are only four possible results: phone, tablet, tv, pc. If none of the first three are detected, it will be assumed that the device has a pc form-factor.

//example
var formfactor = $.restive.getFormFactor();

getResolution

This determines the standard graphic display resolution of the device e.g. VGA, SVGA, qHD, etc.

//example
var res = $.restive.getResolution();

getOrientation

This determines the currently active device orientation. The only two possible results are portrait, and landscape.

//example
var ort = $.restive.getOrientation();

getPixelRatio

This determines the pixel ratio of the device.

//example
var pxr = $.restive.getPixelRatio();

getViewportW

This determines the device viewport width [in device pixels].

//example
var viewport_w = $.restive.getViewportW();

getViewportH

This determines the device viewport height [in device pixels].

//example
var viewport_h = $.restive.getViewportH();

getScreenW

This determines the device screen width.

//example
var screen_w = $.restive.getScreenW();

getScreenH

This determines the device screen height.

//example
var screen_h = $.restive.getScreenH();

getPixelW

This determines the device viewport width [in device-independent pixels].

//example
var css_pixel_w = $.restive.getPixelW();

getPixelH

This determines the device viewport height [in device-independent pixels].

//example
var css_pixel_h = $.restive.getPixelH();

isMobile

This determines whether a device is a mobile device. Returns true if so, false if otherwise.

//example
var is_device_mobile = $.restive.isMobile();

isNonMobile

This determines whether a device is NOT a mobile device. Returns true if so, false if otherwise.

//example
var is_device_non_mobile = $.restive.isNonMobile();

isPhone

This determines whether a device is a Phone. Returns true if so, false if otherwise.

//example
var is_device_a_phone = $.restive.isPhone();

isTablet

This determines whether a device is a Tablet. Returns true if so, false if otherwise.

//example
var is_device_a_tablet = $.restive.isTablet();

isTV

This determines whether a device is a TV or TV-enabled device. Returns true if so, false if otherwise.

//example
var is_device_a_tv = $.restive.isTV();

isPC

This determines whether a device is a Personal Computer. Returns true if so, false if otherwise.

//example
var is_device_a_pc = $.restive.isPC();

NOTE: A pc [in the context of Restive Plugin] is basically any device that is not a phone, tablet, or tv.

isIOS

This determines whether a device is based on the iOS Platform. Returns true if so, false if otherwise.

//example
var is_device_ios = $.restive.isIOS();

isAndroid

This determines whether a device is based on the Android Platform. Returns true if so, false if otherwise.

//example
var is_device_android = $.restive.isAndroid();

isSymbian

This determines whether a device is based on the Symbian Platform. Returns true if so, false if otherwise.

//example
var is_device_symbian = $.restive.isSymbian();

isBlackberry

This determines whether a device is based on the Blackberry Platform. Returns true if so, false if otherwise.

//example
var is_device_blackberry = $.restive.isBlackberry();

isWindows

This determines whether a device is based on the Windows Platform. Returns true if so, false if otherwise.

//example
var is_device_windows = $.restive.isWindows();

NOTE: This method will detect both Windows Phones and Tablets.

isWindowsPhone

This determines whether a device is based on the Windows Phone Platform. Returns true if so, false if otherwise.

//example
var is_device_windows_phone = $.restive.isWindowsPhone();

NOTE: This method will detect only Windows Phones.

isRetina

This determines whether a device has a 'Retina' display i.e. a display with a pixel ratio equal to or greater than 2. Returns true if so, false if otherwise.

//example
var is_device_retina = $.restive.isRetina();

isPortrait

This determines whether a device is in Portrait Orientation mode. Returns true if so, false if otherwise.

//example
var is_device_portrait = $.restive.isPortrait();

isLandscape

This determines whether a device is in Landscape Orientation mode. Returns true if so, false if otherwise.

//example
var is_device_landscape = $.restive.isLandscape();

CSS Reference

This provides some information and guidance regarding how to set up your CSS for use with Restive Plugin.

Graceful Adaptation

Almost every Web Site is first built to provide a good user experience on Personal Computers. Then the Web Site is tweaked to provide a good user experience on mobile devices. We refer to this as "Desktop-First, Mobile-Second" and this is usually how most Web designers will need to approach making their Web sites adaptive to mobiles and other Web-enabled devices.

Graceful Adaptation aims to ensure that as a Web Designer you can do this as easily and quickly as possible. To do this, you will need to execute on the two following broad steps:

  1. Use Restive Plugin to add adaptation logic to your existing Web site (via the intelligent addition of classes to DOM elements)
  2. Add additional [and corresponding] CSS rules to your existing CSS file

Doing this allows you to easily tweak existing Web sites, and it also provides a good execution pathway for building new Web sites.

A Working Example

So let's assume we have an existing Web site that we have designed primarily for a Personal Computer experience, but which we now want to make responsive and adaptive to mobile devices.

Our Web site code base is as follows:

HTML

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Restive Plugin</title>
<meta name="viewport" content="width=device-width, initial-scale=1">

<link rel="stylesheet" href="global.css" type="text/css">

</head>

<body>
	
    <header>
    	<section id="hs-level-1">
        	<article id="hs-level-1-content">
            	<div class="logo"></div>	
            </article>
        </section>
        <section id="hs-level-2">
        	<article id="hs-level-2-content">
            	<nav>
                    <ul class="menu">
                	    <li><a href="#">Item 1</a></li>
                        <li><a href="#">Item 2</a></li>
                        <li><a href="#">Item 3</a></li>
                        <li><a href="#">Item 4</a></li>
                        <li><a href="#">Item 5</a></li>
                        <li><a href="#">Item 6</a></li>
                    </ul>
                </nav>                	
            </article>
        </section>
    </header>
    
	<div id="wrapper">
    	<section id="bs-level-1">
        	<article id="bs-level-1-content">
            	<h1>My Page Title</h1>
                <p>
                 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras dapibus venenatis lacus nec dignissim. Pellentesque nisl diam, congue nec purus ut, convallis consectetur dui. Proin aliquam mauris et nunc accumsan tristique vulputate eu eros. Pellentesque eget massa in magna pellentesque dapibus. Suspendisse accumsan eu mi id lacinia. Nullam sit amet dolor quis ipsum consequat tempor ut ornare mi. Vestibulum volutpat dictum adipiscing. Etiam ac justo condimentum, molestie diam eu, pulvinar elit. Nullam sagittis, ante sagittis eleifend bibendum, nunc elit commodo nunc, ut euismod lectus dui id neque. Etiam ut commodo eros. Aenean sagittis viverra tincidunt. Nunc posuere posuere consectetur. Integer tincidunt tortor eget nulla cursus, ut consectetur leo tristique.
                 </p>
                 <p>
Donec tempus consectetur tellus, non elementum nunc consectetur at. Nunc quis turpis ac ligula tincidunt aliquam. Mauris ante est, pharetra id sem ac, ultricies semper orci. Pellentesque sit amet mauris non massa lobortis ultrices a accumsan est. Donec tempor interdum ante, vitae volutpat neque faucibus eu. Integer sit amet blandit velit. Curabitur justo odio, consectetur vitae urna et, consectetur pharetra nibh. Nunc consectetur porttitor leo, non accumsan velit ultrices eget. Pellentesque vitae consectetur elit, non pharetra odio. Vivamus dictum laoreet dui, a sodales purus tristique sed. Nunc quis elit quam. Praesent facilisis tempor tempus. Etiam ullamcorper felis quis dui auctor aliquam. Cras luctus orci ut porta viverra. Ut eu dui sed libero convallis adipiscing sed ut elit.
				</p>
            </article>
        </section>
    </div>
    
    <footer>
    	<section id="fs-level-1">
        	<article id="fs-level-1-content">
            	<div class="contact">
                <p>1 WhereIWork Lane, WhereILive, USA 10101</p>
                </div>
            </article>
        </section>
        <section id="fs-level-2">
        	<article id="fs-level-2-content">
            	<div class="legal">
                <p>Copyright &copy; 2013 Business Inc.</p>
                </div>
            </article>
        </section>
    </footer>    
    
</body>
</html>

CSS

/** global.css **/
/*  
	CSS Reset by Eric Meyer - Released under Public Domain
    http://meyerweb.com/eric/tools/css/reset/
*/
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, font, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td {margin: 0;padding: 0;border: 0;outline: 0; font-size: 100%; font-weight:normal; vertical-align: baseline; background: transparent;}
body              {line-height: 1;}
ol, ul            {list-style: none;}
blockquote, q     {quotes: none;}
blockquote:before, blockquote:after,
q:before, q:after {content: '';	content: none;}
:focus            {outline: 0;}
ins               {text-decoration: none;}
del               {text-decoration: line-through;}
table             {border-collapse: collapse;border-spacing: 0;}
small, sub, sup { font-size: .83em; }
sub             { vertical-align: sub;}
sup             { vertical-align: super; }

/*------------------------------------------
Global Styles
-------------------------------------------*/
/* 	SET ALL ELEMENTS TO BOX-SIZING : BORDER-BOX */
* {
	-webkit-box-sizing: border-box;
	-moz-box-sizing: border-box;
	box-sizing: border-box;
	*behavior: url(boxsizing.htc);
	/*	If you need support for IE7 and lower make
		sure the boxsizing.htc file is linked properly.
		More info here:  https://github.com/Schepp/box-sizing-polyfill */
}

body {font-family: Arial, Verdana, sans-serif; font-size: 100%;  background-color: #ffffff; margin: 0 auto; -webkit-text-size-adjust: 100%; text-rendering: optimizeLegibility;}
img{max-width: 100%;}

/*------------------------------------------
Layout
-------------------------------------------*/
.clear{clear: both; display:block; overflow:hidden; visibility:hidden;}
#ie .clear{clear:both; display:block; overflow:hidden; visibility:hidden; width:0; height:1px;}
.clearfix:after {visibility: hidden; display: block; font-size: 0; content: " "; clear: both; height: 0;}
.clearfix {display: inline-block;}
/* start commented backslash hack \*/
* html .clearfix {height: 1%;}
.clearfix {display: block;}
/* close commented backslash hack */


header {width: 100%;}
header #hs-level-1 {height: 70px;}
header #hs-level-2 {height: 60px;}

#wrapper {width: 100%; padding: 30px 0 15px 0;}
#wrapper #bs-level-1 {}
#wrapper #bs-level-1-content{}

footer {width: 100%;}
footer #fs-level-1 {}
footer #fs-level-1-content {background-color: #eee;}
footer #fs-level-2 {}
footer #fs-level-2-content {background-color: #ddd;}

section article {width: 960px; margin: 0 auto;}

/*------------------------------------------
Typography
-------------------------------------------*/
h1, h2, h3, h4 {font-weight: bold;}
p {font-size: 110%; padding: 0 0 15px 0; line-height: 1.6em;}

#wrapper section article p {font-size: 120%; padding: 0 0 25px 0;}
#wrapper section article h1{font-size: 180%; padding: 0 0 15px 0;}
footer p {font-size: 100%; padding: 0 0 5px 0; color: #666;}

/*------------------------------------------
Menu
-------------------------------------------*/
header nav {}
header nav ul.menu {margin:0px; padding:0px; list-style-type: none; height: 60px;}
header nav ul.menu li {float: left; background-color: #000; width: 160px; height: 60px; line-height: 60px; vertical-align:middle; text-align: center;}
header nav ul.menu li a {color: #fff;}
header nav ul.menu li a:hover {text-decoration: none;}

/*------------------------------------------
Embellishments
-------------------------------------------*/
header #hs-level-1-content .logo {font-size: 420%; font-weight: bold;}
footer #fs-level-1-content .contact {}
footer #fs-level-2-content .legal {}

/*------------------------------------------
Mobile - for Restive Plugin
-------------------------------------------*/

NOTE: Just in case you didn't notice, our CSS file is embedded by link tag via global.css and not inline.

NOTE: We have placed a section header in our CSS file titled "Mobile - for Restive Plugin" in anticipation of the CSS code we will be adding later on.

As it stands, this code is not responsive or adaptive.

So let's now use the Restive Plugin to make our Web Site mobile-optimized. However, before we start, let's identify all the things we want to have happen to the Web site when a Mobile device is accessing it. We would like to:

  • Change the layout width from 960px to a fluid value of 100%, and add 10px padding on either side
  • Align the logo to the right of the layout if the device is a tablet; and align the logo to the center of the layout if the device is a phone
  • Collapse the horizontal menu to a vertical one, and reduce the height of each menu item if the device is a phone
  • Reduce the text size in the footer area

So now let's install and initialize the Restive Plugin by adding the following to our existing HTML code:

HTML

<!-- Install JQuery version 1.7 or higher -->
<script type="text/javascript" src="jquery.min.js"></script>

<!-- Install Restive Plugin -->
<script type="text/javascript" src="restive.min.js"></script>

<!-- Initialize Plugin -->
<script>
$( document ).ready(function() {
    $('body').restive({
        breakpoints: ['240', '320', '480', '640', '720', '960', '1280'],
        classes: ['rp_240', 'rp_320', 'rp_480', 'rp_640', 'rp_720', 'rp_960', 'rp_1280'],
        turbo_classes: 'is_mobile=mobi,is_phone=phone,is_tablet=tablet',
        force_dip: true
    });
});
</script>

The Installation part is pretty straighforward, we just link the JQuery and Restive Plugin.

From the Initialization part, we see that we have defined four options for Restive Plugin: breakpoints, classes, turbo_classes, and force_dip. Let's now explain what this all means.

The Restive Plugin will actively monitor the viewport of any devices that visit your web site for the following declared breakpoint ranges (as we have defined them above): 0 to 240px, 241 to 320px, 321 to 480px, 481 to 640px, 641 to 720px, 721 to 960px, and 961 to 1280px (Please note that these are device pixels by default and NOT device-independent pixels). If the viewport of the device that visits our Web site is between 0 and 240 pixels wide, Restive Plugin will detect this and it will add the class rp_240 to the <body> tag (which is our JQuery selector); if the viewport is between 241 and 320 pixels wide, it [Restive Plugin] will add the class rp_320, and so on. This is basically how breakpoints and classes work. If you notice, the number of breakpoints items is equivalent to the number of classes items.

turbo_classes is a special feature of Restive Plugin that will add one or more classes [in addition to any other classes previously added] to our <body> tag when certain conditions are met. From our settings, we have specified that we want to add three classes; mobi, phone, and tablet when the device is a mobile device, a phone, and/or a tablet. So if an iPhone 4 visits our web site, the turbo_classes option will tell Restive Plugin to add mobi and phone as classes to the <body> because an iPhone 4 is a mobile device and a phone also. If it was an iPad 2 instead, then what would get added would be mobi and tablet. You'll see why this is useful later on.

Finally, the force_dip option will force breakpoints to consider device-independent pixels [instead of device pixels] in its declared ranges. Restive Plugin by default considers device pixels. However, in certain scenarios, you might want to go with device-independent pixels instead and the force_dip option let's you do this. Consider an iPad 4, which has a retina display [pixel ratio of 2] and a device pixel width of 1536 in portrait orientation. This means that it will not match any of our defined ranges since our breakpoints top out at 1280. However, as our Web site is not so complicated as to warrant additional CSS rules for retina tablets, we want a retina tablets to be classified the same as non-retina tablets e.g. iPad 2. So by setting force_dip to true, Restive Plugin will see only in device-independent pixels, so 1536 [device pixels] will be considered as 768 [device-independent pixels], which obviously matches one of our declared breakpoint ranges.

So let's now append our additional style rules to our CSS file:

CSS

/*------------------------------------------
Mobile - for Restive Plugin
-------------------------------------------*/
.mobi {font-size: 110%;}

.mobi section article {width: 100%; padding: 0 10px;}

.mobi.tablet header #hs-level-1-content .logo {text-align: right;}
.mobi.phone header #hs-level-1-content .logo {text-align: center;}

.mobi.phone header #hs-level-2 {height: auto;}
.mobi.phone header nav ul.menu {height: auto;}
.mobi.phone header nav ul.menu li {float: none; width: 100%; height: 40px; line-height: 40px; border-bottom: 1px dashed #aaa;}

.mobi footer p {font-size: 80%;}

NOTE: This CSS code is appended to our earlier CSS file where we made space for it under "Mobile - for Restive Plugin".

So if we now visit this web page with an iPhone 4, Restive Plugin will add mobi phone rp_320 to the class attribute of the <body> tag. Note that if we didn't set force_dip to true, this value would have been mobi phone rp_640, since Restive Plugin would be considering only device pixels [and not device-independent pixels] in the declared ranges.

So after Restive Plugin does its work, based on our additional CSS rules, we can expect the following outcomes:

  • The font-size for mobile devices will be 110%
  • The layout will become fluid and padding of 10px for the left and right sides will be applied
  • The alignment of our logo will be right for tablets, and center for phones
  • The menu will be collapsed vertically (for phones) i.e. float will be removed, the width will be 100%, and the height of the menu layout has been reset to auto. The height of menu items (<li>) will also become 40px, and a bottom-border will be added to delineate each item.
  • Finally, the footer paragraph font-size will be reduced to 80%

So with Restive Plugin, and with just a few lines of additional code in JS and CSS, we can make a web page responsive and adaptive to mobile devices.