360Works WebAssistant/Documentation
360Works WebAssistant User Guide
WebAssistant allows you to submit forms from FileMaker, and to get the contents of any URL as text or a container.
Getting URL Contents
In its simplest form, you can use the WAGetURL function to get the contents of a URL. If the mime-type of the URL is text, the raw text of the webpage or file is returned. Otherwise, a container is returned containing the image or other data located at the URL.
Submitting Forms
The WebAssistant can simulate a browser submitting a web form. For each "field" you wish to send to a form, call the WASetInputValue function.
Note that the paramName
corresponds to the name
of an input in the HTML form, which may differ from the label for the field as it appears on-screen.
The paramName should match the name
attribute on the <input type="text" name="my_input">
input element in the HTML source code.
In addition to field inputs, you can specify files to upload to a form using the WAUploadFileAtURL function.
Again, the inputName should match the name
attribute on the <input type="file" name="my_upload">
in the HTML source code.
You can specify multiple parameters or file uploads. They will all be sent the next time the WAGetURL function is called.
For more advanced users, there is the option of setting the content of the request manually, using the WASetRawPostData function.
This will be sent as-is in the request, which is useful if (for example) the POST
data should contain an XML document instead of key/value pairs. You are responsible for encoding this information correctly, as it will be sent as-is to the URL.
Example Usage
To add a user to a web-based signup form, you might use something like the following:
Let ( setup = WAReset & WASetInputValue( "first_name" ; "Sam" ) & WASetInputValue( "last_name" ; "Barnum" ) & WASetInputValue( "email" ; "sam@example.com" ) ; WAGetURL( "http://example.com/test/signup.php" ) )
To get an image from a password-protected website, just use the following calculation:
Let ( setup = WAReset ; WAGetURL( "" ; "username=bob123", "password=secretpass" ; "type=container" ) )
To upload files to a web form, pass container data to the WASetInputValue
function, or a URL to the WAUploadFileAtURL
function:
Let ( setup = WAReset ; WASetInputValue( "upload1" ; Products::picture_container ) & WAUploadFileAtURL( "upload2" ; "file:///Users/sam/Pictures/header.jpg" ) ; WAGetURL( "http://example.com/upload.php" ) )
Proxy Support
If you are behind a proxy server, you will need to tell the WebAssistant plugin information about the proxy host, as follows:
WAConfigure("proxyHost", settings::proxyHost) and WAConfigure("proxyPort", settings::proxyPort)
Do this in your startup script, and any further connections will go through your proxy host.
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- WAConfigure ( optionName ; value ) — Set a WebAssistant-related configuration optionName.
- WAGetResponseHeader ( headerName ) — After executing a request with the {@link #WAGetURL} method, you can use this function to examine the HTTP headers in the response.
- WAGetResponseHeaders — This gets a return-separated list of all HTTP header names from the last response.
- WAGetURL ( url { ; key1=value1 ; key2=value2 ; ... ) — Get the contents of a URL, as either TEXT or a CONTAINER object.
- WALastError — Returns defailed information about the last error generated by this plugin.
- WALicenseInfo — Retrieve information about the WebAssistant plugin licensing and version.
- WALoadForm ( html { ; whichForm } ) — Use an HTML form as a starting point for form values.
- WARegister ( licenseKey ; registeredTo ) — Registers the Plugin.
- WAReset — Clears all request parameters, file uploads, and post data.
- WAReturnSavedPageURL — returns the name file URL thats stored
- WASetCharacterSet ( charset ) — Set the character encoding used for sending form values and for decoding fetched URL contents into text.
- WASetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
- WASetInputValue ( inputName ; value ) — Sets a parameter to pass in the POST argument during the next call to {@link #WAGetURL}.
- WASetRawPostData ( dataToPost ) — Set raw POST data to send during the next call to {@link #WAGetURL}.
- WASetRequestHeader ( headerName ; value ) — Set manual HTTP headers to be sent with the request.
- WAStripTags ( html ) — Strip any HTML tags from a block of text.
- WAUploadFileAtURL ( inputName ; url ) — Upload a file during the next call to {@link #WAGetURL}.
- WAVersion — Returns the version number of the WebAssistant plugin.
Function Detail
WAConfigure ( optionName ; value )
Set a WebAssistant-related configuration optionName. Valid options are:
- easySSL
- A 1 or 0 indicating whether or not to use lax SSL certificate checking. This is useful for testing using self-signed certificates, or if you are getting certificate-related errors while connecting to
https
urls. - connectionTimeout
- The timeout in milliseconds until a connection is etablished. A value of zero means the timeout is not used. The default value is zero.
- socketTimeout
- The default socket timeout (
SO_TIMEOUT
) in milliseconds which is the timeout for waiting for data. A timeout value of zero (the default value) is interpreted as an infinite timeout. - userAgent
- Defines the content of the User-Agent header used by HTTP methods.
- proxyHost
- The proxy server host address or hostname.
- proxyPort
- The proxy server port number, defaults to 8080.
- proxyUsername
- The proxy server username.
- proxyPassword
- The proxy server password.
optionName
- the optionName to set.
value
- the value of the optionName.
WAGetResponseHeader ( headerName )
After executing a request with the WAGetURL method, you can use this function to examine the HTTP headers in the response. This can be useful for seeing cookie data which the server is setting. You can use the WAGetResponseHeaders function to get a list of all headers.
headerName
- the name of the HTTP header to fetch
name
, or null if no such header was found.
WAGetResponseHeaders
This gets a return-separated list of all HTTP header names from the last response.
WAGetURL ( url { ; key1=value1 ; key2=value2 ; ... )
Get the contents of a URL, as either TEXT or a CONTAINER object. If there are any input values or file uploads set, they are sent as part of a POST
request.
Otherwise, a GET
request is used to get the contents of the URL.
You can also use this to get the contents of files on your local machine, using the following syntax: file:///path/to/file.txt
.
If the content type of the returned data is text, this function returns the text. Otherwise, a container is returned. Alternatley, you can specify a type to return the URL content as, using the type
parameter (see Optional Parameters below).
Authentication
You can optionally supply a username and password, for accessing password-protected content. This must be passed in with each request, as the values are cleared out after doing the request.
Optional Parameters
The following optional parameters are supported:
- username
- The username to be used for authentication
- password
- The password to be used for authentication
- type
- "text" to fetch the result as a text object, "container" to fetch the result as a container. If no type is specified, the content-type of the URL contents are examined to automatically determine the best type (images, etc. will be returned as containers, text & html will be returned as text)
- encoding The default is application/x-www-form-urlencoded. You can also specify multipart/form-data to force that encoding instead.
Example Usage
To fetch data from a password-protected XML web service as text, you could use the following calcuation:
Set Variable [ $xml = WAGetURL( "http://myservice.com" ; "username=bob" ; "password=secret" ; "type=text" ) ]
url
- the location of the file to get.
optionalParameters
- optional parameters
WALastError
Returns defailed information about the last error generated by this plugin. If another plugin function returns the text "ERROR", call this function to get a user-presentable description of what went wrong.
null
if there was no error.
WALicenseInfo
Retrieve information about the WebAssistant plugin licensing and version.
WALoadForm ( html { ; whichForm } )
Use an HTML form as a starting point for form values. This can be useful if you're simulating a form submission from a page which has many hidden or pre-populated fields. This can often happen on multi-step form submissions.
Calling this function will scan the HTML
parameter text for the form identified by the whichForm
parameter.
For every input element in the specified form
, WASetInputValue will be called with the corresponding inputName and value.
html
- block of HTML code containing one or more
<form>
s whichForm
- the optional id, name, or index of the form to use. If omitted, the first
<form>
will be used.
ERROR
on failure.
WARegister ( licenseKey ; registeredTo )
Registers the Plugin.
licenseKey
- a valid license key string, or the literal string "DEMO" to run in demo mode.
registeredTo
- the company name for the license key used.
WAReset
Clears all request parameters, file uploads, and post data. This should be called before constructing a new request or getting a URL, in case there are some parameters lingering from a previous call that did not complete.
WAReturnSavedPageURL
returns the name file URL thats stored
WASetCharacterSet ( charset )
Set the character encoding used for sending form values and for decoding fetched URL contents into text.
charset
- a character set name, for example
US-ASCII
,ISO-8859-1
,UTF-8
,UTF-16
.
WASetErrorCapture ( errorCapture )
Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call WASetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.
errorCapture
- set to true to suppress the default popups.
WASetInputValue ( inputName ; value )
Sets a parameter to pass in the POST argument during the next call to WAGetURL. If you want to simulate submitting an email signup form, you might call this with the values:
WASetInputValue( "email" ; Contacts::emailAddress )
To send a container field as an attachment, pass the container field as the value
.
WASetInputValue( "photo" ; Contacts::portrait )
If you want to upload the contents of a local file or URL instead of a container, use the WAUploadFileAtURL function instead.
You can call this function multiple times before sending a form. If called twice with the same inputName, this will _not_ overwrite the previous value, but will send both values.
inputName
- the unencoded name of the form input
value
- the unencoded value text, or a container to send as an upload.
WASetRawPostData ( dataToPost )
Set raw POST data to send during the next call to WAGetURL. If used in conjunction with WASetInputValue,
any parameters set in that method will be passed as GET
arguments instead of POST
arguments.
You cannot combine this with calls to WAUploadFileAtURL in the same request. You can call this function multiple times before sending a form.
dataToPost
- raw encoded POST data to send in the next request.
WASetRequestHeader ( headerName ; value )
Set manual HTTP headers to be sent with the request. The most common case you would use this would be to set cookies in the request.
Setting Cookies
To send cookies along with your request, call with with "cookie" as the headerName
, and the cookie data as the value
.
WASetRequestHeader("Cookie", "sessionID=123456789;style=basic")
Other Uses
You can also use this to set the Content-Type of your request, or to pass in any other arbitrary headers you wish.
headerName
- the name of the HTTP header to set
value
- the value of the HTTP header
WAStripTags ( html )
Strip any HTML tags from a block of text.
html
- some HTML.
WAUploadFileAtURL ( inputName ; url )
Upload a file during the next call to WAGetURL.
If one or more files are specified to upload, the data is sent as multipart/form-data
.
If you want to upload the contents of a container field instead of a URL, use the WASetInputValue function instead, passing the container as the value
parameter.
inputName
- the input name to associate with this file.
url
- URL pointing to a file to upload. This can be a local file (
file:///path/to/file
) as well as a remote URL ().
WAVersion
Returns the version number of the WebAssistant plugin.