Skip to content

Scrivito Picks 🍱 A visual style picker for Scrivito

License

Notifications You must be signed in to change notification settings

dcsaszar/scrivito-picks

Repository files navigation

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