version=pmwiki-2.3.21 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=#configphp-order per-user, CondAuth() (-20) (+51)
name=PmWiki.LocalCustomizations
rev=115
targets=PmWiki.GroupCustomizations,PmWiki.WikiAdministrator,PmWiki.DocumentationIndex,PmWiki.Skins,PmWiki.Internationalizations,PmWiki.CustomMarkup,PmWiki.InterMap,PmWiki.PmWikiPhilosophy,PmWiki.Variables,PmWiki.DebugVariables,Cookbook.ControllingWebRobots,Cookbook.Cookbook,PmWiki.BasicVariables,PmWiki.PathVariables,Cookbook.SQLite,Cookbook.CompressedPageStore,Cookbook.PerGroupSubDirectories,PmWiki.UTF-8,PmWiki.MailingLists,PmWiki.Upgrades,Site.PageNotFound,PmWiki.LocalCustomizations
text=(:Summary:Customize your PmWiki installation through @@config.php@@ and @@local.css@@:)%0aA [[Wiki Administrator]] can make a lot of customizations simply by setting variables in the ''@@/local/config.php@@'' and defining cascading style sheets in ''@@/pub/css/local.css@@'' files.  Any group or page can also have [[GroupCustomizations|its own configuration file and configuration css file]].%0a%0aThis page describes how customizations work in general, see [[PmWiki.Documentation Index]] for specific customizations that are commonly performed at many PmWiki installations, including:%0a%0a* [[Skins]] - {Skins$:Summary}%0a* [[Internationalizations]] - {Internationalizations$:Summary}%0a* [[Custom Markup]] - {CustomMarkup$:Summary}%0a* [[InterMap]]s - {InterMap$:Summary}%0a%0a[[#configphp]]%0a!! local/config.php%0a%0aFrom its inception, PmWiki has been designed so that [[Wiki Administrator]]s can greatly customize the way PmWiki displays pages and the markup sequences used to generate pages.  (This is even mentioned explicitly in [[PmWiki Philosophy(#collaborativemaintenance)]] #4 Collaborative Maintenance.)  As a result, the core ''@@pmwiki.php@@'' script makes extensive use of [[PmWiki.Variables]] to determine how markup sequences will be processed and what each individual page will output.%0a%0aThe simplest type of customization is merely setting a variable to 1 (or TRUE).  Here's an example that enables ?action=diag and ?action=phpinfo actions:%0a->%25hlt php%25@@$EnableDiag = 1;@@%0a%0aYou can begin a line with a "#"  (an octothorpe, a.k.a. a hash symbol or pound sign) to add a comment.  Additionally, some built-in PmWiki variables take values other than 1 or 0 (true or false).  Here's another example that customizes the wiki's behavior with respect to search engine web robots (see [[Cookbook:ControllingWebRobots]]):%0a->%25hlt php%25[@%0a# Remove the default "rel='nofollow'" attribute for external links.%0a$UrlLinkFmt = "%3ca class='urllink' href='\$LinkUrl' title='\$LinkAlt'>\$LinkText%3c/a>";%0a@]%0a%0aThe ''@@scripts/@@'' subdirectory (below the directory holding the ''@@pmwiki.php@@'' script) has many customizations.%0aThe PmWiki [[(Cookbook:)Cookbook]] contains many example customizations (recipes) that you can download into the ''@@cookbook/@@'' subdirectory,%0aThe first few lines of each of these scripts generally contain instructions about how to enable (and use) the feature provided by the script.%0a%0aThese customizations are included in your ''@@config.php@@'' site configuration. For most scripts this is done by simply adding lines like:%0a->%25hlt php%25[@include_once("cookbook/recipefile.php");@]%0aand%0a->%25hlt php%25[@include_once("scripts/scriptfile.php");@]%0aat the end of the ''@@config.php@@'' file to enable them.  %0a%0aSome of the scripts are automatically enabled for you via the ''@@scripts/stdconfig.php@@'' script unless you disable it by setting @@$EnableStdConfig=0;@@ in ''@@local/config.php@@''.%0a%0a[[#PostConfig]][[#configphp-order]]%0a!!! Order of the commands in @@config.php@@%0aThe following order is recommended:%0a%0a* define $ScriptUrl and $PubDirUrl, if needed,%0a* define any custom PageStore class, like [[(Cookbook:)SQLite]], [[(Cookbook:)CompressedPageStore]] or [[(Cookbook:)PerGroupSubDirectories]],%0a* next %25hlt php%25[@include_once("scripts/xlpage-utf-8.php")@],%0a* next call %25hlt php%25[@XLPage()@] which needs the definitive writable $WikiDir already set in order to find the wiki page containing the translations,%0a* next include @@authuser.php@@ (if needed), because PmWiki caches some group and page authorization levels when a page is accessed,%0a* next include any other scripts and recipes and their configuration %0a** see for any requirements or advice about the order on the recipe pages: some need to be included before or after others, some need to be configured before the script is included, others after.%0a%0a>>frame hlt php%3c%3c%0aIf you need to set per-page, per-group, or per-user variables or addons, it is recommended to add them into files named @@local/Group.php@@ and @@local/Group.Page.php@@. If you must do it from @@config.php@@, or if you need to set these variables after the local files are included, use the following at the bottom of @@config.php@@:%0a%0a  $pagename = ResolvePageName($pagename);%0a  include_once("$FarmD/scripts/pgcust.php");%0a  list($group, $name) = explode('.', $pagename);%0a  if ($group != 'Private') {...} # do whatever you need%0a  if (CondAuth($pagename, 'edit')) {...} # only for editors%0a%0aAny direct function call in @@config.php@@, like @@CondAuth()@@, @@PageTextVar()@@, @@PageVar()@@, @@RetrieveAuthPage()@@, or others, should be done near the end of @@config.php@@ after the above snippet. Alternatively, you can add those in a custom function or script in the $PostConfig array:%0a%0a  # PmWiki will call this function and include this file '''after'''%0a  #    farmconfig.php, config.php, Group.Page.php and Group.php%0a  #    but '''before''' scripts/stdconfig.php:%0a  function MyFunction1($pagename) {...}%0a  $PostConfig['MyFunction1'] = 25;               # %3c 50%0a  $PostConfig["cookbook/some-addon.php"] = 26;   # %3c 50%0a%0a  # PmWiki will call this function and include this file '''after'''%0a  #    farmconfig.php, config.php, Group.Page.php, Group.php%0a  #    and scripts/stdconfig.php:%0a  function MyFunction2($pagename) {...}%0a  $PostConfig['MyFunction2'] = 125;              # >= 50%0a  $PostConfig["cookbook/other-addon.php"] = 100; # >= 50%0a%0aThe $PostConfig functions and scripts will be called ordered by their values, ie above "MyFunction2" (125) will be called after "other-addon.php" (100). This allows recipe authors more control over the precise order of their recipe compared to other recipes (when that is important).%0a>>%3c%3c%0a%0a''Note, each part is '''not''' required, but if your wiki needs it, this is the recommended order in @@config.php@@.''%0a%0a[[#encoding]]%0a!!! Character encoding of config.php%0a%0aThe encoding used when you save [@config.php@] has an effect. Your text editor should allow you to save config.php in the encoding of your wiki. (The default encoding of PmWiki is ISO-8859-1, for new wikis it is recommended to enable UTF-8.)%0a%0aNewer operating systems like GNU/Linux, FreeBSD and Apple generally default to saving text files in Unicode/UTF-8; in Windows the default encoding is ANSI/Windows-1252 which is almost the same as PmWiki's ISO-8859-1.%0a%0aThe following ''free/libre software'' text editors can edit and save a file in different encodings:%0a* Cross-platform: [[https://kate-editor.org/ |Kate]] (for KDE), [[https://www.geany.org/ |Geany]], [[https://arachnoid.com/arachnophilia/index.html|Arachnophilia]], [[https://www.scintilla.org/SciTE.html|SciTE]], [[https://bluefish.openoffice.nl/index.html|Bluefish]], [[https://www.vim.org/|vim]] and others.%0a* Windows: [[https://notepad-plus-plus.org/ |Notepad++]], [[https://www.contexteditor.org/|ConTEXT]].%0a* OS X: [[https://aquamacs.org/|Aquamacs]].%0a%0aNote that if you use the UTF-8 encoding, you should save your files ''"without Byte Order Mark (BOM)"''.%0a%0aOver time PmWiki will be updated to default to Unicode/UTF-8 encoding, which allows all possible alphabets and languages. See [[UTF-8]] for more information.%0a%0a[[#localcss]]%0a!! pub/css/local.css%0a%0aYou can create this file and set there some custom CSS styles which will override any styles set by skins. For example:%0a%25hlt css%25[@%0a  h1, h2, h3, h4, h5 { color: #880000; } /*dark red titles*/%0a  a { text-decoration: none; } /* don't underline links */%0a@]%0a%0aCSS files are included in the order%0a# @@$PubDirUrl/css/local.css@@ '-- for the wiki-'%0a# @@$PubDirUrl/css/[@{$Group}.css@]@@ '-- for groups-'%0a# @@$PubDirUrl/css/[@{$FullName}.css@]@@ '-- for single pages-'%0a# @@$PageCSSListFmt@@%0a%0a!! Don't modify pmwiki.php or other core files%0a%0aYou should strongly resist the temptation to directly modify the ''@@pmwiki.php@@'' script or the files in the ''@@scripts/@@'' subdirectory.  Any modifications you make to these files will probably be overwritten whenever you [[PmWiki/upgrade(s)]].  Instead, look at some of the sample scripts for examples of customizations that can be performed from ''@@config.php@@''. You can even create your own script to do a customization and use %25hlt php%25@@include_once(...)@@%25%25 to include it from ''@@config.php@@''.  If you do make your own customization script, you can safely put it in the ''@@cookbook/@@'' subdirectory--it won't get overwritten by an upgrade there.  You might also want to submit your customization to the [[MailingLists|pmwiki-users mailing list]] or the [[(Cookbook:)Cookbook]] so that others can benefit from your effort and so that it can perhaps be included in future releases of PmWiki.%0a%0a!! FAQ%0a>>faq%3c%3c [[#faq]]%0aQ: There's no "@@config.php@@"; it's not even clear what a "local customisation file" is!%0aA: The "@@sample-config.php@@" file in the "docs" folder, is given as an example. Copy it to the "local" folder and rename it to "@@config.php@@". You can then remove the "#" symbols or add other commands shown in the documentation. See also [[Group Customizations]].%0a%0aQ: Can I change the default page something other than @@Main.HomePage@@ ($DefaultPage)?%0aA: Yes, just set the $DefaultPage variable to the name of the page you want to be the default.  You might also look at the $DefaultGroup and $DefaultName configuration variables.%0a%0a->%25hlt php%25[@$DefaultPage = 'ABC.StartPage';@]%0a%0aNote the recommendations in $DefaultName and the need to set $PagePathFmt as well if you are changing the default startup page for groups.%0a%0aQ: [[#configphp-group-page]] How do I get the group / page name in a local configuration file (e.g. ''@@local/config.php@@'')?%0aA: Use the following markup in pmwiki-2.1.beta21 or newer:%0a-> %25hlt php%25[@%0a## Get the group and page name%0a$pagename = ResolvePageName($pagename);%0a$page = PageVar($pagename, '$FullName');%0a$group = PageVar($pagename, '$Group');%0a$name = PageVar($pagename, '$Name');%0a@]%0a%0aNote the importance of [[#configphp-order|the order of customizations in @@config.php@@ above]] to avoid caching problems.%0a%0aIf you need the verbatim group and page name (from the request) early in @@config.php@@, $pagename is guaranteed to be set to%0a# Any value of ?n= if it's set, or%0a# Any value of ?pagename= if it's set, or%0a# The "path info" information from REQUEST_URI (whatever follows SCRIPT_NAME), or%0a# Blank otherwise%0aaccording to [[https://pmichaud.com/pipermail/pmwiki-users/2011-May/058905.html|this posting]]%0a%0aQ: Can I remove items from the wikilib.d folder on my site?%0aA: The files named Site.* and SiteAdmin.* contain parts of the interface and the configuration and they should not be removed. The other files named PmWiki* contain the documentation and could be removed.%0a%0aQ: How do I customize my own 404 error page for non-existent pages?%0aA: To change the text of the message, try editing the [[Site.PageNotFound]] page.%0a%0aQ: Is the order of customizations in config.php important?  Are there certain things that should come before or after others in that file?%0aA: Yes, see [[LocalCustomizations#configphp-order|Order of the commands in @@config.php@@]].%0a%0aQ: I have an online hosted wiki, and a local copy on my home computer. How can I differentiate in config.php whether I'm online or on the local computer? So that I don't have to maintain the config.php twice.%0aA: You can try something like the following: %0a%25hlt php%25[@%0aif($_SERVER['SERVER_ADDR'] == '127.0.0.1') {%0a  # Home wiki%0a%0a}%0aelse {%0a  # Online wiki%0a%0a}@]%0aA: You can add %25hlt php%25@@$EnableDiag = 1;@@ to config.php for both servers, and look at ?action=diag.%0a%0aA: The [[https://www.php.net/manual/en/reserved.variables.server.php|$_SERVER]] variable will have different values on the different servers, notably 'SERVER_ADDR' or 'SERVER_NAME'. You can configure the different wikis based on the different values.%0a
time=1678637312