Build Actions #

Build actions are custom actions which are triggered by a user clicking the action button. Build actions can be attached to a Single or a Collection object.

A build action allows the user to use data stored in a Quiqr site object as input for an external program. The value that the external program returns can be displayed, or, if it is a filename, the user can open it.

A typical use case for a build action would a PDF builds. Using Pandoc or Quarto a markdown file could be converted to a nicely formatted PDF file.

Variables #

Before a build action is executed variables will be replaced by a their real values. There are standard Quiqr site variables like SITE_PATH and there are custom declared variables. The custom declared variables can be overruled in the global variable preferences of the installed Quiqr application.

A % symbol needs to be written before a variable name in the definition to let Quiqr know it should be replaced with the real value.

Available standard quiqr site variables:

SITE_PATH: Is replaced with the root folder of the site. E.g. /Users/pim/Quiqr/sites/my-documents.
DOCUMENT_PATH: Is replaced with the path of the file which opened by the user. E.g. /Users/pim/Quiqr/sites/my-documents/content/quotations/001-johnson.md.

Properties #

These are the properties of one build action.

property	value type	optional	description
key	string	mandatory	Keys are for internal use and must be unique.
button_text	string	mandatory	Text displayed on the button.
execute	dictionary	mandatory	Contains different settings to define the external program dispatch.
execute.variables	array with dictionaries	optional	Array with key value pairs containing variable name and their values. If they are used in the `command` or `args` strings. they serve as default values. See example below.
execute.stdout_type	string	optional	The stdout_type can be set to `file_path` or `ascii_message` or `message`.
execute.unix	dictionary	mandatory	Contains command and arguments to run on Linux and macOS systems.
execute.unix.command	string	mandatory	File path to the executable to run. Be aware to enter full paths as Quiqr has no PATH variable set. Variables are replaced before execution.
execute.unix.args	array of strings	optional	All arguments used by the executable. Variables are replaced before execution.
execute.unix.file_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the returned file_path. This is introduced to remap the Windows WSL map to Windows Native file path. See example below.
execute.unix.document_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the document_path. See example below.
execute.unix.site_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the site_path.
execute.windows	dictionary	optional	Contains command and arguments to run on Linux and macOS systems.
execute.windows.command	string	mandatory	File path to the executable to run. Be aware to enter full paths as Quiqr has no PATH variable set. Variables are replaced before execution.
execute.windows.args	array of strings	optional	All arguments used by the executable. Variables are replaced before execution.
execute.windows.file_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the returned file_path. This is introduced to remap the Windows WSL map to Windows Native file path. See example below.
execute.windows.document_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the document_path. See example below.
execute.windows.site_path_replace	array of dictionaries	optional	Array with key value pairs containing search and replace strings for the site_path.

stdout_type’s #

value = file_path - When set to file_path a link to open the result file is displayed after the build action was finished succesfully.
value = message - When set to message the return value is displayed after the build action was finished succesfully.
value = ascii_message - When set to ascii_message the return value is displayed after the build action was finished succesfully. A fixed font is used to maintain correct layout.

Full example of a collection object. #

Configuration #

./quiqr/model/includes/collections/quotation.

amount: 2
build_actions:
- button_text: Build PDF
  execute:
    stdout_type: message
    unix:
      args:
      - '%DOCUMENT_PATH'
      - -t
      - pdf
      command: '%PANDOC_EXECUTABLE'
    variables:
    - name: PANDOC_EXECUTABLE
    - value: /usr/bin/pandoc
    windows:
      args:
      - pandoc.exe
      - '%DOCUMENT_PATH'
      - -t
      - pdf
      command: wsl
  key: magic_simple_pdf
- button_text: Build PDF
  execute:
    stdout_type: file_path
    unix:
      args:
      - run
      - github:wearetechnative/quarto-with-batteries#quarto-for-quiqr
      - --
      - '%DOCUMENT_PATH'
      command: '%NIX_EXEC'
    variables:
    - name: NIX_EXEC
      value: /usr/bin/nix
    windows:
      args:
      - --distribution
      - nixos
      - /run/current-system/sw/bin/nix
      - run
      - --extra-experimental-features
      - nix-command flakes
      - github:wearetechnative/quarto-with-batteries#quarto-for-quiqr
      - --
      - '%DOCUMENT_PATH'
      command: wsl
      document_path_replace:
      - replace: \\/
        search: \\\\
      - replace: /mnt/c
        search: 'C:'
      file_path_replace:
      - replace: 'C:'
        search: /mnt/c
  key: magic_make_pdf
dataformat: yml
extension: md
fields:
- fields:
  - key: company_name
    type: string
  - key: contact_person
    type: string
  groupdata: true
  key: client
  type: pull
- key: date
  type: string
- key: mainContent
  title: Main Content
  type: markdown
folder: content/quotations
hidePreviewIcon: true
itemtitle: Quotation
key: sample_field
title: Quotations
type: empty-line

amount = 2
dataformat = "yml"
extension = "md"
folder = "content/quotations"
hidePreviewIcon = true
itemtitle = "Quotation"
key = "sample_field"
title = "Quotations"
type = "empty-line"

[[build_actions]]
  button_text = "Build PDF"
  key = "magic_simple_pdf"
  [build_actions.execute]
    stdout_type = "message"
    [build_actions.execute.unix]
      args = ["%DOCUMENT_PATH", "-t", "pdf"]
      command = "%PANDOC_EXECUTABLE"

    [[build_actions.execute.variables]]
      name = "PANDOC_EXECUTABLE"

    [[build_actions.execute.variables]]
      value = "/usr/bin/pandoc"
    [build_actions.execute.windows]
      args = ["pandoc.exe", "%DOCUMENT_PATH", "-t", "pdf"]
      command = "wsl"

[[build_actions]]
  button_text = "Build PDF"
  key = "magic_make_pdf"
  [build_actions.execute]
    stdout_type = "file_path"
    [build_actions.execute.unix]
      args = ["run", "github:wearetechnative/quarto-with-batteries#quarto-for-quiqr", "--", "%DOCUMENT_PATH"]
      command = "%NIX_EXEC"

    [[build_actions.execute.variables]]
      name = "NIX_EXEC"
      value = "/usr/bin/nix"
    [build_actions.execute.windows]
      args = ["--distribution", "nixos", "/run/current-system/sw/bin/nix", "run", "--extra-experimental-features", "nix-command flakes", "github:wearetechnative/quarto-with-batteries#quarto-for-quiqr", "--", "%DOCUMENT_PATH"]
      command = "wsl"

      [[build_actions.execute.windows.document_path_replace]]
        replace = "\\\\/"
        search = "\\\\\\\\"

      [[build_actions.execute.windows.document_path_replace]]
        replace = "/mnt/c"
        search = "C:"

      [[build_actions.execute.windows.file_path_replace]]
        replace = "C:"
        search = "/mnt/c"

[[fields]]
  groupdata = true
  key = "client"
  type = "pull"

  [[fields.fields]]
    key = "company_name"
    type = "string"

  [[fields.fields]]
    key = "contact_person"
    type = "string"

[[fields]]
  key = "date"
  type = "string"

[[fields]]
  key = "mainContent"
  title = "Main Content"
  type = "markdown"

{
   "amount": 2,
   "build_actions": [
      {
         "button_text": "Build PDF",
         "execute": {
            "stdout_type": "message",
            "unix": {
               "args": [
                  "%DOCUMENT_PATH",
                  "-t",
                  "pdf"
               ],
               "command": "%PANDOC_EXECUTABLE"
            },
            "variables": [
               {
                  "name": "PANDOC_EXECUTABLE"
               },
               {
                  "value": "/usr/bin/pandoc"
               }
            ],
            "windows": {
               "args": [
                  "pandoc.exe",
                  "%DOCUMENT_PATH",
                  "-t",
                  "pdf"
               ],
               "command": "wsl"
            }
         },
         "key": "magic_simple_pdf"
      },
      {
         "button_text": "Build PDF",
         "execute": {
            "stdout_type": "file_path",
            "unix": {
               "args": [
                  "run",
                  "github:wearetechnative/quarto-with-batteries#quarto-for-quiqr",
                  "--",
                  "%DOCUMENT_PATH"
               ],
               "command": "%NIX_EXEC"
            },
            "variables": [
               {
                  "name": "NIX_EXEC",
                  "value": "/usr/bin/nix"
               }
            ],
            "windows": {
               "args": [
                  "--distribution",
                  "nixos",
                  "/run/current-system/sw/bin/nix",
                  "run",
                  "--extra-experimental-features",
                  "nix-command flakes",
                  "github:wearetechnative/quarto-with-batteries#quarto-for-quiqr",
                  "--",
                  "%DOCUMENT_PATH"
               ],
               "command": "wsl",
               "document_path_replace": [
                  {
                     "replace": "\\\\/",
                     "search": "\\\\\\\\"
                  },
                  {
                     "replace": "/mnt/c",
                     "search": "C:"
                  }
               ],
               "file_path_replace": [
                  {
                     "replace": "C:",
                     "search": "/mnt/c"
                  }
               ]
            }
         },
         "key": "magic_make_pdf"
      }
   ],
   "dataformat": "yml",
   "extension": "md",
   "fields": [
      {
         "fields": [
            {
               "key": "company_name",
               "type": "string"
            },
            {
               "key": "contact_person",
               "type": "string"
            }
         ],
         "groupdata": true,
         "key": "client",
         "type": "pull"
      },
      {
         "key": "date",
         "type": "string"
      },
      {
         "key": "mainContent",
         "title": "Main Content",
         "type": "markdown"
      }
   ],
   "folder": "content/quotations",
   "hidePreviewIcon": true,
   "itemtitle": "Quotation",
   "key": "sample_field",
   "title": "Quotations",
   "type": "empty-line"
}