The administration design switch: settings, designs and roles #

This guide is for administrators and developers who set up the per-session choice of the administration design (the feature). You will read the settings, add an installed design to the list, make sure every offered design lets a user switch back, give the permission to a role, test the result and solve the usual problems. It takes about twenty minutes.

Everything below was checked against the code: kernel/classes/uiswitch/expuiswitchdesignprovider.php, the UI switch registry kernel/classes/uiswitch/expuiswitch.php and eZTemplateDesignResource::designBaseCachePath() in kernel/common/eztemplatedesignresource.php. The framework and the interface language are in UI switch settings.

Guides · Related guides: UI switch settings, Templates and design, Roles and policies, Caches

In short #

• The design switch is the provider design of settings/uiswitch.ini: [UISwitchSettings] ProviderList[]=design (after language) and the group [UISwitch_design].
• AllowedValues[] lists the designs in toolbar order; DesignChain[<design>] gives each its fallback designs; DesignLabel[<design>] its name in the toolbar. A design without a chain, or that is not installed, is not offered.
• Every offered design must render the right toolbar tool admin_ui_switch, or a user who chose it cannot switch back.
• Users need the policy uiswitch/design.
• No cache needs clearing for a switch. After changing the settings, clear the INI cache and deploy as usual.

1. The settings #

Never edit settings/uiswitch.ini. Override it in settings/override/uiswitch.ini.append.php, in a siteaccess's settings/siteaccess/<siteaccess>/uiswitch.ini.append.php, or in an extension's settings/uiswitch.ini.append.php.

The shipped group:

[UISwitchSettings]
ProviderList[]=design

[UISwitch_design]
Class=expUISwitchDesignProvider
Enabled=true
AllowedValues[]
AllowedValues[]=admin4l
AllowedValues[]=admin4
AllowedValues[]=adminui
AllowedValues[]=admin3
AllowedValues[]=admin
AllowedValues[]=admin_classic
DesignChain[]
DesignChain[admin4l]=admin4;admin3;admin2;admin
DesignChain[admin4]=admin3;admin2;admin
DesignChain[adminui]=admin4l;admin4;admin3;admin2;admin
DesignChain[admin3]=admin2;admin
DesignChain[admin]=
DesignChain[admin_classic]=admin
DesignLabel[]
DesignLabel[admin4l]=Admin 4 (layouts)
DesignLabel[admin4]=Admin 4
DesignLabel[adminui]=AdminUI
DesignLabel[admin3]=Admin 3
DesignLabel[admin]=Classic
DesignLabel[admin_classic]=Classic (server-rendered)
RememberPreference=disabled

Where the switch works at all (which siteaccesses) is set by [UISwitchSettings] SiteAccessList[]; empty means every siteaccess whose design list contains an administration design. See UI switch settings.

A design is offered only when all of these hold:

1. it is listed in AllowedValues[] (or it is the siteaccess's own design);
2. its name matches [a-z][a-z0-9_]* (at most 64 characters);
3. it has a DesignChain[] entry;
4. design/<design> exists, or design/<design> of an extension listed in design.ini [ExtensionSettings] DesignExtensions[].

Nothing a user sends is used as a path: a value is accepted only when it is exactly one of the offered designs.

2. Adding an installed design #

Take the classic server-rendered design admin_classic of the extension sevenx_themes_admin_classic (0.2.5 or later) as the example. Its entry is already in the kernel defaults above (AllowedValues[]=admin_classic, DesignChain[admin_classic]=admin, DesignLabel[admin_classic]=Classic (server-rendered)), so the design is offered as soon as its directory exists: the extension registers it in settings/design.ini.append.php (DesignExtensions[]=sevenx_themes_admin_classic). Activating the extension is all that is needed. The extension's own settings/uiswitch.ini.append.php repeats the same three values; that is harmless, a design listed twice is offered once.

Offering AdminUI on other siteaccesses #

adminui is offered on a siteaccess only when the exp_adminui extension is active there, because its design directory is registered by that extension. On a stock installation that is only the adminui siteaccess (ActiveAccessExtensions[]=exp_adminui), where AdminUI is the default design and the other designs are offered.

To offer AdminUI on the admin and editor siteaccesses too, activate the extension in the settings/siteaccess/<siteaccess>/site.ini.append.php of each:

[ExtensionSettings]
ActiveAccessExtensions[]=exp_adminui

This also brings the extension's global settings to that siteaccess: design.ini [ExtensionSettings] DesignExtensions[]=exp_adminui, exp_adminui.ini, and the class icons of its settings/override/icon.ini.append.php (other extensions' own icon maps still outrank them). Its settings for the adminui siteaccess (settings/siteaccess/adminui/: translations, menus and the rest) do not apply. Clear the INI cache and deploy afterwards (section 6).

For a design of your own:

1. Put it in design/<name> or in extension/<extension>/design/<name> with the extension in DesignExtensions[].
2. Add AllowedValues[]=<name>, DesignChain[<name>]=... and DesignLabel[<name>]=... in an override or in your extension's settings/uiswitch.ini.append.php. End the chain with a design that has the switch tool (section 3); admin ends every shipped chain.
3. Add the label to your translations in the context kernel/uiswitch if it should be translated.
4. Clear the INI cache and deploy (section 6).

Do not write AllowedValues[] without a value in an extension: an empty AllowedValues[] line clears the list that was read before it, so the kernel's designs would disappear.

3. Every offered design needs the switch tool #

A user who switches to a design must find the switch again in that design, or they cannot go back until they log out. The tool is the toolbar tool admin_ui_switch, template toolbar/full/admin_ui_switch.tpl:

The design's page layout must also render the right toolbar ({tool_bar name='admin_right' view='full'}; the classic page layout does so while the right menu is shown). The classic page layout (design/admin/templates/pagelayout.tpl) shows the right menu unless the user closed it (admin_right_menu_show=0), as admin4 does, so the switch stays in reach. The siteaccess's toolbar.ini must place the tool there:

[Tool]
AvailableToolArray[]=admin_ui_switch

[Toolbar_admin_right]
Tool[]=admin_ui_switch

The shipped admin, editor and adminui siteaccesses have it. A siteaccess whose own design is the classic one (for example one with SiteDesign=admin) needs these lines in its settings/siteaccess/<siteaccess>/toolbar.ini.append.php to show the switch. The toolbar comes from the siteaccess, not from the chosen design, so one entry serves every design.

The tool is hidden while editing and browsing, and it is empty for a user without any uiswitch/* policy.

4. Giving the permission #

1. Go to Users > Roles and policies and open the role (for example Editor).
2. Edit, New policy, module uiswitch, function design, and save.
3. Assign the role as usual.

The function uiswitch/design exists because design is in ProviderList[]; it takes no limitations. A role with uiswitch/* (or */*, as Administrator has) already includes it. The permission is checked on every request, so removing the policy takes effect at the user's next page.

5. Testing it #

1. Sign in with a test user that holds uiswitch/design (not the shared administrator account, whose preferences are someone's work environment).
2. In the right toolbar, Interface, Administration design: choose Admin 4. The page reloads in admin4.
3. Choose Classic. The page reloads in the classic design, and the Interface box is in its right menu.
4. Choose the first design (the siteaccess's own). The switch is cleared.
5. In a second browser, sign in as another user: the interface is the siteaccess's own design throughout.
6. Open the Audit tab (/audit/dashboard) and look for access.uiswitch.change: one record per change, with provider design and the values before and after.
7. Log out and in again: the siteaccess's own design (unless RememberPreference=enabled).

From a shell, uiswitch/state (GET, signed in) returns the providers the user may use, their designs and the current one as JSON.

The developer tests run without a database:

php vendor/bin/phpunit tests/tests/kernel/classes/uiswitch/expUISwitchDesignProviderTest.php

6. Deploying a settings change #

A switch itself needs no cache clearing: every design has caches of its own. After changing uiswitch.ini or toolbar.ini, clear the INI cache and deploy:

./console exp:velocity deploy --allow-root-user

or, by hand, php bin/php/ezcache.php --clear-tag=ini --allow-root-user, a reload of the PHP-FPM that serves the site, and exp:velocity restart for Velocity. A new provider class needs regenerated autoloads before the settings name it (deploy --kernel for a kernel class). A global cache clear is not needed.

7. Turning it off and on #

When it is off, no setting is changed in memory, no cache variant is used and every cache file name is the one it was without the feature. A stored choice is ignored; with [UISwitch_design] Enabled=false it is also dropped from the session at the next request.

8. Troubleshooting #

Related pages #

• Feature: choosing the administration design
• Developer notes: the administration design switch
• UI switch and its settings
• Roles and policies, Caches, Templates and design