PoNG Module Programming

Please have a look at the other standard modules coming with PoNG.

Basic Module Concept

Modules are defined in the file js/portal-ng-modules.js. The modules are ".js" files in the subdirectory js/pong-modules.

In the js/portal-ng-modules.js you have to do two things:

1. Define the module itself by adding a line

moduleMap.push( "modulename" );

Then PoNG will be include the file js/pong-modules/modulename.js.

PoNG will also load style definitions from the css/pong-modules/modulename.css file.

Modules included with PoNG will have the naming convention pong-<modulename>

2. Define all hooks, given by the module by adding the line

moduleHooks.push( { "hook": "<hookname>", "type": "<module name>", "method":"<hook function name>" } );

The function should be in the module JS file, loaded by step one. It is a good idea, to start all your <hook function name> with your module name, to prevent name collisions with other modules.

There are some hooks in the distribution of PoNG, for example a modal-form hook. You can have a look at these modules to get more insight.

Available Hooks

You can use these hook names in the portal-ng-modules.js:

addHeaderHtml

This is called when the header is created. You can use this to add HTML or script code to the heeder div.

Structure definition: in header can define property-array

• "modules" : [ { "id": "<module-id>", "type": "<module-name>", "param": {<your-optional-parameters>} }, ... ]

Function Parameters:

• id (the id of the resource, as specified in the modules list in the structure file)
• type (the type of action, as specified in the modules list in the structure file)
• pram (optional parameter object)

addFooterHtml

This is called when the footer is created. You can use this to add HTML or script code to the footer div.

Structure definition: in footer can define property-array

• "modules" : [ { "id": "<module-id>", "type": "<module-name>", "param": {<your-optional-parameters>} }, ... ]

Function Parameters:

• id (the id of the resource, as specified in the modules list in the structure file)
• type (the type of action, as specified in the modules list in the structure file)
• pram (optional parameter object)

addActionBtn

Structure definition: in rows or cols you can define property-array

• "actions" : [ { "actionName": "<name>", "type": "<module-name>" }, ... ]

Function Parameters:

• id (the id of the resource, as specified in the structure file)
• actionName (the name of action, as specified in the structure file)
• resourceURL (the URL of the resource, as specified in the structure file)
• Return value: The HTML with the button code, the dialog (div) and script code to add event listeners to the button.

Post conditions: creModal is called with same parameters in a later phase of the life cycle of page creation to load content asynchronous

creModal

Trigger: This is called later int he page set up life cycle, when you use a addActionBtn hook.

Function Parameters

• id
• modalName
• resourceURL
• Return value: none

loadResourcesHtml

Trigger: You simply have to add a type to your resource in the structure definition, e.g.

{
  "layout": {
    ...
    "rows": [
      {
        "rowId": "yxz",
        "resourceURL": "resX",
        "type": "pong-form",
        ...
      },
      ...
    }
  }
}

Function Parameters

• divId (ID in HTML DIV tag, PoNG expects the function to replace the content there)
• resourceURL
• Return value: none

Example

js/portal-ng-modules.js

To define the module and the hook functions in the modules file, you need to

1. add the JS file as element of the <moduleMap/code> array. You only need to specify the base name here. PoNG will add the subpath and .js for you.
2. add your hooks and the function, which you wrote for this as element of the array. As type you should reference your module-name as defined in the <moduleMap/code>

...
moduleMap.push( "my-module" );
moduleHooks.push( { hook: "addActionBtn", type: "my-module", method:"myModuleAddActionBtn" } );
...

js/pong-modules/my-module.js

Implement you module script:

 log( "my-module", "Loading Module");
  
 function myModuleAddActionBtn( id, name, resourceURL ) {
    log( "my-module", "myModuleAddActionBtn:  " + name );
    var html = '<button id="myModuleBtn'+id+'>...</button><div id="myModuleDlg'+id+'">...</div><script>....</script>';
    return html;
 }

Please be prepared, that the the hook may be used more than once. So as seen in the example, you should use the id from the parameters in the HTML id to keep it unique.

It may be required to have the modal form div empty, so you can load it in a later stage of the life cycle. You can use the creModal hook to load it asynchronous. If you do this, you are responsible to keep your HTML ids in sync in both hook functions.

Use your Hook in Structure Definition

{
 "layout": {
   "title": "My Site with a hook", 
   "header": {
      ...
   },
   "rows": [
     {
       "rowId": "example",
       "resourceURL": "MyResource",
       "decor" : "decor",
       ...
       "actions" : [ { "actionName": "MyButton", "type": "my-module" } ]
     },
     {
       ...
     }
   ],
   "footer": {
       ... 
   }
 }
}

The decor tag is important to get the menu bar rendered, so that you can see the button generated by your hook.

Please refer the PoNG Structure Specification for more details.

CSS

At least you should prepare a custom css file for your module with the same name of the module and place it in the folder css/pong-modules/.

Example: my-module.css

#myModuleBtn { font-size:10pt; }