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[ "modulename" ] = {  ... }; 

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

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

Modules coming with PoNG will have the naming convention pong-<modulename> and give you some common core functionality.

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

moduleMap[ "modulename" ] = {   
   "hooks" : [ { "hook": "<hookname>", "method":"<hook function name>" } ]
 };

The function should be in the module JS file, loaded by step one.

It is always 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.

Module Template

To make it easy, there is a hook template. Please have a look on js/pong-modules/module-template.js.

Copy to the file your favorite module name, implement the methods and follow the advices in the comments. To enable you have to put the hooks into js/portal-ng-modules.js.

Available Hooks

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

addHeaderHtml Hook

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 Hook

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 Hook

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 Hook

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 Hook

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

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

Module Constructor Function

• divId (ID in HTML DIV tag, PoNG expects the function to replace the content there)
• resourceURL
• Parmeter (object)

Return value: none

Module Config:

There are two ways to configure the module:

1. Embed the config into the layout in the moduleConfig attribute
2. Load it from the resourceURL or somewhere else

Your code you must be prepared to deal with the 1st option.

function myModuleHTML( divId, resourceURL, params ) {
   ...
   if ( moduleConfig[ divId ] != null ) { // *must* have
       renderHTML( divId, resourceURL, params, moduleConfig[ divId ] );
   } else { // *optional*: load config somwhere else
       $.getJSON( 
           resourceURL+"/myModuleConfig.json", 
               function( config ) {
                   renderHTML( divId, resourceURL, params, config );
               }
           );	
       }	
}

Update Function Hook

This is not a MUST, but nevertheless you should implement this hook.

Trigger: This is typically triggered by other actions on the page. The hook is called, if you call udateModuleData( divId, paramsObj ); from framework.

Function Parameters

• divId
• paramsObj
• Return value: none

Example

Module Map:

moduleMap[ "pong-list" ] = {
  "name":  "pong-list",
     "hooks": [
        { hook: "loadResourcesHtml", method:"pongListDivHTML" },
        { hook: "update", method:"ponglisteUpdateData" }
     ]
};

Code in pong-list.js:

function ponglisteUpdateData( divId, paramsObj ) {
    ...
}

Module 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 map. 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 hooks array. As type you should reference your module-name as defined in the <moduleMap/code>

...
moduleMap[ "my-module" ] = {
       "name": "my-module",
       "hooks": [
           { hook: "addActionBtn", 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; }