_______________________

HeroFlow README, v 1.1

Plugin & Guide by Aaron Cooper, 2015
_______________________



What is this funky jazz?
------------------------

HeroFlow is a plugin to be used in fullscreen or large-image websites to create a large, responsive "Hero" image, to be used with jQuery (1.11).

It's been designed to be as flexible as possible and supports <img> resizing (if you're not using background-image) and carousels.



Who's this for?
---------------

This plugin was created by Aaron Cooper for unlimited use EXCLUSIVELY for Cybacat Ltd and for any sites they produce for other businesses/clients.



How do I use it?
----------------

-- Setting up the HTML --

The HTML is entirely up to you because HeroFlow only relies on one core element that you call the plugin on in jQuery. There's also no CSS file, leaving the styling entirely up to you, or the carousel plugin you're using. Here's a very basic example:

<div class="heroflow">
  <ul>
    <li style="background: url(image/url/here1.jpg) center center no-repeat; background-size: cover;"></li>
    <li style="background: url(image/url/here2.jpg) center center no-repeat; background-size: cover;"></li>
  <ul>
</div>

Really though the HTML will depend on if you're using a carousel plugin and how that prefers to have its HTML laid out.


-- Setting up the JS --

You set up the HeroFlow plugin on your element using jQuery like this:

$('.heroflow').heroFlow(options);


And here's the default options that you can choose to specify yourself if desired:

var options = {
        headerEl: false,		// Optional: Supply the selector for the page's header element to offset the hero image by the height of the header.
        offsetBottom: 0,		// Offset the hero section this many pixels from the bottom of the browser window
        heroPadder: false,		// Optional: supply a selector for an element to match the dimensions of the hero element (useful for a padding element that's behind or in front of the hero element)
    	img: false,				// Optional: supply a selector to locate the correct images to resize inside the hero element
    	slides: false,			// Optional: supply a selector to resize slide elements inside the hero element with the hero's dimensions (useful for preventing elements with background images not filling the hero's space)
    	stripDimensions: false, // Optional: strip the dimension css rules that break a responsive, dynamically resizing hero section (height) from the provided selectors
        forceStrip: false,      // Optional: only works when stripDimensions is not false, this forces the dimensions to be stripped even while resizing the browser window (ONLY use if ABSOLUTELY required, this can slow things down a lot!!)
        scrollArrow: false,     // Set to true to display a clickable/tappable arrow over the top of the hero image
        scrollArrowHTML: false  // Optional: supply HTML in a string to use in place of the hero default arrow (NOTE: THIS OPTION IS NOT YET IMPLEMENTED!!)
};