/ 
Lemonldap-NG-Manager-2.23.0
/ llng-build-manager-files

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.