The preferred use of iQvoc is plugging it into a Rails app. There are lots of configuration options available that allow the extension of core functionality.

To use iQvoc as a Rails Engine simply include the following into your Gemfile

gem 'iqvoc'

All models, controllers, views and routes iQvoc brings are automatically available in your app.

To make it easier to bootstrap a new Rails app that embeds iQvoc we provide a Rails application template.

You can generate a new Rails app and let the template execute the necessary modifications:

Note: The application name has to start with iqvoc_, otherwise you have to manually fix generated namespace constants.

$ wget https://raw.github.com/innoq/iqvoc/master/lib/generators/app/template.rb
$ rails new iqvoc_foobar -m template.rb

See https://github.com/FND/iqvoc_custom_sample for a simplistic example of a customized iQvoc application.

iQvoc defines ApplicationController and ApplicationHelper in the top-level namespace. At the moment you can't redefine these in your app without running into problems. One option would be to use other names.

Also remember to remove app/views/layouts/application.html.erb as iQvoc brings its own application layout file. Or, you can roll your own.

Probably your app comes with its own assets like CSS or JavaScript files. To properly use them in combination with iQvoc's core assets you have to structure your assets in a special manner to respect iQvoc's defaults; your asset directories have to look like this

app/assets/
|-- images
|-- javascripts
|   |-- iqvoc_your_app_name
|   |   |-- your_app_name.js
|   |   |-- foo.js
|   |   `-- manifest.js
|   `-- manifest.js
`-- stylesheets
    |-- iqvoc_your_app_name
    |   |-- your_app_name.css
    |   |-- bar.css
    |   `-- manifest.css
    `-- manifest.css

Your top-level manifest.[js|css] files should contain some defaults in order to load iQvoc's core assets. As an example, we show the expected contents for JavaScript assets. The same pattern must be applied to your SCSS asset manifest.

app/assets/javascripts/manifest.js

//= require framework
//= require iqvoc/manifest

//= require your_app_name/manifest

app/assets/javascripts/your_app_name/manifest.js

//= require your_app_name/your_app_name
//= require your_app_name/foo
//= require your_app_name/bar

By suiting to this structure we are able to provide a sane and concise integration of both iQvoc's core assets as well as your custom assets within Rails standards.