Understanding Configuration Scope

Understanding Configuration Scope

Settings for Liferay DXP’s services and applications are applied at one of four levels, or scopes: System, Virtual Instance, Site, or Widget. Settings made in System Settings are set at a system-scoped level. For scopes labeled other than System, the System Settings values act as defaults. In other words, they identify where the system-wide configuration is overridden. True system-scoped configurations (those under a category’s System Scope heading) are not overridden anywhere.

Some System Settings categories hold entries of multiple scopes.

Scope Definitions

System Scope: Configuration made for system scoped entries are the final value for the application in a system-wide fashion. They affect the whole system and are not overridden anywhere else.

Some System Settings entries are system scoped.

Virtual Instance Scope: Configuration at the Virtual Instance level is overridden in Instance Settings.

Some System Settings are virtual instance scoped.

Site Scope: Configuration at this scope is overridden in each Site.

Some System Settings are Site scoped.

Widget Scope: Configuration at this scope is overridden in each Widget Instance.

Some System Settings entries are widget scoped.

Example: Configuring and Overriding Blogs Comments

If a configuration changed in System Settings is also configurable at a different scope, the System Settings value is a default that can be overridden. Once a configuration change is made at a more granular scope, a change at the system level does nothing.

For example, allowing comments is configurable for each Blogs widget.

  1. Set the default behavior at Control Panel → Configuration → System Settings → Blogs (in the Content and Data category).
  2. In the Blogs Entry under Widget Scope, disable the Enable Comments checkbox.
  3. Add a Blog Entry to a Site’s Content & Data → Blogs application.
  4. Go to a page and add the Blogs Widget to the page.
  5. Click the Options button (Options) for the widget and select Configuration.

You’ll see the same Enable Comments checkbox, and its default is now false (unchecked). Checking the box in the Widget Configuration overrides the System Settings entry. Changing the System Settings configuration has no effect on this widget anymore.

Override widget scoped System Settings from the widget itself.

System Settings and Instance Settings

Instance Settings is similar to System Settings, but configures applications and services at the Virtual Instance scope. Like System Settings, the configuration entries in Instance Settings have a Reset to Default Values option. In Instance Settings, this removes the custom configuration you provided and makes the current value (whether default or custom) from the system scope the default at the virtual instance scope.