Get started with RailsBricks


1. Prerequisites

In order to use RailsBricks, you need the following prerequisites:

  • A computer running Linux or Mac OS X. RailsBricks runs on Windows but it was not extensively tested. Still, reports says it runs smoothly on Windows 7 and Windows 8.
  • Ruby (1.9.3, 2.0.0, 2.1.1 or 2.1.2)
  • Some knowledge about Ruby on Rails development! RailsBricks automates trivial tasks but is not a full-featured app creator. You will implement your own features with Ruby using the Rails framework.

back to top


2. Installation

If you have RailsBricks 1.x installed on your system, you must first uninstall it. RailsBricks 2.x is not compatible with v1.x and will generate conflicts.

2.1 Uninstalling RailsBricks 1.x

Follow these steps:

  1. go to your <user> folder: cd ~
  2. delete the railsbricks directory: rm -rf railsbricks
  3. edit your .bash_profile and remove this line: PATH=$PATH:~/railsbricks

back to top


2.2 Installing RailsBricks

After checking the prerequisites and removing version 1 if necessary, open a terminal window and issue the following command:

gem install railsbricks

You can check that RailsBricks is installed correctly by typing:

rbricks -v

You should have version 2.0.0 or above.

back to top


2.3 Updating RailsBricks

To stay up to date with the latest version of RailsBricks, just enter the following command in your terminal:

rbricks --update

back to top


3. Creating a new Rails app with RailsBricks

From your terminal, go to the directory where you want your new app created and type:

rbricks -n

This will start a wizard prompting you for default values such as your app name, your SMTP server settings, optional Git parameters, etc. Follow the steps. Except the app name, all the values can be changed later.

Upon completing the wizard, RailsBricks will create a new RVM gemset and install Rails into it. Then, it will generate your app.

If you chose to generate a User model for authentication (Simple or Devise), you will be prompted to have test users automatically generated. Answer by y or n and then give the number of test users you want created. When the RailsBricks wizard completes, it will give you your default admin credentials (username: admin, password: 1234).

Move inside app directory and start the web server by typing:

rails server

Open a browser and navigate to the following URL:

localhost:3000

You are now seeing your basic RailsBricks generated Rails app and are ready to implement your awesome functionalities!

3.1 Gems location

Since version 1.1.0, RailsBricks doesn't install required gems inside a separate RVM gemset. Instead, rails '4.1.5' will get installed globally and all RailsBricks generated apps will use this same version.

If you have different versions of Rails installed, add the version number you'd like to use to the rails command like this:

rails _4.1.5_ server
rails _3.2.0_ console
rails _4.0.0_ generate model Thing name:string

All other required gems will be isolated from one another and installed within your app vendor/bundle directory. The rails command will use the correct ones automatically.

back to top


4. Layout

4.1 Common elements

Whether you chose Reset CSS or Bootstrap 3, some common UI elements were included during the app creation.

4.1.1 Page Title

A helper method named "title" is located within app/helpers/application_helpers.rb. In order to use it, just add the following line anywhere in your views:

<% title("some page title") %>
4.1.2 Font Awesome

The font-awesome-sass gem is included and ready to use. It allows you to insert various icons in your views. Have a look at all the included icons on the Font Awesome official site.

If, for example, you want to display the user icon within your page, just add this in your HTML code:

<i class="fa fa-user"></i>

it will render this:

4.2 Reset CSS

If you chose the Reset CSS layout during the RailsBricks wizard, your application UI is not really attractive. It resetted all CSS values based on Eric Meyer's reset CSS styles. Now would be a good time to give a call to your favourite graphic designer!

4.2.1 Flash Messages

A _messages.html.erb partial has been generated in your app/views/layouts and is included in your main application.html.erb view layout. It displays Rails flash messages.

4.2.2 Error Messages

Error messages are wrapped inside a div with an id of error_explanation. Error texts are generated with a class named error-text. Fields with errors have the class field_with_errors applied to them.

4.3 Bootstrap 3

If you selected Bootstrap 3 for the layout during the RailsBricks new app wizard, the bootstrap-sass and RailsLayout gems are included and configured already. Common web UI elements are already generated:

  • _application.html.erb: your main application layout
  • _messages.html.erb: a partial to display Rails flash messages
  • _navigation.html.erb: a partial containing your top level navbar
  • _navigation_links.html.erb: a partial containing your navigation links used by _navigation.html.erb
  • _footer.html.erb: a footer partial included in your main application layout
4.3.1 Overriding Bootstrap 3 default values

By default, RailsBricks generated apps will use Bootstrap 3 default values for the inverse scheme (dark navbar at the top). Most of the styling, colors and typography values are listed within app/assets/stylesheets/framework_and_overrides.css.scss as SCSS variables.

Have a look at the Bootstrap 3 Customize page. For example, the @brand-primary LESS variable is inside framework_and_overrides.css.scss as $brand-primary. As a general rule, if there's a LESS @variable-name in Bootstrap, you find it in RailsBricks generated SCSS as $variable-name.

Experiment with it! Change the navbar color, the padding sizes, the rounded corners radius, the links font... Get crazy and original! It's easily done.

4.3.2 RailsBricks CSS classes

RailsBricks defines few custom CSS classes listed at the bottom of app/assets/stylesheets/framework_and_overrides.css.scss. You'll find classes useful for testing your layout, displaying eye-catching error messages, one that aligns the Rails flash messages with the top navbar, etc.

Again, experiment with them, it's easy and all at the same place.

4.3.3 Forms

All generated forms use a markup compatible with Bootstrap 3 rules. Devise generated forms as well.

back to top


5. Authentication & User model

Defining a User model and an authentication scheme is optional (you can select none in the RailsBricks new app wizard). There are two flavours currently provided by RailsBricks when it comes to authentication: Simple or Devise.

5.1 Simple User model

This option generates a User model made from scratch, close to what you would do manually if you were to follow Ryan Bates' RailsCast #250: Authentication from Scratch. The User model uses the bcrypt-ruby gem to encrypt passwords with the has_secure_password method from ActiveModel. The User model has the following fields:

  • id: integer
  • username: string (minimum 4 chars, maximum 10 chars, only letters and digits)
  • email: string (must adhere to email regex validation)
  • password: string (minimum 4 chars)
  • password_confirmation: string (same as :password)
  • slug: string (unique, used by FriendlyId)
  • admin: boolean (defaults to false)
  • created_at: datetime
  • updated_at: datetime
5.1.1 Usage

When chosing Simple as a User model for authentication, RailsBricks creates a basic admin zone where you can change your account details. By default, it doesn't allow users to register on your app.

This option is convenient when you build an app that only requires a handful of users such as a blog where you'd be the only contributor. Typically, you'd create the initial users inside the seeds.rb file (open it to see an example). For more complex user management features, prefer the Devise option.

5.2 Authentication with Devise

RailsBricks can install and configure the excellent Devise gem for you. When this option is selected, RailsBricks will create a full-blown user management interface within the admin zone. There, you can see users activity, search for users, lock them, promote them to the admin status, etc. Have a look, explore what gets built for you!

By default, the :confirmable option in Devise is turned on. That means your users will need to validate their account email upon registration.

All the necessary views for signing in, signing up, retrieving a lost password, resending the confirmation link, updating an account, etc. are built and styled by RailsBricks.

Make sure that your mailing parameters are correct as the Devise gem will use them to send emails. You entered your email parameters when following the RailsBricks new app wizard. If you need to edit them, they are stored in config/application.yml (not tracked by Git).

back to top


6. Environment variables & secret token

Keep your private stuff private.

6.1 Environment variables

RailsBricks promotes the use of environment variables rather than hardcoded values in your app. This is done using the Figaro gem. In your development environment, all calls to ENV["some_value"] will be redirected to config/application.yml (this file is not tracked by Git by default and you shouldn't change that behavior).

In your production environment, don't forget to add the environment variables to your system.

For example, RailsBricks uses this mechanism to store your email parameters and not publish them if you were to add your app source code to Github.

6.2 Application secret token

By default, new Rails apps receive a secret token, hardcoded inside config/initializers/secret_token.rb. This is not really a good practice. RailsBricks will automatically update your secret_token.rb file to have it generate a secret_token on the fly and store it inside a .secret file (not tracked by Git). This way of doing is similar to what Michael Hartl explains in his Rails Tutorial.

back to top


7. Database

If you opted to have a User model created, RailsBricks will also generate a seeds.rb file for initial data insertion (your default admin account) and test users data.

At any time, you can drop, migrate and seed your development database with the following command:

rbricks -r

back to top


8. Test Framework

When you create a new app with RailsBricks, you can choose to have the default test framework included, a combination of RSpec and Capybara or no test framework at all. If you chose "no test framework", RailsBricks will prevent all rails generate commands to create tests.

back to top


9. Git

RailsBricks offers you to create a local Git repository for your app. If you chose to do so, an initial commit will be done right after your app gets created. A specific .gitignore file is also created to ignore certain files (tmp, .secret, application.yml, databases, etc).

If you chose to have a local repository created, you will also be prompted to set a remote repository. If you do so, your local master branch will be pushed to origin right after your app is created.

back to top


10. Other Gems

RailsBricks generated apps also include Kaminari for easily implementing pagination features. For example, if you chose the Devise User model, the admin zone uses this to paginate your list of users.

FriendlyId is also included with each new RailsBricks generated apps. This gives your app the power to display friendly url's such as /posts/some-article-about-some-things rather than /posts/7874. RailsBricks User models use this feature as well.

back to top


11. Deploying a RailsBricks app

You deploy a RailsBricks generated app just as you would deploy any Rails 4.x app. Still, if you plan to deploy on Heroku, the PostgreSQL and the Rails 12factor gems are already included in your Gemfile within a :production group.

back to top


12. Show what you do

If you have created an app using RailsBricks, send the link and it will be featured on railsbricks.net!

back to top