PoNG Module Programming: Unterschied zwischen den Versionen

Aus MH
Wechseln zu: Navigation, Suche
(Die Seite wurde neu angelegt: „Please have a look at the other standard modules coming with PoNG. Category:PoNG == Basic Module Concep…“)
 
Zeile 7: Zeile 7:
  
 
'''1. Define the module itself''' by adding a line
 
'''1. Define the module itself''' by adding a line
  moduleMap.push( "modulename" );
+
  moduleMap[ "modulename" ] = {  ... };  
Then PoNG will be include the file <code>js/pong-modules/modulename.js</code>.
+
PoNG will include the file <code>js/pong-modules/modulename.js</code>.
  
PoNG will also load style definitions from the <code>css/pong-modules/modulename.css</code> file.
+
PoNG also loads style definitions from the <code>css/pong-modules/modulename.css</code> file.
  
Modules included with PoNG will have the naming convention <code>pong-<modulename></code>
+
Modules coming with PoNG will have the naming convention <code>pong-<modulename></code> and give you some common core functionality.
  
 
'''2. Define all hooks, given by the module''' by adding the line
 
'''2. Define all hooks, given by the module''' by adding the line
  moduleHooks.push( { "hook": "<hookname>", "type": "<module name>", "method":"<hook function name>" } );
+
  moduleMap[ "modulename" ] = {  
 +
    "hooks" : [ { "hook": "<hookname>", "method":"<hook function name>" } ]
 +
  };
 
The function should be in the module JS file, loaded by step one.  
 
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.  
+
 
 +
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.
 
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 <code>js/pong-modules/module-template.js</code>.
 +
 +
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 <code>js/portal-ng-modules.js</code>.
  
 
== Available Hooks ==
 
== Available Hooks ==
 
You can use these hook names in the <code>portal-ng-modules.js</code>:
 
You can use these hook names in the <code>portal-ng-modules.js</code>:
  
=== addHeaderHtml ===
+
=== addHeaderHtml Hook ===
 
This is called when the header is created. You can use this to add HTML or script code to the heeder div.  
 
This is called when the header is created. You can use this to add HTML or script code to the heeder div.  
  
Zeile 34: Zeile 42:
 
* pram (optional parameter object)
 
* pram (optional parameter object)
  
=== addFooterHtml ===
+
=== addFooterHtml Hook ===
 
This is called when the footer is created. You can use this to add HTML or script code to the footer div.  
 
This is called when the footer is created. You can use this to add HTML or script code to the footer div.  
  
Zeile 44: Zeile 52:
 
* pram (optional parameter object)
 
* pram (optional parameter object)
  
=== addActionBtn ===  
+
=== addActionBtn Hook  ===  
 
[[PoNG Structure Specification|Structure definition]]: in rows or cols you can define property-array  
 
[[PoNG Structure Specification|Structure definition]]: in rows or cols you can define property-array  
 
* <code>"actions" : [ { "actionName": "<name>", '''"type": "<module-name>"''' }, ... ] </code>
 
* <code>"actions" : [ { "actionName": "<name>", '''"type": "<module-name>"''' }, ... ] </code>
Zeile 53: Zeile 61:
 
* Return value: The HTML with the button code, the dialog (div) and script code to add event listeners to the button.
 
* 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
 
Post conditions: creModal is called with same parameters in a later phase of the life cycle of page creation to load content asynchronous
=== creModal ===
+
=== creModal Hook ===
 
Trigger: This is called later int he page set up life cycle, when you use a <code>addActionBtn</code> hook.  
 
Trigger: This is called later int he page set up life cycle, when you use a <code>addActionBtn</code> hook.  
  
Zeile 61: Zeile 69:
 
* resourceURL
 
* resourceURL
 
* Return value: none
 
* Return value: none
=== loadResourcesHtml ===
+
=== loadResourcesHtml Hook  ===
 
Trigger: You simply have to add a type to your resource in the [[PoNG Structure Specification|structure definition]], e.g.
 
Trigger: You simply have to add a type to your resource in the [[PoNG Structure Specification|structure definition]], e.g.
 
  {
 
  {
Zeile 70: Zeile 78:
 
         "rowId": "yxz",
 
         "rowId": "yxz",
 
         "resourceURL": "resX",
 
         "resourceURL": "resX",
 +
        "resourceParam": { "kay": "value", ... },
 
         '''"type": "pong-form",'''
 
         '''"type": "pong-form",'''
 
         ...
 
         ...
Zeile 78: Zeile 87:
 
  }
 
  }
  
Function Parameters  
+
==== Module Constructor Function ====  
 
* divId (ID in HTML DIV tag, PoNG expects the function to replace the content there)
 
* divId (ID in HTML DIV tag, PoNG expects the function to replace the content there)
 
* resourceURL
 
* resourceURL
 +
* Parmeter (object)
 +
Return value: none
 +
 +
'''Module Config:'''
 +
 +
There are two ways to configure the module:
 +
# Embed the config into the layout in the <code>moduleConfig</code> attribute
 +
# 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 <code>udateModuleData( divId, paramsObj );</code> from framework.
 +
 +
Function Parameters
 +
* divId
 +
* paramsObj
 
* Return value: none
 
* Return value: none
  
== Example ==
+
'''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 ===
 
=== js/portal-ng-modules.js ===
 
To define the module and the hook functions in the modules file, you need to
 
To define the module and the hook functions in the modules file, you need to
# add the JS file as element of the <code><moduleMap/code> array. You only need to specify the base name here. PoNG will add the subpath and .js for you.
+
# add the JS file as element of the <code>moduleMap</code> map. You only need to specify the base name here. PoNG will add the subpath and .js for you.
# add your hooks and the function, which you wrote for this as element of the <code></code> array. As type you should reference your module-name as defined in the <code><moduleMap/code>
+
# add your hooks and the function, which you wrote for this as element of the <code>hooks</code> array. As type you should reference your module-name as defined in the <code><moduleMap/code>
 
  ...
 
  ...
  moduleMap.push( "my-module" );
+
  moduleMap[ "my-module" ] = {
moduleHooks.push( { hook: "addActionBtn", type: "my-module", method:"myModuleAddActionBtn" } );
+
        "name": "my-module",
 +
        "hooks": [
 +
            { hook: "addActionBtn", method:"myModuleAddActionBtn" }
 +
        ]
 +
};
 
  ...
 
  ...
  

Version vom 17. Februar 2015, 18:24 Uhr

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; }