formQuery: Runtime form input validation and submission

In omegahat/RHTMLForms: Programmatically create R functions corresponding to Web/HTML forms.

Runtime form input validation and submission

Description

This function provides the runtime support for validating the user-specified values for the different form elements relative to the form element descriptions to verify that the values are legitimate. This validation is performed by check Having done this This checks that text values are within the length (number of characters) constraints, that values for radio, checkbox and option menu elements correspond to elements within the enumerated set within the form. And final Having validated the values, it submits the HTTP request that constitutes the form, as it would be submitted by a browser.

Usage

formQuery(args, url, formDescription, ...,
          .extraArgs = character(), .opts = list(),
           .checkArgs = TRUE, .addSubmit = TRUE, style = "POST",
             curl = getCurlHandle(), .cleanArgs = NULL)

Arguments

args	the list of user-specifiable arguments to submit with the form.
url	the URI to which the form will be submitted.
formDescription	the HTMLFormDescription object typically constructed via a call to getHTMLFormDescription. The methods handle processing the top-level description into the different pieces and calling the actual method that does something with it.
...	arguments that are passed on to the form submission function, getForm or postForm
.extraArgs	a characer vector or list of additional arguments that are added to the HTTP request when submitting the form.
.opts	arguments for the form submission that are passed in a different way than the ... mechanism. For example, they may have been created earlier and reused in different calls.
.checkArgs	a logical value indicating whether to validate the arguments. On occassion, it is convenient to bypass this step and assert that values are legitimate.
.addSubmit	a logical value indicating whether the value for the submit button should be added to the form query. Some forms require this to work properly, others do not but can tolerate the extra "information", and some applications will fail if it is present. It is typically harmless to include it but it is worth trying omitting it if the function fails with correct inputs.
style	a value that, if the form is a POST, is passed onto postForm to control which type of POST is used, i.e. 'multipart/form-data' or 'application/x-www-form-urlencoded'.
curl	an object used to make the HTTP request. This can be specified by the caller so that she can reuse a connection across multiple calls. This facilitates working with cookies from a login and reused in subsequent requests.
.cleanArgs	a function that can be used to process all of the arguments in a call to a form before it is sent. This gives the “caller” (or programmer) an opportunity to transform the values provided by the caller into an appropriate form and also to create new arguments. For example, we might have the user specify the year, month and day of interest and in the .cleanArgs function, map this to a POSIXt value and set that as a hidden or additional argument to the form. See http://www.transtats.bts.gov/DL_SelectFields.asp?Table_ID=236 for an example.

Value

The result of submitting the form. Typically this is simply a character string containing the text returned by the HTTP server in response to the form submission. However, the caller can control how the information is returned using the ... and .opts arguments to control the form submission.

Author(s)

Duncan Temple Lang <[e-mail]>

See Also

checkFormArgs

omegahat/RHTMLForms documentation built on Nov. 29, 2023, 12:36 a.m.