--- layout: default ---

Getting started

Once you've downloaded Ratchet, here's what to do next.

  1. 1. Create your pages

    Use these docs as a reference for all the available components and piece together the pages of your app. Customize the style too - make the prototype all your own.

  2. 2. Connect pages with push.js

    Read about push.js then start connecting your pages. Push.js allows you to create a prototype that feels like a real app when you save it to your phone. (Need to have a server running).

  3. 3. Save the prototype to your phone

    There are a few ways to do this, but the simplest is to run a local server on your computer, point Safari on your iPhone to your computer, then click the button and "Add to Home Screen".

Heads up! Ratchet components are written only for iPhone, so many are broken in non-Webkit browsers.

Components

Design patterns that serve as basic building blocks.

Title

Title bar

Title bars are full width and docked to the top of the viewport.

Title

<header class="bar-nav">
<h1 class="title">Title</h1>
</header>

Title bar with buttons

Buttons in a title bar are left or right aligned and should be used for actions.

Left

Title

Right 
<header class="bar-nav">
<a class="button" href="#">
Left
</a>
<h1 class="title">Title</h1>
<a class="button" href="#">
Right
</a>
</header>

Title bar with directional buttons

Directional buttons in a title bar should be used for navigational purposes.

Previous

Title

Next 
<header class="bar-nav">
<a class="button-prev" href="#">
Previous
</a>
<h1 class="title">Title</h1>
<a class="button-next" href="#">
Next
</a>
</header>

Title bar with segmented controller

Title bars can also house segmented controllers (with or without accompanying buttons). It all uses flex-box to create perfectly even spacing no matter their labels.

Left Right 
<header class="bar-nav">
<a class="button" href="#">
Left
</a>
<ul class="segmented-controller">
<li class="active">
  <a href="#">One</a>
</li>
<li>
  <a href="#">Two</a>
</li>
<li>
  <a href="#">Three</a>
</li>
</ul>
<a class="button" href="#">
Right
</a>
</header>

Tab bar

Use Ratchicons in the tab bar to represent different sections of your app.

<nav class="bar-tab">
<ul class="tab-inner">
<li class="tab-item active">
  <a href="#">
    <span class="icon icon-share"></span>
    <div class="tab-label">Label</div>
  </a>
</li>
<li class="tab-item">
  <a href="#">
    <span class="icon icon-share"></span>
    <div class="tab-label">Label</div>
  </a>
</li>
<li class="tab-item">
  <a href="#">
    <span class="icon icon-share"></span>
    <div class="tab-label">Label</div>
  </a>
</li>
<li class="tab-item">
  <a href="#">
    <span class="icon icon-share"></span>
    <div class="tab-label">Label</div>
  </a>
</li>
<li class="tab-item">
  <a href="#">
    <span class="icon icon-share"></span>
    <div class="tab-label">Label</div>
  </a>
</li>
</ul>
</nav>

Note: Use push.js to actually change content.

Standard bars

Standard bars are basic fixed elements that can be positioned in 3 places. These can be used to house buttons or segmented controllers (see following examples).

Block level button 
<!-- Segmented controller in standard bar fixed to top -->
<nav class="bar-standard">
<ul class="segmented-controller">
<li class="active">
  <a href="#">Thing one</a>
</li>
<li>
  <a href="#">Thing two</a>
</li>
<li>
  <a href="#">Thing three</a>
</li>
</ul>
</nav>
<div class="bar-standard bar-header-secondary">
<a class="button-block">Block level button</a>
</div>

Table views

Table views can be used for organizing data, showing collections of links or a series of controls.

  • Item 1
  • Item 2
  • Divider
  • Item 3
<ul class="table-view">
<li>Item 1</li>
<li>Item 2</li>
<li class="table-view-divider">Divider</li>
<li>Item 3</li>
</ul>

Table view with chevrons

Chevrons are created with CSS3, so no image assets are needed. They should be used to indicate that the item is linked.

<ul class="table-view">
<li>
<a href="#">
  Item 1
  <span class="chevron"></span>
</a>
</li>
<li>
<a href="#">
  Item 2
  <span class="chevron"></span>
</a>
</li>
<li>
<a href="#">
  Item 3
  <span class="chevron"></span>
</a>
</li>
</ul>

Table view with counts

  • Item 1 4
  • Item 2 1
  • Item 3 5
<ul class="table-view">
<li>Item 1 <span class="count">4</span></li>
<li>Item 2 <span class="count">1</span></li>
<li>Item 3 <span class="count">5</span></li>
</ul>

Table view with counts and chevrons

<ul class="table-view">
<li>
<a href="#">
  Item 1
  <span class="chevron"></span>
  <span class="count">4</span>
</a>
</li>
<li>
<a href="#">
  Item 2
  <span class="chevron"></span>
  <span class="count">1</span>
</a>
</li>
<li>
<a href="#">
  Item 3
  <span class="chevron"></span>
  <span class="count">5</span>
</a>
</li>
</ul>

Table view with buttons

<ul class="table-view">
<li>Item 1 <a class="button">Button</a></li>
<li>Item 2 <a class="button-primary">Button</a></li>
<li>Item 3 <a class="button-positive">Button</a></li>
<li>Item 4 <a class="button-negative">Button</a></li>
</ul>

Table view with toggles

  • Item 1
  • Item 2
  • Item 3 
<ul class="table-view">
<li>
Item 1
<div class="toggle">
  <div class="toggle-handle"></div>
</div>
</li>
<li>
Item 2
<div class="toggle active">
  <div class="toggle-handle"></div>
</div>
</li>
<li>
Item 3
<div class="toggle">
  <div class="toggle-handle"></div>
</div>
</li>
</ul>

Inset table views

  • Item 1
  • Item 2
  • Divider
  • Item 3
  • Item 4
<ul class="table-view inset">
<li>Item 1</li>
<li>Item 2</li>
<li class="table-view-divider">Divider</li>
<li>Item 3</li>
<li>Item 4</li>
</ul>

Buttons

Buttons come in four flavors and should be used for user actions.

Button Button Button Button 
<a class="button">Button</a>
<a class="button-primary">Button</a>
<a class="button-positive">Button</a>
<a class="button-negative">Button</a>

Buttons with counts

Count button1 Count button1 Count button1 Count button1 
<a class="button">Count button<span class="count count-filled">1</span></a>
<a class="button-primary">Count button<span class="count-primary count-filled">1</span></a>
<a class="button-positive">Count button<span class="count-positive count-filled">1</span></a>
<a class="button-negative">Count button<span class="count-negative count-filled">1</span></a>

<a class="button-filled">Count button<span class="count count-filled">1</span></a>
<a class="button-filled button-primary">Count button<span class="count-primary count-filled">1</span></a>
<a class="button-filled button-positive">Count button<span class="count-positive count-filled">1</span></a>
<a class="button-filled button-negative">Count button<span class="count-negative count-filled">1</span></a>

Block buttons

Block button Block button Block button Block button Block button Block button Block button Block button 
<a class="button-block">Block button</a>
<a class="button-primary button-block">Block button</a>
<a class="button-positive button-block">Block button</a>
<a class="button-negative button-block">Block button</a>

<a class="button-block button-filled">Block button</a>
<a class="button-primary button-block button-filled">Block button</a>
<a class="button-positive button-block button-filled">Block button</a>
<a class="button-negative button-block button-filled">Block button</a>

Segmented controller

Created with flex-box so button sizes and spacing are consistent. Content sections that are to be swapped in and out by the controller should all be siblings and have the class "segmented-controller-item". Then, just give each content section an id and point the link in the segmented controller to that id.

  • Item 1
  • Item 2
  • Item 3 
<ul class="segmented-controller">
<li class="active">
<a href="#item1">Thing one</a>
</li>
<li>
<a href="#item2">Thing two</a>
</li>
<li>
<a href="#item3">Thing three</a>
</li>
</ul>
<ul class="inset table-view">
<li id="item1" class="segmented-controller-item active">
Item 1
</li>
<li id="item2" class="segmented-controller-item">
Item 2
</li>
<li id="item3" class="segmented-controller-item">
Item 3
</li>
</ul>

Counts

Counts come in four flavors and should be used to indicate "how many" of something there are.

1 2 3 4 1 2 3 4 
<span class="count">1</span>
<span class="count-primary">2</span>
<span class="count-positive">3</span>
<span class="count-negative">4</span>

<span class="count count-filled">1</span>
<span class="count-primary count-filled">2</span>
<span class="count-positive count-filled">3</span>
<span class="count-negative count-filled">4</span>

Forms

Choose existing 
<form>
<input type="text" placeholder="Full name">
<input type="search" placeholder="Search">
<textarea rows="5"></textarea>
<a class="button-positive button-block button-filled">Choose existing</a>
</form>

Form with input group

<form>
<div class="input-group">
<input type="text" placeholder="Full name">
<input type="email" placeholder="Email">
<input type="text" placeholder="Username">
</div>
</form>

Form with input group and labels

<form>
<div class="input-group">
<div class="input-row">
  <label>Full name</label>
  <input type="text" placeholder="Mister Ratchet">
</div>
<div class="input-row">
  <label>Email</label>
  <input type="email" placeholder="ratchetframework@gmail.com">
</div>
<div class="input-row">
  <label>Username</label>
  <input type="text" placeholder="goRatchet">
</div>
</div>
</form>

Toggles

Toggles can be used by sliding or tapping the control.

<div class="toggle active">
<div class="toggle-handle"></div>
</div>
<div class="toggle">
<div class="toggle-handle"></div>
</div>

Toggles.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
document
.querySelector('#myToggle')
.addEventListener('toggle', myFunction)

Popovers

Left

Popover title

Right
  • Item1
  • Item2
  • Item3
  • Item4
  • Item5
  • Item6
  • Item7
  • Item8
<div id="myPopover" class="popover">
<header class="bar-nav">
<a class="button" href="#">
  Left
</a>
<h3 class="title">Popover title</h3>
<a class="button" href="#">
  Right
</a>
</header>
<ul class="table-view">
<li>Item1</li>
<li>Item2</li>
<li>Item3</li>
<li>Item4</li>
<li>Item5</li>
<li>Item6</li>
<li>Item7</li>
<li>Item8</li>
</ul>
</div>

Popovers are designed to only fire from title bars. Set the value of the title href to the id of a popover, like so:

<header class="bar-nav">
<a href="#myPopover">
<h1 class="title">Title</h1>
</a>
</header>

Modals

Open modal 
<a href="#myModal" class="button">Open modal</a>

<div id="myModal" class="modal">
<header class="bar-nav">
<h1 class="title">Modal</h1>
<a class="button" href="#myModal">
  Close
</a>
</header>

<div class="content content-padded">
<p>The contents of my modal.</p>
</div>
</div>

Modals are designed to only fire from links. Set the value of the toggle links href to the id of a modal.

Sliders

Can be used with any number of slides with any type of content.

  • ← Slide me 
<div class="slider">
<ul>
<li>
  <img src="assets/img/slide-1.jpg">
  <span class="slide-text">← Slide me</span>
</li>
<li>
  <img src="assets/img/slide-2.jpg">
</li>
<li>
  <img src="assets/img/slide-3.jpg">
</li>
</ul>
</div>

Sliders.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
document
.querySelector('#mySlider')
.addEventListener('slide', myFunction)

Push

Push.js is the engine that connects Ratchet pages together with AJAX and the history api. Push.js is listening to all clicks on a page, so just make sure it's included and link something in your Ratchet project up.

<!-- A one.html link -->
<a href="two.html">Two<a>

This will use push to replace everything in the .content div with the .content of two.html. Also, it will either update or remove .bar-nav and .bar-tab according to their presences in two.html.

Now that pages are being loaded through push, it's easy to specify transitions for animations between pages. There are three different transitions to chose from: fade, slide-in, or slide-out.

<!-- An one.html link that animates to two.html -->
<a href="two.html" data-transition="fade">Two<a>

A working version of push:

Push

<header class="bar-nav">
<h1 class="title">Push</h1>
</header>
<div class="content">
<ul class="table-view">
  <li>
      <a href="two.html" data-transition="slide-in">
          Go to page 2
      </a>
      <span class="chevron"></span>
  </li>
</ul>
</div>

Have a link you don't want to intercepted by push? Try this:

<!-- Use data-ignore="push" to prevent the push.js interception -->
<a href="http://www.google.com" data-ignore="push">Google<a>

Push.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
window.addEventListener('push', myFunction);

Page setup

3 simple rules for structuring your Ratchet pages

  1. 1. Fixed bars come first

    All fixed bars (.bar-nav, .bar-tab, .bar-header-secondary, .bar-footer) should always be the first thing in the <body> of the page. This is really important!

  2. 2. Everything else goes in .content

    Anything that's not a .bar- should be put in a div with the class "content". Put this div after the bars in the <body> tag. The .content div is what actually scrolls in a Ratchet prototype.

  3. 3. Don't forget your meta tags

    They're included in the template.html page included in the download, but make sure they stay in the page. They are important to Ratchet working just right.