Documentation

Installation

To install restive.js, simply link to the plugin after JQuery:

html
<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 refers to the CSS file(s) containing all your stylesheet definitions.

Usage

The basic format for using restive.js is as follows:

html
<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 a Web page 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:

html
<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'],
        force_dip: true
    });
});
</script>

So what does the setup above represent?! Restive.js 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. The force_dip option will force restive.js to consider device-independent pixels [instead of device pixels] in its declared ranges; this is necessary for devices with pixel ratios higher than 1.

So if I have a Google Nexus 5 (1080 pixels by 1920 pixels [in portrait orientation], pixel ratio of 3) and I visited a Web site with the above restive.js configuration, restive.js would add the class css-480 to the body tag, because the viewport falls within 320 pixels and 480 pixels [device-independent]. 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

Responsive

A responsive Web page is one that will adjust to the size of the viewport. It is meant to provide an optimal viewing experience regardless of screen size. Basically, you know your Web page is responsive when its layout automatically adjusts itself as you resize your browser window.

Mobile-friendly

A mobile-friendly Web page is one that will adjust its layout to specific devices or device classes. It is meant to provide a targeted experience for a specific mobile device or device class e.g. smartphones, tablets, etc. It is possible for a Web page to be only mobile-friendly and not responsive.

Adaptive

An adaptive Web page is one that can be setup to adjust its layout to multiple situations beyond just the screen size. For example, an adaptive Web page could be setup to adjust its layout to OS e.g. iOS, Android, etc. It would usually depend on the scope of usage of the Web page.

An adaptive Web page could also encompass mobile-friendly and responsive features.

Modular

Modular Web Design is an approach to web design in which a Web page/site is first broken into components, and then these components are designed, developed, tested, and finally assembled to create a finished Web page/site. A key advantage of this approach is encapsulation.

For example, if you design a Web page widget, and you need to upgrade it, you can simply update the widget without tampering with any of the other component modules that make up the whole Web page.

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

Breakpoints 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 range1.

Restive.js 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.js

  • 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.js 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.js does this automatically.

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

1 Source: Web Site - 1stwebdesigner.com

Special Features

Breakpoint Orientation Markers

Orientation markers are a special feature of restive.js 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; restive.js 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.js 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.js 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:

js
$.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:

js
$.restive.startMulti();

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

$.restive.endMulti();

And, if you feel squeamish about doing things this way, you can always use good 'ol if conditional statements

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

Please see Methods for more information on restive.js methods

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 <body> 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.js 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 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:

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

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:

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

So what's happening here? When a resize of the viewport or change in orientation causes the width of the HTML element identified by the div tag with 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 upper range.

Options

breakpoints

An itemized list of dimensions that define a specific range within which an adaptive action should take place. Restive.js 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.

NOTE: restive.js 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:

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

The above setting means that restive.js 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 restive.js will enable a range of 0 to 240; if 480 is the next item, restive.js 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.js selector, in lock-step with the corresponding breakpoints.

Classes are defined as an array:

js
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.js 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.js settings are as set up below:

js
$('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.js 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:

js
$('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 option enables Modularity (see Concepts above for an explanation) in restive.js. It 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: When using anchor option with element value, you must use a valid JQuery ID selector in your restive.js 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 anchor is used, and its value is element i.e. when Modularity is in effect.

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 set to e or element

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_pc: 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:

js
$('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=r_mobi,is_portrait=r_portrait'
});

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, r_mobi will be added to the <body> tag class attribute

  • If the device is in portrait orientation, r_portrait will be added to the <body> tag class attribute

So if the device is in portrait, and is 640 pixels wide, r_mobi r_portrait 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=r_mobi,is_mobile=r_mobi_plus'

Event Callbacks

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

The following callbacks can are available:

onReady

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

js
$('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.

js
$('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's orientation changes i.e. from portrait to landscape and vice versa.

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

onRotateToP

This callback is triggered just after the device's orientation changes from landscape to portrait.

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

onRotateToL

This callback is triggered just after the device's orientation changes from portrait to landscape.

js
$('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.

js
$('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.

js
$('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.

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

onPhone

This callback is triggered if the device is a phone.

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

onTablet

This callback is triggered if the device is a tablet.

js
$('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.

js
$('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.

js
$('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.

js
$('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.

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

onAddClass

This callback is triggered when restive.js 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.

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

onRemoveClass

This callback is triggered when restive.js 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.

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

Methods

These are the methods available within restive.js. 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.

js
//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.

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

getResolution

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

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

getOrientation

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

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

getPixelRatio

This determines the pixel ratio of the device.

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

getViewportW

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

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

getViewportH

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

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

getScreenW

This determines the device screen width.

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

getScreenH

This determines the device screen height.

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

getPixelW

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

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

getPixelH

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

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

isMobile

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

js
//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.

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

isPhone

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

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

isTablet

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

js
//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.

js
//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.

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

NOTE: A pc [in the context of restive.js] 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.

js
//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.

js
//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.

js
//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.

js
//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.

js
//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.

js
//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.

js
//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.

js
//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.

js
//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.js.

Graceful Adaptation

Almost every Web page is first built to provide a good user experience on desktops. Then the Web page 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 page responsive and/or mobile-friendly.

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.js 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 page that we have designed primarily for a desktop experience, but which we now want to make responsive and mobile-friendly.

Our Web page code base is as follows:

HTML

html
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Restive.JS</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

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.js
-------------------------------------------*/

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.js" in anticipation of the CSS code we will be adding later on.

As it stands, this code is not responsive or mobile-friendly.

So let's now use the restive.js to mobile-optimize our Web page. However, before we start, let's identify all the things we want to have happen to the Web page 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 restive.js by adding the following to our existing HTML code:

HTML

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

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

<!-- Initialize Plugin -->
<script>
$( document ).ready(function() {
    if($.restive.isPC())
    {
        $('body').restive({
            breakpoints: ['560', '960'],
            classes: ['r_mobi r_phone', 'r_mobi r_tablet'],
            force_dip: true
        });
    }
    else if ($.restive.isMobile())
    {
        $('body').restive({
            breakpoints: ['10000'],
            classes: ['nb'],
            turbo_classes: 'is_mobile=r_mobi,is_phone=r_phone,is_tablet=r_tablet,is_landscape=r_landscape',
            force_dip: true
        });
    }
});
</script>

The Installation section is pretty straighforward, we just link the JQuery and restive.js.

From the Initialization section, we've setup our Web page to be both mobile-friendly and fast. On desktops, the layout will be responsive to two breakpoints: 0 to 559px and 560 to 960 pixels. However, on mobile, there are no breakpoints, but we use turbo-classes feature to tell us when the device is a mobile device, when it is phone or tablet, and whether it's in landscape orientation or not. Once you've set this up, that's it! All you need to do now is go to CSS and add some code.

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

CSS

css
/*------------------------------------------
Mobile - for restive.js
-------------------------------------------*/
.r_mobi {font-size: 110%;}

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

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

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

.r_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.js".

So if we now visit this web page with an iPhone 4, restive.js will add nb r_mobi r_phone to the class attribute of the <body> tag.

So after restive.js 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.js, 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.