1 version=pmwiki-2.3.7 ordered=1 urlencoded=1
6 name=PmWiki.GroupCustomizations
8 targets=PmWiki.WikiGroup,PmWiki.WikiAdministrator,PmWiki.LocalCustomizations,PmWiki.GroupHeaders,PmWiki.Passwords,PmWiki.PasswordsAdmin,PmWiki.SecurityVariables,PmWiki.WikiCascades,Cookbook.LocalCSS,PmWiki.LayoutVariables,PmWiki.BasicVariables,PmWiki.GroupAttributes,PmWiki.WikiFarms,PmWiki.HierarchicalGroups
9 text=(:Summary: How to customize a subset of your wiki:)%0a(:Audience: administrators (intermediate) :)%0aOne of the purposes of [[Wiki Group]]s is to allow a [[Wiki Administrator]] to customize the features of PmWiki on a per-group basis. Here is where ''per group customizations'' come into play.%0a%0a!! Group-specific PHP and CSS %0a%0aThe ''@@local/@@'' subdirectory is used to hold local configuration files. %0a%0aThe ''@@pub/css/@@'' subdirectory is used to hold local css files.%0a%0aTo perform [[local customizations]] for a particular WikiGroup, %0a* place the customizations in a file called "''@@%3cgroupname>.php@@''" (where ''@@%3cgroupname>@@'' is the actual name of the page group in question) in the ''@@local/@@'' subdirectory %0a* place the CSS customizations in a file called "''@@%3cgroupname>.css@@''" (where ''@@%3cgroupname>@@'' is the actual name of the page group in question) in the ''@@pub/css/@@'' subdirectory.%0aThese files will be automatically processed after processing any local customizations in the ''@@config.php@@'' and ''@@local.css@@'' files.%0a%0aFor example, to change the image displayed in the upper-left corner of pages in the "@@GroupName@@" WikiGroup, one could create ''@@local/GroupName.php@@'' containing%0a->%25hlt php%25 [@%0a%3c?php%0a $PageLogoUrl = "/myimages/chess.gif";%0a@]%0aThe example's effect would cause all pages in the @@`GroupName@@ [[Wiki Group]] to use "@@/myimages/chess.gif@@" as the logo image instead of the default.%0a%0aTo add markup to the beginning or end of each page in a wiki group, see [[Group headers]].%0a%0a!! Per-page customizations%0a[[#PerPage]] PmWiki also allows per-page customizations; simply use the full name of the page to be customized instead of the group. For example, one can use the file ''@@local/Chess.`HomePage.php@@'' to set local customizations for Chess.`HomePage.%0a%0aAlmost any customization that would be placed in ''@@config.php@@'' can be used as a per-group or per-page customization. %0a%0aAn important exception to this is setting '''per-group or per-page customizations for recipe scripts''' included in @@config.php@@. Most recipe scripts would need any customization variables defined before the script is included. Instead of using a per-group or per-page customization php file, use a per-group or per-page conditional statement in @@config.php@@, before including the recipe script. Example:%0a%0a->%25hlt php%25[@%0a## Inclusion of per-page and per-group local php scripts%0a$pagename = ResolvePageName($pagename);%0ainclude_once("$FarmD/scripts/pgcust.php");%0a%0a$page = PageVar($pagename, '$FullName');%0a$group = PageVar($pagename, '$Group');%0a//per-group customizations:%0aif($group=='GroupName') {%0a $RecipeVariable = 'valueA';%0a etc. ...%0a}%0a//per-page customizations:%0aif($page=='GroupName.PageName') {%0a $RecipeVariable = 'valueB';%0a etc. ...%0a}%0a//include recipe after variables are set:%0ainclude_once('cookbook/recipescript.php');@]%0a''Required reading: [[LocalCustomizations#configphp-order|Order of the commands in @@config.php@@]].''%0a%0a%25red%25 Note that this method cannot be used to set $DefaultPasswords, you should use Group or Page attributes. See [[Passwords]] and [[PasswordsAdmin]] for more information.%0a%0a[[#processingorder]]%0a!! Processing order%0aFor all local customizations, PmWiki first processes the ''@@local/config.php@@'' file, and then looks for a per-page customization file in the ''@@local/@@'' subdirectory to process, followed by any per-group customization file. If no per-page or per-group customizations are loaded, then PmWiki loads ''@@local/default.php@@''. If a per-page customization wants to have the per-group customizations loaded first, it can do so directly by using PHP's %25hlt php%25[@include_once()@] function.%0aFor more information see [[(PmWiki:)wiki cascades]].%0a%0a!! Custom CSS styles per group or per-page%0aTo apply CSS styles to pages of a specific group named [@Group Name@], create a file named ''@@GroupName.css@@'' in the ''@@pub/css/@@'' directory and add the CSS style rules there. To apply styles to a specific page, create a file ''@@GroupName.PageName.css@@'' in this directory with your style rules. Any CSS rules to be applied for all wiki pages can be put into ''@@pub/css/local.css@@''.%0a%0a->%25hlt css%25[@%0a body { background: #F4C4B4; }%0a@]%0a%0aSee also $WikiPageCSSFmt and Cookbook:LocalCSS.%0a%0a!! Preventing group-Level configurations%0aAny customization file can set $EnablePGCust=0; to prevent later page/group/default customizations from being automatically loaded. If a per-page customization needs to have the per-group customizations loaded first, it can do so directly by using PHP's %25hlt php%25[@include_once()@] function.%0a%0a!! Authentication%0aAny passwords required for a group should be set in the group's [[Group Attributes]] page (see [[Passwords Admin]]istration) and not in a group customization file.%0a%0a!! Consider Wiki Farms%0a[[Wiki Group]]s are an easy way to host multiple sites in a single PmWiki installation by giving each site its own group. Another approach is to use [[Wiki Farms]], which allows each site to have its own set of [[Wiki Group]] and local customization files.%0a%0aIf you are looking for nested group levels, you may want to consider [[PmWiki:HierarchicalGroups|Pm's design considerations on hierarchical groups]].%0a%0a!! FAQ%0a>>faq%3c%3c [[#faq]]%0aQ: How can I apply CSS styles to a particular group or page?%0a%0aA: Simply create a ''@@pub/css/Group.css@@'' or ''@@pub/css/Group.Page.css@@'' file containing the custom CSS styles for that group or page. See also Cookbook:LocalCSS.%0a%0aQ: Why shouldn't passwords be set in group (or page) customization files? Why shouldn't group or page passwords be set in @@config.php@@?%0a%0aA: The reason for this advice is that per-group customization files are only loaded for the current page. So, if %25hlt php%25@@[=$DefaultPasswords['read']=]@@ is set in ''@@local/GroupA.php@@'', then someone could use a page in another group to view the contents of pages in GroupA. For example, Main.WikiSandbox could contain:%0a%0a--> %25pmhlt%25[@(:include GroupA.SomePage:)@]%0a%0aand because the ''@@GroupA.php@@'' file wasn't loaded (we're looking at Main.WikiSandbox --> ''@@local/Main.php@@''), there's no read password set.%0a%0aThe same is true for page customization files.%0a%0aQ: Isn't that processing order strange? Why not load per page configuration last (that is after global configuration an per group configuration)?%0a%0aA: Many times what we want to do is to enable a certain capability for a group of pages, but disable it on a specific page, as if it was never enabled. If the per-group config file is processed first, then it becomes very difficult/tedious for the per-page one to "undo" the effects of the per-group page. So, we load the per-page file before the per-group.%0a%0aIf a per-page customization wants the per-group customizations to be performed first, it can use the techniques given [[#processingorder|above]] (using %25hlt php%25@@include_once()@@ or setting @@[=$EnablePGCust = 0;=]@@).%0a
