Merlin

Merlin is the custom JS framework built for CBU by TC. Merlin is named for because it is meant to help creating wizards. Some of the specific features:

• Handles hashing (ie /page#action)
• Handles the magic_spell which does something fancy things with width and height. This is for steps that have transitional effects. (needs a little more looking into)

File(s)

The main Merlin file is in static/js/tc.gam.merlin.js.

Developing

This section will go through making a Merlin Wizard.

Template Markup

<div class="merlin custom-wizard">
    <div class="step step-name-1">
        <!-- Markup, maybe a form -->
        
        <a class="next-button"></a>
    </div>
    <div class="step step-name-2">
        <!-- Markup, maybe a form -->
    </div>
    <div class="step success-step">
        <!-- Thank you message -->
    </div>
    <div class="step error-step">
        <!-- Error message -->
    </div>
</div>

<!-- Add JS, though this is not the greatest way to do this. -->
<script src="/path/to/file.js"></script>

JS Handling

Merlin Object

• name: Arbitrary id for the Merlin application.
• dom: jQuery element for creating a context to search in. Usually made with something like dom.find('.merlin.custom-class-name').
• next_button: jQuery element referring to the button that controls moving the wizard forward. Usually something like dom.find('a.next-button').
• first_step: The step id as defined below for the initial step of the wizard.
• data: Arbitrary JS object for holding data that may be submitted when wizard is complete. When defining the wizard object, this is mostly just a placeholder for defaults.
• use_hashchange: Boolean on whether to use the hash change function. (not sure the scope of this decision)
• steps: jQuery object where each property is a step object. The property name becomes the step id.
  • 'step-id-X': Arbitrary step identifier that holds step object.
    • selector: jQuery selector for this step. Something like '.step.step-name-1'.
    • next_step: Step id of next step. Example: 'step-id-2'
    • inputs: JS object for describing the inputs used in this step.
      • 'input-id-X': Arbitrary input identifier for the input.
        • selector: jQuery selector for the input that this input object refers to. Example: 'textarea.input-class-name'.
        • validators: This is an array of strings that refer to validators. The complete list of validators can be found in the JS Docs on page docs/js/files/tc-gam-validate-js.html. Or in the file static/js/tc.gam.validate.js. For instance: ['min-3', 'max-200', 'required'].
        • hint: String hint that will be used an inline label. For instance: 'Enter text here...'.
        • handlers: JS object of handler functions.
          • 'handler-event-id': Please the full list of available handlers at the inline JS docs on page docs/js/files/tc-gam-merlin-js.html or in the file static/js/tc.gam.merlin.js.
            • function(e, d) { }: Function to handle the event.
    • init: Initialization function. This is mostly about setting classes where needed. This should be called every time the step is invoked. For success steps (ie when the wizard is done), this would be the time to post data).
      • function(merlin, dom) { }: Function to handle the init phase of the step.
    • finish: Finish function. This should be called every time the step is done (ie moving to next step).
      • function(merlin, dom) { }: Function to handle the finish phase of the step.

Inline Documentation

There is a fair amount of inline documentation in the code. Please see Documentation

Merlin is magical, FYI.

/*         Magic!!
      __________________
    .-'  \ _.-''-._ /  '-.
  .-/\   .'.      .'.   /\-.
 _'/  \.'   '.  .'   './  \'_
:======:======::======:======:  
 '. '.  \     ''     /  .' .'
   '. .  \   :  :   /  . .'
     '.'  \  '  '  /  '.'
       ':  \:    :/  :'
         '. \    / .'
           '.\  /.'
             '\/'
*/