Skip to content

Usage

In order to build a frontend first create a project directory with a configuration file prf.config.json in JSON format inside it. The configuration file must at least specify the base URL of the Particiapi server in the base_url property as well as the output directory in the out_dir setting, e.g.:

{
    base_dir: "https://api.example.com/",
    out_dir: "build"
}

Further, optional configuration settings are described below.

If you have installed particiapi-reference-frontend using Go or downloaded a pre-built binary you need to run the following command in order to build the frontend:

prf-build .

In case you have installed particiapi-reference-frontend using npm you need to run the following command to build the frontend and/or add it to the "scripts" object in your package.json:

npm exec prf-build .

The build results are placed in the configured output directory and can be served as static files by a webserver.

The frontend using the default language is placed at index.html, any internationalized variants are placed in subdirectories at <language-tag>/index.html named after their respective language tag.

prf-build

Synopsis

usage: prf-build [options] projectdir
  -verbose
        Enable verbose output

Description

The prf-build command builds fontend using the files in projectdir.

-help : Display usage infformation and exit immediately.

-verbose : Enable verbose output.

Configuration

The configuration file prf.config.json in JSON format supports the following settings:

base_url

Specify the base URL of the Particiapi server (mandatory, string).

Example:

base_url: "https://api.example.com/"

languages

Specify the languages that should be supported by the frontend. The first language will be default language available at the top level of the build directory whereas all other languages will be placed in subdirectories named after their language tag (array of strings).

Example:

languages: ["en", "nl-NL", "de-DE"]

Specify a list of links specific to a language (object mapping language tags to lists of link objects).

A links object contains links which will be displayed in the navigation menu.

Example:

links: {
    "en": [
        {
            "caption": "Home",
            "title": "Homepage",
            "url": "https://www.example.com/"
        },
        {
            "caption": "About",
            "title": "About Us",
            "url": "https://www.example.com/about/"
        }
    ],
    "de-DE": [
        {
            "caption": "Start",
            "title": "Startseite",
            "url": "https://www.example.com/de-DE/"
        },
        {
            "caption": "Über",
            "title": "Über Uns",
            "url": "https://www.example.com/de-DE/about/"
        }
    ]
}

caption

Specifies the caption of the link displayed in the navigation menu (string).

title

Specifies the title attribute of the link displayed in the navigation menu (string).

url

Specifies the target URL of the link displayed in the navigation menu (string).

stylesheet

Specify style sheet below the project directory to be included in addition to the default style sheet (string).

Example:

stylesheet: "style/branding.css"

includes

Specifies a number of optional HTML fragments to include into the frontend template (includes object).

An includes object specifies HTML fragments to included in specific parts of the template.

Example:

"includes": {
    "head": "metadata.html"
    "favicon": "favicon.html"
    "logo": "logo.html"
}

Specifies a file containing a HTML fragment to be included inside the HTML <head> tag (string).

favicon

Specifies a file containing a HTML fragment overwriting the default <link rel="icon"> element for including the favicon (string).

Specifies a file containing a HTML fragment overwriting the default <img> element for displaying the logo (string).

assets_dir

Specifies a directory below the project directory containing assets to be used by the frontend (string, mandatory). The directory will be copied into the "branding" subdirectory below the configured output directory.

Example:

"out_dir": "assets"

out_dir

Specifies the output directory where the build results will be placed (string).

Example:

"out_dir": "build"