Skip to content

Pages API

Provides methods to handle web based requests, and issue responses. For full usage instructions see the Usage section.

Screencasts Available

Get an overview of using the Pages API in a screencast format. Click here for Part I. Click here for Part II.

new

Creates a new pages object instance.

core.pages.new( [request_opts] )

Parameters

Name Description Type Required
request_opts Additional options for the page request. Table N

Request Options

Name Description Type Default
timeout Timeout in milliseconds for the page request. Number 1000
max_file_size The maximum upload file size in bytes. Number 10240
max_file_uploads Maximum amount of uploaded files per request. Number 10

Properties

A pages object instance may contain the following properties.

Name Description Type
hasQuery If the request contains a query string. Boolean
hasForm If the request body is a form. Boolean
isGet If the request is of type "GET". Boolean
isPost If the request is of type "POST". Boolean
isAjax If the request is an ajax style request. Boolean
query The request query string as key/value pairs. Table
form Contains the form (or JSON) data as key/value pairs. Table
files Contains file upload objects (see File Uploads). Table
cookies Contains any set cookie data as key/value pairs. Table
headers The request headers as key/value pairs. Table
method The request method. Will be "GET" or "POST". String
path The uri request path. String

Constants

The pages object has the following constants available.

Name Description Value
GET The GET HTTP method. "GET"
POST The POST HTTP method. "POST"
HTML The HTML content type. "text/html"
JSON The JSON content type. "application/json"
TEXT The plain text content type. "text/plain"

Example

local page = core.pages.new()

Output

response

Sends the configured response back to the client browser.

<page-object>.response(body[, headers][, content][, status])

Parameters

Name Description Type Required
body The data to output to the client browser. String Y
headers Additional headers to send to the client browser. Table N
content The content-type to output to the client browser. Const N
status Numerical http status code to output to the client browser. Number N

Important

One this method is called, the response phase will end. You cannot issue a redirect or status after calling this method.

For more detailed examples see the Usage section.

Example

page.response("Hello There")

render

A helper method that will render a template and then issue a page response as HTML (text/html).

<page-object>.render(tpl_path, tpl_values[, headers])

Important

If you use this helper method, DO NOT use the response method.

Example

page.render(tpl_path, tpl_values[, headers])

renderJson

A helper method that will output JSON (application/json) as a page response. Used for AJAX style responses.

<page-object>.renderJson(data_tbl[, headers])

Important

If you use this helper method, DO NOT use the response method.

Example

page.renderJson(data_tbl[, headers])

renderText

A helper method that will output plain text (text/plain) as a page response.

<page-object>.renderText(text[, headers])

Important

If you use this helper method, DO NOT use the response method.

Example

page.renderText("This is plain text output")

Utilities

template

Compiles a template file with the supplied values. Returns string body, or nil and error.

<page-object>.template(tpl_file, tpl_values)

Parameters

Name Description Type Required
tpl_file The template file name. String Y
tpl_values Values for the template. Table Y

For detailed template usage information see the Templates section.

Example

local body = page.template("greeting.tpl", {greet="Hello!"})

redirect

Redirect the client browser to a different location.

<page-object>.redirect(uri[, isPerm])

Parameters

Name Description Type Required
uri The address to redirect the client browser to. String Y
isPerm Whether this is a premanent redirect. Default: false Boolean N

Important

One this method is called, the response phase will end. You cannot issue a response or status after calling this method.

The uri can be a remote address, for example: https://google.com

Example

page.redirect("/anotherpage")

status

End the response by sending an HTTP status code to the client browser.

<page-object>.status(code)

Parameters

Name Description Type Required
code HTTP numerical status code (reference). Number Y

Important

One this method is called, the response phase will end. You cannot issue a response or redirect after calling this method.

Example

--send `Unauthorized` status
page.status(401)

Uploads

saveFile

Save an uploaded file to the files directory. On success, returns file information table, or nil and an error.

<page-object>.saveFile(fileObj, destPath[, unique])

Parameters

Name Description Type Required
fileObj A file object reference. See File Uploads. Object Y
destPath Path to store the file relative to the files directory. String Y
unique Generate a unique file name for the file. Default: false Boolean N

Public Files

If you plan on displaying uploaded images or allowing downloads of your files from the browser, make sure to save them to the public directory.

Example

local info, err = page.saveFile(page.files.avatar, '/pix')

File Info Keys

Key Description
file The base name the file was stored as.
type The file MIME type. Example: 'image/png'.
size The total file size in bytes.
path The absolute file path where the file was stored.
dirpath The absolute directory path where the file was stored.

discardFile

Clear the uploaded file from the temp directory. Use when you want to abort the actual storage of the file.

<page-object>.discardFile(fileObj)

Usage Note

The saveFile method automatically removes the uploaded file from the temp directory.

Parameters

Name Description Type Required
fileObj A file object reference. See File Uploads. Object Y

Example

local success, err = page.discardFile(page.files.avatar)

Cookies

Retrieving cookies

To retrieve a set cookie value, use the cookies property of the page object.

Example

local userName = page.cookies.userName

setCookie

Set a browser cookie key/value.

<page-object>.setCookie(key, value[, options])

Parameters

Name Description Type Required
key The cookie key name. String Y
value The cookie key value. String Y
options Additional options for the cookie. Table N

Cookie Options

Name Description Type Default
path The path on which this cookie is active. String /
secure Only serve this cookie when using HTTPS. Boolean false
httponly Disable cookie from client-side access. Boolean false
expires How many days until this cookie expires. Number 0

Cookie Expiration

By default, cookies are cleared when the user closes the browser window using the cookie. Set the expires key to set a persistent cookie.

Example

page.setCookie("userName", "Timmy", {
  expires = 2 -- expires in two days
})

clearCookie

Clear a browser cookie key/value.

<page-object>.clearCookie(key[, path])

Parameters

Name Description Type Required
key The cookie key name. String Y
path The path on which this cookie is active. String N

Cookie Path

Most browsers require the cookie path to clear the cookie value if the cookie path has been set to something other than root (/).

Example

page.clearCookie("userName")

Project APIs

callApi

Call a method on a project api endpoint that was built using the core.api.

<page-object>.callApi(project, action, data_params)

Parameters

Name Description Type Required
project The name of the api project. String Y
action The name of the api method to call. String Y
data_params Values to pass to the api method. Table Y

Example

local result, err = page.callApi("default", "test", {greet="Hello!"})