settings.xml

XML schema: settings.xsd · Linking and validation.

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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://www.quiqqer.com/docs/schemas/2.x/settings.xsd">
    <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. A category can also load a package-provided backend control with require:

<category name="vendor.package.tools"
          require="package/vendor/package/bin/backend/Tools">
    <text>Package Tools</text>
    <icon>fa fa-wrench</icon>
</category>

Use an existing AMD control from your package for the require path. For fields stored on individual users, use the category and settings structure in user.xml.

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

Settings Descriptions

Inside a UI <settings> group, use <title> for the heading and <description> for explanatory content. Descriptions appear in document order and support plain text, locale references, and CDATA content. They can appear before the title or without a title and are never used as the heading.

<settings name="vendor.package.general">
    <title>General Options</title>
    <description>Choose the default behavior for this package.</description>
    <input conf="general.enabled" type="checkbox">
        <text>Enable feature</text>
        <description>Apply this option to new records.</description>
    </input>
</settings>

This UI structure also applies to settings groups in project settings, user.xml, group.xml, site.xml, and panel.xml.

Deprecated: <text> directly under <settings> remains readable for backward compatibility, but the XSDs reject it. Use <description> for body text and <title> for a heading. The Settings reader retains its legacy behavior of using the first <text> as the heading if no heading has been set. <text> inside controls, categories, and tabs remains supported and is not deprecated by this change.

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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://www.quiqqer.com/docs/schemas/2.x/settings.xsd">
    <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.