WebCakes/splash.js

Description

Splash.JS is an Object Oriented style plugin.
This plugin takes 1 DOM element and resizes its height based on the height (and width) of the browser window.
The plugin can also take 1-2 other elements (above and/or below) and again resize the middle element based on those 1-2 element(s)' height(s).
It is especially useful for very large window sizes.

Please see the examples directory for very simplified use-cases.

Requirements:

jQuery v1.9+.x -- Download Here

How to Use:

1. Prepare resources

Download jQuery.
Donwload Splash.JS.
Include/Link/Source Files in your project in the above order.

2. Create a new instance of Splash.

var myapp = new Splash();

3. Initialize the plugin.

var myapp = new Splash();
myapp.init( 
  elements = {
    'dynamicObject' : $('#myIntroHeader'),
    'stickyObject' : $('#myWelcomeMessage'),
    'staticObject' : $('#myStaticNavigation')
  },
  options = {
    'pageObjectCheck' : "body.frontpage",
    'onResizeBoolean' : true,
    'debugBoolean' : false
  }
);

The init() method can take 2 objects as parameters. These are the objects and their parameters and the data they expect.

Elements:

The Dynamic Element ( 'dynamicObject' ) => jQuery object -- Required

This is the element that changes its height depending on the height of the browser.

The Sticky Element ( 'stickyObject' ) => jQuery object -- Optional

This is the element that will stick to the bottom of the page.

The Static Element ( 'staticObject' ) => jQuery object -- Optional

This is the element that doesn't move and acts as a regular DOM element. This is best used for Navigation elements.

Options:

A Page Element ( 'pageObjectCheck' ) => jQuery Selector String -- Optional

This is an element on the page that the plugin checks to see if it exists before running. "body.frontpage" looks for <body class="frontpage"> before executing.

Responsive / onResize ( 'onResizeBoolean' ) => true or false Boolean -- Optional ( default: false )

This executes the dynamic element height resizing method as the user resizes the window. This allows for immediate refreshing of the height without a page load.

Debug ( 'debugBoolean' ) => true or false Boolean -- Optional ( default: false )

This turns on debug messages within the browser's console.

If you do not need to use an optional parameter please set it to its default

myapp.init( { 'dynamicObject' : $('#myIntroHeader') } );

Other Methods

myapp.setSplashElements( $('#myIntroHeader'), $('#myWelcomeMessage'), $('#myStaticNavigation') ); // Set Splash elements manually
myapp.setDynamicElementsHeight( 500 ); // Set the height of the dynamic element manually
myapp.setHeightBreakpoint( 1000 ); // When to execute height changes based on height
myapp.setWidthBreakpoint( 767 ); // When to execute height changes based on width
myapp.setPageElementCheck( "body.frontpage" ); // Add a page element to check for before executing

Please see the examples directory for further code examples.

How to Contribute:

Install Grunt

Unfamiliar with npm? Don't have node installed? Download and install node.js before proceeding.

From the command line:

Install grunt-cli globally with npm install -g grunt-cli.
Navigate to the theme directory, then run npm install. npm will look at package.json and automatically install the necessary dependencies.

When completed, you'll be able to run the various Grunt commands provided from the command line.

Available Grunt commands

grunt watch — Will watch for changes inside jquery.splash.js and run jshint to make sure code is clean.
grunt build — Will run jshint for a clean code check and minify jquery.splash.js into jquery.splash.min.js.

Contributing

Everyone is welcome to help contribute and improve this project. There are several ways you can contribute:

Reporting issues.
Suggesting new features.
Writing or refactoring code.
Fixing issues.
Replying to questions within GitHub issues.

Task List

Accomodate potential Padding Height when calculating Dynamic Elements's Height
Organize Global Variables properly.
- Globals should only be used if they're absolutely needed.
Refactor similar methods into one.

WebCakes / splash.js