WIKINDX gives the template designer greater control over the visual
design than did previous templates. It uses a combination of CSS and the
Smarty HTML Templating System (v5) – documentation on Smarty can be found at
https://smarty-php.github.io/smarty/stable/ but you will also find comments and help in the
various .tpl files in wikindx/components/templates/default/.
Certain files must be present for the template to be available to the user in WIKINDX > Preferences or WIKINDX > My Wikindx:
To create a template, a good starting point is to copy the
components/templates/default/ files to components/templates/xxxx/ where xxxx
is a unique folder name for your template.
Edit component.json and change its fields accordingly. After that go to
the components admin panel for refreshing the cached component list.
If the component appears correctly in the panel without error message you can start its customization.
The “images” folder must contain the images that you want to include
directly by a hardcoded link in a .tpl file. For example:
{$tplPath}/images/wikindx-logo.png, where {$tplPath} is the
resource location set by the browser to the root dir of the template.
The icons folder contains the images of icons (for buttons, for example)
whose name is predefined by the core. You can replace the images with
your own icon set, partial or complete - for example, to have a larger
size. If you do not provide an icon or even do not create the “icons”
folder, the default template icons will be used.
The image formats accepted in this folder are gif, jpg, jpeg, png, svg, webp.
Only the general HTML structure and the HTML structure of the main
recordable content (resources, musings …) can be modified. The other
pages inject their own code into the variables {$heading} and {$content}
in content.tpl and content_content.tpl.
Apart from tinymce, all the CSS rules for the project are contained in template.css which gives you great control over the presentation, even on HTML structures which are not in the templates.
Of course there are implicit rules or presentation choices that it is not possible to question or circumvent without modifying the core even if you are a CSS expert. This system was designed to give flexibility without allowing a design change free of any constraints (as might be offered by a blog engine).
The most important variables are commented in the code of the .tpl
files.
For an in-depth understanding of the template system, read the PHP files
in the core/display/ folder, and core/startup/GLOBALS.php.
This is the first .tpl file to be loaded and it acts as a container for
other .tpl files. The core uses only this model. All the others are
pieces of this first for easy reading and maintenance.
The template’s .css file is linked to in display.tpl. You have the option
to override any CSS in the template’s own .css file. To do this, create
a components/templates/override.css file and add CSS there. Custom template
designers should add:
<link rel="stylesheet" href="{$tplPath}/../override.css?ver={$smarty.const.WIKINDX_PUBLIC_VERSION}" type="text/css">
in their display.tpl following the template.css link. CSS in override.css acts
as global CSS overwriting any CSS styling in any template.css.
The ‘ver’ query parameter is important and should be kept. It allows the layout to be refreshed properly when styles change during a release. You can add your own query parameter to do the same if you change the styles.
The same mechanism is valid for JS files, icons, and images (any external resource).
Fisrt level title, hidden in popup windows.
Position the display of the drop-down menus.
This contains the main display logic for the body of the WIKINDX display between menus and footer. WIKINDX expects all such content to be displayed in an HTML table element with class ‘mainTable’.
Secondary information displayed at the bottom of the page.
Disclaimer : this explanation is for beginners.
If you talk German we recommend selfhtml.org otherwise [Mozilla mdn docs][https://developer.mozilla.org] is a good multi-language option. You cannot learn CSS3 in a vacuum. You also need to learn HTML. Our recommendation also includes this aspect.
In addition the World Wide Web Consortium (W3C), which publishs HTML/CSS standards, provides a CSS Learning page full of links and resources for beginners carefully chosen.
You need to read the HTML code in action in your browser to fully understand the relationship with the CSS rules. Use the F12 shortcut with your browser to access the web page inspection tools.
You can also use the browser inspector to change HTML/CSS on the fly and see the effect of a rule without changing the CSS file. Refreshing the page lost your changes.
When you code is ready take the time to validate it with the CSS Validation Service and fix any remaining bugs.
The CSS code is divided into thematic sections whose use is commented.
The default template CSS was written by hand without using ready-made CSS frameworks like BootStrap, Bulma, knacss.
Therefore the code is very concise and focused but the corresponding HTML code cannot be adapted for CSS frameworks.
You also won’t be able to use Flex or Grid layouts except very locally.
Sometimes there are inline styles you will not be able to change. This is something we need to improve.
So it’s not a completely free form.
CSS use a system of conditions (element name, id, class, pseudo-class, selector, media queries), heritage, and order precedence.
The browser read the HTML definition of an element to know what CSS conditions match. When all matching CSS rules are found, it use heritage and order precedence rules to pick the most specific CSS rule.
Higher has more priority.
It applies within an inheritance level : top to bottom, left to right.
The last to speak wins.
Generally it’s a bad idea to use ids because they have to be unique within an HTML page. Still useful for main invariant blocks (e.g. a main menu).
For browsers
For emails
Templates must be compatible with Smarty 5.
The most important change is the removal of support for PHP functions. We replaced the occurrences of the ’explode’ function with ‘join’ [https://sourceforge.net/p/wikindx/v5bugs/678/].