Scrivito Picks

A visual style picker for Scrivito boolean, enum, and multienum attributes.

Installation

npm install scrivito-picks

Usage

ScrivitoPicks.createComponent registers an editor component and returns a component name. Use this for Scrivito SDK < 1.27.0:

// HeadlineWidgetEditingConfig.js
import * as Scrivito from "scrivito";
import * as ScrivitoPicks from "scrivito-picks";

// Add a "My custom style" style picker tab to the headline widget:
Scrivito.provideEditingConfig("HeadlineWidget", {
  title: "Headline",
  propertiesGroups: [
    {
      title: "My custom style",
      component: ScrivitoPicks.createComponent([
        /* my custom attributes */
      ]),
    },
  ],
});

With Scrivito SDK ≥ 1.27.0, ScrivitoPicks.component can be used as an alternative. It returns a component. The properties group key must be set:

import * as Scrivito from "scrivito";
import * as ScrivitoPicks from "scrivito-picks";

Scrivito.provideEditingConfig("HeadlineWidget", {
  propertiesGroups: [
    {
      title: "My custom style",
      key: "my-custom-style",
      component: ScrivitoPicks.component([
        /* ... */
      ]),
    },
  ],
});

Arguments

Both createComponent and component take a single argument.

attributes - An array of attribute options [{attribute: 'myEnum', values: ... }, ...]. For a single attribute, a plain attribute options object can be passed instead of a one-element array.

Attribute options

An object describing how an attribute is presented.

| Option | Description | | ------------------ | ---------------------------------------------------------------------------------------------------- | | attribute | The attribute name. | | values | An array describing the available items and their representation. See value properties. | | title | The attribute title. If false, no title will be shown. Default: the sentence cased attribute name. | | previewClassName | A callback returning the className of a value preview element. | | previewStyle | A callback returning the style of a value preview element. | | previewText | A callback returning the inner text (or component) of a value preview element. | | renderPreview | A render callback for a value preview. If set, preview* options are ignored. | | thumbnail | A callback returning the URL of the thumbnail image for a value. |

If an option has a static value, you can use a string (or an object for the previewStyle property) instead of a callback.

Value properties

An object that describes an attribute value. Individual attribute options can be overridden per value.

| Property | Description | | ------------------ | ------------------------------------------------------------------------- | | value | The attribute value. | | title | The attribute title shown to the user. Default: the sentence cased value. | | previewClassName | Override the previewClassName for this value. | | previewStyle | Override the previewStyle for this value. | | previewText | Override the previewText for this value. | | renderPreview | Override the renderPreview callback for this value. | | thumbnail | Override the thumbnail for this value. |

Callback parameters

Many options can be configured as a callback. The callback receives an object with the following parameters:

| Parameter | Description | | --------- | --------------------------------------------------------------------------------------- | | value | The attribute value of the item. | | page | The Scrivito.Obj containing the edited attribute. undefined when editing a widget. | | widget | The Scrivito.Widget containing the edited attribute. undefined when editing a page. | | content | Convenience parameter for (page \|\| widget). |

Examples

A single attribute

// Create a picker for the `alignment` enum attribute.
// There are three options, each option is represented by a Font Awesome icon.
component: ScrivitoPicks.createComponent({
  attribute: 'alignment',
  values: [
    { value: 'left', previewClassName: 'fa fa-4x fa-align-left' },
    { value: 'center', previewClassName: 'fa fa-4x fa-align-center' },
    { value: 'right', previewClassName: 'fa fa-4x fa-align-right' },
  ],
}),

// Same as the first example, but with custom options titles.
// The Font Awesome icon is computed by a callback.
component: ScrivitoPicks.createComponent({
  attribute: "alignment",
  previewClassName: ({ value }) => `fa fa-4x fa-align-${value}`,
  title: "Horizontal alignment",
  values: [
    { value: "left", title: "Left aligned" },
    { value: "center", title: "Centered" },
    { value: "right", title: "Right aligned" },
  ],
});

// Render custom preview components:
component: ScrivitoPicks.createComponent({
  attribute: "alignment",
  values: [{ value: "left" }, { value: "center" }, { value: "right" }],
  renderPreview: ({ value }) => <i className={`fa fa-4x fa-align-${value}`} />,
});

Multiple attributes

// Create a picker for two attributes, `alignment` and `style`:
component: ScrivitoPicks.createComponent([
  {
    attribute: "alignment",
    values: [
      { value: "left", previewClassName: "fa fa-4x fa-align-left" },
      { value: "center", previewClassName: "fa fa-4x fa-align-center" },
      { value: "right", previewClassName: "fa fa-4x fa-align-right" },
    ],
  },
  {
    attribute: "style",
    title: "Heading style",
    values: [
      {
        value: "h1",
        title: "Level 1 heading",
        previewClassName: "fa fa-4x fa-h1",
      },
      {
        value: "h2",
        title: "Level 2 heading",
        previewClassName: "fa fa-3x fa-h2",
      },
      {
        value: "h3",
        title: "Level 3 heading",
        previewClassName: "fa fa-2x fa-h3",
      },
    ],
  },
]);