App Specification

sindresorhus edited this page Jul 15, 2012 · 32 revisions
Clone this wiki locally

App Specification

We have created this short spec to help you create awesome and consistent todo apps. Make sure to not only read it, but also understand.

Our template should be used as the base when implementing a todo app. Before implementing, we recommend you interact with some of the other apps to see how they're built and how they behave. Check out the Spine app if you need a reference implementation. If something is unclear or could be improved, let us know.

Enjoy :D

General

When there are no todos, #main and #footer should be hidden.

UX

To make it easy to compare frameworks, the app should look and behave exactly like the template and the other examples.

Compatibility

We require apps to work in every browser we support. There's a ie.js file in the assets folder which contains html5shim, es5-shim, classList.js, outerHTML to let you develop without having to think about legacy browsers.

Structure

Recommended file structure:

index.html
css
└── app.css
js
├── app.js
└── lib

Try to follow this structure as close a possible while still keeping to the frameworks best practices.

Components should be split up into separate files and placed into folders where it makes the most sense.

Example:

js
├── app.js
├── controllers
│   └── todos.js
└── models
    └── todo.js

Code

Please try to keep the HTML as close to the template as possible. Remove the comments from the HTML when done. The base.css file should be referenced from the assets folder and not be touched. If you need to change some styles, use the app.css file, but try to keep it to a minimum. Remember to update the relative paths when using the template.

Make sure to follow these:

  • Tab indention
  • Follow the Idiomatic guide to writing JavaScript*, especially the part about beautiful syntax. Please ensure your code follows this closely. If something is unclear, follow the existing style.
  • Use double-quotes in HTML and single-quotes in JS and CSS.
  • JS code should pass JSHint.
  • Use minified version of third-party code and put it in the lib folder.
  • Use a constant instead of the keyCode directly: var ENTER_KEY = 13;

*If you're using CoffeScript this applies to the source files and not the generated output.

Persistence

Your app should dynamically persist the todos to localStorage. If the framework has capabilities for persisting data (i.e. Backbone.sync), use that, otherwise vanilla localStorage. If possible, use the keys id, title, completed for each item. Make sure to use this format for the localStorage name: todos-[framework]. Editing state should not be persisted.

Routing

Routing is required for all frameworks. Use the built-in capabilities if supported, otherwise use the Crossroads.js routing library, which depends on js-signals, both in the assets folder. The following routes should be implemented: #/ (all - default), #/active and #/completed. When the route changes the todo list should be filtered on a model level and the selected class on the filter links should be toggled. When an item is updated while in a filtered state, it should be updated accordingly. E.g. if the filter is Active and the item is checked, it should be hidden. Make sure the active filter is persisted on reload.

New todo

New todos are entered in the input at the top of the app. Pressing Enter creates the todo, appends it to the todo list and clears the input. Make sure to .trim() the input and then check that it's not empty before creating a new todo.

Mark all as complete

This checkbox toggles all the todos to the same state as itself. Make sure to clear the checked state after the the "Clear completed" button is clicked. The "Mark all as complete" checkbox should also be updated when single todo items are checked/unchecked. Eg. When all the todos are checked it should also get checked.

Item

A todo item has three possible interactions:

  1. Clicking the checkbox marks the todo as complete by updating it's completed value and toggling the class completed on it's parent <li>

  2. Double-clicking the container (.view) activates editing mode, by toggling the .editing on it's parent <li>

  3. Hovering over the todo shows the remove button (.destroy)

Editing

When editing mode is activated it will hide the other controls and bring forward an input that contains the todo title, which should be selected by using .select() and not .focus(). The edit should be saved on both blur and enter, and the editing class should be removed. Make sure to .trim() the input and then check that it's not empty. If it's empty the todo should instead be destroyed.

Counter

Displays the number of active todos in a pluralized form. Make sure the number is wrapped by a <strong> tag. Also make sure to pluralize the item word correctly: 0 items, 1 item, 2 items. Example: 2 items left

Clear completed button

Displays the number of completed todos, and when clicked, removes them. Should be hidden when there are no completed todos.