= Qwester

A rails engine used to add questionnaires to rails applications

== Installation

Add this to your Gemfile

    gem 'qwester'

=== Migrations
Qwester includes a set of migrations to build the database tables to match
qwester's models. To use these migrations within the host application, run
this rake task:

    rake qwester:install:migrations

This will copy the migrations to the host application's db/migrate folder.
They will then be run next time the db:migrate task is run:

    rake db:migrate

If you only wish to run the qwester migrations use a scope option:

    rake db:migrate SCOPE=qwester

== Questionnaire

To create a new questionnaire, first create a set of questions that you
wish to appear within the questionnaire. Then create a questionnaire and
associate the questions with that questionnaire. Questions can be used in
multiple questionnaires, and can be ordered within each questionnaire. That
is, the first question in one questionnaire, can be displayed as the second
question in another questionnaire.

=== Questions and Answers

Each question has a number of answers associated with it. The default set of
answers is given by:

    Qwester::Answer.standard_values

However, these can be modified and added to as you require. That is, each
question has a unique set of answers that can be modified as required.

=== Answer selection list helper

The helper method qwester_answers_selection_list will output a set of form
elements matching the answers for the given question, as an unordered list.
The form elements will be radio buttons unless the question is marked as 
'multi-answer', in which case check boxes will be used.

    <%= qwester_answers_selection_list(question) %>

The controller method update_qwester_answer_store can be used to manage the
data submitted from these form elements. It will add the answers to the 
current answer store.

=== Answer store

Submitted answers are stored in an AnswerStore object. On creation, each 
answer_store is assigned a session_id that can then be used within session,
to identify the current user's answer_store. In this way, questionnaire 
submissions can be tracked across multiple submissions.

By default the current answer_store.session_id is stored in 
session[:qwester_answer_store]. If you wish to use a different session key,
set Qwester.session_key in the qwester initializer:

    Qwester.session_key = :your_preferred_key

=== Rule set

Groups of answers can be matched to rule sets using:

    RuleSet.matching(answers)

which will return an array of rule sets that match those answers.

Each rule set has an url associated with it, and this url should lead a user
to a resource either within or outside the app.

RuleSet uses array_logic[http://github.com/reggieb/array_logic] to manage 
the logic used to compare each rule set with the array of answers.

== Dummy

A test app is present within this engine, and provides an example of how
Qwester can be used within a Rails app. See test/dummy.

== Integration with ActiveAdmin

Qwester contains a set of ActiveAdmin register files, that allow Qwester
models to be managed from within the parent app's active_admin space. Of course
ActiveAdmin needs to be installed and working in the parent rails application,
for this to work.

To use the Qwester ActiveAdmin register files, add this to the active_admin 
initializer in your application.

    config.load_paths << Qwester.active_admin_load_path

See test/dummy/config/initializers/active_admin.rb for an example

=== Local modifications of qwester active admin pages
If you wish to over-ride some of Qwester's active admin registers you will
need to reorder the active_admin load_paths. In this case, use this form of
the load_paths declaration:

    config.load_paths = [Qwester.active_admin_load_path] + config.load_paths

One side-effect of this that I have been unable to solve, is that if you modify
an over-riding register file while the app is running, the load order is altered
and the qwester register file over-rides the local app's register file until the
app is restarted. Therefore, you have to restart the app before modifications
to over-riding register files take effect. In practice this only affects the
development environment, as in both test and production the app is restarted 
after a change.

=== Active admin menus
Links to the admin pages for Qwester models will appear in a 'Qwester' sub-menu.
If you wish to change the name of the menu parent group, add this to an 
initializer:

    Qwester.active_admin_menu = 'menu name'

Alternatively, if you want the Qwester models not to be grouped add this to an
initializer:

    Qwester.active_admin_menu = 'none'

See test/dummy/config/initializers/qwester.rb for an example