Customization » History » Revision 5
Revision 4 (Phil Hodgson, 04/05/2014 05:27 PM) → Revision 5/15 (Phil Hodgson, 05/20/2014 07:37 PM)
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>
There are also helpers for text areas (@text_area_answer@) and standard input texts (@text_field_answer@). For example:
<pre>
<div class="consent-form-question">
<p>
If sane only sometimes, please explain when and for what reason this occurs:
</p>
<p>
<%= text_area_answer 'reason_sometimes_sane', { :cols => 60, :rows => 3 } %>
</p>
</div>
</pre>
h3. Adding Custom Validation of Your Custom Question
This is done by adding a site-specific validations file in the @lib@ "override" folder, in the @lib/site_specific/validations.rb@ module. First place the following code in the file:
<pre>
module SiteSpecific
module Validations
extend ActiveSupport::Concern
# *Do not remove this +included+ block!* It is what works the magic.
included do
method_name = "#{self.name.to_s.underscore}_validations"
validate method_name if method_defined? method_name
end
end
end
</pre>
Then after this insert a method called @informed_consent_response_validations@ (after the name of the model relevant to the Participation Consent form). You can check @other_answers@ and add errors in the standard ActiveRecord way. For example:
<pre>
def informed_consent_response_validations
case self.other_answers[:sanity]
when '2'
errors.add( :other_answers, :sanity_not_permitted)
when '1'
if self.other_answers[:reason_sometimes_sane].blank?
errors.add( :other_answers, :explain_occasional_sanity )
end
end
end
</pre>
The messages 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.
explain_occasional_sanity:
Please explain when and why you are sometimes sane.
</pre>
See the documentation on [[Internationalization]] for where to put this.
h4. Automatic Reloading of the Validations Override During Development
As shown in the @development.rb.example@ file, you can add the following line to your @development.rb@ to have validation override changes automatically reload without having to restart your Rails server:
<pre>
ActiveSupport::Dependencies.explicitly_unloadable_constants << 'SiteSpecific::Validations'
</pre>