# Stationed

## Introduction

Stationed is an extensive Rails application generator, providing you with a
starter app full standard goodies such as testing, authentication,
authorization, decorators, tasks and styles. But as an engine it also provides
you with customized scaffold generators including proper tests. Finally, it
provides some basic view helpers that every project tends to need. All in all,
stationed is pretty sweet.

## Installation

In order to use Stationed to generate applications, install the gem:

    % gem install stationed

To use it as an engine in your Rails application, include it in your Gemfile:

    gem 'stationed'

Run `bundle install` and you're all set.

## Application generator

The application generator is invoked using the `stationed` command:

    % stationed my_app

This will generate a default Rails application with the following additions:

* **Rubocop** for automated style guide testing.
* **Pry** for debugging.
* **Guard** for auto-running tests.
* **Rspec** with Simplecov for testing.
* **FactoryGirl** for object factories.
* **DatabaseCleaner** as transaction replacement.
* **Capybara** for feature testing.
* **CapybaraWebkit** for headless browser testing.
* **Pundit** for authorization.
* **Yard** for API documentation.
* **Foreman** for process management.
* **Bourbon, Neat and Bitters and normalize.css** for styling.
* **Draper** for decorators.
* **Gollum** for a built-in development wiki.
* **Devise** for authentication.
* **Turbolinks** removed.
* **Kaminari** for pagination.
* **SimpleForm** for awesome form markup.
* **Haml** for pretty view templates.
* **Webmock** to disallow external HTTP requests in tests.
* **I18nSpec** for automated validation of locale files.
* **Responders** for DRY controllers.

...and some other minor configurations and goodies.

All these additions are stand-alone "plugins" for the base application
generator, so it is easy to adapt them or add others. Have a look at
`lib/stationed/generators/plugins` to see all plugins.

## Helpers

### Page title

The page title helper allows you to set a page title based on a string,
translation key or by a resource. You can easily output it on your page and in
your layout.

* When given no argument, this will return the currently set page title or
  the site-wide default.
* When given a string argument, that will be used in the formatted page
  title (for example with a site-wide suffix).
* When given an ActiveModel-compliant object, its singular and plural human
  names will be interpolated into the model-based title template, along
  with the record's ID.

You can provide templates for page titles using `I18n` in three broad
categories: the `model`, `formatted` and `standard` keys. These will be used
when you set a page title via a model, string or nothing at all, respectively.

You can specify these translation keys on a global default level, per controller
or per controller action. The more specific key will take precedence.

### CRUD link helpers

A collection of helper methods to generate links to CRUD operations with labels
and URLs generated by resources.

For example:

    link_to_new(Post) # => <a href="/posts/new">New Post</a>
    link_to_edit(@product) # => <a href="/products/1/edit">Edit Product 1</a>

You can use I18n to fully customize the labels on these links. There are helper
methods for `new`, `edit`, `show`, `destroy` and `index`, in the variants
`link_to`, `button_to` and `button_link_to` (for links with a `button` class
name).

### Templates

Stationed includes customized scaffold templates for Haml, Rspec and
controllers. These work out of the box, but you can use a generator to install
the templates into your application for easy customization:

    rails generate stationed:templates

## Other

### Note on Patches/Pull Requests

1. Fork the project.
2. Make your feature addition or bug fix.
3. Add tests for it. This is important so I don't break it in a future version
   unintentionally.
4. Commit, do not mess with rakefile, version, or history. (if you want to have
   your own version, that is fine but bump version in a commit by itself I can
   ignore when I pull)
5. Send me a pull request. Bonus points for topic branches.

### Issues

Please report any issues, defects or suggestions in the [Github issue
tracker](https://github.com/avdgaag/stationed/issues).

### What has changed?

See the [HISTORY](https://github.com/avdgaag/stationed/blob/master/HISTORY.md) file for a detailed changelog.

### Credits

Created by: Arjan van der Gaag  
URL: [http://arjanvandergaag.nl](http://arjanvandergaag.nl)  
Project homepage:
[http://avdgaag.github.com/rpub](http://avdgaag.github.com/stationed)  
Date: april 2014  
License: [MIT-license](https://github.com/avdgaag/stationed/LICENSE) (same as Ruby)