##Introduction Master Builder is a simple out of the box front-end templating base used for building new websites created and maintained by Nino Ross Rodriguez. To get started, jump to setup.
##Browser Compatibility
- Chrome (Windows / Mac OS)
- FireFox (Windows / Mac OS)
- Safari (Mac OS)
- Internet Explorer 9+ (Windows)
##Features
- Full responsive framework (number of columns easily manageable)
- Responsive tables
- Ability to swipe left/right on mobile device for long tables
- Ability to "print" the entire table into a PDF for users to view the table in their mobile device and very easy to use
- Awesome mobile menu animation
- IE9 Placeholder fallback
- Dynamically add background images meant to have
background: cover
property, without hard coding in CSS - Uses Grunt to automate compiling into a folder for easy deployment
- "Watches" your development folder and auto-reloads your browser so you don't have to refresh your window every time
- Concatenates and uglifies all CSS and JS files
- Compresses images
- Standard Content to quickly visualize any kind of content
- Lazy loading images (uses jQuery_lazyload )
##Release History
v1.3.1
- Minor bug fixes.
v1.3.0
- Converted mobile menu into jQuery Plugin.
v1.2.1
- Updated PDF Table usage
v1.2.0
- Converted jsPDF table printing into jQuery Plugin.
v1.1.0
- Added lazy loading feature for images. Minor CSS fixes for mobile.
v1.0.0
- Your simple straight-forward base boilerplate for your next project
##Dependencies
###Grunt Javascript Task Runner
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a gruntfile.js
as well as install and use Grunt plugins. Once you're familiar with that process, you may use Grunt commands to compile your project.
###SASS If you haven't used SASS before, be sure to have a read on how to get SASS on your local machine in their installation guide as it will explain how to write your CSS in SASS. The boilerplate is written in SASS and will be compiled by Grunt
###Local PHP Server
Note: You must set the document root in your Local PHP Server to the dist
folder of the project for you to view it in a browser. You can do this by editing the httpd.conf
file. See the example below:
DocumentRoot "C:\xampp\htdocs\Master_Builder\dist"
<Directory "C:\xampp\htdocs\Master_Builder\dist">
###GreenSock TweenMax and TimeLineMax (optional) For the cool menu animation. The files already included in the framework. If you want to read more about TweenMax, you can check it out their website.
###LiveReload (optional)
It will make your life a whole lot easier once you enable this in your browser. No more CTRL + F5
every time you make a change in your codes. Download the extension and install it in your preferred browser.
##Setup Provided that you have Grunt and Ruby installed in your system, follow the steps to get started with your project.
-
Open
package.json
file and changeMaster_Builder
the desired project name. Do not use white spaces. Hyphens and underscores are accepted. -
Open
header.php
andfooter.php
. ChangeMaster_Builder
to the project name that you chose in step 1. -
Open your Command Prompt (Windows) or your Terminal (Mac OSX) and go to the directory of your project.
-
Run the following command:
npm install
. -
Once that is completed, you're ready to rock and roll. You can use the following commands during your development.
##Available Grunt Tasks
grunt
Development Task: Generates the project dist folder for easy deployment to any server. This command will not minify nor uglify your CSS and JS. Recommended on initial start up of a project.
grunt watch
Watch Task: Grunt will listen to any changes in your files will reload your page.
grunt dist
Production Task: Generates the project dist folder for easy deployment in any server. This command will clean the dist
folder, minify, uglify your CSS and JS, and compress your images. In addition to this, Grunt will sift through the header.php
and footer.php
and will change the paths to the minified versions. This will save you time changing them before going to deployment. Recommended when your project is ready to go live.
**A word of caution: ** if you ran a grunt dist
then a grunt watch
, you must do a grunt
first before you watch again. The header.php
and footer.php
will be pointing at the minified versions of the CSS and JS.
grunt validate
Validation Task:_ Will sift through your JS and SASS files to check for any errors.
##What's in the Package?
Master_Builder/
├── _fonts/
├── _icomoon/
├── _images/
│ ├── ie/
│ │ └── transparent.png
├── _scripts/
│ ├── modules/
│ │ ├── rr.mobileMenu.js
│ │ └── rr.tableScrollbar.js
│ ├── plugins/
│ │ ├── minified/
│ │ │ ├── ScrollToPlugin.min.js
│ │ │ ├── TimelineMax.min.js
│ │ │ └── TweenMax.min.js
│ │ ├── jRespond.js
│ │ └── jspdf.cus.js
│ ├── vendor/
│ │ ├── jquery-1.11.3.min.js
│ │ ├── modernizr.js
│ │ └── selectivizr.js
│ └── main.js
├── _scss/
│ ├── common/
│ │ ├── _defaults.scss
│ │ ├── _fonts.scss
│ │ ├── _mixins.scss
│ │ └── _vars.scss
│ ├── components/
│ │ └── mobileMenu/
│ │ ├── _default.scss
│ │ ├── _desktop.scss
│ │ ├── _mobile.scss
│ │ └── _tablet.scss
│ ├── _desktop.scss
│ ├── _mobile.scss
│ ├── _tablet.scss
│ ├── ie.scss
│ ├── main.scss
│ └── responsive.scss
├── styles/
└── tempates/
├── grid/
| └── index.php
├── images/
├── includes/
| ├── footer.php
| ├── header.php
| └── primary-nav.php
├── list/
| └── index.php
├── standard/
| └── index.php
└── index.php
###What Goes Where
_fonts/
- Downloaded webfonts are placed here.
_icomoon/
- Downloaded custom font icons are placed here.
_images/
- Images used across the website are placed here.
_scripts/plugins/
- Place all plugin files in this folder.
_scripts/plugins/minified/
- Place all minified files in this folder.
_scripts/vendor/
-
_scss/
- All SCSS stylesheets.
_scss/common/
- Stylesheets that are commonly used through the entire project.
_scss/components/
- Stylesheets broken down to components for easy modification.
styles/
- Stylesheets from plugins are placed here. Note: You must update header.php
and link the CSS file. CSS in this folder will not be concatincated with the ones you have created.
templates/
- All created pages for the website goes here.
**Note: ** I placed _delete
files in empty folders so Git will push the folders to the repo. You can delete these files onces you have set up the boilerplate.
###What Is Reponsible For What
_scripts/modules/rr.mobileMenu.js
- Where the mobile menu is initialized.
_scripts/modules/rr.tableScrollbar.js
- Where the table printing is initialized.
_scripts/plugins/minified/ScrollToPlugin.min.js
- Responsible for scrolling the page while using TweenMax. Dependent on TweenMax.
_scripts/plugins/minified/TimelineMax.min.js
- Responsible for animating the menu icon on mobile. Dependent on TweenMax.
_scripts/plugins/minified/TweenMax.min.js
- Responsible for all cool JS animation.
_scripts/plugins/jRespond.js
- Creating breakpoints via JavaScript to enable/disable any plugin needed.
_scripts/plugins/jspdf.cus.js
- Responsible for exporting the HTML Table to a PDF. It is based from MrRio's jsPDF with a few lines of tweaks to cater all mobile devices.
_scss/common/_defaults.scss
- Normalizing your HTML build from normalize.css
and HTML5 Boilerplate
_scss/common/_fonts.scss
- Place all CSS webfonts in this file.
_scss/common/_mixins.scss
- Majority of long coding techniques for cross-browser compatibilty is in this file. Have a look and it will make your coding life much better.
_scss/common/_vars.scss
- Common variables that will be used across your SCSS files. Breakpoints, colors and column numbers can be edited here.
_scss/_desktop.scss
- Styles for desktop only.
_scss/_mobile.scss
- Styles for mobile only.
_scss/_tablet.scss
- Styles for tablet only.
_scss/main.scss
- Styles from mobile that can cascade to .desktop.
_scss/ie.scss
- IE8 Specific CSS fixes
##Mobile Responsive Tables
###Problem
Tables with large number of columns and responsive websites don't mix well. The majority's solution is to wrap the table
with a div and assign an overflow-x: scroll
property to allow the users swipe left and right. But users still can't get a glimpse or an overview of the entire table.
###A Possible Solution
The framework will wrap all tables with the class name .printableTable
and create a button as a call to action to "print" and the option to save the table in PDF format by utilizing MrRio's jsPDF plugin. Users have now the ability to view the table in their mobile phones regardless of the manufacturer and or operating system. They can pinch to zoom in or out and swipe in any direction. iOS users has the option of opening the printed table in iBooks or their preferred PDF reader while Android users will save the PDF file in their device automatically and open it in their preferred PDF reader.
##Usage of Features ####HtmlTable to PDF Usage (jquery.pdfTable)
$(element).pdfTable( 'init', {
position: 'float', // top, bottom, float
orientation: 'l', // landscape (l), portrait (p)
unit: 'pt', // pt, mm, cm, in.
format: 'a4', // a3, a4, a5, letter, legal
marginTop: 20,
marginRight: 20,
marginBottom: 20,
marginLeft: 20,
});
Use .pdfTable('init')
to initialize the plugin. The sample code above are the default options if you do not declare any options.
Position is the location of the print button. The default option for this is bottom
.
Orientation is the orientation of the PDF. Options are either 'portrait'
or 'landscape'
(shortcuts 'p'
, 'l'
).
Unit is the measurement unit to be used when coordinates are specified. Options available are 'pt'
(points), 'mm'
, 'cm'
, 'in'
.
Format is the paper size. Available options are 'a3'
, 'a4'
, 'a5'
, 'letter'
, 'legal'
.
The last 4 options are the margins that will be set when the table is printed on the PDF.
###Mobile Menu (jquery.mobileMenu)
<div id="primary-nav">
<nav class="nav" role="navigation">
<div class="wrap">
<h1>
<a href="/">Master Builder</a>
</h1>
</div>
<ul class="lvl1">
<li>
<a href="#" class="no-link"><span>Level 1</span></a>
<ul class="lvl2">
<li><a href="/standard/"><span>Standard Content</span></a></li>
<li><a href="/grid/"><span>Grid System</span></a></li>
<li>
<a href="#"><span>Level 2</span></a>
<ul class="lvl3">
<li><a href="#"><span>Level 3</span></a></li>
<li><a href="#"><span>Level 3</span></a></li>
<li><a href="#"><span>Level 3</span></a></li>
<li><a href="#"><span>Level 3</span></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</div>
You must follow the markup in order for the plugin to work that it is designed to be. If one element or class is missing from the markup, the plugin might not work properly. This plugin currently supports up to 3 levels only.
Add .no-link
to a
tags if it will not lead to anywhere. This way when a user clicks on the link, the dropdown (if available) will open.
$('#primary-nav').mobileMenu('init', {
dropdownPos: 'static', // static, absolute
menuPos: 'top', // top, bottom
displayOn: 'all' // mobile, tablet, desktop/all
});
Use $('#primary-nav').mobileMenu('init');
to initialize the plugin. If you don't assign any options, it will be set to the defaults static
, top
and all
;
displayOn
is which devices you want the mobile menu to display on. The default option for this is all
.
menuPos
is where you want the mobile menu to be positioned. The default option for this is top
.
dropdownPos
is if you want the page to scroll up to the top of the page when the user taps on the mobile menu icon. This option is only applicable for menuPos: 'top'
.
###IE9 Placeholder Fallback
For all input
tags that you want to use the placeholder
property, add an .input-placeholder
class and add a data attribute named data-placeholder
with the desired placeholder text. JS will do the rest.
###Image Background Cover
Add .backstretch
on the div
that you wish to have the image to have a background: cover
property. Then add data attribute named data-background
with the path of the the image. JS will do the rest.
###Printable Table
Add .printableTable
on the table
element that you want the plugin to wrap on mobile device. If the table fits in the mobile device, it will not wrap it in a div
and generate the button
for the user to click. Add a data attribute named data-title
if you want to use the table title as the filename for the PDF.
###Lazy Load Images
<img>
tags must have the class lazy
attached to it and a data attribute named data-original
containing the path of the image. JS will do the rest.
##Issues, Bugs or Feature Requests If you found any bugs, would like to contribute, have comments or suggestions, head down to the issues section and log it in. I will be more than happy to discuss it.
##Features to Come
- Google Material Design components
- Support IE8 for
jquery.mobileMenu
##Credits Ang Ziwei for creating the gruntfile.
MrRio for his awesome jsPDF plugin
GreenSock for making animating so much easier.
##License Copyright 2015 Infinite Imaginations
Licensed under the MIT License