Skip to content

Structure Specification

Jump to bottom Edit New page
ma-ha edited this page Feb 13, 2016 · 3 revisions

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

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

Table of Contents

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:

  • Resource references should have the field name resourceURL
    • references should be URLs (base URL in the examples may be http://my-server.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, 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 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
    • optional: target : "_blank", "_parent", ...
  • modules (optional) Array of objects
    • id (String)
    • type (String)
      • defines the "header module" and hook to be loaded
    • param (Object)
      • any JSON structure of parameters for the hook
Available header module plug-ins:

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": "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": "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": "xyz", "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()"
  • type
    • Specify the view (plug-in module type) to use.
      • example: "type": "pong-table"
  • 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.

View Types (Plug-Ins)

You can use all view module plug ins specified in the modules library.

Example

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

 {
  "layout": {
    "title": "My Demo",
    "header": { ... }
    "rows": [
       {
         "rowId": "wiki",
         "description": "Includes content of my wiki.", 
         "resourceURL": "http://mh-svr.de/mw/",
         "type": "pong-mediawiki"
         "resourceParam": { "page": "WIKI", "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
    • optional: target : "_blank", "_parent", ...
  • 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":"About", "url": "about.html", "targer":"_blank" },
       	{ "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 functionality.",
    "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 a list.",
        "height": "100px",
        "resourceURL": "resX",
        "type": "pong-form",
        "decor" : "decor",        
        "type": "pong-form",
        "modal" : [ { "modalName": "Something", "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 a 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 2015, MH.",
      "description": "The footer has links to impress and contact form.",
      "linkList": [
      	{ "text":"Impressum", "pageURL": "impress.html"},
      	{ "text":"Privacy Note", "pageURL": "privacy.html"}
      ]	
    }
  }
 }
Add a custom footer
Add a custom sidebar
Clone this wiki locally