version=pmwiki-2.2.89 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=Byte Order Mark (more popular than Mask)
name=PmWiki.LocalCustomizations
rev=85
targets=PmWiki.GroupCustomizations,PmWiki.WikiAdministrator,PmWiki.DocumentationIndex,PmWiki.Skins,PmWiki.Internationalizations,PmWiki.CustomMarkup,PmWiki.InterMap,PmWiki.PmWikiPhilosophy,PmWiki.Variables,Cookbook.ControllingWebRobots,Cookbook.Cookbook,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->[@$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%0a->[@%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->[@include_once("cookbook/recipefile.php");@]%0aand%0a->[@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[[#configphp-order]]%0a!!! Order of the commands in config.php %25color=#eee%25'-[[#configphp-order|(link)]]-'%25%25%0a%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 include_once scripts/xlpage-utf-8.php,%0a* next call XLPage() which needs the definitive (rw) $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,%0a* any direct function call in config.php, like ResolvePageName(), CondAuth(), PageTextVar(), PageVar(), RetrieveAuthPage(), or others, if possible, should be done near the end of config.php.%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: [[http://kate-editor.org/ |Kate]] (for KDE), [[http://www.geany.org/ |Geany]], [[http://www.arachnoid.com/arachnophilia/index.html|Arachnophilia]], [[http://www.scintilla.org/SciTE.html|SciTE]], [[http://bluefish.openoffice.nl/|Bluefish]], [[http://www.vim.org/|vim]] and others.%0a* Windows: [[http://notepad-plus-plus.org/ |Notepad++]], [[http://www.contexteditor.org/|ConTEXT]], [[http://www.flos-freeware.ch/notepad2.html|Notepad 2]].%0a* OS X: [[http://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%0a  h1, h2, h3, h4, h5 { color: #880000; } /*dark red titles*/%0a  a { text-decoration: none; } /* don't underline links */%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 @@include_once(...)@@ 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->[@$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%0a->[@%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 [[http://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]].
time=1471897052