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

• WAGetResponseCode —
• 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.
• WAReturnSavedPageURL — returns the name file URL thats stored
• WASetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
• WAStripTags ( html ) — Strip any HTML tags from a block of text.
• WAVersion — Returns the version number of the WebAssistant plugin.

Function Detail

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.

Parameters:

headerName

the name of the HTTP header to fetch

Returns: the value of the first HTTP header named 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.

Returns: all headers from the last request

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" ) ]

Parameters:

url

the location of the file to get.

optionalParameters

optional parameters

Returns: The contents of the URL, as text or a container.

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.

Returns: Error text, or null if there was no error.

WALicenseInfo

Retrieve information about the WebAssistant plugin licensing and version.

WAReturnSavedPageURL

returns the name file URL thats stored

Returns: Filename

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.

Parameters:

errorCapture

set to true to suppress the default popups.

WAStripTags ( html )

Strip any HTML tags from a block of text.

Parameters:

html

some HTML.

Returns: the input HTML with all tags removed.

WAVersion

Returns the version number of the WebAssistant plugin.

Returns: a text version number