Clarity Documentation

Contents:

- Basic Intallation

- Navigating CSS

- Configuring Layouts

- Responsive Javascript

- Responsive Design

- Important Classes

- Choosing a Color Theme

- Customization

- Buttons

- Bootstrap

- Code Editor

- Charts

- Retina Web Font Icons

- Maintaining IE Compatability

- Plugin Documentation

- Release Notes

- Support

# CLARITY DOCUMENTATION

# Basic Installation

To get this template running on your own server upload the contents of the "Upload" folder to the root of your webserver.

When making modifications to this template it is recommended that you work with the files inside the root folder, not the "Upload" folder because the "Development" folder has additional documentation and example files for the included plugins.

Take a look at the included page templates to get an idea of what is possible and how you'd like to configure your applications UI. Some templates have a left sidebar and some have a right and left. The instructions below will guide you through setting up your own preferred layout for when your template first loads.

For production use, it is recommended that all javascript be minified and static assests such as images served from multiple locations.

# Navigating CSS

Sections in the core.css file have headings to make searching the file easy. Throughout this documentation there are references to different sections that you can search for the document's header to find. Examples are @BUTTONS, @PROJECTS, @CALENDAR, @CODE EDITOR, etc.

Some header names of sections you might search for:

- @DASHBOARD VIEW
- @CENTER VIEW
- @MESSAGES
- @INTERFACE FRAME (for UI Layout pane backgrounds)
- @JAVASCRIPT MEDIA QUERY SUPPORT
- @CALENDAR
- @STATS CHARTS
- @SIDEBARS
- @BUTTONS
- @BUTTON OPTIONS
- @BUTTON SIZES
- @BUTTON COLORS
- @DATA TABLES
- @CODE EDITOR
- @PROJECTS DASH SECTION
- @INTERFACE ICON BUTTONS
- @TOPBAR
- @TOPBAR BUTTONS AND INPUT
- @NOTIFICATIONS DROPDOWN
- @LOGIN PAGE
- @FOOTER
- @ALERTS
- @ACCORDION AND BREADCRUMBS
- @MODIFIED BOOTSTRAP
- @MODIFIED RESPONSIVE STRUCTURE
- @IPAD PORTRAIT
- @IPAD LANDSCAPE
- @IPHONE
- @TABLET PORTRAIT
- @TABLET ADDITIONAL

# Configuring Layouts

This theme makes the creation of complex application layouts easy with the jQuery UI Layout plugin. By default the UI Layout plugin will render a top, bottom, left right and center pane. each of these panes is resizable. All of the page templates included in this theme have the south (bottom) pane hidden by default. Instead each pane has been given a custom footer which holds toolbar buttons and sidebar collapse buttons for the center pane. Settings for how the interface panes load can be easily controlled in javascript. Optionally the users layout configuration (visable panes and their sizes) can be saved in a cookie to maintain its state. Lastly, it is also possible to next layouts inside layouts to create even more panges.

Below is a UI Layout snippet with options set for its intial load. As you can see you can disable resizing, set a panes size and min and max sizes, set if the pane should be visable on load and if a pane can open and close.

              var myLayout;

            $(document).ready(function () {

                // this layout could be created with NO OPTIONS - but showing some here just as a sample...
                // myLayout = $('body').layout(); -- syntax with No Options

                myLayout = $('body').layout({

                //  enable showOverflow on west-pane so CSS popups will overlap north pane
                    west__showOverflowOnHover: false

                //  reference only - these options are NOT required because 'true' is the default
                ,   closable:               true    // pane can open & close
                ,   resizable:              true    // when open, pane can be resized
                ,   slidable:               true    // when closed, pane can 'slide' open over other panes - closes on mouse-out

                //  some resizing/toggling settings
                ,   north__slidable:        false   // OVERRIDE the pane-default of 'slidable=true'
                ,   south__resizable:       false   // OVERRIDE the pane-default of 'resizable=true'
                ,   north__resizable:       false   // OVERRIDE the pane-default of 'resizable=true'
                ,   north__initClosed:      true
                ,   north__initHidden:      true
                ,   north__size:            0  // OVERRIDE the pane-default of 'resizable=true'
                ,   south__size:            0   // OVERRIDE the pane-default of 'resizable=true'
                ,   south__spacing_open:    0       // no resizer-bar when open (zero height)
                ,   north__spacing_open:    0       // no resizer-bar when open (zero height)
                ,   south__spacing_closed:  0       // big resizer-bar when open (zero height)
                ,   east__initClosed:       false
                ,   west__initClosed:       false
                ,   south__initClosed:      true
                ,   resizeWhileDragging: true
                //  some pane-size settings
                ,   west__minSize:          190
                ,   west__size:             250
                ,   east__size:             0
                ,   east__minSize:          0
                ,   east__maxSize:          Math.floor(screen.availWidth / 2) // 1/2 screen width
                ,   center__minWidth:       100

                ,   useStateCookie:         true
                });

### Starting with a Content Free Interface Frame

Open the file "interface-frame.html" if you would like to start fresh with adding your own content to the application frame. This file includes the outer app interface, minus the content.

### Making the UI Layout Responsive

Because the layout is being partially generated with javascript we need a way for the layout to update along with CSS media queries. Read the responsive javascript section below to learn how this works.

# Responsive Javascript

This theme has javascript logic specific for desktops, tablets and smartphones. A very small library allows different scripts to be loaded, depending on the media query used in CSS.

This is useful for:

- Loading a different UI Layout with smaller sidebar panes or less panes altogether on tablets and smartphones.
- Loading a javascript file specifically for mobile without impacting the load time on desktops
- Keeping the heaviest scripts for the desktop only to create a faster mobile experience.

Take a look at the "responsive.js" file for an example. Even if you do not plan to use additional responsive javascript, you will need to include this in your page so that the UI Layout plugin stays responsive.

### Setup

Setup your responsive javascript by defining a set of html font-family strings in your stylesheet that correspond to the media queries you wish to test for: (this can be found at the top of your core.css stylesheet)

              /***------ @JAVASCRIPT MEDIA QUERY SUPPORT ------***/

    html {
            font-family: 'mobile';
        }
        * html { /* IE6 */
            font-family: 'desktop'
        }
        *+html { /* IE7 */
            font-family: 'desktop'
        }
        @media \0screen {
            html {  /* IE8 */
                font-family: 'desktop'
            }
        }
        /* Reset your font families here!
         ----------------------------------- */
        body {
            font-family: "Lato", arial, sans-serif;
        }
        /* Queries for supported browsers.
         ----------------------------------- */
        @media only screen and (min-width: 768px) and (max-width: 1024px){
            html {
                font-family: "tablet";
            }
        }
        @media screen and (min-width: 1025px) {
            html {
                font-family: "desktop";
            }
        }

Now define the queries you want to test for. Take a look at your responsive.js file to see how it is being used. Here is a basic example without any scripts added:

              // JAVASCRIPT MEDIA QUERY

    var queries = [
        {
            context: 'mobile',
            callback: function() {
                console.log('Mobile callback. Maybe hook up some tel: numbers?');
                // Your mobile specific logic can go here.
            }
        },
        {
            context: 'tablet',
            callback: function() {
                console.log('tablet callback! Swap the class on the body element.');
                // Your tablet specific logic can go here.
            }
        },
        {
            context: 'desktop',
            callback: function() {
                console.log('wide-screen callback woohoo! Load some heavy desktop JS badddness.');
                // your desktop specific logic can go here.
            }
        }
    ];
    // Go!
    MQ.init(queries);

# Responsive Design

Bootstrap is providing some of the responsive structure for this design, mainly the fluid collumns. The bottom of the core.css file holds additional modications to make this interface function the way it does.

If you are new to responsive design there are two important things to remember when making adjustments to this theme.

1. Be careful when modifying a style, to make sure that you check if it is appearing later in the document under a media query, as you may need to modify it there as well. Forgetting to do this can result in unexpected breaking of your designs layout when activating media queries. It is always easier to do this as you go rather than trying to remember each modififcation later.
2. There are window based media queries and device width based media queries. Some media queries target a specific device only, such as the media query for an iPad in portrait position with device widths. When you resize your browser window this media query will not be activated because it only applies to a device with matching screen dimensions. To test modifications to this in a browser you can temporarily change the media query from "min-device-width" to "min-width".

# Important Classes

When searching for a part of the template that you would like to edit or implement, remember firebug and the web inspector can help you find the ids and classes you need quickly. Here are a few classes you will probably be working with and what they do:

- .dashTop: the container style for the top graph on the dashboard page.
- .dashWidget: This creates the nice boxes on the dashboard page as well as on a few others. Can scale to any width using Bootstraps fluid grid. Span6 will fill have the center view and span12 will fill the entire center view.
- .dashHead: the header bar for dashboard widgets. Must be used on top of the dashwidget box.
- .noPadding: removes padding. Useful for dashwidgets that should not have padding.
- .autoHeight: When applied to dashwigets their height will change to auto instead of a fixed height.
- .message-box: the container style for messages on the dashboard and messages page.

Below is a code snippet of a dashWidget container:

              <div class="row-fluid">
                <div class="span12">
                  <h2 class="dashHead"><i class="icon-ok-sign"></i> Widget Header Here:</h2><!--Header and Icon-->
                  <div class="dashWidget autoHeight"><!--Widget Container set to auto height-->
                  <p>All of your content goes here.</p>
                </div>
              </div>

# Choosing a Color Theme

This theme includes 6 frame colors (topbar and footer bar) and two sidebar colors for a total of 12 color combinations. Each combination has its own stylesheet ready for you to choose. The default grey color scheme is core.css, and additional color schemes are named by their color, ie: blue.css for blue and dark sidebar or blue-light.css for blue with a light sidebar.

# Customization

### Setting Up and Locating Javascript Files

Because of the large amount of javascript involved in the interface, instead of placing snippets directly in the head of the document, they are located in an application.js file. Some pages may have different application.js files. For instance the Graph page template uses application-graphs.js. Additionally each page may have it's own responsive.js file to call certain scripts for different devices. Make sure you check these when editing or building your own template. This is where you'll want most of your javascript to go.

### Starting with a Content Free Interface Frame

Open the file "interface-frame.html" if you would like to start fresh with adding your own content to the application frame. This file includes the outer app interface, minus the content.

# Buttons

This theme includes a variety of custom designed CSS3 buttons. Implementing them is easy. Simply create an anchor element with the class "btn".

    <a href="#" class="btn">Normal</a>

Adding the class .small-btn .large-btn .xlarge-btn or .xxl-btn will change the button size.

Adding the color class next to the button will change the button color. For example: .btn is a standard blue button. Adding the .pink-btn class in addition will make the button turn pink.

To find all the button classes in core.css, search for @BUTTONS.

# Bootstrap

This theme uses Twitter's Bootstrap for some default styling, javascript plugins and easy customization. In the bottom of the core.css stylesheet there is a section with modifications to overide and customize some of Bootstrap's default styling. Search @MODIFIED BOOTSTRAP in core.css to find it. See the Bootstrap documentation for help with implementing additional features from it. If you are having trouble or have a question remember you can contact us!

# Code Editor

The CodeMirror plugin provides this themes code editor functionality. The interface loads with a file list design on the left, an editor window in the center and a live preview on the right. There are also selectable syntax highlighting themes in the footer bar below. When pasting in an HTML file, if you link stylesheets remotely or in the proper path on your local machine you will see a live preview with CSS appear on the right. This layout provides an example of the flexiblity of the template, Being able to load different sidebars with different widths for different pages allows you to build a robust app with many different features.

# Charts

Charts are rendered using the Flot plugin. There is also a Sparkline plugin for rendering smaller charts and sparklines. Take a look at "application-graph.js" which provides the chart data for the graph page template to get an idea of how colors on the data and plot are customized. Search @STATS CHARTS in your core.css file for chart container styling.

# Retina Web Font Icons

This theme includes multiple sets of web font icons. These icons are compatible with all browsers down to IE7. The main set includes all of the icons you would typically find in Twitter's Bootstrap, converted into web font icons. They are implemented the same way you would implement an icon in Boostrap and all the class names are the same.

The Font Awesome Icons use a Creative Commons license and the author requires that you leave the comment above the CSS like this:

    <!-- Retina Webfont for Boostrap from Font Awesome - http://fortawesome.github.com/Font-Awesome -->"

Besides looking great on retina displays, webfont icons can have their color set in CSS like any other font. You can also apply effects like text-shadows and transitions.

Also included are additional opensource webfont icon sets from Zurb and justbenicestudio.

Icon source files are located in the "/fonts" folder. Learn more about each icon set at the links below.

- http://fortawesome.github.com/Font-Awesome/
- http://www.justbenicestudio.com/studio/websymbols/
- http://www.zurb.com/playground/foundation-icons

# Maintaining IE Compatibility

IE 8 and 9 do not support media queries and this means they will not support responsive javascript either. Make sure that you have an alternate script for IE to load instead of it looking at the responsive.js file. The responsive-IE.js is an example of this setup. The responsive-IE.js file includes only the desktop scripts that would be called from responsive.js. Every template included has this setup. Here is an example how how you will want to place it in your document head:

    <!-- Scripts inside js/application.js-->

    <script type="text/javascript" src="js/application-other-pages.js"></script>
    <![if !IE]>
    <script type="text/javascript" src="js/responsive-other-pages.js"></script>
    <![endif]>

    <!--[if lte IE 10]><script language="javascript" type="text/javascript" src="js/responsive-other-pages-IE.js"></script><![endif]-->

# Plugin Documentation

View the application.js file for the page template you are using to see the scripts being used. Each plugin is separated and commented.

Find additional documentation for the included plugins at the links below:

- Bootstrap: Used for it's default styling, responsive collumns, icons and plugins (dropdowns, tabs, tooltips, alerts, modals, etc.) http://twitter.github.com/bootstrap/index.html
- jQuery: jQuery http://jquery.com/
- jQuery UI: Used as a dependancy for plugins like UI Layout and more. Also for datepicker and draggable functionality. http://jqueryui.com/
- jQuery UI Layout: Used for it's creation of interface panes that can be easily hidden and resized. http://layout.jquery-dev.net/
- Flot: Provides a great flexible javascript charting framework http://code.google.com/p/flot/
- Elrte: WYSIWYG Editor http://elrte.org/
- Gritter: Growl style notifications. http://boedesign.com/blog/2009/07/11/growl-for-jquery-gritter/
- OnMediaQuery: Enable responsive javascript so your scripts can react to media queries. https://github.com/JoshBarr/js-media-queries
- CodeMirror: A full blown code editor and live preview. http://codemirror.net/
- Datatables: Sortable, searchable datatables. http://datatables.net/
- Colorpicket: UI Colopicker http://www.eyecon.ro/colorpicker/#implement
- FullCalendar: Functional javascript calendar. http://arshaw.com/fullcalendar/
- Sparkline: Mini charts and sparklines. http://omnipotent.net/jquery.sparkline/#s-docs
- Google Fonts: Open source font collection. http://www.google.com/webfonts/

# Release Notes

Version 1.1 - First feature update

- Color Themes - a total of 12 dimensional CSS3 color combinations available!
- Style Switcher - easily switch through stylesheets with this jQuery plugin.
- Gallery Page Template - A gallery template with CSS3 hover effects.
- Retina Web Font Icons - Interface icons are now retina ready. Over 200 icons to choose from!
- Added Additional Icon Buttons.
- Added More Error Page Templates - 400, 401, 403, 500, 503
- Extra Wide Desktop Layout Optimization - Now this theme looks even better on screens over 1600px wide.
- Custom drag handle on left sidebar now functions as expected.
- Updated Documentation.
- Additional minor fixes.

Version 1.0 - Initial Release

More features and enhancements coming! Contact us with requests or if you believe you have found a bug.

# Support

Need More Help? Have a feature request for a theme? Contact me on Themeforest at:

http://themeforest.net/user/BryanMcAnulty

Thanks for purchasing this file!

Bryan McAnulty

Copyright 2012, Bryan McAnulty