Preferences

There are lots of configurations that may differ based on user experience and preferences. Think of date formats, time zones, theming and more.

These configurations should also have a default value, or may fall back on the preference of the tenant.

Creating a preference

We can optionally at a field now to the TenantPreferenceController and the AuthPreferenceController so users may edit this preference in a form:

Color::make(__('Some color'), 'some_color')
   ->default('#f1f1f1'),

Since these controllers use tabs in their form layouts, be sure to add this field to the layout.

Usage

Backend

To retrieve a preference:

$value = preference('primary_color');

To set a preference:

// On the user:
auth()->user()->setPreference($name, $value);

// On the tenant:
auth()->user()->tenant->setPreference($name, $value);

Front-end

To retrieve a preference:

this.$preference("primary_color");

Extending Preferences

Appending the field collection

Hook into the GetAuthPreferenceFieldsAction action to append fields:

actions()->after(new GetAuthPreferenceFieldsAction(), AppendAuthPreferenceFields::class);

...

class AppendAuthPreferenceFields extends ActionHook
{
    public function __construct(protected AuthPreferenceFields $modified, protected AuthPreferenceFields $original){}

    public function identifier(): string
    {
        return (new GetAuthPreferenceFieldsAction)->identifier() . '.qore-package';
    }

    public function run()
    {
        return $this->modified
            ->push(
                Text::make('Field 1', 'qore_package_field_1')
                    ->default(preference('hoi'))
                    ->fillUsing(function ($value, $validatedData) {
                        ...
                    }),
                Select::make('Field 2', 'qore_package_field_2')
                    ->default(1)
                    ->preventFill(),
            );
    }
}

Storing field data

• preventFill - To prevent storing the field data use preventFill
• fillUsing - To implement your own solution for storing the field data use php ->fillUsing(fn (mixed $value, array $formData) => ... )
• Default behaviour - The preference controller will using auth()->user()->setPreference($fieldName, $fieldValue)

Appending fields best practices

Fields should start with an identifier. One could use the tab title, or the package name qore_package_<actual_field_name>. This prevents field name collisions.

Appending tabs

Hook into the GetAuthPreferenceFieldLayoutTabsAction action to add tabs to the preference field layout:

actions()->after(new GetAuthPreferenceFieldLayoutTabsAction(), AppendAuthPreferenceFieldLayout::class);

...

 class AppendAuthPreferenceFieldLayout extends ActionHook
{
    public function __construct(protected array $modified, array $original){}

    public function identifier(): string
    {
        return (new GetAuthPreferenceFieldLayoutTabsAction())->identifier() . '.qore-package-tabs';
    }

    public function run(): array
    {
        return array_merge(
            $this->modified,
            [
                __('My tab name') => [
                    'qore_package_field_1',
                    'qore_package_field_2',
                ]
            ]
        );
    }
}

Appending tabs best practices

• Try to use clear and distinct tab names to prevent collision.
• Use the $this->modified array instead of $this->original. This prevents accidental overriding of changes made by other hooks.
• Merge your tabs with the tabs existing in $this-modified