Wintermin - Bootstrap Admin Theme

Bootstrap 3 theme designed for Admin Templates

This item is a Bootstrap 3 theme designed to work with admin templates. Built on latest version of Twitter Bootstrap 3 with new features and customizable options.

This document aims to explain the best way to integrate with the product and its components

All the best and enjoy coding.

Before start Tips

Do not start from scratch, use an existing asset and modify it to learn how it works.

Explore the sources for ideas and sample code.

Use Firebug or Chrome Developer Tools to find bugs on your website. Using one of those tools will help you to save time analizing the site and finding elements structure, like classes, id or tags

Quick tip

Open your site with Chrome, press F12 and go to console tab, reload your page and if something goes wrong you will your page errors in red text.

Getting an error message? Someone might have seen it too, try a google search for a quick fix.

Need to compile the source? Get Prepros or CodeKit. Both tools are excellent to work with pre-compiled languages like LESS and JADE.

Installing

After download the zip package from Codecanyon unzip the files in a temporary folder and copy the following folders to your root working directory

- app/

- pages/

- vendor/

Next copy the file called template.html to your working directory. This file is an empty template to use as a boilerplate for your pages.

In case you want to work with the source files (LESS, JADE or Javascript) you will need the folder master/

In case you need to use the upload or chart components you will need the folder server/

The app folder

This folder contains the compiled files. This files are ready to desploy on your server.

The pages folder

This folder contains the compiled html files for the pages included. This files are ready to desploy on your server.

The vendor folder

This folder contains the vendor files used to include plugins and other components. All this components are untouched from its original version so in case you have to update some of them you can do it by simply replacing its content.

The master folder

This folder contains the source files. You will find the following folders inside

- jade

This folder contains JADE files. This files need to be compiled into html files to be displayed by a browser

- less

This folder contains the LESS files for the core styles and bootstrap styles.

- js

Here you will find pure JS files. All this files are concatenated into the file app.js.

The server folder

This folder contains php files asa demostration and guide for the flot chart and file upload components

The following picture describes the main pieces of the layout

The layout is based on the following markup represented with

<html>
  <head>
    #metas and css
  </head>  
  <body>
    <section class="wrapper">
        <nav class="navbar navbar-default navbar-top navbar-fixed-top">
          #navbar top content
        </nav>

        <aside class="aside">
          #aside content (sidebar left)
        </aside>

        <aside class="offsidebar">
          #offsidebar content (right)
        </aside>

        <section>
          <div class="main-content">
            #page content
          </div>  
        </section>
     </section>

     #scripts

  </body>
</html>

The top navbar, is a compoenent based on the classic navbar-top from bootstrap but redesigned to contain a larger and collapsible header,

The sidebar (right) has different behavior on mobile and desktop devices. On desktop, under the class .aside-toggle the navbar is condensed (to save space), on mobiles, under the same class the navbar is displayed on screen and if toggled the navbar hides automatically (off-canvas)

The offsidebar is similar to the sidebar but it hides always off the screen. That means, the offsidebar is an offcanvas components.

The section tag, child of the .wrapper element contains the main content of the page under the element .main-content. All this structure is used to achieve the slide effect on different devices when the sidebar (on mobile) or offsidebar is toggled.

To change the color scheme you have 2 options:

From LESS files

Edit the LESS files in folder master/less/app and the file master/less/bootstrap/variables.less to use the color you want.
Like Bootstrap, most of the colors are based on @brand-* variables. For example, the primary color used for the theme is based on the variable @brand-primary.

You can also edit the files in master/less/theme folder to create your own set of color schemes. This files must be included before the app.css in your page to override the default color set.

Changing the theme from LESS files helps you to avoid bloating your css by not double declaring your color rules.

From CSS files

This template support color schemes including a css file. You can find 4 color options in the folder app/css/, and files are named wintermin-theme*.css

If you want to change or add a new component color, just inspect the color using your favorite browser devtool and then replace the value in the file.

This files are prepared to change the basic color scheme (both sidebars and top navbar) but if you want to make a more deep change I suggest you to check the LESS way which is more simple to large component changes.

Using compiled files

To use the compiled files you only need the content of the app folder.

You only need to link to this files in your pages (or use the template.html as a base) and done. Then you can continue customizing the app.css, app.js or bootstrap.js

It's strongly suggested that you create and use a file custom.css for all your pages to avoid changing the main styles. This will make easy for you to track changes you have made and more simple to detect any issue in case you need support.

Compiling files

Install node and gulp

Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications.

Gulp is a task manager, you can define different tasks to run certain commands. Those commands does the compilation job for JADE and LESS, and concats the JS files.

The package includes under the master/ folder the file gulpfile.js and package.json to install the required componets to compile the source files.

It's not necessary that you use gulp, you can choose to work with your favorite tool to compiles LESS, JADE and concat JS file (e.g. codekit, prepros)

The following steps are intended to be an orientation guide, if you are not experienced with this you will need to learn more about it from Google :)

- To install node, go to http://nodejs.org/
- Then install npm https://www.npmjs.org/doc/README.html

After that, open a terminal and go to the master folder, then run the command npm install. This command will install gulp and all depencies.

Then run gulp to start the task manager

If everything goes fine, you should see the messages in the terminal telling you that most the task are done ok. The task includes a watch to compile automatically all files when they change.

Javascript

The JS files are divided in the app script, the page script and the modules folders.
The module folder is shared by the app and pages script.

The modules folder contains different script used to init different features that requires Javascript. Those modules are plugin definitions (customized for this templates) and others are event listener like the dropdown animation, sidebar toggler, etc.

The app script is app.init.js. This script is concatenated after all modules to have one point where all the modules are loaded and interpreted and so, they are ready to use.

The page script is page.init.js. This script is concatenated after all modules to have one point where all the modules are loaded and interpreted and so, they are ready to use. The difference here is that the modules that you want to include in your pages must be specified in the file gulpfile.js (in case your using gulp)

Do not include the file app.js in all your pages. Find the module and paste the source in page.js to keep pages lightweight and separated from the application source. Or even better, use a tool to concat only the modules required for your pages.

Jade structure

The JADE structure is based on a layout file named main-layout.jade, under the layout/ folder and all templates extends this layout. There are also partials, included in the layout file to separate different section of the page that are common to all templates.

Jade sidebar

The sidebar has a special treatment when using JADE templates. The main file for the sidebar is sidebar.jade under the partials/ folders.
This files include another named sidebar sidebar-config.jade this contains an array definition with the menu elements and mixin that uses that array to iterate and create all menu items.
This technique has the following advantages
- It allows to mark every menu item according to each page compiling, so you don't need to do it manually in the html source.
- You can see more clearly the menu structure and make changes easily without browsing through the markup

Please, note that JADE generates static html templates. This templates need to be converted to PHP/ASP pages to make it dynamic. There are some server implementation on the web that can serve jade files compiling them before sent it to the client.

LESS structure

The LESS files are divided in three folders

bootstrap folder contains the bootstrap files. This files are compiled into bootstrap.css, with just the main bootstrap styles.

app folder contains the custom files for this templates and also it uses variables.less and mixins.less from bootstrap so it's possible to integrate the new components with the framework reducing duplicated declarations and allowing to have a single point of definition.

pages folder contains the custom files pages. Each LESS file in this folder will should be compiled into its CSS version for a particular page. For example, the file include landing.less is included as landing.css just the for the landing page.

There are many ways to keep separated the app source from the pages. The above mentioned are just an example. You should use the best that fit your needs.

Vector Maps

The vector maps are based on the jQuery jVectorMap plugin.
You can find more information about this plugin here and other maps here.

This item implementation uses two object to populate the map. One is for the series and other is for markers.
With series you can choose which region should hilight in the map to display some information associated with that region (e.g. visitors). Markers are similar to the google maps marker, just set a coordinate and a name and the marker will appear on the map.

To change the color scheme of the map, you can play with data-* attributes in the map element, or directly in the js file (app.js or vector-maps.js) by editing the object defaultColors

ClassyLoader

Classyloader allow you to create radial progress bar using jQuery and canvas. This plugin is very simple to use and in js included with this product you can change the options directly from data-* attributes.

There is a special option data-trigger-in-view which allows to start the loader animation when the element is visible on the screen. Just add a markup like follows

<canvas data-toggle="classyloader" data-trigger-in-view="true" data-percentage="100" data-speed="20" data-.... ></canvas>

Filter Tag

This a custom component made to filter elements on screen. You can see a demo in the page FileBox by clicking on each category

The idea behind is, you have one or more buttons to trigger the filter and the elements to be filtered.
For the trigger buttons use data-filter-tag with the value of the group to filter

 <a href="#" data-filter-tag="audio">

For the elements to be filtered use the attribute data-filter-group with the name of the filterable group.

<div data-filter-group="audio" ...> ...</div>

To reset the filter, you can use the special group name "all" in a button attribute. For example

<a href="#" data-filter-tag="all">...</a>

Panel Actions

Panels can perform different actions. Currently there are three actions triggered by clicking an icon in the panel heading. The example markup is like follows

<div class="panel-heading">
   <a href="#" data-perform="panel-dismiss" data-toggle="tooltip" title="" class="pull-right" data-original-title="Close Panel">
      <em class="fa fa-times"></em>
   </a>
   <a href="#" data-perform="panel-collapse" data-toggle="tooltip" title="" class="pull-right" data-original-title="Collapse Panel">
      <em class="fa fa-minus"></em>
   </a>
   <a href="#" data-perform="panel-refresh" data-spinner="traditional" data-toggle="tooltip" title="" class="pull-right" data-original-title="Refresh Panel">
      <em class="fa fa-refresh"></em>
   </a>
   <div class="panel-title">Title Here</div>
</div>

Note the importance of the data-attibutes, the .pull-right class and the icon element.

And those actions are

- Dismiss: With a click the panel closes and remove itself. If the panel in inside a col-* element, it will remove the column to not leave an empty space.

- Collapse: this actions allows to collapse the panel body. This action uses extra clases thar are handled via Javascript transparently.

- Refresh: This action simply triggers an event in the .panel element that can be hooked by any other module to know when the user request a refresh (content reload).

In this action there are two parts to consider

When the user clicks on the refresh button (icon), the handler automatically shows a loading spinner (plugin csspinner) and trigger the event (default name is panel-refresh).

When you bind an element to the refresh event, your function will receive the standard event object and the panel reference (jQuery object) in the second parameter. When your function ends, you need to remove the spinner, to do that, just call the function removeSpinner of the panel element, like this panel.removeSpinner();

At last, the spinner animation can be changed using the data-spinner attribute and the allowed values are the same used in the demo page for the Spinner animations. You can learn more about the spinner plugin here.

Notifications

The notification system is based on the notify component from UIKIT.
There are two way to use it.

- Using a trigger element (via click) like a button , anchor, etc.

<button type="button" data-toggle="notify" data-message="Message .." class="btn btn-default">Button text</button>

data-toggle="notifiy" is what idenitfies the element to be handled by the notify plugin
data-message: the message you want to display. It accepts text or html.
data-options: This is a string of options in json format. Learn more here

- Or when the pages first loads

<div data-toggle="notify" data-onload data-message="..." data-options="{"status":"danger", "pos":"top-right"}" class="hidden-xs"></div>

Note the following

data-onload: When present, the alert box will be displayed automatically when page loads. No value required.
hidden-xs: this class from bootstrap hides the element so its not displayed in the page.

Animations

The animations components uses a plugin called animo.js http://labs.bigroomstudios.com/libraries/animo-js
This plugin uses the animation library animate.css by Dan Eden http://daneden.github.io/animate.css/

Using this plugin allows to run animations directly from jQuery but running CSS3 based animations which makes the animation handling more flexible and performant at the same time.

This plugin is used in the following JS modules

- dropdown-animate: Allow to animate the dropdown when it opens. You see a demonstration in the page dropdown-animations.html

- panel-perform: Allows to animate a panel when it is destroyed by clicking on the cross icon.

- play-animation: This component allows to play animation in an element using another element as a trigger via the click event or by setting an offset so the element animates when it becomes visible when scrolling.

Utilities

This components is a set of CSS classes that helps to create different element or changes a default behavior just adding the class.
This classes are defined in the file utils.less or app.css and they are most used in the creation of widgets.

Example of utilities classes are for clearing margins or add different margins sizes. Same for padding, and also you can set different background colors or text color

Charts

Chart system is based on the plugin Flot Charts

According to the type of chart you want to display, you must provide a set of values so the chart can display it. This set of values are usually stores in database or a file in the server. Because of that, there are PHP files created to server the information for each chart via AJAX POST requests using the JSON format.

Every time a page with a chart is loaded, the script flot-chart.js find the chart elements and request a content for that chart via AJAX POST, this script uses an object defined which does the ajax request, and after receive the data it inits the corresponding chart.

This is an example markup of a chart

<div style="height: 250px;" data-source="server/chart-data.php?type=area" class="chart-area flot-chart"></div>

As you can see you have to define a height, classnames to target a particular type of chart and the data-source.
The data-source is the PHP script location that returns the data in JSON format

There is one main PHP file chart-data.php that routes the request to the corresponding PHP script to return the right data for the chart.
You only need to copy or edit the content a some of the files named chart-data-*.php according to your needs to populate the charts in the page.

Loading from JSON files

To load from a JSON file directly just put the URL to the json file in the data-source attribute like follows

<div style="height: 250px;" data-source="server/chart-data-donut.json" class="chart-area flot-chart"></div>

Due to the need of a PHP backend, you need to run the demo using a server to populate the charts correctly.

File Upload

The file upload component is handlded by a compoent from the framework UIKIT which can handle upload inputs and also uploas via drag-drop zones

The JS script for this component is upload-demo.js and like the name says, this files is a demostration and guid of how to implement your own file upload.

There is also a file in the server folder upload.php which gets the uploaded file information and save its content to the right location.

The save feature is commented so you need to uncomment and edit to set the directories where your uploaded files should be located.

The php script has many consideration regarding to security issues so is preferable to avoid making many changes

Slim Scroll

The slimcroll plugin is used to simulate a scroll bar inside custom components. To use it only wrap the component in the following markup

<div class="scroll-viewport">
  <div class="scroll-content">
    # component content here
  </div>
</div>

Masonry Grid

The masonry grid is a grid that allows to convert a list of items into a column layout. This component is based on CSS3 Columns layout (support).
The grid is "mobile first" and the number of columns can vary from one device to another with max of 12 columns.

To use the masonry grid add the following markup

<div class="row-masonry row-masonry-lg-4">
  <div class="col-masonry">
    # first column
  </div>
  <div class="col-masonry">
    # another column
  </div>
</div>

Note that you can use the responsive columns in a similar way like Bootstrap grid does

.row-masonry-xl-* For large desktops resolutions

.row-masonry-lg-* From normal desktop and above

.row-masonry-md-* From tablet devices and above

.row-masonry-sm-* From mobiles and above

Under mobile, all columns stacks automatically.

Datatables

DataTables is a very flexible, advanced tables plugin for jQuery. This items uses a specialized version of DataTables built for Bootstrap 3. For complete documentation on DataTables, visit their website at https://datatables.net/.

Datatables supports extension to add more usability features.
This item includes the following usage modes

- Zero configuration: This is basic usage, which adds a select to change the number of row to display, an input to filter the content displayed and a pagination. All elements based on Bootstrap classes.

- Column Filtering: allows to use a text input below each columns to filter the table content by adding different filters by columns.

- Column Visibility: allows the user to chose via a dropdown the columns to be displayed by the table dynamically.

Each different usage includes the plugins invocation plus a set of options to add one level more of customization like text translation.

Google Maps

The Google Maps script support the following data attributes which are the most used when customizing a map. If you need more customization edit directly the plugin options.

<div class="gmap" 
     data-toggle="gmap" 
     data-address="address-1; address-2" 
     data-title="title-for-address-1;title-for-address-2" 
     data-maptype="ROADMAP" 
     data-styled 
     data-zoom="14" ></div>

The class .gmap is required to set a height for the map. Google needs a height at least so you can use any other class that provides a height for the element.

Data attributes

data-toggle="gmap" indicates the element must be handled by the Google Map script

data-address indicates the address(es) you want to display. Multiple address can be separated by ;

data-title indicates the text for the popover for each address. Multiple title can be separated by ; and each one will be associated with the respective address in the same order as defined

data-zoom: change the zoom of the map 0 - 19

data-maptype: The type of map. ROADMAP or TERRAIN or SATELLITE

data-styled No value required. If present the map will be styled using the styles arrays defined in the Google Map script.

Full Calendar

This item include the full calender plugin wrapped into a classic application to manage events. This app is intended to show how to work with the most common features that full calendar provides. You can find more on its website at http://arshaw.com/fullcalendar/docs/

The full calendar app is contained in the js module calendar.js and the execution is in 3 steps.

1- createDemoEvents() This function prepares the events data to be displayed when the calendar inits. You can wrap into this function a request to a source to get via ajax the stored events

2- initExternalEvents() attaches all necessary events to the left panel to add, remove and drag/drop events into the calendar

3- initCalendar() this function finally invokes the calendar plugin and displays the events loaded from the source. This function also contains the drop handler to know when an event has been dragged/droppped into the calendar.

At last, the ExternalEvent object is used to handle external events by adding draggable functionality and the internal event data.

All functions above must run inside the document ready event to ensure a correct elements detection.

Portlets

The portlets system allows to drag and re-order panel position in the screen.

The module involved is portlet.js. It makes use of the jQueryUI sortable widget to create the portlet structure. It also use functions to save and restore the portlet position from the browser storage.

About the markup, portlet works switching position between columns. So you need to create a predefined number of columns that will contain your panels with a portlet like behavior. To do that use the following markup as base

<div class="row">
   <div id="portlet-1" data-toggle="portlet" class="col-lg-4">
      <div id="panel-1" class="panel panel-default"> ... </div>
      <div id="panel-2" class="panel panel-primary"> ... </div>
   </div>
   <div id="portlet-2" data-toggle="portlet" class="col-lg-4">
      # your panels here
   </div>
   <div id="portlet-3" data-toggle="portlet" class="col-lg-4">
      # your panels here
   </div>
</div>

Note the two required things

data-toggle="portlet" attribute must be added to every column (.col-*)
Each column and panel needs a unique id to be identified when positions are restored.

Panel State

The panel state is a feature added into the module panel-perform.js used to save the state of the panel if the user has closed or expanded it.
The module uses the internal browser storage via the plugin named store.js

This features needs that panel have a unique id to know how to restore each one when the page loads.

Clear Storage

This module is included in the file clear-storage.js What it does is to simply allow to clear any storage data from a button, link or another clickable element.

Just use any element with the data- atributes like this

<button type="button" data-toggle="reset" data-key="panelState" >Reset something</button>

After the storage has been cleared, the current page is reaload automatically. In case you don't want to auto reaload the page, just open the module clear-storage.js and comment line 20

window.location.reload();

Since version 1.2 when no key has been specified, the module tries to clear all key from browser storage for the current site. A Javascript confirm box is displayed to receive a confirmation from the user before remove.

Form Wizard

The from wizard uses the Javascript module form-wizard.js
The markup required for the wizard is

<form action="/" method="POST">
   <div data-toggle="wizard" data-validate-step="true" class="form-wizard wizard-vertical">
      <ol>
         <li> 
            <h4>Step name</h4>
         </li>
         # other steps ...
      </ol>
      <div>
         # form elements for first step
      </div>
      <div>
         # form elements for other steps
      </div>
   </div>
</form>

As you can see, there a form elements that wraps the entire wizard components.
To activate the wizard script, you must include the attribute data-toggle="wizard"
If you want steps validation just add the attribute data-validate-step="true"

To change the element position you can use the modifier classes wizard-vertical and wizard horizontal.

By removing the the <ol> element you can create a wizard without steps indicators.

CSS Loader

This module is used for the color options menu. You can use this module to append a CSS file in the head section of your page by clicking on a element..

This module could be usefule to change the appearance of behavior according to different user actions.

To use it, you need to create any clickable element with the following attributes

data-toggle="load-css" : this attribute activates the module

data-uri="PATH" : indicates the path to the css file to load. This PATH can be absolute or relative to the HTML document.

Example button

<button type="button" data-toggle="load-css" data-uri="path/to/file.css"> ... </button>

Since version 1.2 the loaded stylesheet is saved automatically in the browser storage to be restores when the page loads. You can disable this option by removing it from the module load-css.js

Toggle State

This module allows to toggle a classname from the body element. This is useful when you need to apply changes that affects the entire layout or more than one element at a time.

Use the following attribute in a clickable element to use it

<a href="#" data-toggle-state="aside-collapsed" data-persists="true">...</a>

data-toggle-state="CLASSNAME" This is the attribute that activates the module for the element. The value is the classname that you expect to apply to/remove from the body after each click.

The attribute data-persists with a true value allows to save the state into the browser storage to be automatically restored when the page is loaded.

The following projects has been used in this item

http://labs.bigroomstudios.com/libraries/animo-js

http://daneden.github.io/animate.css/

http://getbootstrap.com/

http://harvesthq.github.io/chosen/

http://codemirror.net/

http://tarruda.github.io/bootstrap-datetimepicker/

https://github.com/ftlabs/fastclick

http://markusslima.github.io/bootstrap-filestyle/

http://www.flotcharts.org/

http://fortawesome.github.io/Font-Awesome/icons/

http://github.com/marioestrada/jQuery-gMap

http://jquery.com/

https://github.com/chjj/marked

http://modernizr.com/

http://momentjs.com/

http://parsleyjs.org/

http://www.eyecon.ro/bootstrap-slider

http://omnipotent.net/jquery.sparkline/#s-about

http://timschlechter.github.io/bootstrap-tagsinput/examples/bootstrap3/

http://rocha.la/jQuery-slimScroll

https://datatables.net/.

https://github.com/marioestrada/jQuery-gMap

http://arshaw.com/fullcalendar/docs/

http://jh3y.github.io/-cs-spinner/

https://github.com/RobinHerbots/jquery.inputmask

https://github.com/marcuswestin/store.js/

https://github.com/gilluminate/Bootstrap-Wizard

http://jvectormap.com/

http://www.class.pm/projects/jquery/classyloader/

Modified element from UIKIT framework

http://www.getuikit.com/docs/addons_upload.html

http://www.getuikit.com/docs/addons_notify.html

http://www.getuikit.com/docs/addons_markdownarea.html

Demo Images from

http://uifaces.com/

http://www.raumrot.com/10/

http://unsplash.com

Mockups

http://www.techandall.com/web-collage-with-a-perspective-view/

https://dribbble.com/shots/1333240-Chrome-Browser-Mockup-PSD