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.

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)

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.

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

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

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

This are the available configuration options:

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 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:

The following table shows the available operators:

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 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 specifies the space between the grid cell at the top and the top of the body. This item is optional.

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

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.

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 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 (: 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 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.

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.

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. : 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.

These are the latest changes:

• Renamed 'css/pageid.less' to 'css/pageid.css'. Fixes #2.
• Added option 'toc-columns' to specify the number of columns in the toc
• Changed layout of config page in default layout.
• Added search bar to default layout.
• Fixed to wide search results form by setting 'box-sizing' to 'border-…
• Corrected and changed search form:
• Fixed warnings by inserting 'is_array(...)' checks.
• Fixed faulty defines.

For a complete change log, see the commits on Github.

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.

Feel free to add yours here:

• None so far. I use this template for my own local and closed DokuWiki.