View Settings Facet

[KremnevDmitry]

No description provided.

[Flaurite]

UI Settings

UI Settings is a mechanism for saving state from UI components or custom data for an opened View. These settings are saved only for current authenticated user.

UI Settings are persisted in a database in UI_UI_SETTINGS table. JPA entity is UiSettings.

To enable settings, the project must contain a dependency:

implementation 'io.jmix.flowui:jmix-flowui-data-starter'

SettingsFacet

To enable settings in View, it should contain the SettingsFacet. The simplest way to add facet is XML. For instance:

<facets>    
    <settings id="settings" auto="true"/>  
</facets>

Facet with auto="true" tries to find all components with defined ID that supports "settings". All these components will save and apply their settings. For now, these components are:

• DataGrid/TreeDataGrid: saves order of columns, with of columns, sorting;
• Details: saves "opened" state;
• SimplePagination: saves maxResults (if itemsPerPageVisible is true).
• GenericFilter: saves "opened" state;

SettingsFacet XML

The definition of SettingsFacet in XML is:

<settings id="settings" auto="true"/>

• auto attribute. "true" value means that facet finds all components with defined ID that support "settings". "false" value - won't scan all components in View and will get only specified component within its tag.
  Default value - false.

SettingsFacet. Manual mode

If it is required to apply/save settings only for a few components, use facet with auto = false and specify components within settings tag.

<settings id="settings">
    <component id="dataGrid"/>
</settings>

In the example above, only dataGrid saves and applies settings in a View.

SettingsFacet. Exclude components

If it is required to exclude component from facet with auto = true, add component with enabled = false within facet's tag:

<settings id="settings" auto="true">
    <component id="dataGrid" enabled="false"/>
</settings>

In the example abode, all components in a View that supports "settings" apply/save them, excepting dataGrid.

SettingsFacet lifecycle

Navigating to view:

1. SettingsFacet applies "data loading" settings.
2. View's BeforeShowEvent
3. SettingsFacet applies settings.
4. View's ReadyEvent

Closing View:

1. SettingsFacet` saves settings.
2. View's DetachEvent

SettingsFacet handlers

1. setApplySettingsDelegate();

@ViewComponent
protected SettingsFacet settings;

@Install(to = "settings", subject = "applySettingsDelegate")
protected void settingsApplySettingsDelegate(final SettingsFacet.SettingsContext settingsContext) {
    settings.applySettings();
}

2. setApplyDataLoadingSettingsDelegate();

@ViewComponent
protected SettingsFacet settings;

@Install(to = "settings", subject = "applyDataLoadingSettingsDelegate")
protected void settingsApplyDataLoadingSettingsDelegate(final SettingsFacet.SettingsContext settingsContext) {
    settings.applyDataLoadingSettings();
}

3. setSaveSettingsDelegate();

@ViewComponent
protected SettingsFacet settings;

@Install(to = "settings", subject = "saveSettingsDelegate")
protected void settingsSaveSettingsDelegate(final SettingsFacet.SettingsContext settingsContext) {
    settings.saveSettings();
}

[knstvk]

The facet is incorrectly described for Studio:

• Must be in Facets category
• auto property must be set to true automatically

[knstvk]

Rename entity and table:

@Entity(name = "flowui_UserSettingsItem")
@JmixEntity
@Table(name = "FLOWUI_USER_SETTINGS")
@SystemLevel
public class UserSettingsItem implements Serializable {

Also update the localized name:

io.jmix.flowuidata.entity/UserSettingsItem=User settings

[befayer]

Testing on:
Jmix version: 2.1.999-SNAPSHOT
Jmix Studio plugin version: 2.1.SNAPSHOT5696-232
IntelliJ version: IntelliJ IDEA 2023.2.2 (Ultimate Edition)