====== congrid Template ====== ---- template ---- description : A configurable grid layout author : LarsDW223 email : invalid@invalid.org lastupdate : 2018-10-14 compatible : Greebo depends : conflicts : similar : screenshot_img: https://github.com/LarsGit223/dokuwiki-template-congrid/raw/master/doc/CongridTemplateExample.png tags : experimental downloadurl : https://github.com/LarsGit223/dokuwiki-template-congrid/archive/master.zip bugtracker : https://github.com/LarsGit223/dokuwiki-template-congrid/issues sourcerepo : https://github.com/LarsGit223/dokuwiki-template-congrid ---- ===== About ===== The congrid template is a **con**figurable **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 [[template:congrid#the background item|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 ==== These are the latest changes: {{rss>https://github.com/LarsGit223/dokuwiki-template-congrid/commits/master.atom}} For a complete change log, see the [[https://github.com/LarsGit223/dokuwiki-template-congrid/commits/master|commits on Github]]. ===== 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.