Documents

Documents serve to interact with the user via pages with business data that are not dependent on a process: documents are available as long as their definition is on the server.

Documents are defined in the document definition: you can create one or multiple Documents in one document definition. Typically, you want to create your documents in a dedicated Module to allow you to unload the Module without side effects later if necessary. Once you have created a Module with document definitions, all you need to do is upload the Module: The documents will be available in the Document tab of the users as long as the Module remains on the server.

The default application displays the list of Documents available on the server on the Documents tab:

• When the user opens a document, the system creates a Model instance with all the context data and renders and populates the document data.
• When the user submits the document, the document data is saved, typically in the underlying DB via shared Records, and the model instance ceases to exist. Note that the document will remain available in the list of documents since the list contains the types of documents, not their instances: Unlike To-Dos, documents availability does not depend on a Process Task; they are available as long as the definition of the document is on the server and their instances are created on request.

Form with a table in a document

Defining a Document

To define a new document, do the following:

1. Create a document definition file:
   1. Right-click your module.
   2. In the context menu, go to New > Document Definition
   3. In the New Document Definition dialog, define the definition file properties: check its location and modify its name.
2. Open the document definition file.
3. In the Documents area of the Document Editor, click Add.
4. In the right part, define the properties of the document.
   • Name: name of the document unique in the Module

   • Title: document title displayed in the web application

     The title is a String expression, which is re-evaluated on document refresh (for details on the refresh mechanism refer to Application User Interface Forms User Guide).

   • Parameters: list of input arguments of simple data types used by the document

     Parameters are meant to pass data to the document. Note that documents with parameters are not visible in the Documents list in the application.

   • UI definition: expression that returns the UI definition, typically a form call
   • Access rights: boolean expression that defines the condition that must be true to allow the front-end user to access the document
   • Navigation: where to go when the user submits the document
   • Navigation Factory: function that will return the Navigation object to the Document and takes the same parameters as the document
5. If applicable, upload your Module and check the Document on the Documents tab of the Application User Interface.

Navigate Away from Document

To define where to navigate when the user submits a document, define the Navigation property closure: The closure gets as its input parameter all To-Dos that were created when the document form called the createModelInstance() or a synchronous sendSignal() functions.

For example, let's assume a document that references a form with a Button component. The Button component defines an ActionListener with the handle expressions

• createModelInstance(true, findModels("MyModel", 1.0, true) [0], [->]) and
• sendSignal(true, findModelInstances("MyModel", 1.0, true, [->]), "Consider roll-back action.")

The To-dos created by the calls are input of the Navigation closure so you can navigate to one of the to-dos.

You can navigate to to-dos, application pages, external URLs, documents. Here are some examples:

• to-do

  {todos:Set<Todo> ->
    new TodoNavigation(
      todo -> getTodosFor(getPerson("admin"))[0],
      openAsReadOnly -> false)
  }
  

  To navigate to a to-do created from the document, use the input parameter of the navigation closure that holds to-dos created by a createModelInstance() or a synchronous sendSignal() functions: to navigate to the first to-do created by the document form, define Navigation as

  {todos:Set<Todo> ->
    new TodoNavigation(
      todo -> todos[0],
      openAsReadOnly -> false)
  }
  

• application page:

  //navigating to the Documents page:
  { s:Set<Todo> -> new AppNavigation(code -> "documents")}
  

• document:

  //navigating to a document (creates a new document instance):
  { s:Set<Todo> -> new DocumentNavigation(documentType -> myDoc())}
  

• saved document:

  //navigating to a saved document;
  //getMySavedDoc() is a query that returns a SavedDocument):
  { s:Set<Todo> ->
    new SavedDocumentNavigation(savedDocument -> getMySavedDoc())
  }
  

• url:

  //navigating to an external URL:
  { s:Set<Todo> -> new UrlNavigation(url->"www.whitestein.com")}
  

You can also define the Navigation Factory function so you can use it then Navigation property so you do not have to explicitly instantiate the Navigation object with parameters.

Example Navigation Factory

getDateFormNavigation(1)
//instead of
//new DocumentNavigation(
//  documentType -> dateForm(),
//  parameters -> ["id" -> 1]
//  )

Creating a Model Instance and Navigating to its To-Do on Document Submit

To create a model instance from a document and then navigate to one of its To-dos, do the following:

1. Define a listener that will create the model instance:
   1. Attach a listener of the required type to a component.
   2. Create the model instance in its persist action, for example, createModelInstance(true, getModel("myModelName"), null)
      
2. Define a listener with the Submit action (it represents the moment when you want to submit the data and navigate away from the document).
3. In the document definition, define the Navigate property so it returns TodoNavigation to the required To-do.

   \navigates to the first to-do generated by the document:
   {todos:Set<Todo> -> new TodoNavigation(todo -> todos[0], openAsReadOnly -> false)}