1version=pmwiki-2.2.122 ordered=1 urlencoded=1 2author=Petko 3charset=UTF-8 4csum=%25hlt php%25 5name=PmWiki.LocalCustomizations 6rev=100 7targets=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 8text=(: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%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 include_once scripts/xlpage-utf-8.php,%0a* next call 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 or per-group 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%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 in bold. 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: [[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|Notepad2]].%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%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 @@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->%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%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 [[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]]. 9time=1574411138 10