Header Section

The header section is defined by having the .htmql file start with a template comment ({{/*) at the beginning of the first line of the file. The header section is terminated by a template comment (*/}}). Once the header terminates, the HTML content begins.

Header Line Format

Every line within the header section must follow one of the following formats:

NOTE: [] is used to denote optional elements, and <> is used to denote required elements.

• [method modifiers][method:][alias modifiers][alias:][SQL command]
• [method modifiers][method:]@[variable name]=[variable default value]
• [method modifiers][method:]@[variable name]:[SQL command to set variable default value]
• [whitespace][continue SQL command from previous line]
• <method>:[alias:]"[success message]"
• <method>:[alias:]!"[failure message for critical commands only]"
• <method>:[alias:]!!"[failure message for any commands]"
• --[comment]
• +<allow role>
• -<deny role>
• #[menu entry sequence] <menu entry name>
• ##[menu entry SVG tag]

NOTE: When there is ambiguity between whether a modifier is for a method or an alias (e.g. line is !:select ...) then it is assumed to be an alias modifier.

The following sections describe the different parts of the line format.

Method Modifiers

! indicates that all SQL commands executed during this method should be wrapped in a SQL transaction. NOTE: When there are multiple SQL commands in a method, they are wrapped in a SQL transaction by default. This modifier is useful for single commands that need to be wrapped, e.g. when executing a stored procedure

!! indicates that all SQL commands should be marked critical by default (see alias modifier ! for details)

Methods

The HTTP method that this SQL command should run during. Valid options are: GET, POST, PUT, PATCH, and DELETE.

If no method is specified, the method is automatically assigned based on the type of SQL command that is used:

• SELECT defaults to GET
• INSERT to POST
• UPDATE to PUT
• DELETE to DELETE
• All other command types (e.g. EXEC) do not have a default and the template will fail to load if no method is assigned.

You can define a method on its own line, without a command, which indicates that all commands after that line will be considered part of the method until another method-defining line is found.

Alias Modifiers

! indicates that this SQL command should be marked as critical and upon failure will halt execution of all other SQL commands in this method and display an error message returned by the SQL command (unless overridden by a message definition - see the Messages section). By default, commands are not considered critical unless the method has the !! modifier. If a non-critical command fails, any remaining SQL commands continue to be executed and no error is displayed to the user.

!! indicates that this SQL command should be marked as critical and is always expected to affect or return at least one row. For a SELECT (or a write with a RETURNING/OUTPUT clause), this means the query must return at least one record. For a bare write - INSERT/UPDATE/DELETE with no RETURNING/OUTPUT clause - it means the statement must affect at least one row (rows-affected ≥ 1), which is the natural way to require that an UPDATE/DELETE actually matched a row. If the requirement is not met, it is treated the same as a failure (the critical command halts the method and rolls back the transaction). This makes !! safe to pair with a redirect in the canonical save pattern: !!update/!!insert commits when the write changes a row and rolls back when it changes nothing.

$ indicates the SQL command results will be available to the template data as singular set of values, as opposed to the default of being an array for values. If multiple results are returned by a SQL command marked as singular, only the first one will be used. Singular results eliminate the need to use the range function to access the data in the HTML content.

| indicates this SQL command is an alternate command that should be executed if there is a failure of the previous command defined under the same alias. Alternate commands are attempted one at a time in sequence before a critical command is considered to have failed. The first command to complete without error is returned as the template data. This feature is useful for defining a select statement to populate a page with a record, with the alternate query providing default values when creating new records.

NOTE: When alternate commands are defined, if any of the commands are defined with the "!", "!!", or "$" modifiers, those modifiers apply to the primary and all alternate commands for that alias.

You can combine $ with | and ! (or !!) in any sequence.

Aliases

The name of which the results of the SQL command will be available in the template data (e.g. "{{range .alias}}", "{{.alias.field}}")

Alias names must begin with a letter and may contain letters, numbers, and underscores.

Alias names are case-insensitive and are always treated as lowercase in the template data.

If no alias is specified, it will default to the SQL command type (select, insert, update, delete, exec.)

If an alias name is defined multiple times, without the alternate command modifier, then a numeric suffix will automatically be appended to the alias name (e.g. select, select1, select2, etc)

Alias names must not conflict with HTTP method names (GET, POST, PUT, PATCH, DELETE) or any of the special names for HTTP redirection (redirect), file uploads (save), file downloads (download and binary), email sending (email), or row-level access control (guard) - see later in this document for details.

SQL Commands and Parameters

The SQL command to be passed to the database engine. SQL commands can be defined across multiple lines by starting subsequent lines with a whitespace character.

Named parameters can be used in the command by giving the variable name an @ prefix. Even if the database engine does not use @ as a variable prefix (e.g. postgres), the commands must be defined this way and will be translated to an appropriate convention used by the database engine (e.g. positional number variables)

Variable values will be taken from HTTP query parameters and (for methods other than GET) form fields with matching names. See the file uploads section of this document for notes about special handling of fields for multipart file upload.

Default variable values can also be defined for times when no parameter or form field is available.

Variables

Default variable values can be defined by specifying the variable name on a line starting with @

Variable names must begin with a letter and may contain letters, numbers, and underscores.

Variable names are case insensitive within SQL commands but are case sensitive in the template data.

The default variable value can be hardcoded in the template by using an = sign followed by the variable value, or by using an : sign followed by a SQL command that will return a value. When SQL commands are used, only the first field in the first row is used to store the value.

All variable values are treated as scalar; arrays are not supported.

Messages

Messages to be displayed to the user upon completion of the SQL commands in a method.

The success message will be displayed if all critical commands finish. The success message will also be displayed if non-critical commands fail unless an error message prefixed with !! is defined.

The failure message display logic depends on the ! or !! prefix. The !! message will be displayed if any critical OR non-critical commands fail. The ! message will ONLY be displayed if any critical commands fail and the !! message was NOT already displayed.

If you define a blank message (e.g. POST:!"" or POST:"") then no message will be displayed to the user under that condition.

If messages are not defined then the defaults are:

• GET
  • No message when critical commands finish without error
  • Displays an error if any critical or non-critical commands fail
• POST/PUT/PATCH/DELETE
  • Displays a success message if all critical commands finish without error
  • Displays an error message if any critical commands fail
  • No message when non-critical commands fail

The application-wide default message text can be changed for the entire application using the strings configuration section:

• strings.success - shown when a write operation completes successfully (default: "Your changes have been saved.")
• strings.error - shown when a critical write command fails (default: "Your changes were not saved.")
• strings.geterror - shown when a GET command fails (default: "There was a problem retrieving data.")

Comments

Comment lines can be used for making notes about or disabling commands. Comments must start at the beginning of a line, except when they are part of a SQL command (SQL command comments must be in a format supported by that database engine).