LLNG-BUILD-MANAGER-FILES(1p)

NAME
llng-build-manager-files - Regenerate LemonLDAP::NG Manager with plugin extensions

SYNOPSIS
  llng-build-manager-files [--plugins-dir=<path> ...] [options]

DESCRIPTION
This script allows LemonLDAP::NG plugins to extend the Manager interface by adding new configuration attributes, tree nodes (for the configuration tree), and portal constants.

Extensions can be provided in either Perl (.pm) or JSON (.json) format and are loaded from the specified plugins directory.

OPTIONS

--plugins-dir=path
    Directory containing plugin extension files (.pm or .json). Can be specified multiple times to scan several directories. If not specified or a directory doesn't exist, it is skipped with a warning.

--struct-file=path
    Output path for struct.json file.

--conftree-file=path
    Output path for conftree.js file.

--manager-constants-file=path
    Output path for ReConstants.pm file.

--manager-attributes-file=path
    Output path for Attributes.pm file.

--default-values-file=path
    Output path for DefaultValues.pm file.

--conf-constants-file=path
    Output path for Constants.pm file.

--reverse-tree-file=path
    Output path for reverseTree.json file.

--portal-constants-file=path
    Output path for portal Constants.pm file.

--handler-status-constants-file=path
    Output path for StatusConstants.pm file.

--lang-dir=path
    Directory containing language JSON files (e.g., en.json, fr.json). Translations from extensions will be merged into these files.

--verbose, -v
    Show detailed progress information.

--help, -h
    Show help message.

EXTENSION FILE FORMAT

  Perl Format (.pm)
  package MyPlugin::Extension;

  sub attributes {
      return {
          myPluginEnabled => {
              type          => 'bool',
              default       => 0,
              documentation => 'Enable my plugin',
              help          => 'myplugin.html',
          },
          myPluginOption => {
              type    => 'text',
              default => 'default_value',
          },
      };
  }

  sub tree {
      return {
          insert_into => 'generalParameters/plugins',
          nodes => [
              {
                  title => 'myPluginNode',
                  help  => 'myplugin.html',
                  form  => 'simpleInputContainer',
                  nodes => ['myPluginEnabled', 'myPluginOption'],
              }
          ],
      };
  }

  sub ctrees {
      return {
          # Extend oidcRPMetaDataNode with additional options
          oidcRPMetaDataNode => {
              insert_after => 'oidcRPMetaDataMacros',
              nodes => [
                  {
                      title => 'myPluginOidcOptions',
                      form  => 'simpleInputContainer',
                      nodes => ['myPluginOidcAttr'],
                  }
              ],
          },
      };
  }

  sub constants {
      return {
          PE_MYPLUGIN_ERROR => 200,
      };
  }

  sub lang {
      return {
          myPluginEnabled => {
              en => 'Enable my plugin',
              fr => 'Activer mon plugin',
          },
          myPluginOption => {
              en => 'My plugin option',
              fr => 'Option de mon plugin',
          },
      };
  }

  1;

  JSON Format (.json)
  {
    "attributes": {
      "myPluginEnabled": {
        "type": "bool",
        "default": 0,
        "documentation": "Enable my plugin"
      }
    },
    "tree": {
      "insert_into": "generalParameters/plugins",
      "nodes": [
        {
          "title": "myPluginNode",
          "form": "simpleInputContainer",
          "nodes": ["myPluginEnabled"]
        }
      ]
    },
    "ctrees": {},
    "constants": {
      "PE_MYPLUGIN_ERROR": 200
    },
    "lang": {
      "myPluginEnabled": {
        "en": "Enable my plugin",
        "fr": "Activer mon plugin"
      }
    }
  }

AUTH PLUGIN DECLARATION
Authentication plugins can declare themselves via the "authPlugin" key (top level of an extension file, alongside "attributes", "tree", etc.) instead of manually appending to every select list:

  "authPlugin": {
    "k": "JsonFile",
    "v": "JSON File (dev/test)",
    "roles": ["authentication", "userDB"]
  }

Multiple plugins may be declared as an array. Allowed roles are "authentication", "userDB", and "passwordDB". The option is appended to the following core selects based on the declared roles:

•   "authentication" role: "authentication", "authChoiceModules" (auth slot), "combModules"

•   "userDB" role: "userDB", "authChoiceModules" (userDB slot), "combModules"

•   "passwordDB" role: "passwordDB", "authChoiceModules" (password slot)

Appends are deduplicated on the "k" key, so re-running the rebuilder or declaring the same plugin in multiple files is safe.

TREE INSERTION
The "tree" and "ctrees" extensions support the following insertion options:

insert_into
    Path to the target node, using "/" as separator (e.g., "generalParameters/plugins").

insert_after
    Insert new nodes after the node with this title.

insert_before
    Insert new nodes before the node with this title.

If neither "insert_after" nor "insert_before" is specified, nodes are appended at the end.

If "insert_after" or "insert_before" refers to a sibling that does not exist in the target tree, nodes are also appended at the end and a warning is printed on stderr pointing to the offending extension file.

TRANSLATIONS
Extensions can provide translations for their configuration keys using the "lang" function (Perl) or "lang" key (JSON). Translations are specified as a hash where keys are the translation identifiers and values are hashes mapping language codes to translated text.

If a translation is not provided for a specific language, the script will:

1. Use the English ("en") translation if available
2. Fall back to the first available translation

This ensures all language files get an entry even if translations are only provided for a subset of languages.

PORTAL CONSTANTS
Plugin constants should use values >= 200 to avoid conflicts with core constants. A warning is issued if a value below 200 is used.

EXAMPLES
  # Regenerate with plugins (uses default paths from installation)
  llng-build-manager-files --plugins-dir=/etc/lemonldap-ng/manager-overrides.d

  # Multiple plugin directories
  llng-build-manager-files \
    --plugins-dir=/etc/lemonldap-ng/manager-overrides.d \
    --plugins-dir=/usr/share/lemonldap-ng/plugins.d

  # Verbose mode
  llng-build-manager-files --plugins-dir=/etc/lemonldap-ng/manager-overrides.d -v

  # Override specific output paths (useful for testing)
  llng-build-manager-files \
    --plugins-dir=/etc/lemonldap-ng/manager-overrides.d \
    --struct-file=/custom/path/struct.json

SEE ALSO
Lemonldap::NG::Manager::Build, <https://lemonldap-ng.org/>

AUTHORS
LemonLDAP::NG team <http://lemonldap-ng.org/team>

LICENSE
This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.