Module Programming

Table of Contents Basic Module Concept Module Template Client Side Session Available Hooks addHeaderHtml Hook addFooterHtml Hook addActionBtn Hook creModal Hook loadResourcesHtml Hook Module Constructor Function Update Function Hook SetData Function Hook Module dependencies Module Example modules/portal-ng-modules.js modules/my-module/my-module.js Use your Hook in Structure Definition CSS I18N

Basic Module Concept

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

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

1. Define the module itself by adding a line

 moduleMap[ "modulename" ] = {  ... }; 

Initially the framework will include the file modules/<modulename>/<modulename>.js.

Style definitions are imported from the modules/<modulename>/<modulename>.css file.

Modules coming with the framework 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 available, 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 modules/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 modules/portal-ng-modules.js.

Client Side Session

It is easy to transfer information from one page to another by adding data to the sessionInfo array.

Example:

 function initMyModuleHtml( divId, type , params ) {
 	log( "MyModule", "initOAuthHeaderHtml");
 	if ( sessionInfo["MyModule"] == null ) {
 		sessionInfo["MyModule"] = {
 			'someInfo': '',
 			'anotherInfo': ''
 		}
 	}
 	if ( params != null  &&  params.someInfo != null ) {
 		sessionInfo["MyModule"]['someInfo'] = params.someInfo; 
 	}
 }

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 Specification: 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 specification: 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 specification: 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 in the page set up life cycle, when you use a addActionBtn hook.

Function Parameters

• id
• modalName
• resourceURL
• Return value: none

loadResourcesHtml Hook

This is one of the most important hooks, since it is triggered to load the config and render the HTML of the view.

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, tis DIV will be replace by the generated HTML)
• resourceURL
• Parmeter (object)

Return value: none

The framework will put all GET parameters of the page into params.get, so they can be used in the module (ref example below).

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?mode="+params.get['mode'],  //TODO: better param handling: http://<baseurl>/<resourceUL>/myModuleConfig.json?mode=<mode>
                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 ) {
     ...
 }

SetData Function Hook

The hook takes the data as parameter, processes the data and inititates the rendering of the view. It is similar to the update hook, but the resource URL is not called. The typical use case is a search from in one view doing a GET request and a result table in another view. The response of the GET (or a part of it) should be handed over to the table to process and display it.

Module Map:

 moduleMap[ "pong-xyz" ] = {
   "name":  "pong-xyz",
      "hooks": [
         { hook: "setData", method:"pongXyzSetData" }
      ]
 };

Function Parameters

• divId
• data
• Return value: none

Example hook implemenation in pong-xyz.js

 function pongXyzSetData( divId, data ) {
     ...
 }

Calling the hook:

 setModuleData( resId+"Content", dataObj, subPath );

e.g.

 setModuleData( "itemTblContent", dataObj, "result.items" );

or

 setModuleData( "itemTblContent", dataObj, null );

Module dependencies

Modules can be build up on other modules or include 2rd party JS libraries:

Examples:

 moduleMap[ "pong-easytable" ] = {
     "name": "pong-easytable",
     "requires": [ "pong-table" ],
     hooks": [
        ...
     ]
 };
 moduleMap[ "jquery-syntax" ] = {
     "name": "jquery-syntax",
     "hooks": [
         ...
     ],
     "include":[ "syntax/jquery.syntax.js", "syntax/jquery.syntax.cache.js" ] 
 };

Module Example

modules/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. The framework adds 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 === modules/my-module/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 <code>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 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 modules/<modulename>/.

Example: modules/my-module/my-module

 #myModuleBtn { font-size:10pt; }

I18N

Internationalization is supported by default, i.e. changing the language of labels and text on the page.

A user can switch the language, if you use the the i18n module in the header.

The language is setting the language code using the lang GET parameter. Default language is "EN". Please use this setting to load content in the specific language from the resources.

TODO: PoNG will pass the "lang" in the "Accept Language" HTML header field for access of backend resources.

Please use the $.i18n( ... ) JS method to lookup labels and text in the requested language setting. Example JS code:

    var linkHtml= '<a href="' + lnk.url + '">' + $.i18n( lnk.text ) +'</a>';

The used I18N package can also do some grammar, plural and gender things. Please refer the jquery.i18n documentation for details.