AddDeleteLine3

Summary: An easy way to add information to a page and delete it again.
Version: 3 2017.06.07
Prerequisites: Works with php >=5.6.24; should work with php 7
Status: Probably works
Maintainer: Peter Kay
License: As-is, open source
Categories: Blog, Editing, Forms, Templates
Users: (view? / edit)

Questions answered by this recipe

  • How can I add data to a page without having to click on edit?
  • How can I create lists, where users can enter information using a web form?

A very similar recipe with slightly different features is the Fox recipe. If you think that this recipe is nice, but not exactly what you are looking for, then maybe you find it in Fox.

Description

An easy way to add information to a page and delete it again.

The AddDeleteLine recipe provides a way to insert form-data at a pre-defined location in a wiki-page.

A user can create a template, add a form made of standard PmWiki form elements, and then specify where the form-data should be inserted into the page.

Installation

In order to use this recipe, download the file AddDeleteLine3.phpΔ into your cookbook/-directory and add include_once('cookbook/AddDeleteLine3.php'); to your local/config.php

Upgrading from version 1

See AddDeleteLine2#upgrade

Usage

Examples

For examples and a playground, go to the Adl2Examples on http://www.knappi.org (PW: "tryadl2") This uses version 2, but the interface is almost exactly the same.

A simple example:

  (:adl form simpleExample:)
  ||
  ||Your name:||(:input text name:)||||
  ||What do you want to say?||(:input text TheySay:)||||
  ||(:input submit:)||||||(:adl template "||{name} says:||{TheySay}||(:adl delete:)||":)(:adl end:)
  (:adl append simpleExample:)

Might produce after several uses:

Your name:
What do you want to say?
Luna says:Meow meow meow meow?
Micro says:Purr purr purr purrrrr

Markup

The markup can be seperated in three parts:

In order to prevent naming ambiguities, the directives defined in this receipe begin with adl (add delete line).

Input form markup - how to create a form for adding new lines

The typical declaration of an input form is

  (:adl form name [target=[Group.]Page]:) 

// Input field declaration
// (:input text name1 "default value filled in":)
// (:input text name2:)
// other (:input data ...:)
// and formatting data (||table declarations|| * bullet lists, whatever) // etc

(:adl template template-string:)[ or (:adl templatepage template-page:)]
(:adl end:)
  • [Group.]Page is an optional parameter that defines the (possibly different) wiki-page to which the input should be inserted. If no target is specified, the data is inserted into the current page.
  • name is used to identify the correct location within the target page, at which the input data should be inserted. The names #top and #bottom can be used to prepend data at the beginning or to append it to the end of the page.
  • The input field declaration is done using the standard form input markup.
  • The template-string is the text that is actually inserted into the page. It can contain markup that is replaced by the value of the input field or the current date.

If the template-string consists of more than one line, it may be useful to specify the template in a separate wiki-page. In this case, the markup

    (:adl templatepage [Group.]Page:)

should be used.

Anchor markup - where should new lines be inserted

To specify where new lines should be added, the following directives must be written on the target page at the position where the filled template should be inserted.

(:adl prepend name:)
Specifies that data from the form named name is inserted here. Newer entries appear above older entries.
(:adl append name:)
Specifies that data from the form named name is inserted here. Newer entries appear below older entries.
#top or #bottom
if the (:adl form ...:) specifies #top or #bottom for the name, then filled templates are automatically added to the top or bottom of the page - no target anchor is needed.

Template markup

Template string

The template defines how new lines that are added to the page look. The template-string may be a simple string:

  (:adl template My name is {firstname}.:)

If you need to include markup in your template, you may also inclose the template-string in quotes:

  (:adl template "I am using (:other markup {options} etc:)":)
  or
  (:adl template '{firstname} says (:other markup "{text1}":)' :)

When using quotes, you may escape quotes with the backslash ( \ ). The backslash is also escaped with backslash.

  (:adl template "You can end your {markup} with \\\" if you want to \\\"":)
  // might produce the line: You can end your ADL with \" if you want to \"
  // I have no idea why you might want to do it, but you can.

The following replacements are applied to the template string, before inserting the data into the target page:

{name}
is replaced by the value of the form input field named name
So if you have (:input text firstname:), the template might contain "My name is {firstname}."
{date:format}
is replaced by the result of the PHP function date("format"), which allows formatted printing of the current date.
{strftime:format}
is replaced by the result of the PHP function strftim("format"), which also allows formatted printing of the current date, but also supports translated strings like "Montag" instead of "Monday"".
\n
is converted into a new line.
Template page

The markup (:adl templatepage pagename:) will use the contents of pagename as the template. This is useful if you want large templates.

Delete Markup

The following directives can be inserted into the template to allow deleting lines that have been added. Both create a button named "Delete" that will, when clicked, delete their corresponding parts of the wiki page:

(:adl delete:)
This directive adds a button in the template that deletes its own line of PmWiki markup, when clicked.
(:adl delrange:)
This directive adds a button that deletes a range of multiple lines from the wiki page.
The range is defined by the marks #adl begin# and #adl end#. When you want to add and delete entries with multiple lines, you should insert #adl begin# at the very beginning and #adl end# at the very end of the template. The tags will be invisible when looking at the page. Markup that has to be at the beginning of a line (like "!" for headings) still works, if it is written directly after the #adl begin#. An example template using this markup might be
#adl begin#!Topic: {topic}

{contents}

----#adl end#  

which would have exactly the same layout and functionality as

!Topic: {topic}

{contents}

----

Topic: {topic}

{contents}


but mark the beginning and the end of the entry

Multiple form elements with the same name

It's possible to have multiple form elements with the same name, using name[] instead of name. As an example:

  (:adl form multipleexample:)
  Please enter your cat's name:  (:input text name:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  * Enter a toy: (:input text toy[]:)
  (:input submit submit "Run the template":)
  (:adl template {name} likes to play with {toy[]}.\n\n:)(:adl end:)
  (:adl append multipleexample:)

If you filled it out with:

Please enter your cat's name:

  • Enter a toy:
  • Enter a toy:
  • Enter a toy:
  • Enter a toy:
  • Enter a toy:
  • Enter a toy:

You would get the results:

Luna likes to play with string.

Luna likes to play with toy mouse.

Luna likes to play with peacock feathers.

It's best to only have one name[] field currently.

CSS definitions

The form defining the delete button, has the CSS-class adldeletebutton. The default style definition for the class is

.adldeletebutton {
   display: inline;
}
.adldeletebutton input {
   font-size: 80%;
}

to ensure that the button is not standing on its own line. You can change this style by changing the value of HTMLStylesFmt['adddeleteline2'] in your local/config.php .

Notes

Known issues

  • With $RequireAuthor is enabled: It is a good idea to make sure the form has an 'author' fields. If the 'author' field is left empty, the edit form will pop up after submitting the form. The same is true, if no 'author' field is present and no cookie is set in the browser either. A solution may be to insert a default value for the author, or a hidden field, if no author should be entered.
  • It is possible a malicious user might be able to create a form that edits unexpected pages or uses unexpected actions. If this is a concern for anyone, I could probably update the AdlTemplateEngine to avoid PmWiki's form namespace.

Change log / Release notes

Release 3.2017-06-07: updated to PmWiki version 2.2, php version 5.5+ (should run in php 7+). Closed a few holes in the code. Made quotes optional in (:adl template ...:) markup.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at AddDeleteLine3-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.