twbs/ratchet

Build mobile apps with simple HTML, CSS, and JavaScript components.

Ratchet

Build mobile apps with simple HTML, CSS, and JS components.

Table of contents

• Getting started
• Documentation
• Support
• Contributing
• Troubleshooting
• Versioning
• Maintainers
• License

Getting started

• Clone the repo with git clone https://github.com/twbs/ratchet.git or just download the bundled CSS and JS
• Read the docs to learn about the components and how to get a prototype on your phone
• Check out examples

Take note that our master branch is our active, unstable development branch and that if you're looking to download a stable copy of the repo, check the tagged downloads.

What's included

Within the download you'll find the following directories and files, logically grouping common assets and providing both compiled and minified variations. You'll see something like this:

ratchet/
├── css/
│   ├── ratchet.css
│   ├── ratchet.min.css
│   ├── ratchet-theme-android.css
│   ├── ratchet-theme-android.min.css
│   ├── ratchet-theme-ios.css
│   └── ratchet-theme-ios.min.css
├── js/
│   ├── ratchet.js
│   └── ratchet.min.js
└── fonts/
    ├── ratchicons.eot
    ├── ratchicons.svg
    ├── ratchicons.ttf
    └── ratchicons.woff

We provide compiled CSS and JS (ratchet.*), as well as compiled and minified CSS and JS (ratchet.min.*). The Ratchicon fonts are included, as are the optional Android and iOS platform themes.

Documentation

Ratchet's documentation is built with Jekyll and publicly hosted on GitHub Pages at http://goratchet.com. The docs may also be run locally.

Running documentation locally

1. If necessary, install Jekyll (requires v3.0.x).

• Windows users: Read this unofficial guide to get Jekyll up and running without problems.

2. Install the Ruby-based syntax highlighter, Rouge, with gem install rouge.
3. From the root /ratchet directory, run jekyll serve in the command line.
4. Open http://localhost:4000 in your browser, and boom!

Learn more about using Jekyll by reading its documentation.

Documentation for previous releases

Documentation for v1.0.2 has been made available for the time being at http://goratchet.com/1.0.2/ while folks transition to Ratchet 2.

Previous releases and their documentation are also available for download.

Support

Questions or discussions about Ratchet should happen in the Google group or hit us up on Twitter @GoRatchet.

Contributing

Please file a GitHub issue to report a bug. When reporting a bug, be sure to follow the contributor guidelines.

Troubleshooting

A small list of "gotchas" is provided below for designers and developers starting to work with Ratchet.

• Ratchet is designed to respond to touch events from a mobile device. In order to use mouse click events (for desktop browsing and testing), you have a few options:
  • Enable touch event emulation in Chrome (found in the overrides tab in the web inspector preferences)
  • Use a JavaScript library like fingerblast.js to emulate touch events (ideally only loaded from desktop devices)
• Script tags containing JavaScript will not be executed on pages that are loaded with push.js. If you would like to attach event handlers to elements on other pages, document-level event delegation is a common solution.
• Ratchet uses XHR requests to fetch additional pages inside the application. Due to security concerns, modern browsers prevent XHR requests when opening files locally (aka using the file:// protocol); consequently, Ratchet does not work when opened directly as a file.
  • A common solution to this is to simply serve the files from a local server. One convenient way to achieve this is to run python -m SimpleHTTPServer <port> to serve up the files in the current directory to http://localhost:<port>

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, Ratchet is maintained under the Semantic Versioning guidelines. Sometimes we screw up, but we'll adhere to these rules whenever possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major while resetting minor and patch
• New additions without breaking backward compatibility bumps the minor while resetting the patch
• Bug fixes and misc changes bumps only the patch

For more information on SemVer, please visit http://semver.org/.

Maintainers

Connor Sears

• https://twitter.com/connors
• https://github.com/connors

Created by Connor Sears, Dave Gamache, and Jacob Thornton.

License

Ratchet is licensed under the MIT License.

ratchet's Issues

Docs: Finish header (Aesthetics, add social btns, animation etc)

Using .content as a wrapper and .bar-tab hides bottom of content

When using a .bar-tab, the bottom of the content body lives behind the navigation. The value for bottom doesn't fix it since it's not adding an actual space below.

Docs: Fix the assets that inject into the phone

Push.js not working for me

@connors and I fiddled with this and couldn't get it to work with the minified JS. Could just be in scrub mode, but we're going to move on to other bugs and chat with @fat about this later.

Docs: Add media queries.

Block level <buttons>: 100% width is needed. Causes margin issues.

Docs: Write content for each component

We need to write content for each component. When / how to use each.

Rename CSS files to be consistently pluralized

We need list item content base styles

Right now we haven't considered common content structure in a list item.

Slider is off by few pixels for every slide

Ratchet Performance

we're using [foo*='bar'] quite a bit, and these selectors are really expensive. (they're actually the most expensive selector you can run)

Also, CSS evals from right to left (you probably know that) – so doing things like this doesn't actually scope the selector (perf wise makes them even more expensive):

.list [class*="button"]

The above is still running a universal selector * on the entire dom, then checking all attributes for class, then running an expensive regex on each class attr. Then, after it's done that, it checks the dom for list elements, and see's if any of the initial matched elements have a list parent.

I only bring this up because in the sample app i'm building rendering (on the phone) seems a little jank. Also (even without js) the scroll is horrible (though that may be unrelated).

At anyrate, i think we should talk a look at css perf and see if there is anything we can do to improve it.

Also, I remember connor pointing out the other night that the slide.js perf on his phone was a little jank – which is something we should look at in the js.

Block level elements in bars are positioned incorrectly

Letterboxing on iPhone 5 when saved to phone

Forms don't work very well in popovers. Margins are all off.

<[buttons]…

Im missing arrow buttons guys.

First child list dividers have wrong top border (too light)

font-size: 0 on slider

font-size: 0 on slider causes all children to have font-size 0 – and thus all slider content fontsize 0.

should probably fix that.

Create JS for segmented controllers to act like tabs

For popovers we need to style <a>'s within bars.

Right now they turn blue. Blue on blue in the bar hurts the eyes. We should just make it look the same as a default h1 in the title-bar.

<[buttons]…

Im missing arrow buttons guys.

Rewrite titles in .bar-title to actually always be centered

The form labels and input text baselines are not aligned.

Get consistent in CSS with vendor prefixes

We need to decide if we're going to support browsers. Do we need to provide the whole vendor prefix stack or just webkit?

Docs: Make phone sit centered vertically in viewport

Accidental push when scrolling through lists

Allow push.js to work on any element

Not just <a> tags, but on anything by defining the href instead with a data attribute. This should actually be the default since there are tons of locations that aren't <a>'s that I would want to fire pushes (I think).

.content wrapper actually breaks scrolling on longer pages

Currently the toggles flicker a bit when tapped.

Turn one toggle on and then flip another one on the page. You'll notice the flickering.

Counts on block level button are offset to the right.

The positioning is off

Form input backgrounds are bleeding through the rounded corners

Segmented controllers in bars don't support stacked text

Either force the text not to wrap or support the change in height.

Write a real README

Include links to all resources, docs, etc and how to get started. Also how to launch project on phone <3

JS Callback for toggle changing

Can't get build scripts to work

This could be 100% user error, but in the top level of the directory running `build make' is failing?

.list-divider creates broken edges if it's the first or last child in a list

Push.js needs a callback

Decide on single quote vs double quote in our JS.

Callback on slider that can return index of slide

Fill out the CONTRIBUTORS.md page

Sublime text snippet collection

Make all the HTML snippets for sublime text

Toggles in lists are jumpy

Toggles in lists have a huge delay in changing the :before/after content. This means the .toggle-handle animates, but then the active class isn't applied at the right time, but entirely after the animation?

Oddly enough, last children of a list don't have this issue though...

Change lists to use <a> and be full tap target

Also have a way to fallback to a normal

The bottom bar divider has a weird bottom inner shadow.

Focus on element in popovers causes top bar to move down

Inset lists are by % not a given number. Change to explicit number.

Form input margins (top and bottom) don't position well.

:active state for list items

Docs: Fix how base.css screws the whole docs page up

Base.css set body to position fixed among other things. We just need to get in there and override when necessary.

Title in .bar-title is vertically off-centered

Comment the source CSS heavily