Differences

This shows you the differences between two versions of the page.

--- template:ad-hominem [2021-06-17 11:14] – [HTML Blocks] sascha-leib
+++ template:ad-hominem [2024-03-27 13:11] (current) – [Cookies Banner] sascha-leib
@@ Line 2: / Line 2: @@
 ---- template ----
-description   : Simple and lightweight, but modernised version of the default template
+description   : Simple and lightweight, but modernized version of the default template
 author        : Sascha Leib
 email         : ad@hominem.info
-lastupdate_dt : 2021-06-14
+lastupdate_dt : 2024-02-07
-compatible    : 2020-07-29 "Hogfather"
+compatible    : !Frusterick Manners, !Greebo, Jack Jackrum, Kaos
 depends       :
-conflicts     :
+conflicts     : plugin:cookielaw
 similar       : dokuwiki
-screenshot_img: http://ad.hominem.info/img/template-screenshot_01.png
+screenshot_img: http://ad.hominem.info/img/template-screenshot_04.jpg
-tags          : responsive, sidebar, mobile, print, html5, css3, semantic, clean, accessible, !beta
+tags          : responsive, sidebar, mobile, print, html5, css3, semantic, clean, dark, dark-mode, customizable, minimal, accessible, subsite, kaos
-downloadurl   : https://github.com/saschaleib/dokuwiki-template-ad-hominem/archive/refs/tags/0.3.2.zip
+downloadurl   : https://github.com/saschaleib/dokuwiki-template-ad-hominem/archive/refs/tags/2024-02-07.zip
 bugtracker    : https://github.com/saschaleib/dokuwiki-template-ad-hominem/issues
 sourcerepo    : https://github.com/saschaleib/dokuwiki-template-ad-hominem
 ----
-This is an attempt to create a very simple and lightweight template for DokuWiki that stays true to the ideas of the original design but modernizes the code and improve on the usability.
+This is an attempt to create a very simple and lightweight template for DokuWiki that stays true to the ideas of the original design, but modernizes the code and improve on the usability.
-It was designed to work for my DokuWiki site of the same name (link, see below) but may be useful for others, too.
+It was designed to work for my DokuWiki site of the same name (now migrated to [[https://denkfehler.online/wiki/hauptseite/|Denkfehler Online]]), but may be useful for others, too.
-Please keep in mind that this is still "work in progress", and this template may not be ready for production use on other sites. Use with care.
+This is provided "as is", with no explicit or implied claim to be usable for any specific purpose. It is well tested and fine-tuned, but you are using it at your own risk.
 Feedback and bug reports are of course always welcome :-)
@@ Line 33: / Line 33: @@
     * This also works for Wikipedia links!
   * Looks good in print.
-  * Tries to implement [[https://www.w3.org/TR/WCAG21/|WCAG 2.1]] Level AA (not quite there yet, but this is definitely a goal!)
+  * The template implements [[https://www.w3.org/TR/WCAG21/|WCAG 2.1]] Level AA (however, the DokuWiki content renderer has some limitations)
-  * Neatly formatted and standards-compliant code (where possible – the main page text comes from the DokuWiki renderer and that's out of my control).
+  * [[wp>General Data Protection Regulation|GDPR]]-compliant: does not load external resources like font files or others (note that the [[config:jquerycdn]] setting needs to be set to “local delivery only” for GDPR-compliance)
+  * Neatly formatted and standards-compliant code (where possible – again, the DokuWiki content renderer is the limiting factor)
   * Makes better use of larger screens (target is half of a 4K screen), but because the template is fully responsive, smaller is no problem (down to ca. 300px wide)
   * improvements to edit view, media manager, etc.
+  * User-side controlled “dark mode”, i.e. follows the client side dark mode settings.
+  * Improvements to the default functionality, e.g. a resizeable internal link selection widget, etc.
+  * Configuration to override the "home"-link (see below)
+  * Integrated "Cookies" banner functionality
+  * Compatible with PHP8 and DokuWiki “Kaos”.
 ===== Download and Install ======
-Use the following URL to download this template:
+The easiest way to install the template is to use the Extensions Manager in the Admin panel. Just search for "Ad Hominem" and click "install". Then head to the configuration page and select "Ad Hominem" from the [[:template]] popup menu.
+Alternatively, you can download the latest version as a ZIP file from the following page:
   * https://github.com/saschaleib/dokuwiki-template-ad-hominem/releases/
-Refer to [[:template]] on how to install and use templates in Dokuwiki.
+Refer to [[:template]] on how to install and use templates in DokuWiki.
 ===== Configuration =====
-==== Icons ====
-Similar to the default, this template allows for pictures with specific names to be uploaded using the media manager and serve as site icons, etc. These images have to be uploaded either to the root directory, or into the '':wiki:'' namespace.
+The configuration options are now documented on the [[https://github.com/saschaleib/dokuwiki-template-ad-hominem/wiki|GitHub Wiki Page]]. Make sure to read it, to make the most of your DokuWiki!
+In short, the following configuration features are available:
+  * Icons and site logos – specific names to be used to overwrite the default site logos and e.g. the favicon.
+  * Page blocks – you can upload HTML snippets that are then inserted at specific places of all pages, e.g. in the footer or the sidebar.
+  * Template options in the site configuration page (section: "Template options").
+Details on how to configure these can be found on the page linked above.
+===== Cookies Banner =====
+This template has its own, built-in "Cookies"-banner. This function is heavily inspired by Michal Koutný's "[[plugin:cookielaw|cookielaw]]" plugin, but it is much better integrated into the template design, and of course fully configurable.
+There are three settings that control the behaviour of this
+  * "Display the Cookie message banner": can be either "Don't show", "Show on top of page" and "Show on bottom of page". The first option disables the banner altogether.
+  * "The message to display on the Cookie banner": This is a free-text field that allows you to set the text to display. This text is directly copied into a ''<p>'' context in the banner, without escaping. That means you can insert some (inline) HTML for formatting, if needed.
+  * "Link to the “More information” page": this is either an internal or external address that the "More information" link shall link to. Internal addresses should look like, e.g. ''about:cookies'' (this is also the default), external addresses start with either ''%%http://%%'' or ''%%https://%%'' …
+==== Override Home Link ====
+The template has an option to override the "home" link in the settings. What is this good for? Imagine your wiki is not "stand-alone", but rather only a section in your wider website. In this case, you don't want a click on the site name or logo to bring the visitor to the wiki homepage, but rather to your main //site// homepage. Well, this can be done with this option.
+If you enter, for example, "/index.html", the links on the site icon and site name will both lead to this address. In addition, the "home" icon link in the "You are here" navigation (if enabled) will lead to this link, and the wiki homepage will become a normal entry in the site hierarchy.
+Leaving the field empty will keep the original behaviour (home is your wiki homepage) intact.
+===== Dark Mode =====
+This template supports client-controlled “dark mode”. This means that visitors to your site who have "dark mode" activated on their machines will see the site in a suitable dark colour scheme.
+The following screenshots show the light and dark mode side by side:
+{{ https://denkfehler.online/_template/screenshot_13.jpg | Screenshots in light and dark mode }}
+Generally, there is nothing to do for a site admin, but please be aware of this, and make sure to check your site in dark mode from time to time (or in light mode, if you normally use dark mode).
+There are two potential issues to be aware of:
+  * If you used the "Template Style Settings" to override the default colours, notably to create a custom "dark" appearance, you may want to review these settings.
+  * If possible, create images in a way that they also work with dark backgrounds. Especially if you use transparency, it would be good to test and see how these look like with a much darker background.
+There is more documentation available on the project’s [[https://github.com/saschaleib/dokuwiki-template-ad-hominem/wiki|GitHub Wiki Page]], including some ideas on how to deal with problem situations.
+And, of course, you can also override the dark mode colours using the [[plugin:styling|Styling Plugin]], or disable it altogether in the configuration settings (section: Template settings).
-> Note on SVG images: by default, the media manager does not allow the upload of SVG images. To use them, please add a configuration setting in ''mime.local.conf''. Please see [[:mime|MIME Configuration]] for more information.
+===== Cookies =====
-**Site logo:** this is the logo that appears in the top-left corner of every page. Note that this template uses a different default size (64×64 pixels) than the standard template. This file can be named “''logo.svg''” or “''logo.png''” (the preferred format is SVG).
+This template also comes with its own implementation of the [[plugin:cookielaw|Cookielaw Plugin]], and as such, also sets a cookie to remember that the banner has already been shown to the visitor.
-**Favicon:** This is the icon used by the browser, e.g. for bookmarks and/or tabs. This should either be in [[wp>ICO (file format)|Windows Icon Format]] (containing a set of 16, 24 and 48 pixels size icons), PNG, or SVG. The preferred format is Windows Icon, but SVG is the most flexible size. This should be named “''favicon.ico''”, “''favicon.png''” or “''favicon.svg''”.
+The “''cookielaw''” cookie is set for one year (not 10 years as the original), and it can only contain the value “''1''”, which means it can not be used for tracking users. This means it is purely a “technical cookie“ in the sense of the EU’s “E-Privacy Directive”.
-**Apple Touch Icon:** Used by iOS devices when the user places a bookmark on the homescreen. This should be a 180×180 pixels PNG file named “''apple-touch-icon.png''”.
+Please keep in mind, however, that the DokuWiki system sets additional cookies, which are explained on [[faq:cookies|another page]].
-==== HTML Blocks ====
+===== 2-column “compact” print style =====
-The template looks for HTML files that will be included at specific places in the page. This is useful for repeating sections, configuration options, etc. These files can be located in the ''/conf/'' directory, or directly in the template directory (''/lib/tpl/ad-hominem/'').
+Since 1.5 there is now an option to switch from the default "basic" print style to a more "compact" 2-column style.
-=== Metadata ===
+This "compact" style is typographically more advanced and IMHO also looks a lot better, but it requires some work from the editor to make sure the page works well in print.
-The file “''meta.html''”, if it exists, will be included at the end of the ''<head>'' section. This can be used to add specific metadata to all pages of the site. For example, load additional CSS or JavaScript files, links to your social-media accounts, etc.
+Most importantly, use the class "''print-wide''" can be used to mark up sections that should span both columns, e.g. for images, tables, etc.
-=== Header ===
+If you use the [[plugin:wrap|Wrap]] plugin, you can simply wrap (pun intended) such a section with:
-An area in the page header, located just below the search field, is reserved for the content of the file “''header.html''”, if it exists. This is a good place to add site-wide notifications, like warning of technical problems, etc.
+> ''<WRAP print-wide>''
+>  …
+> ''</WRAP>''
-=== Sidebar ===
+Another option is the [[plugin:adhoctags|Ad.Hoc Tags]] plugin of the same author, which allows you to use a larger number of HTML tags, including the possibility to simply add class names (and other attributes) in your code. Here you could write, e.g.:
-There are two hooks for HTML files in the sidebar: one on top (called “''sidebarheader.html''”), and another at the bottom (“''sidebarfooter.html''”). These can be used to add navigation items that should repeat on all pages (e.g. a link to the homepage, or to legal mentions).
+> ''<aside print-wide>''
+>  …
+> ''</aside>''
-=== Page Content ===
+Last but not least: ''<figure>'' blocks are also spanning both columns by default and also have specialized styling to make sure they look good in print (including their ''<figcaption>''s). If you want to override this behaviour, you can keep them in a single column by adding the class ''print-narrow''.
-A repeating section on top of the main page content (above the “youarehere” links) can be added by placing a file called “''pageheader.html''” in the template directory.
+Other print-related classes include ''noprint'' and ''print-only'', which do exactly what their names promise.
-Likewise, at the bottom of the page (after the “Last changed” item). The file to be inserted here has to be called “''pagefooter.html''”.
+===== HTML Tags =====
-=== Footer ===
+As of DokuWiki “Jack Jackrum”, embedding HTML tags in the DokuWiki code is no longer supported. In order to still allow semantic markup to be added, the autor of this template also provides a plugin, [[plugin:adhoctags|Ad-Hoc Tags]], which enables //specific// HTML tags in a more Wiki-like syntax.
-There is a footer section reserved for a static HTML file called “''footer.html''”. If there are bullet lists in this file, they will be displayed as inline lists in mobile view (similar to the other footer sections).
+This has been developed with, and is designed to be used with this template (though it is fully useable with other templates as well, of course).
-===== Sites using this Template =====
+===== Visit my site =====
-  * [[https://ad.hominem.info/de/hauptseite|Ad Hominem Info]]
+The best way to experience this template is by browsing my sites, which make full use of it:
+  * [[https://denkfehler.online/wiki/hauptseite/|Denkfehler Online]]
+  * [[https://fallacies.online/wiki/index|Fallacies Online]]