== Sidebar configuration ==

Here you can create sidebars. Each sidebar is represented by a .conf/html/wiki file:
  * .conf gets sidebar contents from a plugin;
  * .html contains raw HTML inserted directly into the sidebar;
  * .wiki is formatted using your UverseWiki settings and used as sidebar contents.

File name can begin with a positive number (up to 99) followed by a space or extension that, if present, controls the order in which sidebars are sorted. It doesn't affect anything else.

Regardless of the extension each file has the same structure:

  setting = value
  setting 2 = value 2
  == Sidebar title [==]
  Sidebar contents based on file extension (conf, html or wiki).

Thus, file is split into 3 sections: sidebar General Configuration, Title and Contents.

Configuration section consists of key=value pairs and has the same format as any config/*.conf file:
  * must be encoded in UTF-8 and use Unix line feeds (LF);
  * blank lines and comments starting with "#" or ";" are ignored;
  * multiline values can be defined as "setting = { [LineFeed] contents [LineFeed] } [LineFeed]" ("contents" can contain more line feeds).

You can omit Configuration (then the Title will be the first line). You can define a titleless sidebar by leaving two or more "=" symbols on one line. You can also omit Contents when using a sidebar plugin that doesn't require it. In any case, title must be specified if it's empty and all other sections are also empty.

The Title string is localizable using config/blog lang.conf (it's first looked up there and output as is if none found). Title line must begin with '==' and may optionally end on '=='.

Title can be no title ("titleless" sidebar, when entire line consts of '==' - no caption is shown) or title can be empty (when line is '== ==' - in this case plugin might substritute its own default value).

=== Other sidebar files ===
In addition to required .conf/htm/wiki file each sidebar can have other files that must start with the same base name as the main sidebar file:
  = <basename>.lang.<ext> == If localization plugin is installed it will look up these files depending on the visitor's language; example: my_sidebar.ru.conf;
  = <basename>-<size>.{png,gif,jpg,jpeg,bmp} == One or more icons of different sizes that are usually put near the sidebar title by the template (which size is used is also template-dependent).

The config/sidebars directory may also safely contain any other files to be referred to from .html/wiki sidebars or other places.

=== General Configuration ===
  = icons == Space-separated list of icon sizes to be allowed for showing near the sidebar title; if not present all available icons (including plugin defaults) are used; possible sizes are: 16, 24, 32, 48;
  = show/hide == Controls how multiple 'show' or 'hide' settings are processed; values are 'and' and 'or'; default is 'and' for 'show' and 'or' for 'hide'. Testing of 'show/hide ...' settings stops if result can be predicted (that is, if one item became False for AND matching or one item became True for OR);
  = show on pages == If present, the sidebar will only be displayed on the listed pages (comma-separated); page names are: main, blog comments, blog list, blog post, blog post without category;
  = hide on pages == Similar to 'show on pages' but with the opposite meaning (showing sidebar on all but listed pages);
  = show on chance == On each visit the value (V) is matched against an inclusive 0..99 random number (R) and if V > R then the sidebar is shown;
  = show/hide on dates == Two settings; comma-separated (,) list of date/time masks - see below for more details;
  = show/hide on user agents == Two settings; pipe-separated (|) list of case-insensitive text strings that can contain '?' and '*' wildcards;
  = show/hide on robots == Two boolean settings;
  = show/hide on ips == Two settings; comma-separated (,) list of IP addresses; octets can be '*' to match any octet in that positions (e.g. '192.168.*.*');
  = show/hide on ports == Two settings; space-separated list of ports; supports inclusive ranges. Example: "80 443 1023-1105".
  = show/hide if were events == Two settings; comma-separated (,) list of event names that will be checked for occurrence before the sidebar is output (near the end of page request). Attention: this setting only works if 'count events' is enabled in other.conf;
  = cache == A boolean value where '1/on/yes/y' enable caching of this sidebar; the cache is cleared by one of 'regenerate ...' options or none if there are none;
  = regenerate on age == Regenerates cached sidebar contents if caching is enabled and its age is more than given number of seconds;
  = regenerate if empty == A boolean value preventing caching if sidebar contents was generated as empty;
  = regenerate on events == Comma-separated (,) list of event names that, when fired, will clear cached sidebar data; unlike 'regenerate if were events' this monitors all events on all page loads instead of only those preceding displaying of the sidebar on current request;
  = regenerate ... == You can use any of 'show' or 'hide' options above - e.g. 'regenerate on ips' or 'regenerate if were events'.

An error occurs if both 'show ...' and 'hide ...' settings are specified.

Settings that accept list of values (e.g. 'show on user agent') ignore spaces appearing before and after the list separator (so that 'msie|webkit' is the same as "msie | webkit" but different from 'msie|web kit').

Plugins might provide additional options.

==== Show/hide on dates ====
Value is a comma-separated list of masks which are of two types:
  1. Date/time strings that resolve to specific timestamps; format: "[period start] [-] [period end]", where 'period start' and 'end' each can be either a timestamp (positive number) or a time string recognized by PHP strtotime(); if dash (-) is present then either side (but not both) of it can be omitted to match 1/1/1970 and 19/1/2038 respectively; if it's omitted then the value matches an entire period unless there are seconds given - in this case it matches only this specific timestamp, otherwise:
     * if there are no seconds but minutes are given - matches an entire minute (0-59 seconds);
     * if there are neither minutes nor seconds but there are hours - matches entire hour;
     * similarly with day (no hours - matches entire day), month (no day - matches entire month) and year.
  2. Date/time masks - format: "mask = variant[, variant[, ...]]", where mask is a string recognized by PHP date() and 'variant's are its formatted versions that must be considered as "matching". For example, "w = 0, 6" matches on each Sunday and Saturday and "d.m = 31.01, 1.01, 2.01" matches on December the 31st and January the 1st and the 2nd.

In case of date/time strings (type #1), if dash (-) is given then start/end parts don't have to be precise up to seconds: if hours are not given the day's 00 AM (for start) or 12:59:59 PM (for end) is used, if there's no day - first day (for start) or last (for end) of the month is used, etc.

Note that the above works only if your dates use this format: "[YY]YY.M.D H:M:S" (24-hour format; parts might be absent but the order and separators must be as specified).

== Plugin sidebars ==
Sidebar file must be named "<plugin>[ - <anything>].conf" where <plugin> defines which plugin generates the contents for this sidebar and <anything>, if given (after " - "), can be any text that you might use to help identify a particular sidebar.

Sidebar Contents section (after Title) is actually plugin-dependent but usually uses the same syntax as the General Configuration section. It is used to set plugin-specific configuration affecting the generated contents.

If a plugin generates no contents or if there's no plugin specified in the file name the sidebar is hidden. If there's no user-specified icon or title or they're empty the sidebar uses default values provided by its plugin.

=== Example ===
For example, let's suppose you want to create 3 sidebars:
  1. One on the main page with the list of your most recent posts;
  2. One on any post view page with the list of recent posts in current post's category;
  3. And another one on the post view page with your latests posts in other categories.

As you can see, all sidebars get their content from the same plugin and only differ in its configuration. You need to make 3 files and fill them like this:

config/sidebars/posts - main.conf:
  show on pages = main
  == Latest posts ==
  ; plugin config follows
config/sidebars/posts - category.conf:
  show on pages = blog post
  == Latest posts ==
  ; plugin config follows
config/sidebars/posts - other.conf:
  show on pages = blog post
  == Latest posts ==
  ; plugin config follows

== Text sidebars ==
Text sidebars are simplest to create; sidebar file extensions are .html and .wiki. Contents section of the sidebar file contains either unprocessed raw HTML or wiki text formatted using current UverseWiki settings.

All General Configuration options apply for such sidebars; however, note that even though caching can be used with text sidebars it's useless (for .html) or nonoptimal (for .wiki) because the former is already in HTML form and the latter uses much better automatic caching mechanism.