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. Its keys include:

  • editor_preferences: the General toggles plus a keybindings map
  • favourite_components: the user's starred component names
  • preview_preferences: device sizes, preview order and split-view preferences
  • For tours and category ordering: category_order, has_seen_onboarding_tour, tour_enabled, announcements_enabled, seen_features and seen_announcements

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)
const settings = await liveview.userSettings.load()
await liveview.userSettings.save({
    editor_preferences: { ...settings.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 Hyva_Cms::cms ("Hyvä CMS") root ACL resource, so any admin user with access to Hyvä CMS can read and save their own settings:

  • 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.

Preference Sections

Add a Hyva\CmsLiveviewEditor\Block\Adminhtml\Liveview\PreferenceSection child under editor.preferences in layout XML, with an id, label, sort_order and body template. Its Alpine component registers with window.liveviewPreferenceSections and can provide onOpen, onShow, onClose, settingsPayload, save and onSaved callbacks.

Use settingsPayload when sections contribute to the same stored key: ordinary per-key writes replace that key's whole value. Dispatch preference-section-dirty with {id, dirty, canSave} to tell the dialog whether the section has changes and can be saved. Section bodies initialize when first visited; do not overwrite settings for a section the user has not opened.

For component category defaults, extend Hyva\CmsLiveviewEditor\Model\Component\CategoryOrder by content type. User overrides remain separate. Browser header arrangements and clipboard history are not stored in the CMS user-settings JSON.