IntroductionVersion 1.6.1 of ReDBox introduced a new method for defining forms and workflows. These new forms can be seen in action in the "Researcher Dashboard" as the Data Management Planning Tool (DMPT) and the self-submission form for collections. A central design goal was to make it easier for sites to customise (completely redo) the forms as they are likely to need local decisions regarding the appropriate fields and display text. In order to achieve this goal, a number of new features have been put into place:
This How-To provides an overview of the process for customising the DMPT and self-submission forms. It's a somewhat technical process so requires some technical skills. The information here is likely to also provide you a starting point for adding new forms and workflows to ReDBox and Mint.
Thanks!We'd like to thank the following stakeholders for their assistance in this work:
Key directories/files
Getting to workDon't let the "Key directories/files" section worry you too much - most of the customisation work is done in configuration-level files.
Configuring the systemThere are a few items you'll need to add to system-config.json in order to get the forms up and running. The config segment below should appear in your configuration - handy if something doesn't appear to be working. Also check out our sample config. The role of these elements will be described in the rest of this document. { ... "transitionWorkflow": { "transitions": [ { "name": "Researcher Record", "from-workflow-id": "self-submission", "from-workflow-step": "self-submission-submitted", "to-workflow-id": "dataset", "to-workflow-step": "metadata-review" } ] }, ... "houseKeeping": { "config": { ... "jobs": [ ... { "name": "transitionWorkflow", "type": "external", "url": "http://localhost:${jetty.port}/redbox/default/hkjobs/transitionWorkflow.ajax", "timing": "0 0/15 * * * ?" }, ... ] }, ... "transformerDefaults": { ... "jsonVelocityPDF": { "id": "jsonVelocityPDF", "sourcePayload": ".tfpackage", "templatesPath": "${fascinator.home}/pdf-templates", "checkForTFMETAProperty": "true", "TFMETAPropertyName": "generatePDF", "TFMETAPropertyValue": "true", "clearPropertyOnTransform": "true", "versioning": "true" }, "dmpToSelfSub": { "id": "jsonVelocity", "sourcePayload": ".tfpackage", "templatesPath": "${fascinator.home}/templates/self-submission/selfSub.vm", "checkForTFMETAProperty": "true", "TFMETAPropertyName": "copyTFPackage", "TFMETAPropertyValue": "dmpToSelfSub", "clearPropertyOnTransform": "true", "transformSource": "true" } ... }, Configuring a workflow As in prior versions, the workflow configuration is provided in a harvest definition:
The "stages" element in
You can see that we have 2 stages: "dmpt-draft" and "dmpt-complete". The following options are provided:
The security and visibility settings are the traditional role-based model used in ReDBox but, in terms of the DMPT, this isn't overly useful - a data plan is owned by an individual and not a role. This meant that a new option is needed (owner_edit_allowed) to indicate that, when the object is created, the user that created the object is given direct ownership. In the config above, those in the admin role can still manage the object (as you'd expect). The user can change ownership via the user interface but we won't go into that here.
ReDBox workflows are simple things - they move forward in a linear fashion. There's no ability to setup complicated workflow logic such as conditionals so don't start planning in-depth flow charts. Instead, the transitions approach lets an object in a specific state move to another stage. More about this a bit later.
A gotcha to watch forDid you notice that the stage names use a <workflow>-<stage> format (e.g. dmpt-draft)? This is required as it's actually the stage names that are used by the system when handling workflows. Each stage should have a unique "name" property across the system (not just across a specific workflow).
For the very technicalIf you're wanting to dig further:
Unfortunately, the template property inherits a somewhat confusing notion from the base workflow implementation. Whilst it's used in "dmpt-complete", it actually relates to the previous stage ("dmpt-draft"). Basically, it's used as a progression element that tells the workflow plugin what needs to be done to get to that stage.
Setting up the form fieldsThe workflow configuration describes the progression through which the object/record moves in the system - what's now needed is to map a form configuration to each stage so that you can define what the user sees. Take a look at
home/form-configuration/dmptform.json and you'll find it starts with:
The " Each element in "
Just glancing at A field is defined with properties such as:
The following subsections take a look at possible fields. Note: Where you see odd text such as dmpt.heading.welcome, these will make more sense when you get the "Language files" section. Text and HTMLA heading is quite easy:
A plain old paragraph:
An HTML label:
You can also add straight HTML. The example below is basic but you'll notice in the configuration files native-html can be used to insert tricky layouts etc
Text fieldsA text input:
{ "component-type":"text-input", "field-name":"dc:relation.bibo:Website", "label":"", "additional-classes":"" }, The label property can be set for the text-input rather than have a separate label element. A textarea:
Some fields are repeatable - they allow the user to type an entry and add it to a list of values:
Date pickersDate pickers are defined as text-input components with a dateYMD set for the "additional-classes" property. { "component-type":"text-input", "field-name":"dc:coverage.vivo:DateTimeInterval.vivo:start", "label": "", "additional-classes":"dateYMD" }, LookupsThe following segment provides a drop-down using a set of options from a JSON file ( portal/dashboard/dashboard/dmpt/data/projectActivityType.json ){ "component-type":"data-source-dropdown", "field-name":"dc:subject.anzsrc:toa.rdf:resource", "label":"", "field-name-label":"dc:subject.anzsrc:toa.skos:prefLabel", "sourceUrl":"dmpt/data/projectActivityType.json" }, These components can also use Mint as a source: { "component-type": "data-source-dropdown", "field-name": "dc:language.dc:identifier", "field-name-label": "dc:language.skos:prefLabel", "label": "", "sourceUrl": "proxyGet.script?ns=Languages&qs=count%3D9999", "listKey": "results", "labelKey": "dc:title", "idKey": "dc:identifier" }, OthersThe People field is a tricky one - it's best to hit the mailing list if you're trying to hack it. The Field or Research widget is a bit more involved and I'll just highlight it here rather than get stuck into it: { "component-type":"repeatable-anzsrc-selection", "label":"FoR code(s)", "fieldName":"dc:subject.anzsrc:for.0.rdf:resource", "fieldNameLabel":"dc:subject.anzsrc:for.0.skos:prefLabel", "sourceUrl":"proxyGet.script?ns=ANZSRC_FOR&qs=count%3D999%26level%3D", "dataLevel":"top", "mandatory":"false", "idKey":"rdf:about", "labelKey":"skos:prefLabel", "listKey":"results", "defaultValue":"skos:narrower", "anzsrcType":"for" }, ValidationYou're likely to need to check some fields and this is where the "validation" property comes in: { "component-type":"text-input", "field-name":"dc:title", "label":"", "additional-classes":"", "validation": { "save-rules": [ "required" ], "validation-id": "dc:title", "focus-id": "dc:title", "validation-messages":{ "required": "Project name is required" } } },
ControlsThe transition-control component provides our form with functions to move to the next "div" or save { "component-type": "transition-control", "transitions": [ { "name" : "Back" }, { "name" : "Next" } ] }, { "component-type": "transition-control", "transitions": [ { "name": "Save", "form-submit-action": "save", "type": "button" }, { "name": "Save and close", "form-submit-action": "save", "type": "button", "close": true, "closeUrl": "dmpt/details" } ] } For the very technicalThe current display format for the forms is based on a "wizard" display whereas the review workflow forms use a tab display. We intend to make this configurable in future versions but if you want to change it now, check the
portal/dashboard/dashboard/form-components/dmptform-footer.vm template and you can edit it to use a tab display rather than wizard.js .The form components (component-type) use a set of velocity templates that deserve their own documentation but can be accessed at:
These components use a set of JQuery-based UI widgets called the JAFFA library:
Language filesRather put the text (e.g. labels and help) directly into the user interface or form configuration, a language service allows you put all of your text into a properties file. The properties file consists of a series of key/value pairs (with each pair on a single line).
In the last section, the form configuration featured 2 key elements (content and help) that refer to a language file entry rather than put the text directly into the config. For example:
If you take a look in
home/language-files directory you'll find a set of properties files, specifically one called dmpt-help and another dmpt-form . Whilst the two properties used above can be found in their pertinent file, the sample below combines the two:
As you can see, the key used in the form definition is provided in a properties file with a text value for use in the display.
If you'd like to use different strings in your system, you'll need to:
The language service is enabled via the "services" array in system-config.json. There's not really much to configure here, just make sure your config features the segment below:
Transitions (self submission to main review workflow)In the 1.6.1 version of ReDBox there is 1 transition that takes place:
It's important to note that, with a transition, the object/record isn't copied/cloned - it's the same object/record, just in a new workflow stage. Because of the security setup in the main review workflow, the user can see their record but will no longer be able to edit it. The record is able to transition easily as the self-submission forms and review forms use the same fields so no field mapping takes place. Transitions are defined in the
transitionWorkflow section of system-config.json. Below you can see the config for the situation described above (it's rather self-describing):
A housekeeping job is configured to check for objects awaiting transition:
Cloning (DMPT to self-submission)Once a user is happy with a data management plan, they can create a self-submission collection based on that plan. This is different to the transition just described as a copy needs to be made. The process also takes place as soon as the user clicks the action - it doesn't use the housekeeping system as the user will expect to see a result within moments. The process for this cloning is:
The transformer is defined in system-config.json: "transformerDefaults": { "dmpToSelfSub": { "id": "jsonVelocity", "sourcePayload": ".tfpackage", "templatesPath": "${fascinator.home}/templates/self-submission/selfSub.vm", "checkForTFMETAProperty": "true", "TFMETAPropertyName": "copyTFPackage", "TFMETAPropertyValue": "dmpToSelfSub", "clearPropertyOnTransform": "true", "transformSource": "true" }
Change the data plan PDFThe PDF created for a data management plan uses a template ( home/pdf-templates/Data Management Plan.vm ). For the PDF transformer to work correctly, this template MUST create XHTML-compliant output.The settings are defined in the transformerDefaults section of system-config.json:
Other resources
|
Documentation > HOW-TO >