Complete overhaul of the docs

HZ-labs · Sep 21, 2013 · 880e4b3 · 880e4b3
1 parent 61d713e
commit 880e4b3
Show file tree

Hide file tree

Showing 4 changed files with 144 additions and 61 deletions.
diff --git a/docs/api/2-Vex Dialog.md → docs/api/1-Basic.md b/docs/api/2-Vex Dialog.md → docs/api/1-Basic.md
@@ -1,18 +1,6 @@
-## Vex Dialog
+## Basic
 
-When including `vex.dialog`, you get dropin replacements for `alert`, `confirm`, and `prompt`.
-
-### Including
-
-To use Vex Dialog, minimally, you must include:
-
-```html
-<script src="vex.dialog.js"></script>
-```
-
-To get the basic styles, you'll addionally want to include a theme. See the Vex API documentation for how to include themes.
-
-### API
+### Dialog API
 
 Vex Dialog exposes 4 main apis:
 

diff --git a/docs/api/2-Themes.md b/docs/api/2-Themes.md
@@ -0,0 +1,63 @@
+## Themes
+
+To use a builtin theme, you must include the theme style sheet, and set vex `className` to match match:
+
+```html
+<link rel="stylesheet" href="vex-theme-default.css" />
+<script>vex.defaultOptions.className = 'vex-theme-default';</script>
+```
+
+At the moment, there are 5 themes:
+
+<table class="hs-table">
+<tr>
+<th>Name</th>
+<th>`className`</th>
+<th></th>
+</tr>
+<tbody>
+<tr><td>Default</td><td>`vex-theme-default`</td><td><a href data-theme="vex-theme-default">Example</td></tr>
+<tr><td>Operating System</td><td>`vex-theme-os`</td><td><a href data-theme="vex-theme-os">Example</td></tr>
+<tr><td>Plain</td><td>`vex-theme-plain`</td><td><a href data-theme="vex-theme-plain">Example</td></tr>
+<tr><td>Wireframe</td><td>`vex-theme-wireframe`</td><td><a href data-theme="vex-theme-wireframe">Example</td></tr>
+<tr><td>Flat Attack!</td><td>`vex-theme-flat-attack`</td><td><a href data-theme="vex-theme-flat-attack">Example</td></tr>
+</tbody>
+</table>
+
+Instead of setting `vex.defaultOptions.className`, you could instead set the `className` option when opening a vex. Here's an example of that.
+
+### Inline Theme Example
+
+```coffeescript
+vex.defaultOptions.className = 'vex-theme-os';
+vex.dialog.alert
+    message: 'Testing the wireframe theme.'
+    className: 'vex-theme-wireframe' # Overwrites defaultOptions
+```
+
+<!-- Resources for the demos -->
+<p style="-webkit-transform: translateZ(0)"></p>
+<script src="/vex/js/vex.js"></script>
+<script src="/vex/js/vex.dialog.js"></script>
+<link rel="stylesheet" href="/vex/css/vex.css" />
+<link rel="stylesheet" href="/vex/css/vex-theme-default.css">
+<link rel="stylesheet" href="/vex/css/vex-theme-os.css">
+<link rel="stylesheet" href="/vex/css/vex-theme-plain.css">
+<link rel="stylesheet" href="/vex/css/vex-theme-wireframe.css">
+<link rel="stylesheet" href="/vex/css/vex-theme-flat-attack.css">
+<script>
+    (function(){
+        vex.defaultOptions.className = 'vex-theme-os';
+
+        $('[data-theme]').each(function(){
+            $(this).click(function(e){
+                e.preventDefault();
+                vex.dialog.alert({
+                    message: 'Testing the <code>' + $(this).data('theme') + '</code> theme.',
+                    className: $(this).data('theme')
+                });
+                return false;
+            });
+        });
+    })();
+</script>
diff --git a/docs/api/1-Vex.md → docs/api/3-Advanced.md b/docs/api/1-Vex.md → docs/api/3-Advanced.md
@@ -1,45 +1,34 @@
-## Vex
+## Advanced
 
-### Including
+### DOM Structure
 
-To use Vex, minimally, you must include:
-
-```html
-<script src="vex.js"></script>
-```
-
-To get the basic styles, you'll addionally want to include:
+When opening a dialog, vex appends the following HTML to `appendLocation` (which defaults to `body`).
 
 ```html
-<link rel="stylesheet" href="vex.css" />
+<div class="vex">
+    <div class="vex-overlay"></div>
+    <div class="vex-content">
+        <div class="vex-close"></div>
+    </div>
+</div>
 ```
 
-#### Themes
+If `showCloseButton` is set to false, `<div class="vex-close"></div>` will be ommitted.
 
-To use a builtin theme, you must additionally include the theme style sheet, and set the theme className:
+Optional class names or inline CSS can be added to any of these elements by setting any the following options (with defaults shown):
 
-```html
-<link rel="stylesheet" href="vex-theme-default.css" />
-<script>
-    vex.defaultOptions.className = 'vex-theme-default';
-</script>
+```
+className: ''
+css: {}
+overlayClassName: ''
+overlayCSS: {}
+contentClassName: ''
+contentCSS: {}
+closeClassName: ''
+closeCSS: {}
 ```
 
-At the moment, there are 5 themes:
-
-<table class="hs-table">
-<tr>
-<th>Name</th>
-<th>`className`</th>
-</tr>
-<tbody>
-<tr><td>Default</td> <td>`vex-theme-default`</td></tr>
-<tr><td>Operating System</td> <td>`vex-theme-os`</td></tr>
-<tr><td>Plain</td> <td>`vex-theme-plain`</td></tr>
-<tr><td>Wireframe</td> <td>`vex-theme-wireframe`</td></tr>
-<tr><td>Flat Attack!</td> <td>`vex-theme-flat-attack`</td></tr>
-</tbody>
-</table>
+The CSS options take an object to be passed to jQuery's `.css` function.
 
 ### API
 
@@ -103,23 +92,29 @@ Here are the defaults:
 defaultOptions:
     content: ''
     showCloseButton: true
+    escapeButtonCloses: true
     overlayClosesOnClick: true
     appendLocation: 'body'
     className: ''
     css: {}
     overlayClassName: ''
     overlayCSS: {}
+    contentClassName: ''
+    contentCSS: {}
     closeClassName: ''
     closeCSS: {}
 ```
 
-There are some class names in `vex.sass` you can use for the `className` property:
+### Note about Includes
 
-- Use `vex-content-auto` when making a simple dialog.
-- Use `vex-content-tall` when you want to support something with a scrollable middle.
-- Use `vex-content-tall-and-wide` or `fullscreen` when you want to take up most or all of the screen, respectively.
+To use Vex, minimally, you must include:
 
+```html
+<script src="vex.js"></script>
+<link rel="stylesheet" href="vex.css" />
+```
 
+We also recommend including `vex.dialog.js` and a theme file. However, these are not actually required. To include both `vex.js` and `vex.dialog.js`, use `vex.combined.js` (or `vex.combined.min.js`). All of these files can be found in the ZIP which you can [download here](/vex).
 
 <!-- Resources for the demos -->
 <p style="-webkit-transform: translateZ(0)"></p>

diff --git a/docs/intro.md b/docs/intro.md
@@ -13,18 +13,42 @@ Vex is a modern dialog library which is highly configurable, easily stylable, an
 - Open multiple dialogs at once and close them individually or all at once
 - Built in CSS spinner for asynchronous dialogs
 
-Let's jump right into a hot demo.
+#### Requirements
 
-#### Demo
+- jQuery
+
+#### Browser Support
+
+- IE8+
+- Firefox 4+
+- Current WebKit (Chrome, Safari)
+- Opera
+
+#### Including
+
+For the most common usage of Vex, you'll want to include following:
+
+```html
+<script src="vex.combined.min.js"></script>
+<script>vex.defaultOptions.className = 'vex-theme-os';</script>
+<link rel="stylesheet" href="vex.css" />
+<link rel="stylesheet" href="vex-theme-os.css" />
+```
+
+That will give you all of the APIs for both Vex and Vex Dialog, and set you up with the "Operating System" theme. If you'd prefer another theme, check out [Themes](/vex/api/themes).
+
+#### Confirm Demo
+
+One of the simplest ways to use Vex is to call `vex.dialog.alert`, `vex.dialog.confirm`, or `vex.dialog.prompt`. In this demo, we're using `vex.dialog.confirm` to ask the user to confirm the answer to a simple question.
 
 <a class="demo-confirm hs-brand-button">Destroy the planet</a>
-<div class="demo-result-simple hs-doc-callout hs-doc-callout-info" style="display: none"></div>
+<div class="demo-result-confirm hs-doc-callout hs-doc-callout-info" style="display: none"></div>
 <script>
 $('.demo-confirm').click(function(){
     vex.dialog.confirm({
         message: 'Are you absolutely sure you want to destroy the alien planet?',
         callback: function(value) {
-            $('.demo-result-simple').show().html('<h4>Result</h4><p>' + (value ? 'Successfully destroyed the planet.' : 'Chicken.') + '</p>');
+            $('.demo-result-confirm').show().html('<h4>Result</h4><p>' + (value ? 'Successfully destroyed the planet.' : 'Chicken.') + '</p>');
         }
     });
 });
@@ -39,24 +63,26 @@ vex.dialog.confirm
         console.log if value then 'Successfully destroyed the planet.' else 'Chicken.'
 ```
 
-### Demo
+#### Login Demo
+
+Here's a more complex demo in which we use `vex.dialog.open` (a more generic method which `alert`, `confirm`, and `prompt` all call internally) to build a login dialog.
 
-<a class="demo hs-brand-button">Log in</a>
-<div class="demo-result hs-doc-callout hs-doc-callout-info" style="display: none"></div>
+<a class="demo-login hs-brand-button">Log in</a>
+<div class="demo-result-login hs-doc-callout hs-doc-callout-info" style="display: none"></div>
 <script>
-    $('.demo').click(function(){
+    $('.demo-login').click(function(){
         vex.dialog.open({
             message: 'Enter your username and password:',
             input: '' +
-                '<input name="username" type="text" placeholder="Username" />' +
-                '<input name="password" type="password" placeholder="Password" />' +
+                '<input name="username" type="text" placeholder="Username" required />' +
+                '<input name="password" type="password" placeholder="Password" required />' +
             '',
             buttons: [
                 $.extend({}, vex.dialog.buttons.YES, { text: 'Login' }),
                 $.extend({}, vex.dialog.buttons.NO, { text: 'Back' })
             ],
             callback: function (data) {
-                $('.demo-result').show().html('' +
+                $('.demo-result-login').show().html('' +
                     '<h4>Result</h4>' +
                     '<p>' +
                         'Username: <b>' + data.username + '</b><br/>' +
@@ -86,6 +112,17 @@ vex.dialog.open
         console.log 'Username', data.username, 'Password', data.password
 ```
 
+#### Learn More
+
+To learn more about how to use Vex, visit our API pages.
+
+- [The Basics](https://github.hubspot.com/vex/api/the-basics)
+
+#### Credits
+
+Vex was built by [Adam Schwartz](https://twitter.com/adamfschwartz)
+
+
 <!-- Resources for the demos -->
 <p style="-webkit-transform: translateZ(0)"></p>
 <script src="/vex/js/vex.js"></script>