CustomAttrForm

Summary: How to customise the prompt on the attributes page (?action=attr)
Version: 2009-07-24
Prerequisites: pmwiki 2.1 for changing the prompt; 2.2.5 for changing the actual inputs
Status:
Maintainer:
Categories: Layout Passwords

Questions answered by this recipe

How can I customise my Attributes page (?action=attr)?
How do I implement a custom AttrForm page?
How do I change or limit the input fields that display on an Attributes page?

Description

This page describes how to customise the prompt on the attributes page (?action=attr).

The process of changing what is displayed when visiting any Attributes page is a two-parter - currently, one must deal with 1) the message at the top of the page separately from 2) the actual input fields presented at the bottom of the page. The following sections deal with these two separate set-up tasks.

Changing the prompt message

The default message on any page called via ?action=attr states:

MyGroup.MyPage Attributes

Enter new attributes for this page below. Leaving a field blank will leave the attribute unchanged. To clear an attribute, enter 'clear'.

If you want to create your own custom prompt message, simply

  1. create a new page at Site.AttrForm? and add whatever text and PmWiki markup you want to show up at the top of the attributes page
  2. add the following line of code to config.php:
    $PageAttrFmt = 'page:Site.AttrForm';
NOTE: This only changes the text above the password inputs on the attributes page, but doesn't change the inputs themselves - the inputs have to be dealt with separately. We'll talk about that below.

Example: CustomAttrForm with 3-Tiered Auth

The following example (and the one in the next section) assumes a 3-tiered approach (admin-, attr-, & edit-users) to password set-up, geared for Group Projects that have their own Group on the wiki, with a Group "Admin" who maintains the group, and a single 'edit' password assigned for anyone else who is eligible to participate and add content. This setup only uses passwords, and no usernames. There are obviously other ways to do this, and differing scenarios, but this is the setup I find useful and hopefully it'll be useful for illustrating. It assumes the following password-setup:

  • attr-password: created by the Group's Admin (attr-level) when the new group is created. Before the Group Admin has arrived, there might be no default edit- or attr-passwords set for the site, or perhaps the Wiki Admin has assigned some openly known default passwords, as set up in config.php:
    $DefaultPasswords['attr'] = crypt('edit_password');
    or $HandleAuth['attr'] = 'edit';.
  • edit-password: also created by the Group Admin (attr-level)
  • uploads-password: @_site_edit
  • read-password: no password

And so here specifically are the roles and abilities that we've set up:

  1. the group editors (auth edit) - the collaborators who have a password that enables them to:
    • create new pages within the group
    • edit pages within the group
    • upload files
  2. the group admin (auth attr) - the person(s) who starts and "administers" or "maintains" this group with a separate password, and has the power to do all of the edit-priviledges above, plus the ability to:
    • change the edit password
    • delete pages
    • set up email notifications
  3. the wiki admin (auth admin) - the Real Admin, who possesses the admin password for the whole site

Here's an example of a CustomAttrForm (pasted into Site.AttrForm) that addresses this scenario when either the Group-Admin or entire Wiki Admin visit MyGroup.GroupAttributes?action=attr:

/* THESE ARE THE INSTRUCTIONS FOR THE ADMIN & ATTR FORMS FOR CHANGING PASSWORDS */
(:linebreaks:)

[-[[{*$Group}/ | < Back to {*$Group}]]-]
!!{*$Groupspaced} :: Passwords

>>indent<<
/* INSTRUCTIONS FOR ADMIN, WITH REMINDERS, ETC - FOR ANY PAGE ON THE WIKI */
(:if expr auth admin && name GroupAttributes:)
Enter new default attributes for ''all pages'' in the group: '''''{*$Group}'''''.
(:if expr auth admin && !name GroupAttributes:)
Enter new attributes for this page only: '''''{*$Group}/{*$Name}'''''.
(:if auth admin:)
Leaving a field blank will leave the attribute unchanged.
Some common password inputs:
* To clear an attribute, enter ''clear''.
* To allow a page to be edited even if a group or site password is set, enter ''@nopass''
* To lock a page for everybody but the admin, enter ''@lock''
* To assign the any of the site's site-wide passwords, enter \
''@_site_edit'', ''@_site_read'', ''@_site_admin'' or ''@_site_upload''

/* MESSAGE FOR ATTR USERS, i.e. THE GROUP-ADMIN, ONLY ON THE GROUPATTRIBUTES PAGE */
/* Exclude any Groups that you don't want to display this message */
(:elseif expr auth attr && name GroupAttributes && !group Site,Main,PmWiki:)
Enter your new, ''case-sensitive'' password below.
Leaving a field blank will leave the password unchanged.
You may need to login again after changing your password.

/* Instruction on implementing Group Passwords */
'''For Groups:'''

## Decide on two separate passwords -- an ''adminPassword'' and an ''editPassword''.
*** The ''adminPassword'' is for you to maintain the group
*** The ''editPassword'' is for everyone in the group to edit pages and add content.
## Fill out the password blanks like this:

-->''Set new edit password:''   adminPassword  editPassword
-->''[-(that's right, put both passwords in, with a space in between them)-]''

-->''Set new attribute password:''   adminPassword
-->''[-(the term "attribute" is PmWiki-lingo referring to the ability to change passwords -\
only the group admin should be able to do this)-]'' 

->That should do it.

If you run into any problems, just contact the [[mailto:webmaster@mysite.com | webmaster]] for some help.
(:ifend:)
>><<

overtones99 July 24, 2009, at 10:13 PM

To the Group-Admin (auth attr), the message on the GroupAttributes page should now look like:

< Back to MyGroup?

My Group :: Passwords

Enter your new, case-sensitive password below.
Leaving a field blank will leave the password unchanged.
You may need to login again after changing your password.
For Groups:
  1. Decide on two separate passwords -- an adminPassword and an editPassword.
    • The adminPassword is for you to maintain the group
    • The editPassword is for everyone in the group to edit and add content.
  2. Fill out the password blanks like this:
Set new edit password: adminPassword editPassword
(that's right, put both passwords in, with a space in between them)
Set new attribute password: adminPassword
(the term "attributes" is PmWiki-lingo referring to the ability to change passwords - only the group admin should be able to do this)
That should do it.

If you run into any problems, just contact the webmaster -> mailto:webmaster [snail] mysite [period] com for some help.

And for the Admin of the entire site (auth admin), the message on any Attributes page should now look like:

< Back to MyGroup?

My Group :: Passwords

Enter new attributes for this page below.
Leaving a field blank will leave the attribute unchanged.
To clear an attribute, enter 'clear'.
Some common password inputs include:
  • for a page that can be edited even if a group or site password is set: @nopass
  • to lock a page for everybody but the admin: @lock
  • to assign the site's site-wide passwords: @_site_edit, @_site_read, @_site_admin or @_site_upload

Changing the fields

The following information applies to PmWiki 2.2.5 (not-yet-released as of 7/25/09) and beyond, due to a bug in the core that previously prevented the following from working correctly...

When visiting an Attributes page via ?action=attr, one usually sees a default set of four password inputs: read, edit, attr, and upload. In order to limit which fields appear, then you'll have to actually substitute your own function for PmWiki's PrintAttrForm function - the function that determines which $PageAttributes currently exist, and then generates an input field for each of them - with your own conditional code plugged into it. Here's how to accomplish this:

  1. add the following line of code to config.php:
    $HandleAttrFmt = array(&$PageStartFmt, &$PageAttrFmt, 'function:MyPrintAttrForm', &$PageEndFmt);
  2. then, create your own custom PrintAttrForm function, calling it MyPrintAttrForm, and add it somewhere in config.php (the name doesn't matter, as long as it matches whatever you put in the above statement for 'function:MyPrintAttrForm'). Below is an example of what this might look like:

Example: MyPrintAttrForm Function

For this scenario, please imagine the 3-tiered password structure (admin, attr, edit) that was used in the previous example. We have created a new function, MyPrintAttrForm, to substitute for PmWiki's PrintAttrForm, and pasted it into config.php. The new function is basically a copy of MyPrintAttr with some conditionals included.

# Have the HandleAttrFmt function call our function instead
$HandleAttrFmt = array(&$PageStartFmt, &$PageAttrFmt, 'function:MyPrintAttrForm', &$PageEndFmt);
# Our new function, substituting for PrintAttrForm in pmwiki.php
function MyPrintAttrForm($pagename) {
  # ALL OF THIS TOP PART IS THE SAME AS IN THE ORIGINAL PrintAttrForm FUNCTION
  global $PageAttributes, $PCache, $FmtV;
  echo FmtPageName("<form action='\$PageUrl' method='post'>
    <input type='hidden' name='action' value='postattr' />
    <input type='hidden' name='n' value='\$FullName' />
    <table><br>",$pagename);
  $page = $PCache[$pagename];  
  foreach($PageAttributes as $attr=>$p) {
    if (!$p) continue;
    if (strncmp($attr, 'passwd', 6) == 0) {
	$setting = PageVar($pagename, '$Passwd'.ucfirst(substr($attr, 6)));
	$value = '';
    } else { $setting = @$page[$attr]; $value = @$page[$attr]; }
    $prompt = FmtPageName($p,$pagename);

    # THIS IS WHERE YOU MIGHT ADD SOME CONDITIONALS, 
    # LIMITING CERTAIN INPUTS TO ONLY APPEAR ON CERTAIN PAGES OR FOR CERTAIN USERS
    # IT'S A LOOP, GOING THROUGH EACH OF THE ATTRIBUTES COLLECTED IN THE $PageAttributes ARRAY
	## my 3-tiered Group Version: only display 'edit' & 'attr' for attr-users
	if( # if admin, show all
	    CondAuth($pagename, 'admin')
	     ||
	    # if user has attr-privileges, show 'edit' and 'attr' fields
	    ( strpos($attr,'edit')==true || strpos($attr,'attr')==true )
	   )
	{
           # this is simply the Input field that will appear for each attribute 
           # for which the above conditional proves true - probably want to leave this alone
	    echo "<tr><td><i>$prompt</i></td>
		<td><input type='text' name='$attr' value='$value' /></td>
		<td>$setting</td></tr>";
	}
  }
  echo FmtPageName("</table><input type='submit' value='$[Save]' /></form>", $pagename);
}

overtones99 July 24, 2009, at 10:13 PM

Notes

Release notes

  • 2009-07-25 - new recipe page

See also

Contributors

overtones99

Comments

See discussion at CustomAttrForm-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.