Skip to content
📌 OpenRun 1.0 is released, read the announcement

Templates

OpenRun uses Go HTML templates for returning data to the client. See template for an overview of the template syntax. Hugo docs are a good source for an overview of using go templates.

The Sprig template library functions are included automatically. Two functions from Sprig which are excluded for security considerations are env and expandenv.

Two extra functions static and fileNonEmpty are added for handling static file paths. These helper functions are also added:

FunctionNotes
pathEscape, pathUnescapeURL path segment escaping (Go url.PathEscape)
queryEscape, queryUnescapeURL query string escaping (Go url.QueryEscape)
safeHTMLMarks a string as pre-escaped HTML, opting it out of the template’s contextual escaping. Any user input in the string must be escaped first
relTimeRenders a time.Time or RFC3339 string as a relative age, like 3 hours ago. An optional resolution argument widens it: {{ relTime .t 2 }} gives 1 day 3 hours ago
openrun_staticReturns the content-hashed /_openrun/static url of a browser asset served by the OpenRun server, like htmx.min.js

static function

This function takes a file name and returns the url for a file in the static folder with a sha256 hash included in the file name. This approach is similar to the hashfs library. If the static folder contains a file file1 with the content file1data, then a call to static "file1" will return /test/static/file1-ca9e40772ef9119c13100a8258bc38a665a0a1976bf81c96e69a353b6605f5a7, assuming the app is installed at /test.

  • Caching: the file name has a hash based on the file contents. The OpenRun file server serves aggressive cache headers Cache-Control: public, max-age=31536000 when this file is referenced by the browser.
  • Content changes: when the file contents change, the content hash and the file name change. The files on disk are not renamed, only the filesystem used by the OpenRun server in memory sees the hashed file names.
  • No build step: the usual approach to aggressive static asset caching renames the static file on disk to include the hash, which requires a build step. The hashfs approach avoids the build step.
  • Cost: in prod mode, the file hash computation and compression are done once, during app installation. There is no runtime penalty. In dev mode, the file hashing is done during the api serving.

fileNonEmpty function

The fileNonEmpty function returns a bool, indicating whether a static file with that non-hashed name is present and is not empty. This can be used to conditionally include style files if present.

For example

{{ if fileNonEmpty "css/style.css" }}
   <link rel="stylesheet" href="{{ static "css/style.css" }}" />
{{ end }}

checks if the “css/style.css” file is present and not empty. If so, it is linked using the static function, which returns a hashed file name which can be cached aggressively.

The path passed to static and fileNonEmpty functions should not include static, it is automatically added. So use {{ static "css/style.css" }}, not {{ static "static/css/style.css" }}

Template File Location

Templates are loaded once on app initialization. In dev mode, they are automatically reloaded on file updates. By default, the app source home directory is searched for template files. This can be changed by adding this directive in the ace.app config.

app.star
settings={
    "routing": {"template_locations": ["*.go.html", "templates/*.go.html"]}
}

The default is ["*.go.html"]. When adding directories:

  • "*.go.html" still needs to be present in the list, since generated files are created in the app home directory.
  • All folders in the list need to contain at least one template file.
  • File names have to be unique across folders. Files are referenced by their name, without the folder name, when used in template import directives.

Structured Template Layout

The default in OpenRun is to load all the templates in one parse operation (the WordPress layout). This is easy to get started with but can result in challenges when the same template block needs to be duplicated in different files. OpenRun also supports a structured template layout (the Django layout). See this blog for an explanation about the differences between the two layouts.

If there is a base_templates folder in the app main folder with one or more *.go.html files, the structured template layout is used:

  • All the base template files are loaded in one parse operation.
  • Each of the files in the app main folder is then individually loaded.
  • Each top level file has access to its own template blocks plus the base templates.

This has the advantage that the main templates can have duplicate templates, with no conflicts because they are loaded individually. For example, if there is a base_templates/base.go.html file with

{{define "full"}}
<html>
  <head></head>
  {{block "body" .}} {{end}}
  <footer></footer>
</html>
{{end}}

and a index.go.html file with

{{define "body"}} My Index Body {{end}} {{- template "full" . -}}

and a help.go.html file with

{{define "body"}} My Help Body {{end}} {{- template "full" . -}}

then a route using index.go.html will get the HTML for the index page and route using help.go.html will get the HTML help page. Although the body is defined in two template files, there is no conflict since the root level template files are loaded independently.

Without structured template layout, if a duplicate block is found, the one to be used depends on the order in which the files are loaded. To use a different base-template directory, set base_templates to a single directory name:

app.star
settings={
    "routing": {"base_templates": "template_helpers"}
}

App Layout

Custom layout (custom_layout=True): the app developer has to create the index.go.html file. Add a directive like:

{{ template "openrun_gen_import" . }}

in the head section to ensure that the auto generated openrun_gen_import directives are loaded in the page. This will include the style files, HTMX library and the live reload functionality in dev mode.

Default layout: the auto generated index_gen.go.html file is used. The app developer has to provide a openrun_body block. It can be in any template file, the convention is to use app.go.html. For example:

{{block "openrun_body" .}}
   Data is {{.Data}}
{{end}}

In both custom layout and default layout modes, the template context is the same req object that is passed to the Starlark handler. The .Data binding has the data returned by the handler function for the route, and request properties are available directly in the template, for example .UserId, .CustomPerms, and .AppRBACEnabled.

For example:

{{block "openrun_body" .}}
   User: {{ .UserId }}
   Perms: {{ .CustomPerms }}
   RBAC enabled: {{ .AppRBACEnabled }}
   Data is {{ .Data }}
{{end}}

Static Root Files

FolderServed atContent based hashingUse for
static/static under the app pathSupportedMost regular static file serving
static_rootThe root path of the appNot supportedWell known files like favicon.ico and robots.txt

For example, if an app is installed at example.com: and a robots.txt file needs to be served, a file static_root/robots.txt can be added to the app. This is automatically served at example.com/robots.txt.

  • The static folder path is stripped from the route name.
  • The file name should not conflict with any of the API routes defined in the app.
  • Nested folders are looked up in the static root folder.
  • Most regular static file serving use cases should use the static folder, not the static_root folder.