Skip to content

Hyvä CMS User Settings API

This page covers the developer-facing storage and JavaScript API behind Hyvä CMS's Editor Preferences and User Settings: where settings are stored, how to read and write them from JavaScript, and how third-party modules can extend them.

User Settings Storage

User settings are stored in the hyva_commerce_user_settings table, which is owned by the Hyva_Commerce base module. Hyvä CMS adds a cms column that holds a JSON document with two top-level keys:

  • editor_preferences: the General toggles plus a keybindings map
  • favourite_components: the user's starred component names

Default component classes are not stored per user. They live in Magento system configuration at hyva_cms/editor_settings/default_component_classes (global scope) and are applied server-side when a component is created.

User Settings JavaScript API

The per-user settings are exposed through liveview.userSettings:

// Load the current user's settings (memoized; safe to call repeatedly)
await liveview.userSettings.load()

// Save a partial settings object (shallow-merged into the stored JSON)
await liveview.userSettings.save({ editor_preferences: { sidebarOnLeft: true } })

Favorites have their own helper, liveview.favourites:

// Toggle a component in the current user's favourites
await liveview.favourites.toggle('banner')

// Check whether a component is favourited
liveview.favourites.is('banner')

The editor exposes settings through Alpine stores:

  • Alpine.store('userSettings') has the shape { favouriteComponents: [], settings: {}, loaded: false }.
  • Alpine.store('preferences') holds the General toggles keyed by preference id, for example Alpine.store('preferences').sidebarOnLeft.
  • Alpine.store('keybindings') holds { definitions, bindings }.

Extending User Settings

Third-party modules can mirror their own settings key onto an Alpine store property by listening for the liveview:user-settings:init event and calling registerStoreBinding:

document.addEventListener('liveview:user-settings:init', (event) => {
    event.detail.userSettings.registerStoreBinding('my_module_settings', {
        storeKey: 'myModuleSettings',
        defaultValue: {}
    })
})

After binding, the value saved under my_module_settings is mirrored onto Alpine.store('userSettings').myModuleSettings, and saving through liveview.userSettings.save({ my_module_settings: ... }) persists it for the current user.

User Settings Controllers and ACL

User settings are read and written through admin controllers gated by the Magento_Backend::content ACL resource:

  • GET liveview/user/getsettings returns the current user's saved settings.
  • POST liveview/user/savesettings shallow-merges a settings object into the stored JSON.

Default component classes use separate controllers (liveview/config/get and liveview/config/save) that write to system configuration, restricted to a whitelist of allowed config fields.