get-url

Fetch data from, or post data to, a specified URI.

Summary

[get-url url]

Parameter	Description	Default
url	The URI you want to retrieve data from.	None
authpass	Password to send for authentication.	None
authuser	User name to send for authentication.	None
content	Freeform data to pass to the remote URI as part of the request.	None
content_type	Set the MIME Content-Type header for "POST" and "PUT" requests.	application/x-www-form-urlencoded
form	CGI variable(s) to pass to the remote URI as part of the request.	None
method	HTTP retrieval method.	GET
scratch	Save the returned content to the named scratchpad variable.	None
strip	Strip all but the body text.	No
timeout	Maximum time to wait for a response from the remote server.	180
useragent	Browser identification value to send with this request.	libwww-perl/version

Examples

Tag expansion example

[get-url http://www.cursor.biz/index.html]

Perl example

$Tag->get_url({
url => 'http://www.cursor.biz/index.html',
});

or similarly with positional parameters:

$Tag->get_url('http://www.cursor.biz/index.html');

Warning

Calling this tag from embedded Perl or a local UserTag etc. is likely to fall foul of the security constraints provided by the

Safe module. This is dependent upon your SafeUntrap setting, of course.

Description

This tag can be used to fetch data from, or post data to, a specified URI.

For instance, the following will POST a form consisting of two CGI variables, called "first_name" and "last_name", to the "http://www.example.com/someform.html" URI. Any data received as a result of the posting of this request will be collected and stored in a scratchpad variable called "result":

[get-url
method="POST"
url="http://www.example.com/someform.html"
content_type="multipart/form-data"
useragent="@@MV_PAGE@@/1.0"
scratch="result"
strip=1
form=|
first_name=[value fname]
last_name=[value lname]
|]

Parameters

url

The URI from which you would like to retrieve data.

The "url" parameter must contain a fully formed URI, including the protocol, the host/domain name and the page/path. For example, "http://www.example.com/path/to/foo.html".

URI parameters (CGI variables) should be specified using the form or content parameters, rather than encoded into the URI using the url parameter.

authpass

Password to send for authentication, if required by the remote URI.

authuser

User name to send for authentication, if required by the remote URI.

content

Freeform data to pass to the remote URI as part of the request. If the request type is "POST" or "PUT" then the data will be sent as form data, otherwise it will be appended to the requested URI, as URI parameter(s).

Multiple variables must be separated from one another using an ampersand (&) character.

This tag will not hex-encode non-word characters in the content for you. You must call [filter op="urlencode"] yourself, if your data is likely to contain non-word characters.

Note

This parameter's value will be overridden if a form parameter is also provided.

content_type

If you are POSTing a request to the URI then you may need to override the default Content-Type HTTP header value. The default Content-Type for "POST" and "PUT" methods is "application/x-www-form-urlencoded"".

Note

The "content_type" parameter is ignored for request methods, other than "POST" and "PUT", if no form or content is provided.

form

CGI variable(s) to pass to the remote URI as part of the request. If the request type is "POST" or "PUT" then the variable(s) will be sent as form data, otherwise they will be appended to the requested URI, as URI parameter(s).

Variables must be specified as "name=value" pairs, and each variable must be on its own line. Non-word characters in the names and values will be URI-encoded automatically.

Note

This parameter's value will override the value if the content parameter.

method

The HTTP retrieval method you would like to use. Valid methods are "GET", "HEAD", "POST" and "PUT".

scratch

If this parameter is given then the return value will be saved to the named scratchpad variable instead of simply being returned as this tag's output.

strip

This tag will return all of the content received from the requested URI by default. If you set this parameter true then only the content between "<body>" and "</body>" will be returned.

timeout

Don't wait any longer than this amount of time for a response from the remote server.

This parameter can be specified as a number of seconds, or can be specified as a time interval, such as "1 minute" or "20 seconds" etc.

The default timeout value is 180 seconds (or "3 minutes").

useragent

The browser identification value you would like to send with this request.