version=pmwiki-2.3.30 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum="form" attribute (+6)
ctime=1181479161
name=PmWiki.Forms
rev=97
targets=Cookbook.InputDefault,PmWiki.EditVariables,PmWiki.OtherVariables,PmWiki.Functions,Cookbook.FormValidation,Cookbook.FormExtensions,Cookbook.InputFormsAndJavaScript,PmWiki.PageLists,Cookbook.PmForm,Cookbook.Fox,Cookbook.Input,Cookbook.WikiForms,Cookbook.ProcessForm
text=(:Summary:How you can embed input forms into wiki pages:)%0aThis page explains how you can embed input forms into wiki pages. Input forms don't actually handle processing of the form data -- the feature simply allows creation of forms inside wiki pages. Forms processing can be found in the Cookbook (see below).%0a%0a!! Markup%0aTwo directives are used to begin and end forms:%0a%0a    %25pmhlt%25[@(:input form "url" method:)@]%0a    ...%0a    %25pmhlt%25[@(:input end:)@]%0a%0aThe %25pmhlt%25[@(:input form:)@] directive starts a form that will post to ''url'' (optional ''action=''url) using the supplied ''method'' (optional ''method=''method).  The ''url'' must be in quotes if not specified via ''action=''.  If the url is omitted, then the current page is assumed.  If ''method'' is omitted then "POST" is assumed.  An optional [@name="FormName"@] argument can be used to name the form.  You can explicitly state @@action=url@@ or @@method=get@@ or you can simply use them as positional parameters.%0a%0aIf your site uses ?n=Group.Page to specify the pagename then having a field %25pmhlt%25[@(:input hidden name=n value={$FullName}:)@] will allow your form to post to the current page as an alternative to fully specifying the action=url.%0a%0aThe %25pmhlt%25[@(:input end:)@] directive ends the current form.%0a%0a%25pmhlt%25Note that this feature doesn't ensure that the form output is correct HTML -- it assumes the author knows a little bit of what he or she is doing. Notably, [@(:input form:)@] and [@(:input end:)@] shouldn't appear inside tables, and all form fields and controls should be inside an [@(:input form:)...(:input end:)@] block. Also note that not all browsers support all field types - as of 2023, the [@(:input month:)@] field is still [[https://caniuse.com/mdn-html_elements_input_type_month|unsupported]] by desktop Firefox and Safari.%0a%0a[[#standardinputcontrols]]%0a!!Standard input controls%0aThe standard input controls are:%0a%0a    %25pmhlt%25[@(:input text name "value" size=n:) @]%0a    %25pmhlt%25[@(:input hidden name "value":) @]%0a    %25pmhlt%25[@(:input password name "value":) @]%0a    %25pmhlt%25[@(:input search name "value":) @]%0a    %25pmhlt%25[@(:input number name "value" min=x max=y step=z:) @]%0a    %25pmhlt%25[@(:input email name "value":) @]%0a    %25pmhlt%25[@(:input tel name "value":) @]%0a    %25pmhlt%25[@(:input url name "value":) @]%0a    %25pmhlt%25[@(:input date name "value":) @]%0a    %25pmhlt%25[@(:input month name "value":) @]%0a    %25pmhlt%25[@(:input color name "value":) @]%0a    %25pmhlt%25[@(:input radio name "value" "label" checked=checked:) @]%0a    %25pmhlt%25[@(:input checkbox name "value" "label" checked=checked:) @]%0a    %25pmhlt%25[@(:input select name "value" "label":) @] - see [[#select|select]]%0a    %25pmhlt%25[@(:input datalist id "value":) @] - see [[#datalist|datalist]]%0a    %25pmhlt%25[@(:input default default-name "default-value":)  @] - see  [[Cookbook:InputDefault|default]]%0a    %25pmhlt%25[@(:input textarea name [=value=] rows=n cols=n:) @]%0a    %25pmhlt%25[@(:input file name "label":) @]%0a    %25pmhlt%25[@(:input image name "src" "alt":) @]%0a    %25pmhlt%25[@(:input reset name "label":) @]%0a    %25pmhlt%25[@(:input button name "value":) @]%0a    %25pmhlt%25[@(:input pmtoken:) @] - see [[#pmtoken|pmtoken]]%0a    %25pmhlt%25[@(:input submit name "value":) @]%0a%0aWhere ''name'' and ''value'' are in the HTML syntax: name="addr" value="808 W Franklin".%0a%0aA PmWiki-specific input control is "e_author" which will be pre-filled with the current author name, and if $EnablePostAuthorRequired is set, will have a @@required="required"@@ attribute:%0a    %25pmhlt%25[@(:input e_author:) @] %0a%0aFor most controls the markup has the form:%0a%0a    %25pmhlt%25[@(:input type name "value" parameter="value":) @]%0a%0awhere ''type'' is the type of input element (described below), ''name'' is the name of the control, ''value'' is its initial value, and parameters are used to specify additional attributes to the control. If ''value'' contains spaces, enclose it in quotes; if it contains newlines (for textarea and hidden elements), enclose it in %25pmhlt%25[@[=...=]@]. %0a%0aFor example, the following creates a text input control with a size of 30 characters:%0a%0a(:markup:)%0a(:input text authorid "Jane Doe" size=30:)%0a(:markupend:)%0a%0aFor convenience, an author can also specify name and value arguments directly using %25pmhlt%25[@name=@] and [@value=@] attributes (same as HTML):%0a%0a(:markup:) %0a(:input text name=authorid value="Jane Doe" size=30:)%0a(:markupend:)%0a%0aFor the @@textarea@@ control a value can be set from PmWiki 2.2.0beta45 onwards. Enclose the value in %25pmhlt%25[@[=...=]@] if  it contains spaces or new lines.%0a%0aThe %25pmhlt%25[@submit@] control will more often be written as:%0a%0a    %25pmhlt%25[@(:input submit value="label":) @]%0a%0aHere's a more complete example, e.g., for a login prompt:%0a%0a(:markup:) [=%0a(:input form "https://www.example.com":)%0a(:input hidden action login:)%0a||     Name:||(:input text username:)         ||%0a|| Password:||(:input password password:)     ||%0a||          ||(:input checkbox terms yes "Accept Terms" required=required:) ||%0a||          ||(:input submit value="Log In":) ||%0a(:input end:)%0a=]%0a%0a[[#field_attributes]]%0a!! General form field attributes%0a* %25pmhlt%25[@(:input ... focus=1:)@] Setting @@focus=1@@ causes that field to receive the initial focus when the form is first opened.%0a%0a* The following advanced HTML attributes are supported: @@name, value, id, class, rows, cols, size, maxlength, action, method, accesskey, tabindex, multiple, checked, disabled, readonly, enctype, src, alt, title, required, placeholder, autocomplete, min, max, step, pattern, list, formnovalidate, accept, autofocus, lang, form@@. For a more detailed description, see their counterparts in the [[https://www.w3.org/TR/html5/forms.html#common-input-element-attributes|w3c reference: HTML5 form attributes]] (not all of them can be used for all types of form fields).%0a%0a* For checkboxes and radio inputs, the "label" attribute text will be displayed ''after'' the input as a %3clabel> element. Clicking on it will check or uncheck the input. The label can only be plain text (no inline formatting like bold or links).%0a%0a* In addition to these, the following attributes can be used for accessibility enhancements: @@role, aria-label, aria-labelledby, aria-describedby, aria-expanded, aria-pressed, aria-current, aria-hidden@@.%0a%0a* In addition to the default attributes, you can use custom data attributes like @@data-some-variable=value@@ or @@data-other="Some data"@@  (usable by custom JavaScript, CSS or by some libraries). The attribute must start with "data-" and only contain lowercase Latin letters [a-z] and dashes [-].\\%0aThis can be disabled in @@config.php@@ with the line @@$EnableInputDataAttr = 0;@@%0a%0a* %25pmhlt%25[@(:input form ... data-pmconfirm="Really submit form?":)@] or [@(:input submit ... data-pmconfirm="Proceed?":)@],  when the form is submitted, or when the user clicks on the button, will open a confirmation box with the question, allowing the user to proceed or cancel (from PmWiki 2.3.22). This works on the elements ''form, submit, reset'', and ''button''. The text in quotes will be shown to the user. Example:%0a>>indent%3c%3c%0a(:markup:)%0a(:input button bname "Delete all pages" data-pmconfirm="Are you sure you want to delete all pages? This cannot be undone.":)%0a(:markupend:)%0a>>%3c%3c%0a%0a* Any unsupported attributes in the wiki markup will not be included in the HTML output.%0a%0a[[#select]]%0a!! ([=:=]input select ... :)%0a%0aThe basic form of a select box is a sequence of options:%0a%0a(:markup:) [=%0a(:input form:)%0a(:input select name=abc value=1 label=alpha :)%0a(:input select name=abc value=2 label=beta  :)%0a(:input select name=abc value=3 label=gamma :)%0a(:input submit:)%0a(:input end:)%0a=]%0a%0aThe values can be specified positionally:%0a %25pmhlt%25[@(:input select abc 1 alpha :)@]%0a%0aWe can specify the size of the selection box:%0a %25pmhlt%25[@(:input select abc 1 alpha size=3 :)@]%0a%0aYou can specify a multiple select box (only the first item needs to have "size=3 multiple" attributes):%0a %25pmhlt%25[@(:input select abc 1 alpha size=3 multiple:)@]%0a%0aTo have an element selected, use @@selected=selected@@:%0a %25pmhlt%25[@(:input select abc 2 beta selected=selected:)@]%0a%0aNote that to have two select boxes inline, not only should you give them different @@name=@@ parameters, but also place a separator, like a character, %25pmhlt%25[@ @] or even the null sequence [@[==]@] between them:%0a(:markup:)%0a(:input form:)%0a(:input select name=FIRST value=1:)(:input select name=FIRST value=2:)[==]%0a(:input select name=SECOND value=3:)(:input select name=SECOND value=4:)%0a(:input end:)%0a(:markupend:)%0a%0a%25note pmhlt%25 Note, in the HTML output, only the attributes @@label@@, @@value@@ and @@selected@@ are applied to the [@%3coption>@] HTML tag. Any other attributes, including @@name@@, @@id@@, @@class@@ and @@title@@ are applied to the wrapping [@%3cselect>@] HTML tag, and later definitions replace previous ones.%0a%0a%0a[[#datalist]]%0a!! ([=:=]input datalist ... :)%0aThis allows a number of values (suggestions) to appear in a drop-down menu allowing the user to select one of the values or to fill a new, different value. The markup accepts named or positional attributes:%0a%0a  %25pmhlt%25[@(:input datalist id "value":) @]%0a  %25pmhlt%25[@(:input datalist id=id value="value":) @]%0a%0aAn existing %25pmhlt%25[@(:input text:)@] field needs to have an attribute @@list=id_of_the_datalist@@ to attach the suggestions.%0a%0aThe datalist element is invisible and can be anywhere in the page. The suggestion menu appears when the user starts typing in the attached text field and filters the suggested values that contain the letters typed in the text field.%0a%0a(:markup:) [=%0aType a browser name: (:input text browsers list=dlist_id :)%0a(:input datalist dlist_id Firefox:)%0a(:input datalist dlist_id Chrome:)%0a(:input datalist dlist_id Safari:)%0a(:input datalist dlist_id Edge:)%0a(:input datalist dlist_id MSIE:)%0a(:input datalist dlist_id Opera:)%0a(:input datalist dlist_id Lynx:)%0a=]%0a%0aThis is a recent addition to the HTML standard, see https://caniuse.com/#feat=datalist for current browser support.%0a%0a%25pmhlt%25Note that if you have a datalist element immediately following another datalist element, not only should you give them different @@id=@@ attributes, but also place a separator, like a character, [@ @] or the null sequence [@[==]@] between them: [@%0a(:input datalist dl_1 First:)%0a(:input datalist dl_1 Second:)[==]%0a(:input datalist dl_2 First:)%0a(:input datalist dl_2 Second:)%0a@]%0a%0a[[#pmtoken]]%0a!! ([=:=]input pmtoken:)%0a%0aThis includes a unique session identifier as a hidden input field to prevent cross-site request forgeries (CSRF). Can be included in custom forms, and the custom action handlers receiving the form can check if the request is valid by calling [[Functions#pmtoken|pmtoken(1)]].%0a%0aThe "name" of the HTML input element, by default 'pmtoken', can be changed by setting for example %25hlt php%25@@$FmtV['$TokenName'] = 'myCSRFtoken';@@. In your form you still need to have %25pmhlt%25[@(:input pmtoken:)@] which will use the new name for the HTML element.%0a!! See Also%0a*[[Cookbook:Input Default]] {Cookbook.InputDefault$:Summary}%0a*[[Cookbook:Form Validation]] {Cookbook.FormValidation$:Summary}%0a*[[Cookbook:Form Extensions]] {Cookbook.FormExtensions$:Summary}%0a*[[Cookbook:Input Forms and JavaScript]] {Cookbook.InputFormsAndJavaScript$:Summary}%0a*[[PageLists#searchbox]] The [@(:searchbox:)@] directive creates a form to search the wiki%0a%0aCompatible recipes:%0a* [[Cookbook:PmForm]] {Cookbook/PmForm$:Summary}%0a* [[Cookbook:Fox]] {Cookbook.Fox$:Summary}%0a* [[Cookbook:Wiki Forms]] {Cookbook/WikiForms$:Summary}%0a* [[Cookbook:ProcessForm]] {Cookbook/ProcessForm$:Summary}%0a%0a
time=1707204755