Document store definition
Document stores are constructed by passing a delegate object as an argument to P.defineDocumentStore()
The delegate is a collection of properties and methods which define how your Document store should function.
externalData
std_document_store
will set the following properties within externalData
for each FormInstance
it creates.
"std_document_store:key" |
The key of the instance. |
"std_document_store:instance" |
The instance. |
"std_document_store:store" |
The document store object. |
Delegate interface
property name
Required. The internal name of the Document store. This name will be used when querying the document for data or values and can not be shared with any other Document store defined on your plugin.
property keyIdType
The type that will be used for the key
of your form, if it is not int
function formsForKey(key, instance, document)
Required. Return an array of forms.
You can use the value of key
and the document
to return different forms for different instances and documents. document
may be a historical version when using the document viewer.
IMPORTANT: The forms returned for a given key
should not vary depending on the currently active user. If you need to display or edit different forms for different people, use shouldDisplayForm()
and shouldEditForm()
.
Note that using the instance to determine forms is unlikely to be that interesting, and the methods and properties which require the list of forms cannot be used in this method.
function keyToKeyId(key)
If the key you are using is not the keyId, use keyToKeyId to transform a key object and into a keyId by return value.
function blankDocumentForKey(key)
Return what the blank document for a given key should be. You should return a JSON document that sets any default values you want to be set when the user first edits the document store.
function formIdFromRequest(request)
Given a request object, return a form ID. By default the Document store will use the second extraPathElements
.
function alwaysShowNavigation(key, instance, document)
Return true
to always multi-page navigation, overriding the default to only show it when it’s necessary.
function onSetCurrentDocument(instance, document, isComplete)
Called when the current document is set.
function onCommit(instance, user)
Called when commit()
is called.
function updateDocumentBeforeEdit(key, instance, document)
Called before a form is to be edited to change the current document. Changes to the document in this function are only saved if the user saves the form.
Use this if your form uses information from other sources that may change between edits.
function shouldDisplayForm(key, form, document)
Return true
if this form should be displayed when rendering the instance as a document.
Use form.formId
to determine which form is being queried.
function shouldEditForm(key, form, document)
Return true
if this form should be edited. Use this to stop users from editing individual forms.
Use form.formId
to determine which form is being queried.
function prepareFormInstance(key, form, instance, context)
Prepare a FormInstance
for the form.
IMPORTANT: Always check form.formId
to check you’re preparing the right form.
Use this to setup things like dynamic form choices
and external data
, for example:
var docStore = P.defineDocumentStore({ // ... , prepareFormInstance: function(key, form, instance, context) { if(form.formId === "form_name") { if(key.kind === "film") { instance.choices("genres", ["Action", "Comedy", "Horror"]); instance.externalData({ interest: "film" }); } else { instance.choices("genres", ["Thriller", "Drama"]); instance.externalData({ interest: "literature" }); } } } });
function getAdditionalUIForViewer(key, instance, document)
Use this to define additional UI to be displayed when rendering the form viewer.
Return an object containing locations and deferred renders.
Property | Location |
top | Displayed at the top of the page |
bottom | Displayed at the bottom of the page |
The properties are optional.
var docStore = P.defineDocumentStore({ // ... , getAdditionalUIForViewer: function(M, instance, document) { return { top: P.template("top").deferredRender(view) }; } });
function getAdditionalUIForEditor(key, instance, document, form)
Use this to define additional UI to be displayed when rendering the form editor. Check form.formId to only display on certain forms in the docstore.
Return an object containing locations and deferred renders.
Property | Location |
top | Displayed at the top of the page, above the form navigation |
formTop | Displayed above the form, after the form navigation |
bottom | Displayed at the bottom of the page, below the form navigation |
formBottom | Displayed below the form, before the submit buttons and form navigation |
The properties are optional.
var docStore = P.defineDocumentStore({ // ... , getAdditionalUIForEditor: function(M, instance, document, form) { return { top: P.template("top").deferredRender({}), formBottom: P.template("form-bottom").deferredRender({}) }; } });
property enableSidebarPanel
A boolean that enables items to be added to the top right of the form viewer. The sidebar is populated by implementing the "std:document_store:sidebar_panel"
service, which passes in a builder
parameter.
Example
An example small definition, where meetingDetails
and outcomes
are two defined forms:
var meetingRecordStore = P.defineDocumentStore({ name: "meetingRecord", formsForKey: function(key) { return [meetingDetails, outcomes]; }, blankDocumentForKey: function(key) { return { meetingDate: new Date() }; } });