Webtalk

Welcome to Webtalk, a framework for building web applications using Logtalk with SWI-Prolog as the backend. Templating features are provided by the simple_template SWI-Prolog pack.

Dependencies

• SWI-Prolog >= 7.7.1

• Logtalk >= 3.12.0

• simple-template >= 1.2.0

Configuration

All configurations, set using config_property/2 or daemon_option/2, are currently in config.lgt and can be adjusted using environment variables. daemon_option/2 is only to be used to store options related to running the server as a unix daemon. Environment variables are expected to be prefixed by the atom set using app_prefix/1 in config.lgt. The default prefix is WEBTALK_. The environment variables that are currently supported are detailed below.

config_property/2 related:

All of these options are passed to the templating system to be made available in template files.

• WEBTALK_SERVER_PORT - configures server_port, which is the port used when the application run using http_server/2 instead of http_daemon/1. Default is 5000.

• WEBTALK_SITE_NAME - configures site_name, which is the name of the site displayed in the navigation bar when using the default theme. Default is Webtalk.

• WEBTALK_JQUERY_VERSION - configures jquery_version, which is the version of the jQuery library used in the default theme. Default is 3.2.1.

• WEBTALK_JQUERY_VALIDATE_VERSION - configures jquery_validate_version, which is the version of the jQuery validate library used in the default theme. Default is 1.17.0.

• WEBTALK_POPPER_VERSION - configures popper_version, which is the version of the Popper.js library used in the default theme. Default is 1.11.0.

• WEBTALK_BOOTSTRAP_VERSION - configures bootstrap_version, which is the version of the Bootstrap responsive framework that the default theme is based on. Default is 4.0.0-beta.

daemon_option/2 related:

The details of all these options, except for daemonize and daemon_https_only can be found on the http_daemon/0 documention page on the SWI-Prolog website.

• WEBTALK_DAEMONIZE - configures daemonize, which is a boolean value that inicates if the application is to be run using http_daemon/1 instead of http_server/2. Default is false.

• WEBTALK_DAEMON_HTTPS_ONLY - configures https_only, which, if set to true, forces all HTTP requests to be redirected to HTTPS. Default is false.

• WEBTALK_DAEMON_PORT - configures daemon_port, which is --port on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_IP - configures daemon_ip, which is --ip on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_DEBUG - configures daemon_debug, which is --debug on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_SYSLOG - configures daemon_syslog, which is --syslog on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_USER - configures daemon_user, which is --user on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_GROUP - configures daemon_group, which is --group on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_PIDFILE - configures daemon_pidfile, which is --pidfile on the documentation page. Default is /var/run/webtalk.

• WEBTALK_DAEMON_OUTPUT - configures daemon_output, which is --ouput on the documentation page. Default is /var/log/webtalk.log.

• WEBTALK_DAEMON_FORK - configures daemon_fork, which is --fork on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_HTTP - configures daemon_http, which is --http on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_HTTPS - configures daemon_https, which is --https on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_CERTFILE - configures daemon_certfile, which is --certfile on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_KEYFILE - configures daemon_keyfile, which is --keyfile on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_PWFILE - configures daemon_pwfile, which is --pwfile on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_PASSWORD - configures daemon_password, which is --password on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_CIPHERLIST - configures daemon_cipherlist, which is --cipherlist on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_INTERACTIVE - configures daemon_interactive, which is --interactive on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_GTRACE - configures daemon_gtrace, which is --gtrace on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_SIGHUP - configures daemon_sighup, which is --sighup on the documentation page. If unset, the package default is used.

• WEBTALK_DAEMON_WORKERS - configures daemon_workers, which is --workers on the documentation page. If unset, the package default is used.

Usage (Linux)

The following commands are to be issued in the base directory:

http_server/2 mode:

$ swilgt -s app.lgt

http_daemon/1 mode:

Environment variables may precede the command.

$ WEBTALK_DAEMONIZE=true sudo -E bash -c 'swilgt -s app.lgt'

Running Webtalk as a service

For an example on how to run Webtalk as a systemd service, see the service template file of the webtalk-ops repository.

Development

Webtalk supports customisation via pluggable themes and extensions. The best practice when developing a custom application is to avoid hacking the core at all costs and perform customizations via themes and extensions placed in the app/theme and app/extension directories respectively.

Blueprints

Custom pages can be added to an application by way of custom blueprints. As a best practice, each custom blueprint should be placed in its own subdirectory of the app/blueprint directory, and should contain a .lgt file with the same name as the directory. For example, to create a blueprint that defines all the first level pages in your website's content structure, you could create a blueprint called first_level at app/blueprint/first_level/first_level.lgt.

To have such a blueprint overwrite core's main blueprint, one would just have to reassign the HTTP handlers for the endpoints in main to the first_level class. For example:

:- http_handler(root(.),
    [Request]>>(first_level::index(Request)), [id("first_level.index")])

Themes

Each custom theme must be placed in its own subdirectory of the app/theme directory. The name of the subdirectory must correspond to the name of the theme and must contain, at least, a JSON theme info file, theme.json, and a Logtalk theme file, theme_{{theme_name}}.lgt. In addition to these, the theme directory must also contain a static subdirectory, that is used for serving static files such as CSS, JS and image files, and a template subdirectory that contains the HTML templates for the views that are rendered for the user. The directory tree below shows the structure of the default base theme that is bundled with Webtalk.

base
├── static
│   ├── css
│   │   ├── simple-sidebar.css
│   │   └── style.css
│   └── js
│       ├── install.js
│       └── script.js
├── template
│   ├── auth
│   │   └── login.html
│   ├── base.html
│   ├── config
│   │   ├── appearance.html
│   │   ├── extensions.html
│   │   ├── index.html
│   │   └── vendor.html
│   ├── install
│   │   └── index.html
│   └── main
│       └── index.html
├── theme_base.lgt
└── theme.json

The expected values for the JSON info file are:

• name - The name of the theme, which must match the name of the theme directory.
• title - The title of the theme that is displayed in configuration pages.
• description - A brief description of the theme that is displayed in configuration pages.
• version - The version number of the theme.

The theme_{{theme_name}}.lgt fil