<NME> README.md
<BEF> pageguide.js
============

An interactive guide for web page elements using jQuery and CSS3.

## How-to:
1. Add references in your code to pageguide.js, jQuery & pageguide.css
2. Add a document ready callback to setup the page guide
3. Add a simple `<ul>` to the bottom of the pages you want the pageguide to appear on.
4. Customize the page guide tour title.

## An example:

### Step 1 - Add pageguide.js 


Pageguide comes with an example implementation (the files are in `/example`) which you can run locally with [Grunt](http://gruntjs.com/). Assuming you have a working copy of [npm](https://www.npmjs.com/) installed on your machine, open up a terminal, navigate to the root `pageguide` directory, and run:

    $ npm install
    $ grunt server
Then navigate to [http://localhost:3000/example/](http://localhost:3000/example/) in your browser.

Read the [Getting Started](http://tracelytics.github.io/pageguide/) page for information on the framework contents and more.

## How-To:
1. Add references in your code to jQuery, pageguide.min.js & pageguide.min.css
2. Add a single pageguide `init()` call within a `document.ready` callback.
3. Add a simple `<ul>` to the bottom of the pages you want the pageguide to appear on.
4. Customize the page guide tour title.
5. (Optional) Add a welcome message to display to your users on page load.

## An Example:

### Step 1 - Add pageguide js

Add `<script src="{YOUR_PATH}/pageguide.min.js"></script>` to the bottom of your html document, right before your closing `</body>` tag.

Minified js is located in /dist/js/ (the source file is in /js/).

### Step 2 - Add pageguide.css

Add `<link rel="stylesheet" href="{YOUR_PATH}/pageguide.css">` to the header of your html document.

Minified css can be found in /dist/css/. Source LESS file is in /less/.

### Step 3 - Add setup code

Add the following block of JavaScript to your html document:


```javascript
$(document).ready(function() {
    tl.pg.init({ /* optional preferences go here */ });
});
```

### Step 4 - Choose the elements that you want included in the page guide.
pageguide.js matches the first occurrence of the selector you specify in the `<ul>` you put on your pages in the next step.

### Step 5 - Add the pageguide.js `<ul>` near the bottom of your pages.
The `data-tourtarget` attribute for each `<li>` should contain the selector for the element you wish to target with this step. Optional: use the classes `tlypageguide_left`, `tlypageguide_right`, `tlypageguide_top`, or `tlypageguide_bottom` to position the step indices.

```html
    <ul id="tlyPageGuide" data-tourtitle="REPLACE THIS WITH A TITLE">
      <li class="tlypageguide_left" data-tourtarget=".first_element_to_target">
        <div>
          Here is the first item description. The number will appear to the left of the element.
        </div>
      </li>
      <li class="tlypageguide_right" data-tourtarget="#second_element_to_target">
        <div>
          Here is the second item description. The number will appear to the right of the element.
        </div>
      </li>
      <li class="tlypageguide_top" data-tourtarget=".third_element_to_target > div.is_here">
        <div>
          Here is the third item description. The number will appear above the element.
        </div>
      </li>
      <li class="tlypageguide_bottom" data-tourtarget="#fourth_element_to_target">
        <div>
          Here is the fourth item description. The number will appear below the element.
        </div>

By default, the modal will continue to launch on page load until a user either a) launches pageguide, or b) dismisses the message by clicking `.tlypageguide_dismiss`. User preference for a particular URL is stored in localStorage with a cookie fallback.


## See it IRL:
* http://tracelytics.github.com/pageguide

## Contribute
Bugfix?  Cool new feature?  Alternate style?  Send us a pull request!

1. We use [Grunt](http://gruntjs.com/) to develop, test, and compile pageguide.js
   into `/dist`:

    ```bash
    $ cd pageguide
    $ npm install -g grunt-cli
    $ npm install
    $ grunt
    ```

1. Create a feature branch and make some code changes

1. Add unit tests (in `/js/test/unit`) and ensure your tests pass by running
   `grunt`.

1. Send us a detailed pull request explaining your changes.

## License
Copyright (c) 2013 Tracelytics, AppNeta

Pageguide is freely redistributable under the MIT License. See LICENSE for details.

<MSG> Merge branch 'april-features' of github.com:tracelytics/pageguide into april-features

<DFF> @@ -1,15 +1,24 @@
 pageguide.js
 ============
 
-An interactive guide for web page elements using jQuery and CSS3.
+An interactive guide for web page elements using jQuery and CSS3. Check it out IRL at http://tracelytics.github.com/pageguide!
 
-## How-to:
+## Table of Contents
+* [How-To](#how-to)
+* [An Example](#an-example)
+* [Options](#options)
+* [Requirements](#requirements)
+* [Tested In](#tested-in)
+* [Contribute](#contribute)
+
+## How-To:
 1. Add references in your code to pageguide.js, jQuery & pageguide.css
 2. Add a document ready callback to setup the page guide
 3. Add a simple `<ul>` to the bottom of the pages you want the pageguide to appear on.
 4. Customize the page guide tour title.
+5. (Optional) Add a welcome message to display to your users on page load.
 
-## An example:
+## An Example:
 
 ### Step 1 - Add pageguide.js 
 
@@ -84,9 +93,77 @@ This element will display as an introductory welcome modal to your users when th
 
 By default, the modal will continue to launch on page load until a user either a) launches pageguide, or b) dismisses the message by clicking `.tlypageguide_dismiss`. User preference for a particular URL is stored in localStorage with a cookie fallback.
 
-
-## See it IRL:
-* http://tracelytics.github.com/pageguide
+## Options
+
+Pageguide can take a hash of options in `init()`. All are optional.
+
+<table>
+    <tr>
+		<th>Option</th>
+		<th>Type</th>
+		<th>Default</th>
+		<th>What it do</th>
+	</tr>
+	<tr>
+		<td><code>auto_show_first</code></td>
+		<td>boolean</td>
+		<td><code>true</code></td>
+		<td>Whether or not to focus on the first visible item immediately on PG open</td>
+	</tr>
+	<tr>
+		<td><code>loading_selector</code></td>
+		<td>selector</td>
+		<td><code>'#loading'</code></td>
+		<td>The CSS selector for the loading element. pageguide will wait until this element is no longer visible starting up.</td>
+	</tr>
+	<tr>
+		<td><code>track_events_cb</code></td>
+		<td>function</td>
+		<td>noop</td>
+		<td>Optional callback for tracking user interactions with pageguide.  Should be a method taking a single parameter indicating the name of the interaction. (default none)</td>
+	</tr>
+    <tr>
+    	<td><code>handle_doc_switch</code></td>
+		<td>function</td>
+		<td><code>null</code></td>
+		<td>Optional callback to enlight or adapt interface depending on current documented element. Should be a function taking 2 parameters, current and previous data-tourtarget selectors. (default null)</td>
+	</tr>
+    <tr>
+    	<td><code>custom_open_button</code></td>
+		<td>selector</td>
+		<td><code>null</code></td>
+		<td>Optional id for toggling pageguide. Default null. If not specified then the default button is used.</td>
+	</tr>
+    <tr>
+    	<td><code>pg_caption</code></td>
+		<td>string</td>
+		<td><code>page guide</code></td>
+		<td>Optional - Sets the visible caption</td>
+	</tr>
+    <tr>
+    	<td><code>dismiss_welcome</code></td>
+		<td>function</td>
+		<td>(see source)</td>
+		<td>Optional function to permanently dismiss the welcome message, corresponding to <code>check_welcome_dismissed</code>. Default: sets a localStorage or cookie value for the (hashed) current URL to indicate the welcome message has been dismissed, corresponds to default <code>check_welcome_dismissed</code> function.</td>
+	</tr>
+    <tr>
+        <td><code>check_welcome_dismissed</code></td>
+		<td>function</td>
+		<td>(see source)</td>
+		<td>Optional function to check whether or not the welcome message has been dismissed. Must return true or false. This function should check against whatever state change is made in dismiss_welcome. Default: checks whether a localStorage or cookie value has been set for the (hashed) current URL, corresponds to default dismiss_welcome function.</td>
+	</tr>
+</table>
+
+## Requirements
+
+* jQuery 1.7 - 2.0
+
+## Tested In:
+
+* OSX
+  * Chrome 26
+  * Firefox 20
+  * Safari 6.0.4
 
 ## Contribute
 Bugfix?  Cool new feature?  Alternate style?  Send us a pull request!

Merge branch 'april-features' of github.com:tracelytics/pageguide into april-features