scrivito-picks

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",
      },
    ],
  },
]);