Skip to content

Commit

Permalink
Complete overhaul of the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
adamschwartz committed Sep 21, 2013
1 parent 61d713e commit 880e4b3
Show file tree
Hide file tree
Showing 4 changed files with 144 additions and 61 deletions.
16 changes: 2 additions & 14 deletions docs/api/2-Vex Dialog.md → docs/api/1-Basic.md
Original file line number Diff line number Diff line change
@@ -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:

Expand Down
63 changes: 63 additions & 0 deletions docs/api/2-Themes.md
Original file line number Diff line number Diff line change
@@ -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>
67 changes: 31 additions & 36 deletions docs/api/1-Vex.md → docs/api/3-Advanced.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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>
Expand Down
59 changes: 48 additions & 11 deletions docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>');
}
});
});
Expand All @@ -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/>' +
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 880e4b3

Please sign in to comment.