Pages API
Provides methods to handle web based requests, and issue responses. For full usage instructions see the Usage section.
Screencasts Available
Get a basic 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!"})