Fox

Summary: Form processor to add, replace, copy, delete content plus upload files and send email notifications using templates and Input markup
Version: 2017-12-04
Prerequisites: PmWiki 2.2.76, PHP 5.4 minimum
Status: stable
Maintainer: HansB
License: GPL2
Download: fox.phpΔ
Users: +13 (View / Edit)
Discussion: Fox-Talk

Overview

Fox is a PmWiki form processing extension, to process the input from form controls such as text boxes, drop-down select boxes, radio buttons and check boxes etc and create output using templates and the submitted text and content, which will be saved to the current page or other target pages, even to multiple pages or email notifications. more...

Full Documentation

Installation & Security Configuration (from the documentation)

Requires PmWiki 2.2.76, PHP 5.4 minimum

Install by downloading, and copying Cookbook/fox.phpΔ to a (new) cookbook/fox/ directory and Cookbook/fox.cssΔ to a pub/fox/ directory, and adding to your local config file:

include_once("$FarmD/cookbook/fox/fox.php");

Page permissions need to be set, either in a local config file or on SiteAdmin.FoxConfig, before Fox can do any work!
This measure has been added to provide full security, especially important if you want to enable Fox for form posting on edit-protected pages.

By default Fox is prohibited from posting to any page. $FoxPagePermissions need to be set with page patterns and associated actions for Fox to be able to do anything, with only a few exceptions!

An admin can set a number of variables to control some posting permissions, as local configurations, sitewide in config.php or restricted to groups or pages. All Fox configuration variables need to be set before including the fox.php script. Do not use local/Group.php or local/Group.Name.php files for setting configuration variables, if you use include_once(.....fox.php...) in config.php, as such customisation files will only be loaded after config.php! Use conditionals in config.php instead. See the example below.

$FoxAuth = 'edit';
By default users with edit permission are allowed to post. Set $FoxAuth = 'read'; to open posting to pages which are edit protected. Set $FoxAuth = 'ALWAYS'; to allow posting even to pages which are read protected (private pages). Consider setting $FoxAuth to the right level for just the pages you need, using conditionals in config.php, before including fox.php. If you want logged in users to post, but not allow them to edit pages, consider adding a new authorisation level: Adding AuthLevels
$EnablePostDirectives = false;
By default users are not allowed to post directives of form (:...:). Set $EnablePostDirectives = true; to allow posting of directives.
$EnableFoxUrlInput = false;
By default input via url parameters is not permitted. Setting it to 'true' will allow such input.
$EnableAccessCode = false;
By default a special random generated access code is not required. Set $EnableAccessCode = true; to require use of access code. You need to provide also a hidden accesscode field and a text field named access for a user to enter the access code displayed, via a page variable {$AccessCode}.
$EnableFoxDeleteMsg = false;
Set to true if you want a delete confirmation message displayed when clicking any delete links or buttons. If desired, change $FoxDeleteMsg, the default confirmation message, which is:
$FoxDeleteMsg = 'Please confirm: Do you want to delete this post?';
$FoxPagePermissions['namepattern'] = 'action';
This is an array of page name patterns as keys and allowed or disallowed Fox actions as values. By default it is prohibited to post to any pages. The admin needs to add patterns and associated actions in order for Fox to be permitted posting or deleting posts etc. Page name patterns can be added to SiteAdmin.FoxConfig (you need to create this page, see example below) or to a local config file (for instance config.php) using
$FoxPagePermissions['namepattern'] = "actionname,actionname,..";. Action names are add, replace, ptv, copy, newedit, delete, pagedelete, mail, all, none. all meaning all Fox actions are allowed, none meaning no Fox actions are allowed. See examples in box below.
Exceptions
Fox is allowed to post to the page which contains the form (current page) and to other pages if certain string patterns are present in the page. Fox looks for strings (:foxprepend, (:foxappend or (:foxallow and for (:fox formname .
$FoxConfigPageFmt = '$SiteAdminGroup.FoxConfig';
Default page for page permission patterns (you need to create it if you want it, alternatively add to the FoxPagePermissions array). Add each patterns on a new line, like Test.*: add,delete (this will allow posting and deleting of posts (via Fox delete links) to any page in the Test group). These patterns are read as part of $FoxPagePermissions.

Configuration example for config.php:

# allow comment posting for all visitors in group 'Public'
$group = PageVar($pagename, '$Group');
if ($group=='Public') {
   $FoxAuth = 'read';
   $FoxPagePermissions['Public.*'] = 'add';
}
# allow all foxactions on all pages for admin 
if (CondAuth($pagename,'admin')) {
   $EnableFoxUrlInput = 'true';
   $FoxPagePermissions['*.*'] = 'all'; 
}

Page permission example using SiteAdmin.FoxConfig:

# allow adding or deleting posts for pages in Test group:
Test.*: add,delete
# allow adding but deny deleting posts for pages in Data group:
Data.*: add,-delete
# Deny any Fox actions in SiteAdmin group:
SiteAdmin.*: none
# Allow all actions on all pages (if you can trust all editors)
*.*: all

Latest Version History (full history)

  • 2017-12-04: small code improvements for template markup and for the way foxdelete links are constructed via templates.
  • 2017-06-21: simpler code for callbacks in var replacements, needs PHP 5.4 minimum. A more complicated version (fox-pre54.php) is available for older pre PHP 5.4 systems.
  • 2017-06-16: replaced Markup_e() calls with Markup() calls, and replaced RE() calls with preg_replace_callback() calls, both changes for PHP 7.2 compatibility.
  • 2017-05-20: Major code update: Fox will process all foxactions for one target page in one go, with page being opened and saved just once, for speedier processing. Bugfix for foxtemplate parameter, which will now work without problems in foxadd and foxreplace markup directives, even with multiple markups targeted to same page. Current page set as default for foxaction='display'. Some internal variables and functions are renamed while revising the code for creating a page target list and processing the targets. Fixed bugs in input and template handling.

Extension Modules

  • Fox Delete - add delete links for deleting lines or sections with Fox
  • Fox Edit - add edit links for editing page sections and PTVs with Fox
  • Fox Notify - add email notifications and mailing capability to Fox forms

Example Applications (in the Cookbook)

Some example applications using Fox explained:

Contributors

User notes +13: 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.