Tapestry

h1. Customization

h2. Overriding Default Views, Partials, Templates, etc.

It is possible to override any Rails view in the application by mimicking the directory structure in @app/views@ but under another folder @site_specific/app/views@. For example, to use your own version of @_dashboard.html.erb@ in @app/views/pages@ you would put it in @site_specific/app/views/pages@.

You can override the @#{Rails.root}/site_specific@ folder itself with the environment variable TAPESTRY_OVERRIDE_PATH, so that the folder can be left entirely outside of the Tapestry code base.

It is important to understand that including this folder, any subfolders, and all files is _optional_. If you do not wish to override a particular view, leave it out of the override folder.

h3. Caveat

_This statement to be followed up after more investigation._

It is my impression that when using multiple paths that the technique of using @explicitly_unloadable_constants@ for having files reload without restarting the server will not work properly. This could mean that while developing these site-specific files that the server has to be restarted after each change.

h3. Overriding @lib@ Files

The same logic works for files in the override path under the @lib@ subfolder, i.e. either @#{Rails.root}/site_specific/lib@ or @#{ENV['TAPESTRY_OVERRIDE_PATH']}/lib@.

h2. Adding Custom Questions to the "Participation Consent" Form

Currently this text and form are found in @views/participation_consents/show.html.erb@. This currently saves the user's responses in the InformedConsentResponse model. There is in this model a field called "other_answers" that is a serialized Hash where any number of "dynamically defined" answers can be saved with keys of your choosing. To accomplish this you have to add form inputs that end up with a @name@ attribute that looks like (e.g. to record "age"): @other_answers[age]@ and it will be recorded in the "other_answers" Hash in the model under the :age key.

There is a view helper for creating radio boxes for the participation concept form using this "other_answers" field. Example:

<pre>

  <div class="consent-form-question">

    <p>

      Would you judge yourself to be sane?

      <%= radio_answers( 'sanity', [['0', 'No'],

                                    ['1', 'Sometimes'],

                                    ['2', 'Yes']] ) %>

    </p>

  </div>

</pre>

h3. Adding Custom Validation of Your Custom Question

This is done by overriding a site specific validations file in the @lib@ override folder, in the @lib/site_specific/validations.rb@ module. By adding a method called @informed_consent_response_validations@ (after the name of the model relevant to the Participation Consent form) to the copy of this module you've placed in the @lib/site_specific@ _override_ folder, you can check @other_answers@ and add errors in the standard ActiveRecord way. For example:

<pre>

    def informed_consent_response_validations

      if self.other_answers[:sanity] == '2'

        errors.add( :other_answers, :sanity_not_permitted)

      end

    end

</pre>

The message should be placed in your locale file under:

<pre>

en:

  activerecord:

    errors:

      models:

        informed_consent_response:

          attributes:

            other_answers:

              sanity_not_permitted: 'You are not permitted to be sane.'

</pre>