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

BuildForms

<< | Forms-related | Enable HTML >>

Goal

Create an HTML form with Wiki markup, save values in a file, and pass values to a user defined function.

(see CompareFormsRecipes)

Solutions

Install the buildforms addon

• buildforms.phpΔ script.

This is a preliminary version - Please report any problem in the discussion paragraph below or by mail.

• File buildforms.php goes in cookbook directory
• Set in /local/config.php:
  include_once ("cookbook/buildforms.php");

Notes and comments

• php code size: 11.5 ko.

Usage

• Only one markup per line
• \\ don't work (eat the markup), use [[<<]] to change line.

form opening with (:frminit:)

form closing (imperative) by (:frmend:)

All markup names should be different, if not the last overwrite the other.

Elements :

• (:frmbutton name0 function=frmufmyfunction:) button send parameters, saves them in a file, and run the function (optional, if set, it should exist)
• (:frmfield name1:) ordinary field
• (:frmtext name2 rows=x cols=y:) multiline text
• (:frmcheck name3:) Checkbox
• (:frmradio name4:) radio button list
• (:frmop option1:) first radio button
• (:frmop option2:) second radio button
• any command close the list
• (:frmselect name5:) select box
• (:frmop sel1:) first select element
• (:frmop sel2:) second select element
• Any new command close the list, but you may want to close the list (HTML tag </select>) before a new command if you are in a table cell, for example.
  In that case, use (:frmendselect:) to close the list before a new command and before the end of the table cell.

To have a multiple line select box, set parameter size=n n being the line number

Displayed text is equal to the markup name, but you can change that with the parameter disp="display anything"

frmfield display the disp text after the input box. If you want to display the input box on the right of the text, you should use 'pos=right' parameter, and you will probably have to set the field in a table to align it properly:

(:frmfield name1 disp="Text displayed" pos=right:)

• (:frmmsg name6:) can display a message returned by your function (deleted et next submission), or run a function and display the return message

default values are set with value=anyvalue or value="another value"

For radio and select box, set as value the chosen option name to set this option as default.

To have a checkbox checked by default, set value=nameofchk e.g. :

 (:frmcheck chk_x value=chk_x disp="option to be selected":)

regex='regex expression' control and capture your input. If not valid, the value is left unmodified

New in rev0.7: user function name should start by 'frmuf' ('form user function', use lower case) to improve safety.

While all buttons submit the form, there are buttons with special behaviour:

• 'ok' button send parameters to a cgi, if 'action=' parameter set
• 'reset' came back to default parameters (practically, it wipes the Group.Page.val file)
• 'cancel' came back to parameters previously recorded
• 'wipe' wipe files Group.Page.prm and Group.Page.val which were created for pages which no longer exists, to make a directory cleanup.
• (:frmbutton ok disp="Submit form":) or (:frmbutton ok disp=Ok:)
• (:frmbutton reset disp=Reset:)
• (:frmbutton default:)
• (:frmbutton wipe disp="wipe orphan form files":)

Complementary parameters can be defined by setting their name in the init (no blanks, comma separated)

(:frminit params=param1,param2:)

and then you will set in each markup a fixed value.

(:frmfield namex param1=xx param2=yy:)

Hidden field (to be stored or sent to a cgi)

• (:frmhidden value:) or (:frmhidden "this is a value":)

Some markup examples :

 
(:frminit params=csstype,area:)
(:frmbutton ok disp="&nbsp; Ok &nbsp;" function=skincsscre:)[[<<]]
(:frmmsg msgresult:)[[<<]]
(:frmfield sztext value=100% disp="Text - def:100%"
   regex="[1-9][0-9][0-9]?%" size=4 csstype=font-size area=body:)[[<<]]
(:frmfield sidemrgl value=8px size=3 regex="[0-9][0-9]?px"
   disp="Left - def:8px" csstype=padding-left area=#wikileft:)
(:frmend:)

Please note that instead what is shown above for better presentation, each markup shall be on one line only.

These parameters will be stored in the file $pagename.prm, and then set in a global value to be used by your client function.
The values are stored in the file $pagename.val with the format :

 
name1:value1
name2:value_x
name3:value_z
name3:multilines text`2nd line and`third line

So, to send back a message to your page, you have only to append to the $pagename.val file :

 "\n"."msgname:text of the message"

msgname being the name of your markup. This message will not be resubmitted by the form, so deleted at next post.

See the new skinnice module as an exemple of use :

skinnice2.phpΔ

Have a look to the site example for detailed use. More infos to come.

Site example :

• http://www.rouzeau.net/w3/pmwiki.php?pagename=Main.BuildForm

read password is 'miaou' .

Application example

• http://www.rouzeau.net/w3/pmwiki.php?pagename=Main.SkinConfig2

read password is 'miaou' .

The format of the $pagename.prm file is :

 
name1:value="value x" function="myfunc" perspar1="constant1x" perspar2="constant2x" 
name2:value="value 2" regex="expr." perspar1="constant1y" perspar2="constant2y" 
name3:value="value 3" size="nn" perspar1="" perspar2="" 

To send the parameters to an external cgi, set the parameter 'action=' in the frminit directive as in: (:frminit action="http://www.myownsite.org/cgi-bin/fromWiki.cgi":)

Parameters are stored locally before being sent to the cgi.

Only an 'ok' button send the values to the cgi, so you can have a 'save' button to store locally before sending to the cgi.

As for now, parameters are not get from the CGI. If someone needs it, please inform and supply a valid address with a working CGI able to return parameters.

Reading parameters

You can read parameters from another page with the (:frd:) directive.

Defining a default page where the parameters should be read is done with (:frmreadinit:) as in :

(:frdinit Mypage:) or (:frdinit Agroup.Mypage:)

and then the parameters are read from this page:

(:frd paramname:)

This simply display brute parameter, but you can improve the display with the 'disp' flag, which have different behaviour following the kind of input (field, checkboxe, radiobutton, etc.) and use the content of the 'disp=' parameter in the data source page

(:frd paramname disp:)

If you want to read only one parameter from a specific page, you can do with an optional 'page=' parameter:

(:frd paramname page=Agroup.OtherPage:)

Restrictions

• Do not work when $EnableIMSCaching is activated
• Names of the markups should be lower case letter or numbers
• Words reserved for names: default, msgerr, ok, reset, wipe
• Words reserved for parameters: action, align, disp, name, page, params, pos, regex, size, value
• Functions name should be lowercase (this is a php requirement for functions called by a variable)
• For a field, the text can only be displayed on the right - will be modified
• List of values includes buttons - might be cancelled later

Configuration

On PmWiki2 only.

Translations

License

GPL

History

• 8 mar. 2005 V0.1 - 1rst issue -
• 2 april 2005 V0.6 - add sending to a cgi, read page parameters
• 23 april 2005 V0.7 - user function should start by 'frmuf'
• 16 may 2005 V0.8 - reintroduced clearstatcache() when reading a file - corrected site example not working because caching is activated.

Contributor

PRZ

Comments

See discussion at BuildForms-Talk