Templates (v4)

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://www.smarty.net/ 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:

  • display.tpl
    • header.tpl (optional if merged with display.tpl)
    • menu.tpl (optional if merged with display.tpl)
    • content.tpl (optional if merged with menu.tpl)
      • content_abstract.tpl (optional if merged with content.tpl)
      • content_attachments.tpl (idem)
      • content_cite_fields.tpl (idem)
      • content_content.tpl (idem)
      • content_custom.tpl (idem)
      • content_file_list.tpl (idem)
      • content_heading_block.tpl (idem)
      • content_ideas.tpl (idem)
      • content_metadata.tpl (idem)
      • content_musings.tpl (idem)
      • content_note.tpl (idem)
      • content_paging.tpl (idem)
      • content_paraphrases.tpl (idem)
      • content_quotes.tpl (idem)
      • content_ressource.tpl (idem)
      • content_ressource_information.tpl (idem)
    • footer.tpl (optional if merged with display.tpl)
    • template.css (stylesheet of the template)
    • component.json (metadata description of the component)
    • README.txt (optional file that provides more info than component.json)
    • images/* (static images for css/HTML)
    • icons/* (images of icons inserted at runtime in HTML by the core – you must follow the same names as default theme)

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.

Template files

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.

display.tpl

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:

header.tpl

Fisrt level title, hidden in popup windows.

Position the display of the drop-down menus.

content.tpl

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

footer.tpl

Secondary information displayed at the bottom of the page.

template.css

Disclaimer : this explanation is for beginners.

Where to find a good tutorial

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.

Tools

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.

CSS Coding Style

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 Rules Reminder

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.

Heritage rules

  1. External files
  2. HTML embedded style elements
  3. HTML inline style attributes (e.g. style=“color:yellow”)
  4. Old named HTML style attributes (e.g. color=“yellow”)

Higher has more priority.

Order of precedence rules

It applies within an inheritance level : top to bottom, left to right.

The last to speak wins.

Comment about the current accepted practise

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

  • External files should be privileged.
  • Inline style attributes are useful when a website has a single design or for a quick fix but should be avoided if possible.
  • Old named HTML style attributes are deprecated (HTML 4 feature).

For emails

  • On the contrary, inline style attributes and old named HTML style attributes are useful to design because email readers are a strange and wild world!

History

v4

From version 6.7.3 (or template v5) the component template configuration file config.txt is obsolete. Collapse of menu levels is controlled by users.