settings.xml

settings.xml defines package configuration values and the backend settings UI for those values.

Use it when a package needs administrator-configurable options. QUIQQER imports the configuration defaults and can render settings windows from the XML structure.

Basic Structure

Create settings.xml in the package root.

<?xml version="1.0" encoding="UTF-8"?>
<quiqqer>
    <settings>
        <config>
            <section name="settings">
                <conf name="enabled">
                    <type><![CDATA[bool]]></type>
                    <defaultvalue>1</defaultvalue>
                </conf>
            </section>
        </config>
    </settings>
</quiqqer>

config declares the stored configuration values. window describes how those values are presented in the backend.

When config has a name, QUIQQER stores the values in etc/<name>.ini.php. If the name is omitted for an installed package, QUIQQER uses a package-specific path below etc/plugins/.

Config Sections

Group configuration values with <section>.

<config>
    <section name="settings">
        <conf name="cache">
            <type><![CDATA[bool]]></type>
            <defaultvalue>1</defaultvalue>
        </conf>

        <conf name="html_cache_max_age_header">
            <type><![CDATA[integer]]></type>
            <defaultvalue>3600</defaultvalue>
        </conf>
    </section>
</config>

Use simple names for sections and configuration keys. Configuration keys should be stable because package code reads them by section and name.

Common types include:

• bool
• integer
• string

A section with type="project" creates project-specific configuration sections.

<section name="settings" type="project">
    <conf name="enabled">
        <type><![CDATA[bool]]></type>
        <defaultvalue>1</defaultvalue>
    </conf>
</section>

Each conf uses string as default type and an empty value as default when no type or defaultvalue is declared. Declare both explicitly for public package configuration.

Settings Window

Use <window> to define the backend settings window.

<window name="quiqqer-cache" menu-parent="/settings/quiqqer/">
    <title>
        <locale group="quiqqer/cache" var="settings.title"/>
    </title>
    <params>
        <icon>fa fa-clone</icon>
    </params>
</window>

Use localized titles and descriptions for administrator-facing text.

Categories And Settings Groups

Use <categories> and <category> to group settings inside the window.

<categories>
    <category name="cache_settings" priority="5">
        <text>
            <locale group="quiqqer/cache" var="settings.category.title"/>
        </text>
        <icon>fa fa-clone</icon>

        <settings title="settings" name="settings">
            <title>
                <locale group="quiqqer/cache" var="settings.category.content.title"/>
            </title>
        </settings>
    </category>
</categories>

Use categories for larger settings pages and feature groups.

QUIQQER reads categories from settings/window/categories/category. Project settings windows are declared below project/settings/window.

Inputs

Use inputs to connect backend controls to configuration values.

<input conf="settings.cache" type="checkbox">
    <text>
        <locale group="quiqqer/cache" var="settings.cache"/>
    </text>
    <description>
        <locale group="quiqqer/cache" var="settings.cache.description"/>
    </description>
</input>

The conf attribute points to section.name. The input type controls the rendered control.

Common input types in current packages include:

• checkbox
• number
• text
• hidden

Use <select> when the setting should be selected from fixed options.

<select conf="css.css_inline">
    <option value="">
        <locale group="quiqqer/cache" var="settings.css_inline.nothing"/>
    </option>
    <option value="inline">
        <locale group="quiqqer/cache" var="settings.css_inline.inline"/>
    </option>
</select>

Custom Backend Controls

Settings pages can include package-provided backend controls with data-qui.

<input type="hidden"
       data-qui="package/quiqqer/cache/bin/backend/settings/ClearCache">
</input>

Use custom controls for actions or UI that cannot be represented by standard inputs.

For reusable core input shortcuts and data-qui examples, see Controls And Inputs.

Read Settings In PHP

Package settings can be read through the package config.

$Package = QUI::getPackage('vendor/package');
$Config = $Package->getConfig();
$enabled = $Config->getValue('settings', 'enabled');

Use the same section and key names that are declared in settings.xml.

Real Package Shape

quiqqer/cache defines configuration values and a settings window with grouped inputs:

<quiqqer>
    <settings>
        <config>
            <section name="settings">
                <conf name="cache">
                    <type><![CDATA[bool]]></type>
                    <defaultvalue>1</defaultvalue>
                </conf>
            </section>
        </config>

        <window name="quiqqer-cache" menu-parent="/settings/quiqqer/">
            <title>
                <locale group="quiqqer/cache" var="settings.title"/>
            </title>
            <params>
                <icon>fa fa-clone</icon>
            </params>
        </window>
    </settings>
</quiqqer>

quiqqer/cron adds settings to its own window and to an existing system window:

<window>
    <title>
        <locale group="quiqqer/cron" var="settings.title"/>
    </title>
</window>

<window name="quiqqer">
    <categories>
        <category name="update" index="10">
            <text>
                <locale group="quiqqer/cron" var="settings.update.category.title"/>
            </text>
        </category>
    </categories>
</window>

Practical Checklist

Before adding settings.xml:

• Define defaults in <config>.
• Keep section and key names stable.
• Set a config name when the package should write to a specific config file.
• Use localized titles, labels, and descriptions.
• Group settings into clear categories.
• Use standard input types when possible.
• Add custom backend controls only when a normal input is not enough.
• Read settings through the package config in PHP.