• View
• Edit
• History
• Attach
• Print
• Backlinks

Fox

See also Fox-Comments

Questions answered by this recipe

How can I set up comment and other forms to post to various pages?
How can I allow users to post comments and other forms, without giving them edit access?
How can I allow users to be able to delete their posts, without giving them edit access?
How can I build a forum, CMS, a blog, a contact list, an appointment list, an address book?

Overview top

Fox is a form processing extension, using PmWiki's built in Input forms. Fox will process the input from form controls such as text boxes, drop-down select boxes, radio buttons and check boxes etc and create output with use of templates, which can be saved to the current page or other target pages, even to several pages.

In its default mode Fox will not overwrite or delete any pages, but will add content at the bottom (the default), or the top, or other specific places in the target page(s), or an anchored page section. The template Fox uses can be a character string, or a section in a template page, or a whole page, including standad pmWiki markup for formating etc. Special replacement variables in the template will be replaced with values from the associated input control fields.

Fox can save input as PTVs (page text variables), and will add and update PTVs as required. PTVs can be saved in different formats, the default is a "hidden" markup format, other formats are as special text list (used by the recipeinfo box at the top in the cookbook group here), or as definition list, or as anchored section. Input from an array of controls (for instance checkboxes) will be saved as a comma separated list.

A special replace action can replace content on a target page or page section. Using marks and keywords Fox can be used as a string replacement tool (search and replace), even using regular expressions, or overwrite whole sections or pages with new content, again using a template to create formatted output.

The copy action will copy source page content (as template) to a target page, or a section from a source page to a section of a target page, without changing anything. This means that input from controls is ignored, no variable replacements are performed and no template is processed. Instead the template page content becomes the source for the copy action, and the target page content will be exactly the same.

Last but not least, by using a display action, Fox can direct the output to appear at a specific location on the page, without it actually been saved to the page. This is very useful to display content from other pages, to display search results, or data from PTVs selectable by a user through input form controls.

Fox has a number of extensions: special delete links or buttons can be added with FoxDelete, with which either single lines added by Fox or whole multi-line additions can be deleted. For this Fox uses special markup as spaceholders on the template. Edit links can be added with FoxEdit. Through such links can parts of a page like sections or PTVs, or a whole page, be loaded into custom Fox edit forms, for instance to edit PTV data with each PTV value in a text box. FoxNotify is an email notification extension integrated with Fox forms.

Fox has various security configuration to control which fox action shall be allowed for which pages or wiki groups, and what level of authorisation is needed for users to submit form input. Even users who do not have edit rights can be allowed to submit input, and some special security features help controlling misuse, for instance built-in Captcha support and disabling of posting markup directives or expressions.

Fox can be used to direct output to multiple pages, using multiple templates, with the possibility to mix different fox actions for different pages. Even pagelists can be used to set target pages, and wiki wildcard pagenames with the help of markup expressions from PowerTools.

Fox has grown substantially, out of modifications and improvements to AddDeleteLine2, combining most of its features and the best of CommentBoxPlus, and adding many new features.

Fox has a growing list of applications, and many application examples are documented in the cookbook.

Installation top

Requires PmWiki 2.2.0 beta.

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

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. Read below about security configuration settings.

Usage

Fox Form Markup top

Fox can be applied in numerous ways, but basically it provides special markup to replace the (:input form ..:) and (:input end:) directives while using all the other (:input:) directives (see Input), and processing the submitted form input for formatted output to some page(s) or location.

Start of form:

End of form:

In addition to the start and end fox markup you can use some special markups in between. Each of these can be used multiple times, and Fox will build a list of target pages with associated templates and other parameters included in each markup:

(:foxadd ''TemplatePage=>TargetPage'' ... :)

for adding content.

(:foxreplace ''TemplatePage=>TargetPage'' ... :)

for replacing content.

(:foxcopy ''TemplatePage=>TargetPage'' ... :)

for content copying (no variable replacements). Note that only the template gets copied as content. Any page attributes of the template page are ignored!

(:foxptv TargetPage ptvfields=.. ptvfmt=.. ptvclear=.. :)

for adding and updating PTVs (page text variables)

(:foxmail template=EMailTemplate target=EMailList :)

for sending email message to small group of recipients on EMailList (needs FoxNotify).

Page sections can be used for templates as well as targets, like DisplayTemplates#topic and TargetPage#section, and full page names can be used, as well as multiple TemplatePage=>TargetPage pairs (see more below on multiple targets).

(:foxtemplate "one line template string":)

for forms needing no multiline template. The foxtemplate markup will be used if no template pages are specified. You can only use it once in a form. It is convenient for a quick and short templates. Note that \n will create a line break.

(:foxpreviewtemplate "one line template string":)

optional alternative template for preview invoked by a 'Preview' button.

(:foxcheck name .... :)

setting input validation checking for inut field name. See Input Validation

Parameters: top

• formname is a required unique name for the form, which needs to be specified as the first parameter in the fox and foxend markup.

Optional parameter foxaction

foxaction=display

the output will be displayed at the page location marked with the (:foxdisplay:) or (:foxdisplay formname:) markup, and will not be saved to the page.

foxaction=copy

Instead of adding content, content will be copied, without any template processing.

foxaction=replace

Instead of adding content, existing content will be replaced with new content. The template will be processed and evaluated.

foxaction=mail

form output will create email message and sent to recipients listed on target page, with help of FoxNotify.

Options for adding content (the default) or the (:foxadd ....:) markup

put=

a keyword designating where Fox will add the new content on the page. It defaults to bottom of a page or section. (deprecated formerly place=).

put=top

adding content to the top of the page (deprecated formerly #top).

put=bottom

adding content to the bottom of the page (default) (deprecated formerly #bottom).

put=aboveform

adding content above the form (deprecated formerly #append).

put=belowform

adding content below the form (deprecated formerly #prepend).

put=above and mark=STRING

adding content above the line with a marker given with parameter mark=STRING.

put=below and mark=STRING

adding content below the line with a marker given with parameter mark=STRING.

put=insert and mark=STRING

adding content after (right of) a marker given with parameter mark=STRING.

put=insertbefore and mark=STRING

adding content before (left of) a marker given with parameter mark=STRING.

Alternatively using markup as marker:

(:foxappend formname:) or (:foxprepend formname:)

two markups used as placement markers for posts to be appended or prepended; these take precedence over the above. Warning : this directive must have a text before the top of the page, either it did not work.

(:foxprepend formname #markername:) or (:foxappend...

extending the above by adding an anchor marker name. Using an input control to choose amongst options, and naming it foxplace, one can post to different markers according to the choosen option, as a way gather votes. See FoxVoting example.

Options for foxaction=replace, or the (:foxreplace ...:) markup:

put=string and mark=STRING

replace first occurrence of string given with mark=STRING with new content.

(:fox ReplaceString foxaction=replace put=string target={$FullName} :)
(:foxtemplate "{$$newstring}":)
(:input text mark :)
(:input text newstring :)
(:input submit post 'Post':)
(:foxend ReplaceString :)

put=all and mark=STRING

replace all occurrences of string given with mark=STRING with new content.

put=allplus and mark=STRING

replace all occurrences of string given with mark=STRING with new content, even any STRING found in fox forms.

put=regex and mark=REGEX

replace all occurrences of regular expression given with mark=REGEX with new content, even any REGEX match found in fox forms.

put=marktomark and mark=STRING and endmark=STRING

replace content between two markers in page specified with parameters mark=STRING and endmark=STRING with new content.

put=overwrite

replace all content with new content.

More optional parameters:

template=TemplatePage

Fox will use TemplatePage to format the post. GroupName.TemplatePagename is allowed too. See about use of template below. Use template=0 if no template is required. Alternatively fox will use a one-line template string provided in a directive (:foxtemplate "template string":). If used this needs to be put between form start and end. A template page specified has priority and overrides any template string given. The template string can be only a single line. For multi-line templates create a template page.

target=PageName

Fox will post to page PageName instead of the current page. GroupName.PageName is allowed too. If a list of page names is given Fox will post to each page, using a corresponding template. See below.

foxtemplate="String"

Fox will use template String.

uptarget=PageName and upload=1

input from a file input box (or several) will be used to upload file(s) to target page. See Upload Files input form

redirect=PageName and redirect=1

After posting Fox will redirect to page PageName. The default is to stay on the current page. redirect=1 will redirect to targetpage, or last in list. redirect=URL will redirect to url string given. Note that you can specify also an anchor to redirect to a page section, and url arguments, if you want to pass on arguments or open a page with a certain action.

cancelredirect=PageName

When using a Cancel button (a submit button with 'cancel' instead of 'post' as the control name) Fox will redirect to PageName. All options of redirect= apply to cancelredirect as well.

foxfilter=filter1,filter2,filter3,..

tells Fox to apply custom filters for preprocessing field values See below.

foxfields=name1,name2,name3,..

can be used to tell Fox which fields may possibly be not set and empty, as happens when using checkboxes. Can also be used as (:input hidden foxfields name1,name2 :).

formcheck=name1,name2,name3,..

will enable javascript checking if any of the fields named are empty, display a warning message and prevent posting till fields have values.

keepinput=1 or keepinput=name1,name2,..

After successful posting all input values or values of named fields will be redisplayed in the fields. Default is that entered values will be cleared from all fields if the post was successful. If the posting was aborted values will be redisplayed.

pagecheck=1

Fox will not post if target page exists.

pagecheck=PageName1,PageName2,..

Fox will not post if any of the named pages exist.

foxcheckmsg=String

Message displayed with markup (:foxmessages:) after an input error raised by (:foxcheck ...:) markup. Default is an error message set by config variable $FoxCheckErrorMsg = 'Please enter valid input!';

foxsuccess=String

Message displayed with markup (:foxmessages:) after successful posting. The target pagename can be added by using a replacement variable like {$$target} or as a link using [[{$$target}(?action=browse)]].

foxfailure=String

Message displayed with markup (:foxmessages:) after failed posting. The target pagename can be added as for foxsuccess above.

Parameters for adding and updating PTVs :

ptvtarget=PageName

Fox will replace the value for any PTV on page PageName for which it has an input value from a field with the PTV name. If you need to restrict the PTV update to certain named PTVs, use the next parameter as well. See also Adding and Updating PTVs below.

ptvfields=name1,name2,name3,..

If this is given Fox will only replace values for the PTVs named. ptvtarget=PageName needs to be specified as well.

ptvfmt=text or deflist, or section

Sets format of PTVs for adding new PTVs specified with ptvfields. Default is hidden PTV.

ptvclear=name1,name2,name3,..

On form submission any named fields which are empty (with no value, but not 0) will clear the corresponding PTVs (erasing their values). This option allows empty input on specific input fields. Normally empty input will be ignored, and in order to clear a PTV a special keyword needs to be used. This is defined with variable $FoxClearPTVFmt and defaults to the keyword NULL: input of NULL will clear a PTV.

ptvclear=1

as above, but effective for all input fields saving to PTVs.

ptvupdate=1

Fox will use target page(s) given for ptvtargets, and update PTVs on the target page corresponding to input field names if the page exists, otherwise use a template supplied to create the page. ptvtarget= does not need to be specified.

Using Input controls top

Fox works fine with the standard PmWiki (:input type name .... :) controls. Standard input as well as array input can be processed. The name of the input control can be used as a replacement variable {$$name} in the template and in other form fields as value. When using controls for multiple selection or multiple inputs, for instance with (:input select ... :), use name[] in the form and {$$name[]} in the template to create an input array.

There are other special considerations to be made:

• As an enhancement to security the submit button needs to be named post.
• If you want to prevent the posting of empty multi-line textarea fields, name the control text.
• Do not use template as name for an input control.
• target and newedit are reserved names for target pagenames. An input text box can be used to set a pagename value. If this control is named target, Fox will post to the pagename entered, if the control name is newedit, Fox will open the target page in edit mode.
• foxgroup is a reserved name for a target group. A GroupName for the target page can be specified using an input control of name foxgroup, for instance a (:input text foxgroup:) or (:input select foxgroup GROUP1:) etc.
• Error messages can be displayed by putting markup (:foxmessage:) into the page, best just above the Fox form (recommended, as often page posting permissions are not set properly). See also use with Input Validation
• To retain input values after posting use keepinput=1 as parameter. Use keepinput=name1,name2,name3 etc. to keep the input values for fields name1, name2, name3 etc.

Upload Files input control

(:input file upfile size=60:) can be used for uploading (attaching) files. upfile in this example is the name of the control. One or several (with different names) can be used inside a fox form, in addition to other input controls. Fox will do the usual posting plus the file upload on form submission. In the (:fox formname ...:) markup either upload=1 or uptarget=TargetPageName needs to be set.

• upload=1 will direct upload attached to current page or target page set with target=PageName.
• uptarget=TargetPageName will attach upload file(s) to the page specified. Only one upload target can be specified.

To optionally rename the file use a text input box like (:input text upfile_name :) for instance. Note that it's upfile_name corresponds to the input file box name of upfile, the new name box needs to use the file box name with an added _name postfix.

The following replacement variables can be used in the template to post file attributes file name, file extension, file type and file size, or to use for input validation in (:foxcheck ...:) markup. upfile is the name of the input file control, i.e (:input file upfile:). Change it for different file controls.

• {$$upfile_name} holds the file name.
• {$$upfile_ext} holds the file extension.
• {$$upfile_type} holds the file type.
• {$$upfile_size} holds the filesize in bytes.

Upload Security: In order to successfully upload files the user needs PmWiki upload authorisation. $FoxAuth is not used.

Input Validation top See also FoxValidationExamples

Fox has two levels for input checking, simple client-side javascript and server-side php:

(:fox formname ... formcheck=name1,name2..:)

a simple client-side (instant) java script check to alert if a named input field is left empty. This is only effective if user has a javascript enabled browser. A more effective method is the following php validation.

(:foxcheck name ... :)

(:foxcheck name [match='STRING'] [regex='PATTERN'] [if='CONDITION'] [msg='ERROR MSG']:)

PHP input validation check on input from field name. You can also use a list of names; name1,name2,.. etc.

Parameters:

• name is the first argument. Or name=name1,name2,.. - There need to be input from named fields. If a named field is left empty the check fails. If the field is named by name=$:Var, use as name ptv_Var.
• match is the second argument. Or use match='STRING'. Input has to match STRING. Wiki wildcard characters are allowed.
• regex='pattern' - Input has to match regex pattern. Use this to create more precise pattern masks than match.
• if='condition' - Input has to fulfill condition. Conditions for use are the same as with the (:if ...:) conditional markup.
• msg='error message' - If the input check fails error message will be displayed using (:foxmessage ..:) markup. If msg is not set a default error message will be used instead.

(:foxmessage ... :)

(:foxmessage [formname] [name] [list=nocheck]:)

Markup to display Fox error and success messages. Output is inline text and can by styled with wiki markup, for instance like %red%'''(:foxmessage:)''' giving a red bold message.

Usage:

• (:foxmessage:) will display all Fox messages.
• (:foxmessage formname:) will display all Fox messages resulting from submission of form formname.
• (:foxmessage formname list=nocheck:) will display Fox messages from form formname but exclude all messages resulting from input checks set with (:foxcheck name ..:).
• (:foxmessage formname list=check:) will display messages resulting from input checks set with (:foxcheck name ..:), but exclude all other messages.
• (:foxmessage formname name:) will display fox error message resulting from input check set with (:foxcheck name ..:). Use this markup for instance beside each input field, to give field specific error messages right next to the field causing the error.
• If the field to be checked is named by name=$:Var (for PTVs when using (:input default source ....:)), use as name ptv_Var.

Using page variables top

You can use page and page text variables normally. You can also use them in templates. Fox provides some special page variables:

• {$FoxPostCount} will give counted number of posts on the page (use for displaying total number of posts).
• {$AccessCode} will give a three digit random number, which Fox can check against an entry in a field named access, to require users entering a random code, as a measure against robot postings. To have fox checking for a match of accesscode and access-post, the admin needs to set $EnableAccessCode to true.

Template Markup top

Any content on the template page will become part of the new page entry. PmWiki page variables are allowed. Special replacement variables are used to mark where content from input fields are placed.

{$$name}

is replaced by the value of the form input field named name

{$$name[]}

is replaced by the array values of the form input fields named name[]

{$$(expr ... )}

Markup expressions with this syntax (two $ dollar signs after the initial curly bracket ) are evaluated when the template gets processed.

{$$(ftime 'format' 'when')}

is replaced with a formatted date or time string, using MarkupExpressions#ftime (this utilises the PHP strftime function). The {$$(strftime:format)} markup is deprecated. Example for a timestamp: {$$(ftime "%A %d %B %Y %H:%M:%S")}

{$$(date:format)}

is replaced with a formatted date or time string, according to the PHP date function. Example: {$${date:d.m.Y - H:i)}

\n

is converted into a new line.

{$$foxgrouptitle}

this is created early and takes the value from a foxgroup field or parameter. It is for use where special characters and spaces may want to be preserved, as {$$foxgroup} will be replaced by a sanitised WikiWord valid for full pagenames. Use for instance to create a target group link: [[{$foxgroup}/| {$$foxgrouptitle}]]

To post replacement variables without them being replaced by a value, in order for instance to post a fox form defined as a template, use {$$$...} instead of {$$...}, i.e. {$$$name} instead of {$$name} etc.

delete links and buttons template markup

Install foxdelete.phpΔ and use the following template markup to generate delete links and buttons for deleting single lines or ranges.

{[foxdelline]}

is replaced by a delete link which can be used to delete the line it is part of.

{[foxdelline button]}

is replaced by a delete button for deleting a single line, as the link above.

{[foxdelrange]}

is replaced by a delete link which can be used to delete a range of lines, marked with special #foxbegin# and #foxend# markers. Any lines between these invisible markers, including a range delte link or button, will be deleted by clicking the link or button

{[foxdelrange button]}

is replaced by a delete button for deleting a range of lines, as the link above.

Delete link label and tooltip

a custom delete label for link or button can be specified inside the markup like for instance:

{[foxdelrange 'Delete Post']} : Delete Post will be the label for new delete links.

{[foxdelrange label='Delete Post' tooltip='delete section: abc']}: delete link with added tooltip.

Config Security Settings top

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.

$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 and allowed or disallowed Fox actions. By default it is prohibited to post to any pages in the Site and SiteAdmin groups and in the PmWiki group. 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

$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 
# (Site and SiteAdmin groups remain excluded)
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 Main group:
Main.*: none
# Allow all actions on all pages (if you can trust all editors)
*.*: all

Field Substitutions top

Values from various fields can be combined in another field. For instance the target page name can be created with input from a number of input controls:

(:input hidden target "{$$name}-{$$surname}":) 
Name: (:input text name "":) 
Surname (:input text surname "":)

Fox Filter Functions (for developers) top

You can preprocess (filter) the posted field values using custom filters. A recipe script can define its own filter function and add it to the $FoxFilterFunctions array like this:

$FoxFilterFunctions['mycustomfilter'] = 'MyCustomFilterFunction';
function MyCustomFilterFunction($pagename, $fields) {
   ...process any field values here....
   return $fields;
}

Then a Fox form can call the filter function with parameter foxfilter=mycustomfilter or as a hidden input control of form (:input hidden foxfilter mycustomfilter :)

Fox will use a series of filters in the specified order if several filter function names are given, like

You can find use of foxfilters in FoxForum. Additional examples of filters can be found in Fox-FilterExamples

Multiple Target Pages top

If a list of page names is supplied Fox will post to each page, using a corresponding template page. Use either this syntax:

(:fox formname ... target=TargetPage1,TargetPage2,TargetPage3 
template=TemplatePage1,TemplatePage2,TemplatePage3:)
etc. 

or for more flexibility use special markup (:foxadd ...:), (:foxptv ...:), (:foxreplace ... :) and (:foxcopy .... :), for example:

(:fox formname :)
(:foxadd TemplatePage1=>TargetPage1 ...parameters... :)
(:foxadd template=TemplatePage target=TargetPage ...parameters... :)
(:foxadd TemplatePage3=>TargetPage3 ...parameters.. :)
(:foxptv PTVTarget1,Target2,Target3 ..ptv parameters...:)
(:foxreplace TemplatePage3=>TargetPage3 ...parameters.. :)
(:foxcopy TemplatePage1=>TargetPage1 TemplatePage2=>TargetPage2 .... :)
....other input controls and submit button...
(:foxend formname:)

Specify either a TemplatePage=>TargetPage pair (or several), or template=TemplatePage target=TargetPage parameters.

• foxcopy will not process any replacement variables, just copy the page without change.
• You can use full page names: Group.Template=>GroupA.TargetA, and use a template section:

Template#section=>GroupA.TargetA and a section on a target page: target=TargetPage#section.

• (:foxptv ...:) does not use or require a template parameter.
• If the foxgroup=TargetGroup parameter is used to define a target group, do not use group names for your target pages. Otherwise they will become part of the name!
• If you use foxgroup and need some page target to be in a different target group, you can use a \backslash to "escape" the merging of the group part with the name: TemplatePage=\GroupB.TargetPage

Fox generates a list of template and target pairs, processing any (:foxadd ... :), (:foxptv ...:), (:foxreplace ... :) and (:foxcopy ... :) markup first, as found in sequence, and assigns actions and placements and parameters to each, using defaults if necessary. If no parameter is given, Fox will use the previous one used in the markup.

If redirect=1 is set, Fox will, after posting to all the pages, redirect to the last target page. To redirect to another page use redirect=PageName.

By setting several target-template pairs Fox can post different field values to different pages. Field substitutions will be applied generally.

To see behind the scenes how Fox assigns parameters to targets and in what order targets are processed you can set temporarily in fox.php near the beginning: $FoxDebug = 3;
On form submission Fox will echo the target array. Make sure you don't use redirect= though!

Adding and Updating PTVs (Page Text Variables) top

Fox can add content and also update PTVs on a target page. Content will be added first, PTVs updated last in Fox's processing.
By using the parameter ptvtarget=PageName Fox will update any PTV on page PageName with new input from an input field with the name of the PTV. Fox will update all PTVs it finds matching input field names. It will use whatever format the PTVs got, just replacing the values. It will not create new PTVs automatically, unless the ptvfields= parameter is used, specifying target PTVs.

Using parameter ptvfields=name1,name2,name3,.. will restrict the PTV update to the named PTVs. If the target page has not got a PTV named with ptvfields, it will be created as a hidden PTV.

Using parameter ptvfmt=keyword will create PTVs named with ptvfields and not existing in the target page according to the keyword format:

ptvfmt=text

text list format, as used in the recipeinfo section. Syntax is Name: Value, starting on a new line.

ptvfmt=deflist

definition list format, syntax is : Name : Value , starting on a new line.

ptvfmt=section

anchored section format, syntax is ''[[#name]] multi line value... [[#nameend]]

ptvfmt=hidden

(default, no need to specify this) hidden PTV format with syntax (:Name: Value:)

ptvfmt=extra

custom hidden PTV format defined in foxforum.php with syntax (::Name: Value::)

By default if a field is empty when the form gets submitted, Fox will ignore this field and will not clear any existing value of a PTV with the field name. Instead to clear a PTV you need to input a special string defined with config variable $FoxClearPTVFmt, which is by default NULL. This default behaviour can be changed with the ptvclear parameter:

ptvclear=1

any empty field when submitted will clear a corresponding PTV.

ptvclear=name1,name2,name3,..

any empty field named will clear the corresponding PTV.

To add or update PTVs on more than one target page,

• either provide a target page list for ptvtarget: ptvtarget=Target1,Target2,Target3 etc. Any ptv parmeters given will be applied to processing for all target pages.
• or use one or several markups (:foxptv Target options...:). Any ptv parameters used in each markup will be applied for the specific Target page process.

Parameter ptvupdate=1 used in the (:fox formname ..:) markup is for special cases to avoid duplicating target and ptvtarget parameters: With target=PageName template=Template ptvupdate=1 a new page can be created according to the template provided, with PTVs being created through the template and input values. But if such a form submits again to the same page, the template will be ignored and only existing PTVs will be updated. No new PTVs will be added.

Adding a 'Preview' top

Fox output can be previewed by adding a 'Preview' button to the form, plus a (:foxpreview:) markup to display the preview:

(:input submit preview 'Preview':)

Add a submit button with exact name preview and button label 'Preview' (substitute text of your choice).

(:foxpreview:) or (:foxdisplay:)

Add directive at the place in the page where you would like the preview to be shown.

(:if foxpreview:)

Optional - conditional markup to show text only when 'Preview' is clicked.

(:foxpreviewtemplate "...":)

Optional - Alternative template markup used for the preview instead of the standard (:foxtemplate "....":) or other template page.

previewtemplate=PAGENAME

Optional - Alternative template parameter used for preview instead of template=... parameter.

Fox is also specially configured to work in conjunction with FoxEdit links, so FoxEdit forms can use a 'Preview' button.

Notes top

Custom conditional author

Note that I am using also a custom conditional in some templates in my examples, to check an author name against an author field value previously set. It is defined like this in config.php:

# add conditional markup: (:if author AUTHORNAME:)
->$Conditions['author'] = "\$GLOBALS['Author']==\$condparm";

Hide Delete Links with Conditonal Markup

Adding a delete link to the template like this

will display the link only if the author name entered or previously entered and stored in the author cookie matches a value for author set previously in an author field. - This is not a foolproof secure method to prevent deletions of posts since someone else can use the same author name! The only safe way is to use (:if auth admin:){[foxdelrange]}(:if:) if $FoxAuth level is set to 'read', and to prevent viewing of th epage source by adding to the local config:

which then requires edit permission to view the source.
Or set it to 'admin' if you can't trust editors.

More on Security Considerations

If you add any line or range delete buttons or links in a template, Fox will generate special linekeys, made up of a timestamp and a random number element, to provide unique identifiers for each range of lines, or each line carrying a line delete link or button. Clicking a delete button or link will send the unique linekey attached to it, and Fox will look for the line or range of lines and delete it. I have used conditional markup in my examples to hide all delete links not associated with the author name. And generally I have not been able to delete any posts, if I could not see a delete link or button (and the opposite I find to be true: if a user sees delete links he/she can delete posts). But I am not sure how secure this is. It may be advisable to prevent action=source for users without edit permission, since the pmwiki source will carry all the linekeys. I am curious about other people's experiences regards the delete action, so I can revise it as necessary.

In any case all page modifications are recorded in the page history, and changes to a page are appearing in RecentChanges pages.

Extensions top

• FoxDelete - add delete links
• FoxEdit - add edit links to edit page sections and single or sets of PTVs
• Fox Notify - add email notification capability to Fox forms

Example Applications top

See also some example applications explained:

• Fox Comment Box - form to post comments
• Fox Contacts - create and maintain contact information pages. Data is stored as PTVs.
• Fox Forum - experimental forum package for both one thread per page and one page per post forums.
• Fox Blog - experimental very simple blog example
• Fox Page Management - forms for creating new pages, new groups and copying pages
• Fox Text Replace - replace text strings on multiple pages
• Fox Voting - forms for creating a voting list and multi choice voting
• Fox Simple Todo List - form to create a simple todo list
• Shoutbox - instant cross-wiki communication for authors
• Fox Shoutbox Alternative - a slightly different shoutbox
• Fox Cat - structured category and cross-group linking
• Fox Calculator - simple calculator demonstrating the display foxaction
• Data Plates - creating forms for database access

Release Notes top

Comments

See Discussion at Fox-Comments

See Also top

• Input for standard (:input ...:) markup information.
• FormValidation to add javascript validation to your form. Fox has built-in php validation, see above at Input Validation

Contributors

• HansB