wiki:docs_layout

layout notes

example layout

{
    "moduleid"    : "energy"
    ,"label"      : "Energy"
    ,"help"       : "help for Energy"
    ,"executable" : "energy.py"
    ,"panels"     : [
      {
        "root" : {
            "size"     : [ rows, columns ]  (optional - defaults to [ "auto", "auto" ] )
                          where rows can be
                             numeric specifying the number of rows
                             an array of relative widths, eg. [ 1, 1, 1 ] for 3 rows of equal width
                             "auto" (default) to automatically grow as needed
                          where columns can be
                             numeric specifying the number of columns
                             an array of relative widths, eg. [ 1, 1, 1 ] for 3 columns of equal width
                             "auto" (default) to automatically grow as needed
            ,"align"  : "right" # optionally specify alignment ("left" or "right" or "center"; default "left" )
            ,"gap"    : "5px" # optionally specify a gap between grid boxes, default "10px"
            # label & data are relative to the location of the field
            ,"label"    : [ row, column ] (optional - defaults to [ 1, 1 ] )
                          where row can
                             numeric for an absolute row
                             a range, e.g. [ start-row, end-row ]
                          where column can be
                             numeric for an absolute column
                             a range, e.g. [ start-column, end-column ]
            ,"data"     : [ row, column ] (optional - defaults to [ 1, 2 ] )
                          where row can
                             numeric for an absolute row
                             a range, e.g. [ start-row, end-row ]
                          where column can be
                             numeric for an absolute column
                             a range, e.g. [ start-column, end-column ]
            ,"repeats" : {
                    "size"     : [ rows, columns ] (optional  - defaults to [ "auto", [ 1, 1 ] ) defines the grid of the new repeater panel
                    ,"location" : [ rows, columns ] (optional - defaults to [ "next", "full" ] ) defines location for the repeater in the panel
            }
        }
      }
      ,{ 
        ,"subpanel1" : {
            "parent"    : "root" (default if not included)
            ,"size"     : [ rows, columns ] (optional - defaults to [ "auto", "auto" ] )
            ,"location" : [ row, column ]   (optional - defaults to [ "next", "next" ] )
                          where row can be
                             numeric for an absolute row
                             a range, e.g. [ start-row, end-row ]
                             "full" for the full row
                             "next" (default if not specified) to automatically increment from previously used position
                             "same" to not automatically increment the row
                          where column can be
                             numeric for an absolute column
                             a range, e.g. [ start-column, end-column ]
                             "full" for the full column
                             "next" (default if not specified) to automatically increment from previously used position 
            ,"label"    : [ row, column ]   (optional - inherits)
            ,"data"     : [ row, column ]   (optional - inherits)
            ,"align"    : "right"           (optional - inherits)
            ,"gap"      : "10px"            (optional - inherits) 
            ,"repeats"  : {                 (optional - inherits) 
                    "size"     : [ rows, columns ] (optional  - defaults to size of panel ) defines the grid of the new repeater panel
                    ,"location" : [ rows, columns ] (optional - defaults to [2, 1/-1 ] ) defines location for the repeater in the panel
            }
        }
      }
      ,{ 
        ,"subpanel2" : {
            "parent"  : "subpanel1"
            ,"size"     : [ rows, columns ] (optional - defaults to [ "auto", "auto" ] )
            ,"location" : [ row, column ]   (optional - defaults to [ "next", "next" ] )
            ,"label"    : [ row, column ]   (optional - inherits)
            ,"data"     : [ row, column ]   (optional - inherits)
            ,"align"    : "right"           (optional - inherits)
            ,"gap"      : "10px"            (optional - inherits) 
            ,"repeats"  : {}                (optional - inherits) 
        }
      }
    ]
    ,"fields"   : [
        {
            "role"       : "input"
            ,"id"        : "module_header"
            ,"label"     : "Energy Example"
            ,"type"      : "label"
            ,"default"   : "header4"
            ,"prehline"  : "true"
            ,"posthline" : "true"
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits)
                ,"data"     : [ row, column ] (optional - inherits) 
                ,"align"    : "right"         (optional - inherits)
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
        ,{
            "role"        : "input"
            ,"id"         : "m"
            ,"label"      : "mass [kg]"
            ,"type"       : "float"
            ,"required"   : "true"
            ,"help"       : "Enter the mass in kilograms"
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits )
                ,"data"     : [ row, column ] (optional - inherits ) 
                ,"align"    : "right"         (optional - inherits )
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
        ,{
            "role"        : "input"
            ,"id"         : "c"
            ,"label"      : "Speed of light [m/s]"
            ,"type"       : "float"
            ,"default"    : 299792458
            ,"required"   : "true"
            ,"help"       : "Enter the speed of light in meters/second"
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits )
                ,"data"     : [ row, column ] (optional - inherits ) 
                ,"align"    : "right"         (optional - inherits )
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
        ,{ (optional manual placement of submit button)
            "role"        : "input"
            ,"id"         : "b_submit"         (n.b. must be exact match)
            ,"type"       : "button"
            ,"label"      : "Optional label"  (optional)
            ,"buttontext" : "Submit"          (optional - defaults to 'Submit' )
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits )  
                ,"data"     : [ row, column ] (optional - inherits )
                ,"align"    : "right"         (optional - inherits )
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
        ,{ (optional manual placement of reset button)
            "role"        : "input"
            ,"id"         : "b_reset"         (n.b. must be exact match)
            ,"type"       : "button"
            ,"label"      : "Optional label"  (optional)
            ,"buttontext" : "Reset to default values"          (optional - defaults to 'Reset to default values' )
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits )  
                ,"data"     : [ row, column ] (optional - inherits )
                ,"align"    : "right"         (optional - inherits )
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
        ,{
            "role"        : "output"
            ,"id"         : "e"
            ,"label"      : "Energy [J]"
            ,"type"       : "text"
            ,"layout"    : {                  (optional - defaults to layout:parent:root)
                "parent"    : "root" or a defined panel e.g. "subpanel1" or not included for "root"
                ,"location" : [ row, column ] (optional - defaults to [ "next", "next" ] )
                ,"label"    : [ row, column ] (optional - inherits )
                ,"data"     : [ row, column ] (optional - inherits ) 
                ,"align"    : "right"         (optional - inherits )
                ,"repeats"  : {}              (optional - inherits - only used for repeater fields) 
            }
        }
    ]
}

specification notes

  • panels defines structure at top level
  • layout defines structure at field level
  • properties are inherited
    • any pattern that gets repeated in layout should be supported in panel

program notes

program type description
genapp/etc/perl/ga_layout.pm compile-side builds panels/layout, available in layout
genapp/languages/html5/js/layout.js browser-side creates html
genapp/bin/ga_layout.pl cli test layout build from module file

plan forward

  • as-is each field builds its table position "statically" as entries are processed
    • repeat.js strips this info for repeaters
    • probably cleaner to build essential field info and push layout control to browser
      • convert .input's & .output's to TBD, e.g. js:ga.module.label js:ga.module.data & ga.module.eval & ga.module.display()
      • rewrite repeat.js to directly use this data
      • id info in a "replaceable" format ? (e.g. as needed by repeat.js)
  • code to build layout from module json so we can test
    • perl process module file and extract layout info, build layout data structures
    • node js: layout->html mockup
    • leverage grid.js & qr.js (possibly also repeat.js)

old format

            "columns" : c or "auto" or not included for "auto" or array of relative widths (eg. [ 1, 1, 1 ] for 3 columns of equal width)
            ,"rows"   : r or "auto" or not included for "auto" or array of relative widths (eg. [ 1, 1, 1 ] for 3 rows of equal width)
            ,"row"     : row-in-parent or [ row start, row-end for a span ] or "full" or "next" (default if unspecified) to automatically increment from what what previously used or "same" to not automatically increment cursor row on eol
            ,"column"  : column-in-parent or [ col start, col-end for a span ] or "full" or "next" (default if unspecified) to automatically increment from what what previously used

use cases

  • multicolumn like in earlier sgci templates
  • use cases from Joseph / Susan
    • met with Joseph, he indicated we had sufficient info
  • general grouping (e.g molecular viewer with associated informative output fields)
    • future buttons with executable callbacks
  • repeaters of various types & nested
  • possible use of flexbox h & v internally
  • staging
  • modal dialogs -> panel

no longer relevant?

  • possible expose "horizontallayout" "verticallayout"

bootstrap sass

  • e.g. npx node-sass -w scss/customs.scss -o html5/css

Work in progress

process notes

  • processed layout to file
    1. genapp -kl to write processed extracted layout in output/language/layout/module.json
  • process module json directly to layout
    1. ga_layout.pl modules/module.json > moduleprocessed.json to process layout directly from module json, bypassing genapp for testing
    2. node genapp/tmp/layout/layout2html.js moduleprocessed.json > module.html to produce html without field info
  • process generated module html to layout'd html
  1. genapp
  2. node genapp/tmp/layout/layouttest.js output/html5/ajax/menu/module.html > module.html extract ga.layout matching lines from html to produce layout
  • substitutions:
    • __panels__ contains unprocessed module:panels
    • and
    • __layout__ contains fully processed module:panels and module:fields

done

  • genapp run generates extracted layout in output/language/layout/
  • -> converted back to [] for panels
    • lessens user panel text requirements
  • perl to convert extracted layout into "fully populated"
    • [done - to test] panels processed into final format
      • -> next: js to take processed panels into html for visualization
        • [done] for panels
        • [done] for fields
      • [done] all inherited attributes locally id'd
      • [done] parent panel id'd
    • [done] position in panel for label & data given explicit values
    • maybe: id's replaced by easy substitutes for repeat.js (%%id%%) (see repeat.js)
  • [done] js to take fully populated layout into html
  • [done] merge ga_layout.pl into genapp_util.pl
    • [done] also leave as command line for testing

todo

  • take a subset of field types and modify for new layout control
    • types/ type.input, type.output, input.header, input.footer, output.header, output.footer
    • integration notes
  • layout2html.js -> grid.js or layout.js
  • figure out repeaters
    • subgrid?
    • layout controls?
  • provide separate align for label and data
    • inherted
  • how about complex fields like images, jsmol or plotting ?
  • other decorations
    • prehline
    • posthline
    • norow
    • others?
  • classes for types

meeting notes

  • background colors etc for each panel
  • small arrows on number of genapp theme
    • appears native, nicer in chrome & safari vs firefox
  • bootstrap themes to select
    • as long as bootstrap 4
  • live switch of themes
    • punt
      • load style sheets based upon settings
      • css variables (bootstrap defines, likely not using them)
        • possibly used for color theme switching (lightweight version)
  • control of non-module area
    Hi Emre,
    
    Here are the CSS class names to add:
    
        On the input field <input/> elements, add “ga-field-input-control”. For output fields add “ga-field-output-control”.
        On the submit button add “ga-button-submit”. For the reset button add “ga-button-reset”.
        For fields that are type=label, add “ga-field-input-header{1,2,3,4}” to the <label/> element.
        On the root panel add “ga-module”
    
    I updated the html and ga-bootstrap.scss to reflect these tmp/layout/modules_for_paper/genapp-theme: https://github.com/ehb54/genapp/commit/55bb5dde3f1365d682f9b40b5746f2603bf229a9
     
    Thanks,
    Marcus
    
  • bootswatch
    I’m not sure if I actually tried this, but with Bootswatch the imports are:
    
    @import "./node_modules/bootswatch/dist/[theme]/variables";
    @import "./node_modules/bootstrap/scss/bootstrap";
    @import "./node_modules/bootswatch/dist/[theme]/bootswatch";
    
    Bootswatch is actually a set of themes, so you would replace [theme] with the Bootswatch theme name, see https://bootswatch.com/ for a list of the themes.
    default
    cerulean
    cosmo
    cyborg
    darkly
    flatly
    journal
    litera
    lumen
    lux
    materia
    minty
    pulse
    sandstone
    simplex
    sketchy
    slate
    solar
    spacelab
    superhero
    united
    yeti
    
    

work

  • emre - more to do for layout
    • more work to make layout through to genapp generated modules
  • Marcus - integrate this "scss" mech. into genapp generation
    • list of classes for field types
      • div class for whole field
      • spec out the classes (possibly in gw submission paper)
  • goal - by gateways - use layout & themes

Last modified 4 months ago Last modified on Jun 5, 2020, 9:34:18 AM