PoNG Module Programming: Unterschied zwischen den Versionen
Mh (Diskussion | Beiträge) (Die Seite wurde neu angelegt: „Please have a look at the other standard modules coming with PoNG. Category:PoNG == Basic Module Concep…“) |
Mh (Diskussion | Beiträge) |
||
(2 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt) | |||
Zeile 2: | Zeile 2: | ||
[[Category:PoNG]] | [[Category:PoNG]] | ||
== Basic Module Concept == | == Basic Module Concept == | ||
− | Modules are defined in the file <code> | + | Modules are defined in the file <code>modules/portal-ng-modules.js</code>. The modules are ".js" files in the subdirectory <code>modules/<modulename></code>. |
− | In the <code> | + | In the <code>modules/portal-ng-modules.js</code> you have to do two things: |
'''1. Define the module itself''' by adding a line | '''1. Define the module itself''' by adding a line | ||
− | moduleMap | + | moduleMap[ "modulename" ] = { ... }; |
− | + | PoNG will include the file <code>modules/<modulename>/<modulename>.js</code>. | |
− | PoNG | + | PoNG also loads style definitions from the <code>modules/<modulename>/<modulename>.css</code> file. |
− | Modules | + | 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 | ||
− | + | 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>modules/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>modules/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 | + | ==== 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 == | ||
+ | === modules/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>< | + | # 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 | + | moduleMap[ "my-module" ] = { |
− | + | "name": "my-module", | |
+ | "hooks": [ | ||
+ | { hook: "addActionBtn", method:"myModuleAddActionBtn" } | ||
+ | ] | ||
+ | }; | ||
... | ... | ||
− | === | + | === modules/my-module/my-module.js === |
Implement you module script: | Implement you module script: | ||
<pre> | <pre> | ||
Zeile 138: | Zeile 201: | ||
=== CSS === | === 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 <code> | + | 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 <code>modules/<modulename>/</code>. |
− | Example: '''my-module | + | Example: '''modules/my-module/my-module''' |
#myModuleBtn { font-size:10pt; } | #myModuleBtn { font-size:10pt; } |
Aktuelle Version vom 24. Februar 2015, 21:03 Uhr
Please have a look at the other standard modules coming with PoNG.
Inhaltsverzeichnis
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" ] = { ... };
PoNG will include the file modules/<modulename>/<modulename>.js
.
PoNG also loads style definitions from the modules/<modulename>/<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 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
.
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)
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:
- Embed the config into the layout in the
moduleConfig
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 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
modules/portal-ng-modules.js
To define the module and the hook functions in the modules file, you need to
- 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. - 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" }
]
};
...
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 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 modules/<modulename>/
.
Example: modules/my-module/my-module
#myModuleBtn { font-size:10pt; }