All pages
Powered by GitBook
1 of 22

Web Support

This module provides the CLI runtime with all the web server BIFS, components and utilities need for mocking, testing and feature auditing.

This module provides web support for the BoxLang core OS runtime without needing a web server.

This means that it will add all the necessary web support to the BoxLang runtime so you can test, simulate, and mock web requests and responses from the CLI. This is a great way to test your web applications without the need for a web server.

# For Operating Systems using our Quick Installer.
install-bx-module bx-web-support

# Using CommandBox to install for web servers.
box install bx-web-support

THIS MODULE IS NOT NEEDED FOR COMMANDBOX OR THE MINISERVER. IT'S PURELY FOR TESTING, MOCKING AND AUDITING.

Settings

Here are the default settings for this module you can configure:

settings = {
    // The default port for the mock web server
    port = 8080,
    // The default host for the mock web server
    host = "localhost",
    // The default web root for the mock web server
    webRoot = server.java.executionPath,
    // If you want your mock web server to be always secure (SSL)
    secure = false,
    // The key used in the `server` scope we use to track the mock server
    requestKey = "bxMockServer"
};

Functions

Here are some functions collaborated for mocking/testing

getMockServer()

Creates a new mock server and stores it in the request context. If it exists already, it will return the existing one.

/**
 * Creates a new mock server and store it in the request context
 * If it exists already, it will return the existing one
 *
 * @webroot string The webroot to use for the mock server, defaults to the module setting
 * @host string The host to use for the mock server, defaults to the module setting
 * @port numeric The port to use for the mock server, defaults to the module setting
 * @secure boolean Whether the mock server should be secure, defaults to the module setting
 * @force boolean Whether to force the creation of a new mock server
 *
 * @return MockHTTPExchange
 */
function invoke(
    string webroot,
    string host,
    numeric port,
    boolean secure,
    boolean force = false
){

startMockRequest()

Handle the start of a mock request using passed arguments.

/**
 * Handle the start of a mock request
 */
function invoke(
	// Request Settings
	string path = "/",
	string method = "GET",
	string pathInfo = "",
	string queryString = "",
	string contentType = "text/html",
	string body = "",
	struct urlScope = {},
	struct formScope = {},
	struct cookieScope = {},
	struct headers = {},
	// Response Mock Settings
	numeric responseStatus = 200,
	string responseContentType = "text/html",
	string responseBody = "",
	struct responseHeaders = {},
	// Web Server Settings
	string webroot,
	string host,
	numeric port,
	boolean secure,
	boolean force = false
){

GitHub Repository and Reporting Issues

Visit the GitHub repository for release notes. You can also file a bug report or improvement suggestion via Jira.

Reference

This package is a collection of utilities, tools, BIFS, components, etc that can be built into the BoxLang servlet and mini server runtimes.

Built-in Functions

web

FileUpload

Processes file uploads from the request

Method Signature

FileUpload(destination=[string], filefield=[string], accept=[string], nameconflict=[string], strict=[boolean], allowedExtensions=[string])

Arguments

Argument
Type
Required
Description
Default

destination

string

true

The destination directory for the uploaded files.

filefield

string

false

The name of the file field to process.

accept

string

false

The accepted MIME types for the uploaded files.

nameconflict

string

false

The action to take when a file with the same name already exists in the destination directory.

error

strict

boolean

false

Whether to strictly enforce the system specified upload security settings.

true

allowedExtensions

string

false

The allowed file extensions for the uploaded files.

Examples

Related

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

FileUploadAll

Processes file uploads from the request

Method Signature

FileUploadAll(destination=[string], filefield=[string], accept=[string], nameconflict=[string], strict=[boolean], allowedExtensions=[string])

Arguments

Argument
Type
Required
Description
Default

destination

string

true

The destination directory for the uploaded files.

filefield

string

false

The name of the file field to process.

accept

string

false

The accepted MIME types for the uploaded files.

nameconflict

string

false

The action to take when a file with the same name already exists in the destination directory.

error

strict

boolean

false

Whether to strictly enforce the system specified upload security settings.

true

allowedExtensions

string

false

The allowed file extensions for the uploaded files.

Examples

Related

  • FileUpload

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

Forward

Leads the request to a different page.

This function acts like the location functionality except that the relocation is done directly on the server and not the browser

Method Signature

Forward(template=[string])

Arguments

Argument
Type
Required
Description
Default

template

string

true

The logical path to which the request should be forwarded to.

Examples

Related

  • FileUpload

  • FileUploadAll

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

GetHTTPRequestData

Uppercase a string

Method Signature

GetHTTPRequestData(includeBody=[boolean])

Arguments

Argument
Type
Required
Description
Default

includeBody

boolean

true

true

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

GetHTTPTimeString

Describe what the invocation of your bif function does

Method Signature

GetHTTPTimeString(date=[any])

Arguments

Argument
Type
Required
Description
Default

date

any

false

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

GetPageContext

Gets the current java PageContext object that provides access to page attributes and configuration, request and response objects.

If not running in a servlet, this will be a fake class attempting to provide most of the common methods.

Method Signature

GetPageContext()

Arguments

This function does not accept any arguments

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • HtmlFooter

  • HtmlHead

  • Location

  • SetEncoding

HtmlFooter

Writes text to the footer section of a generated HTML page.

It is useful for embedding JavaScript code, or putting other HTML tags or deferred scripts.

Method Signature

HtmlFooter(text=[string])

Arguments

Argument
Type
Required
Description
Default

text

string

true

Text to add to the footer area of an HTML page.

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlHead

  • Location

  • SetEncoding

HtmlHead

Writes text to the head section of a generated HTML page.

It is useful for embedding JavaScript code, or putting other HTML tags, such as meta, link, title, or base in an HTML page header.

If there is no head section in the HTML page, the function will create one.

Method Signature

HtmlHead(text=[string])

Arguments

Argument
Type
Required
Description
Default

text

string

true

Text to add to the head area of an HTML page.

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • Location

  • SetEncoding

Location

Relocates to a different pages.

Method Signature

Location(URL=[string], addToken=[boolean], statusCode=[integer])

Arguments

Argument
Type
Required
Description
Default

URL

string

true

The URL of web page to open.

addToken

boolean

false

clientManagement must be enabled.

statusCode

integer

false

The HTTP status code. Values: - 300 - 301 - 302 - 303 - 304 - 305 - 306 - 307

302

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • SetEncoding

SetEncoding

Sets the character encoding (character set) of Form and URL scope variable values; used when the character encoding of the input to a form, or the character encoding of a URL, is not in UTF-8 encoding.

Method Signature

SetEncoding(scope_name=[string], charset=[string])

Arguments

Argument
Type
Required
Description
Default

scope_name

string

true

The name of the scope to set the character encoding for.

charset

string

true

The character encoding to set.

Examples

Related

  • FileUpload

  • FileUploadAll

  • Forward

  • GetHTTPRequestData

  • GetHTTPTimeString

  • GetPageContext

  • HtmlFooter

  • HtmlHead

  • Location

Components

web

HtmlHead

Writes text to the head section of a generated HTML page.

Component Signature

<bx:HtmlHead text=[string] />

Attributes

Atrribute
Type
Required
Description
Default

text

string

false

Examples

HtmlFooter

Writes text to the footer section of a generated HTML page.

Component Signature

<bx:HtmlFooter text=[string] />

Attributes

Atrribute
Type
Required
Description
Default

text

string

false

Examples

Location

Generates custom HTTP response headers to return to the client.

Component Signature

<bx:Location URL=[string]
addToken=[boolean]
statusCode=[integer] />

Attributes

Atrribute
Type
Required
Description
Default

URL

string

false

addToken

boolean

false

statusCode

integer

false

302

Examples

Cookie

Defines web browser cookie variables, including expiration and security options.

Component Signature

<bx:Cookie name=[string]
value=[string]
secure=[boolean]
httpOnly=[boolean]
expires=[any]
samesite=[string]
path=[string]
domain=[string]
encodevalue=[boolean] />

Attributes

Atrribute
Type
Required
Description
Default

name

string

true

value

string

false

secure

boolean

false

httpOnly

boolean

false

expires

any

false

samesite

string

false

path

string

false

domain

string

false

encodevalue

boolean

false

true

Examples

Header

Generates custom HTTP response headers to return to the client.

Component Signature

<bx:Header name=[string]
value=[string]
charset=[String]
statusCode=[integer]
statusText=[string] />

Attributes

Atrribute
Type
Required
Description
Default

name

string

false

value

string

false

charset

String

false

UTF-8

statusCode

integer

false

statusText

string

false

Examples

Content

This component is used to send content to the client, such as HTML pages, files, or binary data or it can also be used to set the content type of the response.

Component Signature

<bx:Content type=[string]
deleteFile=[boolean]
file=[string]
variable=[any]
reset=[boolean] />

Attributes

Atrribute
Type
Required
Description
Default

type

string

false

deleteFile

boolean

false

false

file

string

false

variable

any

false

reset

boolean

false

true

Examples