--- 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

{% highlight html %}

Title

{% endhighlight %}

Title bar with buttons

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

Left

Title

Right
{% highlight html %}
Left

Title

Right
{% endhighlight %}

Title bar with directional buttons

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

Previous

Title

Next
{% highlight html %}
Previous

Title

Next
{% endhighlight %}

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
{% highlight html %}
Left Right
{% endhighlight %}

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
{% highlight html %}
  • Item 1
  • Item 2
  • Divider
  • Item 3
{% endhighlight %}

Table view with counts

  • Item 1 4
  • Item 2 1
  • Item 3 5
{% highlight html %}
  • Item 1 4
  • Item 2 1
  • Item 3 5
{% endhighlight %}

Table view with toggles

  • Item 1
  • Item 2
  • Item 3
{% highlight html %}
  • Item 1
  • Item 2
  • Item 3
{% endhighlight %}

Inset table views

  • Item 1
  • Item 2
  • Divider
  • Item 3
  • Item 4
{% highlight html %}
  • Item 1
  • Item 2
  • Divider
  • Item 3
  • Item 4
{% endhighlight %}

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
{% highlight html %}
  • Item 1
  • Item 2
  • Item 3
{% endhighlight %}

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
{% highlight html %} 1 2 3 4 1 2 3 4 {% endhighlight %}

Form with input group

{% highlight html %}
{% endhighlight %}

Form with input group and labels

{% highlight html %}
{% endhighlight %}

Toggles

Toggles can be used by sliding or tapping the control.

{% highlight html %}
{% endhighlight %}

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

{% highlight js %} // Only needed if you want to fire a callback document .querySelector('#myToggle') .addEventListener('toggle', myFunction) {% endhighlight %}

Popovers

Left

Popover title

Right
  • Item1
  • Item2
  • Item3
  • Item4
  • Item5
  • Item6
  • Item7
  • Item8
{% highlight html %}
Left

Popover title

Right
  • Item1
  • Item2
  • Item3
  • Item4
  • Item5
  • Item6
  • Item7
  • Item8
{% endhighlight %}

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

{% highlight html %}

Popover title
{% endhighlight %}

Modals

Open modal
{% highlight html %} Open modal {% endhighlight %}

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
{% highlight html %}
  • ← Slide me
{% endhighlight %}

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

{% highlight js %} // Only needed if you want to fire a callback document .querySelector('#mySlider') .addEventListener('slide', myFunction) {% endhighlight %}

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.

{% highlight html %} Two {% endhighlight %}

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.

{% highlight html %} Two {% endhighlight %}

A working version of push:

Push

{% highlight html %}

Push

{% endhighlight %}

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

{% highlight html %} Google {% endhighlight %}

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

{% highlight js %} // Only needed if you want to fire a callback window.addEventListener('push', myFunction); {% endhighlight %}

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.