Differences

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

--- wiki:dokuwiki-css-doc [25/08/2021 00:37] – [Styling based on page property] ztrulphcs
+++ wiki:dokuwiki-css-doc [25/08/2021 07:21] (current) – ztrulphcs
@@ Line 1: / Line 1: @@
-====== CSS Stylesheets ======
+====== css ======
-Most of [[:DokuWiki]]'s presentation can be controlled through CSS stylesheets. DokuWiki defines some very minimal styles itself. The rest of the CSS definitions come from the [[:template]] and [[:plugins]] used.
+using css... bla bla bla
-All CSS files are fetched through a single dispatcher in [[xref>lib/exe/css.php]] which also handles caching, pattern replacement, [[LESS]] preprocessing and optimizing. The loading of the stylesheets amongst other things is done via the ''tpl_metaheaders()'' function, so don't forget to have it within your template.
-===== Stylesheet Modes =====
-There are five types of stylesheet modes:
-  * **screen**: This is used when displaying pages in the web browser
-  * **print**: Definitions here will be used for printing pages
-  * **all**: Applied in all display modes
-  * <del>**rtl**: Definitions in ''rtl'' files will be loaded additionally when a right-to-left [[:localization|language]] is used</del> :!: **[[deprecated]], see [[#RTL Styles]]**
-  * **feed**: Applied when displaying the [[:syndication|feed]]
-==== RTL styles ====
-The RTL mode has [[devel:releases#deprecation|deprecated]] since release 2012-10-13 "Adora Belle", and should therefore not be used anymore. The new and better technique to write styles for right-to-left [[:localization|languages]] is by using ''[dir=rtl]'' in front of each CSS selector within styles for any of the other modes. E.g.
-<code css>
-.someClass {
-    float: left;
-    background-color: __background__;
-}
-[dir=rtl] .someClass {
-    float: right;
-}
-</code>
-===== DokuWiki Stylesheets =====
-[[:DokuWiki]] loads its stylesheets from 4 sources, which are loaded in this order:
-==== 1. Base Stylesheets ====
-These stylesheets are located within ''/lib/styles''. They define basic styling, like the appearance of error messages.
-==== 2. Plugins Styles ====
-Plugins may define their own style definitions using the following files:
-^ Mode        ^ CSS File ^
-| screen      | ''style.css'' or ''screen.css''  |
-| print       | ''print.css''  |
-| all         | ''all.css'' |
-| <del>rtl</del>         | <del>''rtl.css''</del> :!: **deprecated, see [[#RTL Styles]]**  |
-| feed        | ''feed.css'' |
-Stylefiles with extension ''.less'' are supported as well. However you can use [[LESS]] formatting in both the ''*.css'' and ''*.less'' files.
-To fit in well into any template's color scheme, plugin authors should use the [[style.ini#guaranteed color placeholders]].
-:!: Stylesheets from plugins are loaded even if a plugin is not used (but not if a plugin is [[plugin:extension|disabled]]).
-:!: Styles defined here should take care of conflicts. So please be careful when writing a plugin. If possible add a prefix to your styles so that you're sure they won't conflict.
-==== 3. Templates Styles ====
-Template's stylesheets are loaded from the selected template dir. [[:DokuWiki]] reads the template's ''[[style.ini]]'' located within the directory and loads all CSS that are referenced within that file. The loading is done according to the [[#Stylesheet Modes|current mode]].
-  * Changes to ''style.ini'' by wiki admins have to be stored in ''conf/tpl/<tpl>/style.ini''. If the changes are applied via the [[plugin:Styling]] Plugin, this file is automatically created.
-  * See also: [[templates|Template Development]]
-==== 4. User Styles ====
-Additional styles, independently from the used template can be defined by the wiki administrator by creating the following CSS files in the wiki's configuration folder (''conf/'' in unadjusted wikis):
-^ CSS File                                                             ^ When it is used                                                                                  ^
-| ''conf/userstyle.css''\\ ''conf/userstyle.less''                     | Applied in screen mode                                                                           |
-| ''conf/userprint.css''\\ ''conf/userprint.less''                     | Applied when a page is printed                                                                   |
-| <del>''conf/userrtl.css''</del>\\ <sub>Since Angua deprecated</sub>  | Applied when a right-to-left interface language is used :!: **deprecated, see [[#RTL Styles]]**  |
-| ''conf/userfeed.css''\\ ''conf/userfeed.less''                       | Applied when displaying the [[:syndication|feed]]                                                |
-| ''conf/userall.css''\\ ''conf/userall.less''                         | Applied in all display modes                                                                     |
-(Note: the ''.less'' are possible since 2015-08-10 "Detritus".)
-These style files are useful to override small portions of template or plugin styles without running into problems on updating those later.
-The following example reduces the bottom margin of the h2 and h3 headings when viewing in browser:
-<code css userstyle.css>
-h2, h3 {
-  margin-bottom: 4px;
-}
-</code>
 ===== Using IDs =====
@@ Line 92: / Line 9: @@
 In plugins use ''<pluginname>%%__%%<id>''. For example '' 'searchindexplugin%%__%%buttonfield' ''
-===== Styling based on page property =====
+===== Styling based on page properties =====
-Most often people only need to modify a style of some element on all pages. For example one may want to change the font style for h1 heading. But from time to time, it is desirable to modify a style only on certain page. You could want a special background for any page in the ''attic'' namespace so that reader instantly realize that they are reading outdated documentation left as a reference. One could also want to add a specific style to some elements if visitor is a connected user, or only on edit page but not when viewing the page. This is possible because most template use an internal DokuWiki function called [[xref>tpl_classes()]]. All you need to know is that this function is used by templates to add classes based on page properties to one of the top div element. For example, when a connected visitor is reading the page [[:wiki:syntax]] the default template produces this div element :
+Most often people only need to modify a style of some element on all pages. For example one may want to change the font style for h1 heading. But from time to time, it is desirable to modify a style only on certain page. You could want a special background for any page in the ''attic'' namespace so that readers instantly realize that they are reading outdated documentation left as a reference. One could also want to add a specific style to some elements if visitor is a connected user, or only on edit page but not when viewing the page. This is possible because most template use an internal DokuWiki function called [[xref>tpl_classes()]]. All you need to know is that this function is used by templates to add classes based on page properties to one of the top div element. For example, when a connected visitor is reading the page [[:wiki:syntax|:wiki:syntax]] the default template produces this div element :
   <div id="dokuwiki__top" class="site dokuwiki mode_show tpl_dokuwiki loggedIn   showSidebar hasSidebar lv_1 ns__wiki ns_wiki_ pg_syntax pg_wiki_syntax">
@@ Line 122: / Line 39: @@
-  * ''site''\\ No idea what it means, when it is present...
   * ''dokuwiki''\\ This class is always present
-  * ''tpl_<name_of_template>''\\ By default, this will be ''tpl_dokuwiki''. If you use the [[template:sprintdoc]], this will be ''tpl_sprintdoc''. and if you use the [[template:artforwater|Art for water]] template, this will be ''tpl_artforwater''.
   * ''mode_<ACT>''\\ the action that created the page. Most of the time, this will be ''mode_view''. But see [[devel:action_modes]] for a list of action modes. Note that plugins may create more actions.
-  * ''loggedIn''\\ This class is present only for connected user. There is no <<notloggedin>> or <<loggedout>> class.
+  * ''tpl_<name_of_template>''\\ By default, this will be ''tpl_dokuwiki''. If you use the [[template:sprintdoc]], this will be ''tpl_sprintdoc''. and if you use the [[template:artforwater|Art for water]] template, this will be ''tpl_artforwater''.
+  * ''loggedIn''\\ This class is present only for connected user. There is no <<notloggedin>> or <<loggedout>> class. To target page for not loggedIn users, use the '':not()'' CSS pseudo class.
   * ''notFound''\\ This class is added for non existent page. Follow this link [[:this:page:does:not:exist:on:purpose|:this:page:does:not:exist:on:purpose]] ; the rendered page will have this ''notFound'' class in its main DW div.
   * ''home''\\ This class is only present on the main DokuWiki page.
+  * ''<del>showSidebar</del>'' and ''<del>hasSidebar</del>''\\ These 2 elements shown are **not** added by the [[xref>tpl_classes()]] function. They are specific to the default template and not described here (although their meaning is quite obvious)
   * ''lv_<X>''\\ This is the tree depth level of a page. for [[:dokuwiki|:dokuwiki]] page, this level is 0 (zero), so the class will be ''lv_0'' ; for the page [[devel:css|devel:css]] this will be 1, ''lv_1'' and for [[fr:plugin:struct:aggregation|fr:plugin:struct:aggregation]], this will be 3, ''lv_3''.
   * ''%%ns__<namespace-chain>%%''\\ These class are built on the page namespace. Each namespace component concatenated with ''_'' separator. If a namespace has an ''_'' in its name, then this result in a ''%%__%%'' in the class name. examples :
@@ Line 143: / Line 60: @@
     * page ''[[fr:plugin:struct:aggregation|fr:plugin:struct:aggregation]]'' => class ''%%ns_aggregation_%%''
     * page ''matching_food_and_drinks:big_juicy_steak:pan_galactic_gargle_blaster'' => class ''%%ns_big__juicy__steak_%%''
-''%%pg_<full-page-id>%%''\\
+  * ''%%pg_<full-page-id>%%''\\ Same thing as the namespace one, but for the page name. ''_'' in page name are also doubled in the class name. examples :
-    * page ''[[|]]'' => class ''%%%%''
+    * page ''[[:start|:start]]'' => ''%%pg_start%%''
+    * page ''[[fr:plugin:struct:aggregation|fr:plugin:struct:aggregation]]'' => class ''%%pg_fr_plugin_struct_aggregation%%''
+    * page ''matching_food_and_drinks:big_juicy_steak:pan_galactic_gargle_blaster'' => class ''%%pg_matching__food__and__drinks_big__juicy__steak_pan__galactic__gargle__blaster%%''
+  * ''%%pg_<rel-page-id>%%''\\ Same thing as the full-page-id one but don't use the namespace components. For pages in the root namespace, this would be the same as <full-page-id>, so it is not present
+    * page ''[[:start|:start]]'' => nothing
+    * page ''[[fr:plugin:struct:aggregation|fr:plugin:struct:aggregation]]'' => class ''%%pg_aggregation%%''
+    * page ''matching_food_and_drinks:big_juicy_steak:pan_galactic_gargle_blaster'' => class ''%%pg_pan__galactic__gargle__blaster%%''
+==== example selectors ====
-===== Using images and importing styles =====
+To target all start page in any namespace use this
+  div.dokuwiki.pg_start
-Relative links to images (''url(...)'') and imported stylesheets (''@import ...'') in your own stylesheets are automatically fixed by DokuWiki's CSS dispatcher by treating them relative to the template's root directory.
+To target the main page
+  div.dokuwiki.home
-An example: In a plugin, you want to use an image in the sub directory ''images'' from your ''style.css''. You can simply write the following CSS:
+To target a page exactly in the fr namespace
+  div.dokuwiki.ns__fr.lv_1
-<code css>
+To target a page anywhere in the fr namespace (meaning [[fr:syntax|fr:syntax]] or [[fr:plugin:struct:aggregation|fr:plugin:struct:aggregation]])
-.someclass {
+  div.dokuwiki.ns__fr
-   background-image: url(images/icon.gif);
-}
-</code>
-DokuWiki will automatically change the URL, so that the image will be found in the plugin directory, relative to the template directory.
+To target "this page does not yet exist" in any namespace when using the [[template:boozurk|boozurk]] template and only for  anonymous user and when user is viewing the page but not editing it
+  div:not(.loggedIn).dokuwiki.notFound.mode_show.tpl_boozurk
-**Notes**:
+==== A note for non english page and namespace ====
-  * ''url(...)'' in ''@import folder/style.less'' are not automatically fixed, the dispatcher assumes these are at top level ''lib/exe/'', not in the actual folder.
-  * ''@import folder/style.css'' is handled by the CSS-dispatcher/LESS-parser as normal [[https://developer.mozilla.org/en-US/docs/Web/CSS/@import|CSS]]. So it is not directly included in the ''css.php''. However, the relative references with ''url(...)'' to ''style.css'''s actual folder are working. Importing css-files is only working if you add these in a ''all.css''/''all.less'', because these place them as really the first lines of the css.php-file. Via the other files these css-imports are ignored, because they are not really on the first line but on the first line of the e.g. a ''@media screen {...}'' block.
-===== Caching =====
+CSS accepts [[all non ascii codepoints above U+0080 in class names. However, support for these CSS class name may vary from browser to browser. Note also that the page ID and namespace ID in dokuwiki depend on the [[config:fnencode]] settings
-All CSS files are fetched through a single dispatcher in ''lib/exe/css.php'' which also handles caching, amongst other things. The cache expires if files are changed that are mentioned above in the section   [[#DokuWiki stylesheets]] or are referred in the ''style.ini'' of your template. Note: Imported stylesheets (''@import'') are not checked for changes.
-If you are making changes, ensure that you refresh the cache of your browser by a //Hard reload/Force Refresh// (e.g. in Chrome/Firefox use ''Ctrl+F5'').
-===== Browser (Internet Explorer) Specific CSS =====
-DokuWiki does not provide features to address browser specific CSS rendering, therefore any standard approach can be used in your template files.
-The [[https://forum.dokuwiki.org/post/40148|suggested approach]], which will allow the DokuWiki CSS-Dispatcher to process and deliver the CSS normally, is to use conditional comments ([[http://www.mediacollege.com/internet/html/detect/detect-ie.html|mediacollege:detect-IE]] or [[http://en.wikipedia.org/wiki/Conditional_comment|WikiPedia Conditional Comments]]) to create <div id> wrappers around the entire content - the wrappers specify the version of IE in use (see the [[https://github.com/selfthinker/dokuwiki_template_starter/blob/master/main.php#L30|dokuwiki_template_starter]] as an example).
-This wrapper method inserts a specific CSS style ID around the entire content. Your template .css file (design.css, content.css, etc.) then creates browser specific styles by starting a line with #ID.  An example, as used for IE7 would be:
-<code css>
-#IE8 #dokuwiki__header h1 {
-  ...css styles...
-}
-</code>
-You will need to edit the files in your template (ie. ''detail.php'', ''main.php'', etc.) and insert the relevant conditional checks.

Tools

menus and quick search

quick search

site status

location indicator

Page Tools

meta data for this page

Differences