PoNG Structure Specification

Aus MH
Version vom 17. Februar 2015, 18:34 Uhr von Mh (Diskussion | Beiträge)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
Wechseln zu: Navigation, Suche

Defining the "structure" replaces the writing of HTML code to set up a page of different information resources.

The PoNG "structure" is a JSON result, which comes from the server, e.g. as GET response for URL .../svc/layout/main/structure. The loading and processing of the structure defines the rendering lifecyle of the page in the browser. After that the user can interact with the page.

By default, index.html will load the structure of layout/main. There is a simple "layout" control feature available. If you utilize the GET parameter "layout" the value (in this Exampe XYZ) will be used to determine the layout definition, so if you load:

  • http://mysite.xyz/basedir/index.html?layout=XYZ

the structure JSON is get from

  • http://mysite.xyz/basedir/svc/layout/XYZ/structure

JSON basics

Even if you are new to JSON, it is very easy to understand: It is a structured key/value text data format, so you can use any text editor to define the "structure". Some JSON hints:

  • Key/value pattern: "key": <value> where values can be of type string, object or array, see below
  • Strings
    • "stringName": "This is the value of stringName"
  • Objects with inner fields use { } braces
    • "objectName": { "field1": "value of field one", "field2": "value2", "embeddedObject": { ... } }
  • Arrays of objects are defined using [ ] braces
    • "arrayName": [ {...}, {...} ]
  • Optional fields: simply delete the key (and the value) from the JSON structure.

Resource References

As far as I know, there is no standard for referencing resources within JSON data, as we have in HTML (href).

Conventions to use in PoNG:

  • Resource references should have the field name resourceURL
    • references should be URLs (PoNG base URL in the examples may be http://mserver.xyz/basepath/). References can be one of these tree types:
      • relative URL without trailing "/", e.g. "resourceURL": "svc/myResource" are relative to the indec.html of PoNG, so it reference to http://mserver.xyz/basepath/svc/myResource
      • URL with trailing "/", e.g. "resourceURL": "/otherResource" reference to http://mserver.xyz/otherResource
      • Full qualified URL , e.g. "resourceURL": "http://otherserver.xyz/any-path/externalResource"
  • Other references names, e.g. images or files, should end with URL,c e.g.: "logoURL"

Layout Rules

The "layout" should be a simple explanation of the portal and its views.

I.e., the "layout" should have

  • no content
  • no graphic design and no CSS related things
  • no details of the views
    • just the main resource definition and its type
    • top level actions and
    • top level dialog definitions

Notice: Please add "description" elements to all the objects in the layout. This enables a barrier free view of PoNG in the future. Actual these fields are optional, but please be prepared, that you get a "non barrier free" label on your portal page later on, if these fields are missing.

Hierarchy

Root element is layout. The root element has the fields:

  • title (String: definition of page title)
  • description (text, may be tool tip, but not be displayed)
  • header (Object for header definition)
  • rows (Array of main content row definitions)
  • footer (Object for footer definition)

Structure: layout root element (JSON format)

{
 "layout": {
   "title": "My Page",
   "header": {
       ...
   },
   "rows": {
       ...
   },
   "footer": {
       ...
   }
}

Header

Header structure:

  • logoURL (optional): String
    • alternatively to logoURL you can use logoText
  • description (text, may be tool tip, but not be displayed)
  • linkList (optional): Array of objects
    • text : String
    • url : String
  • modules (optional) Array of objects
    • id (String)
    • type (String)
    • param (Object)
      • any JSON structure of parameters for the hook

JSON Example Header Structure

{
 "layout": {
    ...
    "header": {
      "logoURL": "logo.png",
      "description": "You can use the login button to authenticate and access restricted resource views.",
      "linkList": [
      	{ "text":"Help", "url": "help.html"},
      	{ "text":"Login", "url": "login.html"}
      ],
      "modules" : [ { "id": "myHeaderDiv", "type": "my-header", "param": { "config":"1234" } }, ... ] 
    },
    ...
}

Main

The main DIV consists of a "row" array: 

{
 "layout": {
   "title": "PoNG Demo",
   "header": { ... }
   "rows": [ { ... }, { ... }, ... ],
   "footer": { ... }
}

Each element of the rows can be either a "resource" or otherwise a cols array of columns.

Each element of the cols can be either a "resource" or otherwise a rows array.

This recursion enables to set up any possible arrangement of information on your web page. 

{
 "layout": {
   "title": "PoNG Demo",
   "header": { ... }
   "rows": [ { "resourceURL": "xyz/", ... }, { "cols": [ { ... }, { ... }, ... ] }, ... ],
   "footer": { ... }
}


The properties of a "rows" element are:

  • rowId is the unique ID of the row (which is a DIV)
  • height is height of the row, the with is 100%

The properties of a "cols" element are:

  • colId is the unique ID of the columns (which is a DIV)
  • width is width of the row
  • height is optional the height of the column, the height can also be defined by the containing row heights

Resources

Resources are columns or rows with a defined resourceURL property. Resources terminate the recursion of embedding cloumns in rows and rows in columns.

Resource Fields:

  • title (optional)
  • resourceURL
    • Defines the URL of the resource.
    • Important: depending on the resource, the ending "/" may be very important.
    • URLs can be relative or full specified
      • relative URL example: "resourceURL":"gnuplot/"
      • full specified URL example: "resourceURL":"http://mh-svr.de/mw/"
  • resourceParam
    • Defines the parameters used for this resource. Typically a plug-in module picks up the parameters. The resourceParam is a JSON object.
      • example : "resourceParam": { "page": "PoNG", "wikiRef":"/mw/index.php/", "wikiImg":"/mw/images/" }
    • If no module is used (no "type" is set), the parameters are used as GET parameters
  • description
    • Please describe the resource here. This description enables barrier free portals.
  • width
    • Width of the DIV
  • height
    • Height of the DIV
  • headerURL (optional)
    • Defines where to load content for a resource header section
  • footerURL (optional)
    • Defines where to load content for a resource footer section
  • decor
    • Defines the graphic layout of the resource, a good value is "decor". There are DIVs on all borders of the resource rendered and you can apply your layout there.
      • example: "decor": "decor"
  • actions
    • Array of action buttons. Actions are visible if you specify the decor option. Each array element is an object with the properties:
      • actionName Label and name of the action
      • type Name of the to the plug-in module to use for the action button hook
    • example: actions
      • "actions" : [ { "actionName": "Config", "type": "modal-form" }, { "actionName": "Help", "type": "pong-help" } ]
  • callback
    • After building up the HTML for the resource these JavaScript function is called.
      • example "callback": "startAnimation()"
  • modal
    • Array of modal dialog objects. The buttons to start the modal dialogs are visible if you specify the decor option. Modal dialogs are pop ups, which block any other interaction with the HTML page, until the dialog is closed. You can define an array of modal dialogs for each resource. The name of the modal dialog will be used in the URL to load it, e.g. for the resource with the resourceULD myResource and an embedded dialog with the name dialogXy, PoNG will load the modal dialog from http://www.mysite.com/svc/myResource/dialogXy/
    • Object properties:
      • modalName is the ID of the dialog
      • label will be displayed, or used as tooltip for the icon image
      • icon JQuery icon name
  • type
  • moduleConfig
    • By default the meta description of the resource is located at the resourceURL, here you can embed it. The PHP backend does ist ths way to make it configurable.

Example

This is a page with a header, one huge resource DIV and a footer. 

{
 "layout": {
   "title": "PoNG Demo",
   "header": { ... }
   "rows": [
      {
        "rowId": "wiki",
        "description": "Includes content of my wiki.", 
        "resourceURL": "http://mh-svr.de/mw/",
        "type": "pong-mediawiki"
        "resourceParam": { "page": "PoNG", "wikiRef":"/mw/index.php/", "wikiImg":"/mw/images/" },
        "actions" : [ { "actionName": "Search Page", "type": "modal-form" }, { "actionName": "Help", "type": "pong-help" } ],
        "height": "600px",
        "decor": "wiki-decor"
      }
   ],
   "footer": { ... }
}

Footer

Footer structure:

  • description (text, may be tool tip, but not be displayed)
  • linkList (optional): Array of objects
    • text : String
    • url : String
  • modules (optional) Array of objects
    • id (String)
    • type (String)
    • param (Object)
      • any JSON structure of parameters for the hook
  • copyrightText
    • (HTML) text
    • if empty, an empty copyright box will be generated
    • if not there, a default copyright boy will be gererated

JSON Example Footer Structure

{
 "layout": {
    ...
    ...
    "footer": {
      "description": "The footer has links to impress and contact form.",
      "linkList": [
      	{ "text":"Impress", "url": "impress.html"},
      	{ "text":"Contact form", "url": "contact.html"}
      ],
      "modules" : [ { "id": "myFooterDiv", "type": "my-footer", "param": { "confABC":"xy" } }, ... ] 
    }
}

Full JSON "structure" Example

{
 "layout": {
   "title": "Title",
   "description": "This page demonstrates some functions of PoNG.",
   "header": {
     "logoURL": "logo.png",
     "description": "You can access links to a dummy help page and a dummy login page here.",
     "linkList": [
     	{ "text":"Help", "pageURL": "help.html"},
     	{ "text":"Login", "pageURL": "login.html"}
     ]
   },
   "rows": [
     {
       "rowId": "stat",
       "description": "Just a demo of the PoNG list.",
       "height": "100px",
       "resourceURL": "resX",
       "type": "pong-form",
       "decor" : "decor",        
       "type": "pong-form",
       "modal" : [ { "modalName": "Anything", "icon": "ui-icon-home" }	],
       "actions" : [ { "actionName": "Config", "type": "modal-form" }, { "actionName": "MyDlg", "type": "modal-form" } ]
     },
     {
       "rowId": "r1",
       "height": "400px",
       "cols": [
         {
           "columnId": "control",
           "description": "Just a demo of the PoNG table.",
           "width": "40%",
           "resourceURL": "resX",
           "type": "pong-table",
           "decor" : "decor"
         },
         {
           "columnId": "plot",
           "description": "This is a plot of some sin() functions, but you can modify the plot with the config action button.",
           "width": "60%",
           "decor" : "decor",
           "resourceURL": "gnuplot",
           "callback": "grmh()",
           "actions" : [ { "actionName": "Config", "type": "modal-form" },{ "actionName": "fullWidth" }, { "actionName": "fullScreen" } ]
         }
       ]
     }
   ],
   "footer": {
     "copyrightText": "Copyright 2013, MH.",
     "description": "The footer has links to impress and contact form.",
     "linkList": [
     	{ "text":"Impressum", "pageURL": "impress.html"},
     	{ "text":"Privacy Note", "pageURL": "privacy.html"}
     ]	
   }
 }
}
Abgerufen von „https://mh-svr.de/mw/index.php?title=PoNG_Structure_Specification&oldid=169“