PoNG Module Programming - Versionsgeschichte

Mh am 24. Februar 2015 um 19:03 Uhr

2015-02-24T19:03:35Z

Mh: /* Basic Module Concept */

2015-02-24T19:00:06Z

‎Basic Module Concept

Mh am 17. Februar 2015 um 17:24 Uhr

2015-02-17T17:24:22Z

Mh: Die Seite wurde neu angelegt: „Please have a look at the other standard modules coming with PoNG. Category:PoNG == Basic Module Concep…“

2014-03-30T16:28:24Z

Die Seite wurde neu angelegt: „Please have a look at the other standard modules coming with PoNG. Category:PoNG == Basic Module Concep…“

Neue Seite

Please have a look at the other [[PoNG_Modules#Standard_Modules_coming_with_PoNG|standard modules coming with PoNG]].
[[Category:PoNG]]
== Basic Module Concept ==
Modules are defined in the file <code>js/portal-ng-modules.js</code>. The modules are ".js" files in the subdirectory <code>js/pong-modules</code>.

In the <code>js/portal-ng-modules.js</code> 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 <code>js/pong-modules/modulename.js</code>.

PoNG will also load 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>

'''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 <code>portal-ng-modules.js</code>:

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

[[PoNG Structure Specification|Structure definition]]: in header can define property-array
* <code>"modules" : [ { "id": "<module-id>", "type": '''"<module-name>", "param": {<your-optional-parameters>}''' }, ... ] </code>
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.

[[PoNG Structure Specification|Structure definition]]: in footer can define property-array
* <code>"modules" : [ { "id": "<module-id>", '''"type": "<module-name>", "param": {<your-optional-parameters>}''' }, ... ] </code>
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 ===
[[PoNG Structure Specification|Structure definition]]: in rows or cols you can define property-array
* <code>"actions" : [ { "actionName": "<name>", '''"type": "<module-name>"''' }, ... ] </code>
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 <code>addActionBtn</code> hook.

Function Parameters
* id
* modalName
* resourceURL
* Return value: none
=== loadResourcesHtml ===
Trigger: You simply have to add a type to your resource in the [[PoNG Structure Specification|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
# 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 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>
...
moduleMap.push( "my-module" );
moduleHooks.push( { hook: "addActionBtn", type: "my-module", method:"myModuleAddActionBtn" } );
...

=== js/pong-modules/my-module.js ===
Implement you module script:
<pre>
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;
}
</pre>
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</code> from the parameters in the HTML id to keep it unique.

It may be required to have the modal form <code>div</code> empty, so you can load it in a later stage of the life cycle. You can use the <code>creModal</code> 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 <code>css/pong-modules/</code>.

Example: '''my-module.css'''
#myModuleBtn { font-size:10pt; }

@@ Zeile 25: / Zeile 25: @@
 == Module Template ==
-To make it easy, there is a hook template. Please have a look on <code>js/pong-modules/module-template.js</code>.
+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>js/portal-ng-modules.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 ==
@@ Zeile 143: / Zeile 143: @@
 == Module Example ==
-=== js/portal-ng-modules.js ===
+=== 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 <code>moduleMap</code> map. You only need to specify the base name here. PoNG will add the subpath and .js for you.
@@ Zeile 156: / Zeile 156: @@
   ...
-=== js/pong-modules/my-module.js ===
+=== modules/my-module/my-module.js ===
 Implement you module script:
 <pre>
@@ Zeile 201: / Zeile 201: @@
 === 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>css/pong-modules/</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.css'''
+Example: '''modules/my-module/my-module'''
   #myModuleBtn { font-size:10pt; }

@@ Zeile 2: / Zeile 2: @@
 [[Category:PoNG]]
 == Basic Module Concept ==
-Modules are defined in the file <code>js/portal-ng-modules.js</code>. The modules are ".js" files in the subdirectory <code>js/pong-modules</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>js/portal-ng-modules.js</code> you have to do two things:
+In the <code>modules/portal-ng-modules.js</code> you have to do two things:
 '''1. Define the module itself''' by adding a line
   moduleMap[ "modulename" ] = {  ... };
-PoNG will include the file <code>js/pong-modules/modulename.js</code>.
+PoNG will include the file <code>modules/<modulename>/<modulename>.js</code>.
-PoNG also loads style definitions from the <code>css/pong-modules/modulename.css</code> file.
+PoNG also loads style definitions from the <code>modules/<modulename>/<modulename>.css</code> file.
 Modules coming with PoNG will have the naming convention <code>pong-<modulename></code> and give you some common core functionality.

@@ Zeile 7: / Zeile 7: @@
 '''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
-  moduleHooks.push( { "hook": "<hookname>", "type": "<module name>", "method":"<hook function name>" } );
+  moduleMap[ "modulename" ] = {
 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 <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.
@@ Zeile 34: / Zeile 42: @@
 * 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.
@@ Zeile 44: / Zeile 52: @@
 * pram (optional parameter object)
-=== addActionBtn ===
+=== addActionBtn Hook  ===
 [[PoNG Structure Specification|Structure definition]]: in rows or cols you can define property-array
 * <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.
 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.
@@ Zeile 61: / Zeile 69: @@
 * resourceURL
 * 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.
+  {
@@ Zeile 70: / Zeile 78: @@
           "rowId": "yxz",
           "resourceURL": "resX",
           '''"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)
 * resourceURL
 * Return value: none
-== Example ==
+'''Example'''
 === js/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 <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",
   ...