GettingStarted

Getting Started with YourPlatform

This guide will explain how to create a new rails application integrating the your_platform engine. After some costumization examples, bootstrapping the database, setting up a custom organizatial structure and some comments on deploying the application are discussed.

Installing Ruby on Rails

Creating a New Rails App

Make sure to replace my_platform with the name of your project in underscore notation.

$ cd ~/rails
$ rails new my_platform --database=mysql --skip-test-unit

Initializing Git

Make sure git is installed and your global git information are set correctly.

$ git init
$ git add .
$ git commit -m "initial commit"

Adding github repository.

Adding Gems

# Gemfile
# ...
# Testing Environment
group :test, :development do
  gem 'guard'
  gem 'rspec-rails'
  gem 'guard-rspec'
  gem 'capybara'
  gem 'poltergeist'
  gem 'factory_girl_rails'
  gem 'database_cleaner'
  gem 'guard-spork'
  gem 'spork'
  gem 'simplecov', require: false
end

# JavaScript Runtime
gem 'execjs'
gem 'therubyracer', :platform => :ruby

# YourPlatform
gem 'your_platform'

Then run bundle install in order to install the gems.

This is also a good point to create a new git commit.

$ git add .
$ git commit -m "adding basic gems"

Development Shortcuts

# ~/.bashrc
alias be='bundle exec'

Setting Up the Database

Make sure you have a running MySQL database running in your development machine.

You can either create a mysql user for the application, or you can give the application root access to your development database.

Either way, fill in username and password for the development and the test section in config/database.yml.

Then create the databases needed for development and testing:

be rake db:create
be rake your_platform:install:migrations   
be rake db:migrate
be rake db:test:prepare
be rake your_platform:db:bootstrap

Setting up the ApplicationController

The your_platform engine is not namespaced. Thus, one can't inherit the app's ApplicationController from the engine's ApplicationController. Instead, one has to reopen the class in order to modify it:

# app/controllers/application_controller.rb
#
# This extends the your_platform ApplicationController
require_dependency YourPlatform::Engine.root.join( 'app/controllers/application_controller' ).to_s

class ApplicationController   # no inheritance here!
  # your additions go here, later
end

Including the ApplicationHelper

Since your_platform has got its own ApplicationHelper, which is needed for the main app, either delete the local application helper or have it include the your_platform application helper.

# (a) remove the local application helper
# bash
rm app/helpers/application_helper.rb

# or, (b) have the local application helper include the your_platform application helper
# app/helpers/application_helper.rb

# This extends the your_platform ApplicationHelper
require_dependency YourPlatform::Engine.root.join( 'app/helpers/application_helper' ).to_s
# ...

Provide a logo

Provide a file logo.png at app/assets/images/logo.png.

Remove the Rails index.html

# bash
rm public/index.html

Now, you should see a welcome page by your_platform rather than by rails when you visit http://localhost:3000.

Require Assets

// app/assets/javascripts/application.js
// ...
//= require your_platform
// ...

/* app/assets/stylesheets/application.css
 * ...
 *= require your_platform
 * ...
 */