DokuWiki

It's better when it's simple

User Tools

Site Tools


template:congrid

congrid Template

Compatible with DokuWiki

  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" unknown
  • 2016-06-26 "Elenor Of Tsort" unknown
  • 2015-08-10 "Detritus" unknown

template A configurable grid layout

Last updated on
2018-10-14
Repository
Source

Tagged with experimental

About

The congrid template is a configurable grid based template.

The idea behind the template is to be able to quickly change the overall layout of the page and to be able to use different layouts in different situations. The template enables the administrator to configure different layouts per selector. A selector decides when to use a certain layout. The most simple is * which just means “use this layout if there is no better match”. Other selectors match the current action or parts of the current request (e.g. id or page).

So this template is more a construction kit for templates. Because of this and because development of the template is not finished, I only recommend it to people who love experimenting and who are not planning to use it an an productional environment.

Features

This is a short overview of the features of this template:

  • switch layout depending on the current situation
  • JSON based layout configuration
  • the grid is described by a table/JSON array
  • grid cells have a name, cells with the same name are joined to become a single bigger cell
  • the ratio of the cells specify the size that a cell's content gets
  • grid cells are represented by well-known type names which specify which content shall be displayed (e.g. “content” for the wiki page content or “title” for the title section)
  • pages or well-known types can be grouped into one cell
  • pre-installed optional backgrounds based on CSS gradients
  • optional scroll-areas which cause page scrolling if the mouse pointer is hovered over them
  • option to render the toc inside the wiki page or outside in an extra grid cell
  • different themes (planned)

Status

For now I consider this template as :!: experimental :!: for the following reasons:

  • not heavily tested, especially not on different browsers
  • not tested on mobiles
  • CSS grid layouts are quite new and seldomly used (see https://www.w3schools.com/css/css_grid.asp for general information about CSS grid layouts)
  • still under construction

:!: The bottom line is: this template is under construction and subject to changes which might not be backwards compatible to earlier versions. :!:

Installation

Refer to template on how to install and use templates in DokuWiki.

Customization

The template can be customized using the “Template Style Settings” and by the template's configuration.

Template Style Settings

The Template Style Settings are mostly self explanatory. See a short overview below:

Option name Function
Main text color Sets the main text color
Main background color Sets the background color
Alternative text color Sets the alternative text color
Alternative background color Sets the alternative background color
Neutral text color Sets the neutral text color
Neutral background color Sets the neutral background color
Border color Sets the border color
Highlight color (for search results mainly) Sets the highlight color
The general link color Sets the link color
Text color for template error messages Sets the color of template error messages (actually only used in case of unknown cell type names)
Color for the very background (behind the content box) Sets the color of the background (HTML body)
The color for links to existing pages Sets the color of links to existing wiki pages
The color for links to non-existing pages Sets the color of links to non-existing wiki pages
The width of the full site (can be any length unit: %, px, em, …) Sets the site's width
The width of the sidebar, if any (can be any length unit: %, px, em, …) deprecated (will soon be removed)
Below screensizes of this width, the site switches to tablet mode untested
Below screensizes of this width, the site switches to phone mode untested
Theme color of the web app untested
Height of the logo Sets the height of the logo
Width of the logo Sets the width of the logo
Font size of the title Sets the font size of the title
Text color of the title Sets the text color of the title
Background color of the title Sets the background color of the title
Font for the title Sets the font of the title
Text color of the trace section Sets the text color of the trace section
Background color of the trace section Sets the background color of the trace section
Text color of the you-are-here section Sets the text color of the you-are-here section
Background color of the you-are-here section Sets the background color of the you-are-here section
Left and right margin for code sections Sets a margin on the left and right side of code sections
Definition of “user” border Defines the user border

Configuration

This are the available configuration options:

Option name Function
Theme The theme the template is using. Actually there is only one: White.
Layouts JSON encoded description of the grid parameters.
BreadcrumbsSep Separator for breadcrumbs.
YouAreHereSep Separator for you-are-here.

The Layouts settings describes the grid layout and is JSON encoded. If the JSON parsing of Layouts fails, then the templates falls back to a default layout. This is stored in the file tpl_default.php. As the JSON encoding can easily be broken e.g. by a missing comma I suggest to use one of the several online JSON decoders to validate the Layouts settings.

As a start let's have a look at a shortend Layouts object which is showing the global parameters:

{
    "layouts":
    [
        /* Start of a single layout definition... */
        {
            "select": [ "*" ],
            "background":"cicada-stripes",
            "top":"5vh",
            "height":"90vh",
            "grid-vert-space":"20",
            "toc":"on-page",
            "grid":
            [
                /* ... encoding of grid array ... */
            ],
            "cells":
            [
                /* ... encoding of cells array ... */
            ]
        }
        /* ...end of the definition. */
    ]
}

The outer part of the JSON object consists of the array Layouts which can contain multiple layout definitions. One array element represents one layout. The comments show the start and end of the layout. Each layout array element is an object who's items control the layout content.

The "select" item

The select item specifies in which situation a layout shall be used. It is an array of strings. Each string is a whitespace separated list of conditions. The conditions grouped together in one string must all be true to match (logical and). The strings grouped together in the select array represent a choice, so if at least one of them matches, the layout might get selected (logical or). In this case, with only one layout, it would be selected. In cases with more than one matching layout/select item, the template will select the layout with the most specific matching select item. That e.g. means that a select item with two conditions wins over an item with only one condition.

Each condition consists of a variable name, followed by an operator, followed by a value to compare with. One exception is the * used in the example above. It matches allways but is least specific. So a matching select item which consists of a condition using a variable comparison will always win over the match-all select item. This way the * can be used to specify the default layout.

The following table shows the variable names which can be used in the select item:

Variable name Function
do Comparison with the do parameter contained in the actual request URL.
ID Comparison with the actual page ID.
page Comparison with the page parameter contained in the actual request URL.
ACT Comparison with the actual action.

The following table shows the available operators:

Operator Meaning
== The value specified must match the actual value of the variable.
!= The value specified must not match the actual value of the variable.

Value is simply a freely chosen string. Let's have a look at some examples:

"select": [ "*" ]

This will always match.

"select":["page==config"]

This select matches if page is set to “config”. That means a layout with this select item would be used during configuration.

"select":["do==edit", "ACT==preview"]

This select matches if do is set to “edit” or if ACT is set to “preview”. That means a layout with this select item would be used in edit or preview mode.

The "background" item

The background item can be used to give the background behind the page content (the HTML body element) a predefined look. The following pre-defined backgrounds are available:

  • weave
  • upholstery
  • bricks
  • diagonal-stripes
  • tablecloth
  • waves
  • lined-paper
  • blueprint-grid
  • cicada-stripes
  • honey-comb
  • cross-dots
  • cross
  • tartan
  • japanese-cube

Unknown values will be ignored. This backgrounds can also be used for the different cells. But this will be described later. This item is optional.

The "top" item

The top item specifies the space between the grid cell at the top and the top of the body. This item is optional.

The "height" item

The height item specifies the height of the grid in total. This item is optional.

The "grid-vert-space" item

The grid-vert-space item specifies how much space shall be between the grid rows in total in percent. If e.g. grid-vert-space is set to 10 and the layout has 5 rows, then the space between the 5 rows will make up 10% of the space available for the grid. If grid-vert-space is omitted, then there will be no space between the grid rows. This item is optional.

The "toc" item

If the toc item is set to “on-page” then the table of contents will be rendered on/inside the content area. If the toc item is set to “off-page” (or any other value except “on-page”) then the table of contents will not be rendered. In this case the table of contents will be missing if not an extra cell is defined for it in the cells section. This will be described later. This item is optional.

The "grid" item

The grid item consists of a table. Each row in the table is represented by an array which includes strings. The strings represent cell names. This can be names which are well-known (hard-codec/implemented in the template) or user defined containers. If the template parses a cell name, it will then put/render the corresponding content into that cell at that position of the grid. Cells which have the same name as cells around them, will be joined into one big cell. This means they simply span multiple columns or rows. A cells size can not be explicitly specified. The cell size is determined by the ratio of the cell compared to the total columns or rows. E.g. if a cell spans two columns and the grid table has 10 columns in total, then the cells width will be 20% of the overall space of the grid (minus the space between the cells, if any).

Let's have a look at an example:

{
    "layouts":
    [
        /* Start of a single layout definition... */
        {
            /* Other items... */
            "grid":
            [
                [ "title",      "title",      "title",       "content", "content", "content", "content", "content", "content", "space"            ],
                [ "title",      "title",      "title",       "content", "content", "content", "content", "content", "content", "space"            ],
                [ "breadcrumbs","breadcrumbs","breadcrumbs", "content", "content", "content", "content", "content", "content", "scroll-up-area"   ],
                [ "breadcrumbs","breadcrumbs","breadcrumbs", "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "scroll-down-area" ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "footer",     "footer",     "footer",      "footer",  "footer",  "footer",  "footer",  "footer",  "footer",  "space"            ]
            ],
            "cells":
            [
                /* ... encoding of cells array ... */
            ]
        }
        /* ...end of the definition. */
    ]
}

As described before, we have a table describing or grid's content by using well-known names or user defined container names. Well-known names have a fixed meaning. Actually, the following names are defined and implemented in the congrid template:

Name Meaning
content The cell will contain the content or the wiki page/the wiki article. This also incudes the page ID at the top and the document information at the bottom.
empty The cell will be empty. This means it will be hidden and the background is visible.
footer The cell will contain the footer.
pagetools The cell will contain the pagetools.
scroll-down-area The cell will contain an arrow pointing down. If the user hovers over the cell with the mouse pointer, then the wiki article will scroll downwards.
scroll-up-area The cell will contain an arrow pointing up. If the user hovers over the cell with the mouse pointer, then the wiki article will scroll upwards.
search The cell will contain the search bar.
sitetools The cell will contain the sitetools.
space The same as empty (FIXME: cleanup required)
tagline The cell will contain the tagline.
title The cell will contain the wiki title.
toc The cell will contain the table of contents. This is useful in conjunction with the option “toc”:“off-page”
trace The cell will contain the breadcrumbs trace.
usertools The cell will contain the usertools.
youarehere The cell will contain the you-are-here section.

If a cell name is not listed in the table above, then it is considered to be a container. A container can group multiple well-known items in one cell or it can be used to render one or more wiki pages into a cell. The later can be used to render the sidebar. The contents and look of a cell are defined in the cells section. If a cell contains a well-known item, then it is not required to define the content. If the cell contains a container, then the cells section must include a definition with the same name. Otherwise the reference in the grid is invalid and an error message will be displayed in that cell.

The "cells" item

The following code section again shows the grid example from above but this time with the corresponding cells section:

{
    "layouts":
    [
        /* Start of a single layout definition... */
        {
            /* Other items... */
            "grid":
            [
                [ "title",      "title",      "title",       "content", "content", "content", "content", "content", "content", "space"            ],
                [ "title",      "title",      "title",       "content", "content", "content", "content", "content", "content", "space"            ],
                [ "breadcrumbs","breadcrumbs","breadcrumbs", "content", "content", "content", "content", "content", "content", "scroll-up-area"   ],
                [ "breadcrumbs","breadcrumbs","breadcrumbs", "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "pagetools"        ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "scroll-down-area" ],
                [ "cont-side",  "cont-side",  "cont-side",   "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "cont-tools", "cont-tools", "cont-tools",  "content", "content", "content", "content", "content", "content", "space"            ],
                [ "footer",     "footer",     "footer",      "footer",  "footer",  "footer",  "footer",  "footer",  "footer",  "space"            ]
            ],
            "cells":
            [
                {
                    "id":"default",
                    "css":
                    {
                        "border":"5px outset black"
                    }
                },
                {
                    "id":"pagetools",
                    "list-type":"no-text",
                    "css":
                    {
                        "border":"5px outset black",
                        "opacity":"0.5"
                    }
                },
                {
                    "id":"cont-side",
                    "flex":
                    {
                        "direction":"column"
                    },
                    "pages": ["sidebar"],
                    "css":
                    {
                        "border":"5px outset black",
                        "opacity":"0.75"
                    }
                },
                {
                    "id":"cont-tools",
                    "flex":
                    {
                        "direction":"column"
                    },
                    "items": ["usertools", "sitetools"],
                    "css":
                    {
                        "border":"5px outset black",
                        "opacity":"0.75"
                    }
                },
                {
                    "id":"breadcrumbs",
                    "flex":
                    {
                        "direction":"column"
                    },
                    "css":
                    {
                        "border":"5px outset black",
                        "padding":"0",
                        "margin":"0",
                        "opacity":"0.75"
                    },
                    "items": ["trace", "youarehere"]
                },
                {
                    "id":"trace",
                    "css":
                    {
                        "height":"100%"
                    }
                },
                {
                    "id":"youarehere",
                    "css":
                    {
                        "height":"100%"
                    }
                },
                {
                    "id":"scroll-up-area",
                    "css":
                    {
                        "margin":"auto auto 10px auto",
                        "opacity":"0.5",
                        "height":"64px",
                        "width":"64px"
                    }
                },
                {
                    "id":"scroll-down-area",
                    "css":
                    {
                        "margin":"10px auto auto auto",
                        "opacity":"0.5",
                        "height":"64px",
                        "width":"64px"
                    }
                },
                {
                    "id":"sitetools"
                },
                {
                    "id":"usertools"
                },
                {
                    "id":"title",
                    "css":
                    {
                        "border":"5px outset black",
                        "background-color":"MediumSeaGreen",
                        "color":"white",
                        "text-shadow":"-1px -1px 0 #000, 1px -1px 0 #000, -1px 1px 0 #000, 1px 1px 0 #000",
                        "opacity":"0.85"
                    }
                },
                {
                    "id":"footer",
                    "flex":
                    {
                        "direction":"column"
                    },
                    "css":
                    {
                        "border":"5px outset black",
                        "margin":"auto 0",
                        "font-size":"0.75em",
                        "padding":"0.5em 2em",
                        "text-align":"center",
                        "opacity":"0.75"
                    }
                }
            ]
        }
        /* ...end of the definition. */
    ]
}

The cells item is an array of objects. Each object describes one cell. A cell must have an id. The id is the name of the cell which can be referenced in the grid. The id/name can be of 3 different kinds:

  • default: any cell which id is not found in the cells section will use the definition of the default cell.
  • well-known name: the cell entry describes the layout of the cell. The content is defined by it's name.
  • container: the cell entry describes the layout and content of the cell.
container cells

As described before, container cells need to define which content shall be rendered. Therefore they need to include an item with the name items or pages. Let's have a look at two examples from above:

    "items": ["usertools", "sitetools"],

This means the cell shall contain the well-known items usertools and sitetools.

    "pages": ["sidebar"],

This means the cell shall contain the page/article sidebar.

cell items

Apart from the id, items and pages items there can be some more items included in a cell definition. This is the complete list describing their name and usage:

  • css:
    The css item defines an object containing CSS properties. Each property is defined by it's name and the corresponding value. The item is optional.
  • flex:
    The flex item can be used to give a cell a flex-row (value row) or flex-column (value column) layout. Both are placeholders for a group of CSS properties. The properties for a flex-row are:
    div.flex-row {
        display: flex;
        flex-direction: row;
        justify-content: center;
        align-items: center;
    }

    The properties for a flex-column are:

    div.flex-column {
        padding: 0;
        margin: 0;
        display: flex;
        flex-direction: column;
    }

    The item is optional.

  • list-type:
    The item can be useful for use with the pagetools cell. A value of no-text will prevent text from being shown in that cell. A value of no-icons will prevent images from being shown in the cell. The item is optional.
  • border:
    The item can be used to assign a pre-defined border style. Actually only semi-transparent is available (also see the credits section). The item is optional.
  • corners:
    If set to round then a 25px border radius will be applied to the cell. The item is optional. FIXME: this is just a shorthand for a single CSS property. So it might better be removed.
  • background:
    As for the body, background can also be used for cells to assign a pre-defined background. See The "background" item for defined values. The item is optional.
  • toc-columns:
    Specifies the number of columns for the table of contents. It only has an effect if the table of contents is placed in an extra grid cell.

Development

Latest changes

Credits

This template is partly based on the work of others. I thank the following people for their work:

  • Authors of the DokuWiki template
    This template heavily re-uses code of the standard template. Thanks for the huge effort spent in developing and testing it.
  • Lea Verou: The CSS code for semi-transparent borders are taken from her book “CSS SECRETS”. Thanks for the inspiration and detailed solutions described in the book.
  • Lea Verou and other authors: Thanks for sharing some beatiful and compact backgrounds on http://lea.verou.me/css3patterns/. The pre-defined backgrounds use their work.

Sites using this Template

Feel free to add yours here:

  • None so far. I use this template for my own local and closed DokuWiki.
template/congrid.txt · Last modified: 2018-10-21 19:22 by LarsDW223