Loading ...

OpenWGA 7.0 - OpenWGA Concepts and Features

Design and development » HDBModel framework » HDBModel in TMLScript » Event scripts » Defining event scripts

Hierarchical event scripts

Hierarchical events run before and after a create/update/delete operation is performed. They are only available for content documents, not for storage documents.

Valid names for hierarchical events are built the following way:

  • Take the name of one of the available operations, starting with a capital letter: "Create", "Update" or "Delete"
  • Prefix it with a "pre" or a "post", depending on if the script should run before or after the operation

So resulting event names, and therefor event method names, are  "preCreate", "postUpdate" and the such.

The main purpose of "pre" events is the validation if the operation should happen at all given the current documents status. if the script determines that it should not it should call the method hdbModelEvent.cancel() which cancels the operation. Therefor these events are guaranteed to run before any data modification is done. However because of this they are not able to validate the data produced by the modifications. Validating these should be done on the simple script "onSave" instead.

The main purpose of "post" events is to execute subsequent functionalities that should be ran after the operation has been done. After the creation of a content you could for example create some default subcontent directly on it. Therefor these events are guaranteed to run after all modification is done, including automatic ones like building a storage substructure for new contents:

this.postCreate = function(e) {

   // Create default categories
  HDBModel.createContent("category", e.getContent(), {
      title: "Public",
      allowed: true,
     }
  );

  HDBModel.createContent("category", e.getContent(), {
      title: "Private",
      allowed: false,
    }
  );

}

As you see it is perfectly valid to create/update other documents in "post" event scripts via HDBModel methods. But you MUST NOT update the document on which the operation runs in any "post" event. Triggering an update would again invoke the event scripts which most likely would result in an endless recursion and stack overflow. You should avoid these situations, but as a "last resort" you could instead use the WGAPI method doc.save(), which does not trigger hierarchical events.

Events with the given names run directly on behalf of the content which is created/updated/deleted. 

However these events are called hierarchical because they also may be defined to run on behalf of any child content in the case that a content below the "current content" gets created/updated/deleted. For example: In the Basics example, you could define an event script for "project" documents which should get triggered when any "task" document below it gets created.

For this you simply have to suffix the desired event name with the content class of the child content, whose operations should trigger the script. This content class suffix should also be camel-cased and all characters not valid in JavaScript identifiers removed. So for the use case given above a method named "preCreateTask" would be defined in the "project" event module.

We could use this to validate, if the project is still "open" so new tasks make any sense:

this.preCreateTask = function(e) {

  if (content().getItemValue("status") == "closed") {

    e.cancel("Cannot create task for closed project");

  }

}

This would also work if "task" contents weren't immediate child contents of "project" contents and there were some other content class in-between.

Hierarchical event scripts normally run in the WebTML context of the content whose event script is called. So in the "preCreateTask" example above the "project" document is in context. The content on which the operation is actually done is available there from the event object under hdbModelEvent.content. In the "postCreate" example, where modified content and the content of the script are the same, the context of course lies on this document.

There are two exceptions to this WebTML context rule: "preCreate" and "postDelete". This is simply because the document of the script is not yet / not any more available at that time the event script runs. Therefor the following applies:

  • "preCreate" runs in the context of the reference document given to the create operation
  • "postDelete" runs in the context of the parent document of the deleted content