Interface for engines providing editor extensions.

function MyFileSelectionHandler(options) { this.call =
  function(file) { // invoked with the selected file };

  this.getReferer = function() { // the path to return to
    when the back button is clicked // or after file
    selection return '/some/path'; } }

editor.registerPageConfigurationMixin({
  externalLinks: function() {
    return new Backbone.Collection(this.get('external_links'));
  }
}

state.pages.get(1).configuration.externalLinks().each(...);

editor.selectFile('image_files',
                           'my_file_selection_handler',
                           {some: 'option for handler'});

editor.selectFile({name: 'image_files', filter: 'some_filter'},
                           'my_file_selection_handler',
                           {some: 'option for handler'});

API to allow access to failure UI and recovery.

Can watch collections for errors saving models and display the error allong with a retry button.

editor.failures.watch(collection);

It's possible to add failures to the UI by adding instances of subclasses of Failure:

editor.failures.add(new OrderingFailure(model, collection));

Failure and subclasses are used in the failures api.

Subclasses that represent failures that are can not be retried should override catRetry with false. Retryable failures should implement retryAction.

Watch Backbone collections to track which models are currently being saved. Used to update the notifications view displaying saving status/failutes.

Mixins for models with a nested configuration model.

Triggers events on the parent model of the form change:configuration and change:configuration:<attribute>, when the configuration changes.

import {configurationContainer} from 'pageflow/editor';

const Section = Backbone.Model.extend({
  mixins: [configurationContainer({autoSave: true})]
});

const section = new Section({configuration: {some: 'value'}});
section.configuration.get('some') // => 'value';

Remove model from collection only after the DELETE request has succeeded. Still allow tracking that the model is being destroyed by triggering a destroying event and adding a isDestroying method.

Mixins for Backbone models and collections that use entry type specific editor controllers registered via the editor_app entry type option.

import {editor, entryTypeEditorControllerUrls} from 'pageflow/editor';

editor.registerEntryType('test', {
// ...
});

export const ItemsCollection = Backbone.Collection.extend({
  mixins: [entryTypeEditorControllerUrls.forCollection({resources: 'items'})
});

new ItemsCollection().url() // => '/editor/entries/10/test/items'

import {editor, entryTypeEditorControllerUrls} from 'pageflow/editor';

editor.registerEntryType('test', {
// ...
});

export const Item = Backbone.Model.extend({
  mixins: [entryTypeEditorControllerUrls.forModel({resources: 'items'})
});

new Item({id: 20}).url() // => '/editor/entries/10/test/items/20'

Mixin for Backbone models that shall be watched by modelLifecycleTrackingView mixin.

A Backbone collection that is automatically updated to only contain models with a foreign key matching the id of a parent model.

Base view to edit configuration container models. Extend and override the configure method which receives a ConfigurationEditorView to define the tabs and inputs that shall be displayed.

Add a translationKeyPrefix property to the prototype and define the following translations:

• <translationKeyPrefix>.tabs: used as tabTranslationKeyPrefix of the ConfigurationEditorView.

• <translationKeyPrefix>.attributes: used as one of the attributeTranslationKeyPrefixes of the ConfigurationEditorView.

• <translationKeyPrefix>.back (optional): Back button label.

• <translationKeyPrefix>.save_error (optional): Header of the failure message that is displayed if the model cannot be saved.

• <translationKeyPrefix>.retry (optional): Label of the retry button of the failure message.

Override the goBackPath property or method to customize the path that the back button navigates to. Defaults to /.

Override the defaultTab property or method to set the initially selected tab.

Override the getActionsMenuItems method to add menu items to the actions dropdown.

The view navigates back when the model is destroyed. Override the containingCollection property or method to also navigate back when the model is removed from the returned collection.

Base class for input views that reference models.

Input view to reference a file.

Input view for oEmbed URLs that resolves and normalizes URLs via oEmbed.

Extends UrlInputView to validate URLs via oEmbed and optionally transform them using provider-specific processing functions. The oEmbed response is not stored; it's only used during validation to normalize/transform the URL.

new OembedUrlInputView({
    model: contentElement,
    propertyName: 'url',
    displayPropertyName: 'displayUrl',
    providerNameProperty: 'provider',
    providers: {
      bluesky: {
        supportedHosts: ['bsky.app', 'bsky.social'],
        transform: function(response) {
          // Return canonical URL from response
          return response.url || response.author_url;
        }
      },
      instagram: {
        supportedHosts: ['instagram.com', 'www.instagram.com'],
        skipOembedValidation: true
      }
    }
  });

Mixin for Marionette Views that sets css class names according to life cycle events of its model.

A button that displays a drop down menu on hover.

A menu item that shows a confirmation dialog before calling a destroy callback.

A generic list view with items consisting of a thumbnail, text and possibly some buttons or a navigation arrow.

Models inside the collection must implement the following methods:

Base thumbnail view for models supporting a thumbnailFile method.

Mixin for input views handling common concerns like labels, inline help, visiblity and disabling.

Label and Inline Help Translations

By default #labelText and #inlineHelpText are defined through translations. If no attributeTranslationKeyPrefixes are given, translation keys for labels and inline help are constructed from the i18nKey of the model and the given propertyName option. Suppose the model's i18nKey is "page" and the propertyName option is "title". Then the key

activerecord.attributes.page.title

will be used for the label. And the key

pageflow.ui.inline_help.page.title_html
pageflow.ui.inline_help.page.title

will be used for the inline help.

Attribute Translation Key Prefixes

The attributeTranslationKeyPrefixes option can be used to supply an array of scopes in which label and inline help translations shall be looked up based on the propertyName option.

Suppose the array ['some.attributes', 'fallback.attributes'] is given as attributeTranslationKeyPrefixes option. Then, in the example above, the first existing translation key is used as label:

some.attributes.title.label
fallback.attributes.title.label
activerecord.attributes.post.title

Accordingly, for the inline help:

some.attributes.title.inline_help_html
some.attributes.title.inline_help
fallback.attributes.title.inline_help_html
fallback.attributes.title.inline_help
pageflow.ui.inline_help.post.title_html
pageflow.ui.inline_help.post.title

This setup allows to keep all translation keys for an attribute to share a common prefix:

some:
  attributes:
    title:
      label: "Label"
      inline_help: "..."
      inline_help_disabled: "..."

Inline Help for Disabled Inputs

For each inline help translation key, a separate key with an "_disabled" suffix can be supplied, which provides a help string that shall be displayed when the input is disabled. More specific attribute translation key prefixes take precedence over suffixed keys:

some.attributes.title.inline_help_html
some.attributes.title.inline_help
some.attributes.title.inline_help_disabled_html
some.attributes.title.inline_help_disabled
fallback.attributes.title.inline_help_html
fallback.attributes.title.inline_help
fallback.attributes.title.inline_help_disabled_html
fallback.attributes.title.inline_help_disabled
pageflow.ui.inline_help.post.title_html
pageflow.ui.inline_help.post.title
pageflow.ui.inline_help.post.title_disabled_html
pageflow.ui.inline_help.post.title_disabled

Text based input view that can display a placeholder.

Input view for attributes storing configuration hashes with boolean values. See inputView for further options.

Input view for boolean values. See inputView for further options

Input view for selecting one value from a small set of options using radio buttons. See inputView for further options.

Input view for a color value in hex representation.

See inputWithPlaceholderText for placeholder related further options. See inputView for further options.

Render an input that is only a label. Can be used to render additional inline help.

See inputView for further options

Input view for a number.

See inputView for further options.

Input view that verifies that a certain URL is reachable via a proxy. To conform with same origin restrictions, this input view lets the user enter some url and saves a rewritten url where the domain is replaced with some path segment.

That way, when /example is setup to proxy requests to http://example.com, the user can enter an url of the form http://example.com/some/path but the string /example/some/path is persisited to the database.

See inputView for further options

this.input('url, ProxyUrlInputView, {
  proxies: [
    {
      url: 'http://example.com',
      base_path: '/example'
    }
  ]
});

A drop down with support for grouped items. See inputView for further options

Render a separator in a ConfigurationEditorView tab.

this.view(SeparatorView);

A slider for numeric inputs. See inputView for options

Input view for multi line text with simple formatting options. See inputWithPlaceholderText for placeholder related options. See inputView for further options.

Input view for a single line of text.

See inputWithPlaceholderText for placeholder related further options. See inputView for further options.

Display view for a link to a URL, to be used like an input view. See inputView for further options

Input view for URLs. See inputView for further options

A table cell providing a button which destroys the model that the current row refers to.

Attribute Translations

The following attribute translation is used:

• .cell_title - Used as title attribute.

A table cell mapping column attribute values to a list of translations.

Attribute Translations

The following attribute translations are used:

• .cell_text.<attribute_value> - Used as cell content.
• .cell_text.blank - Used as cell content if attribute is blank.
• .cell_title.<attribute_value> - Used as title attribute.
• .cell_title.blank - Used as title attribute if attribute is blank.

A table cell mapping column attribute values to icons.

Attribute Translations

The following attribute translations are used:

• .cell_title.<attribute_value> - Used as title attribute.
• .cell_title.blank - Used as title attribute if attribute is blank.

A table cell representing whether the column attribute is present on the row model.

Attribute Translations

The following attribute translations are used:

• .cell_title.present - Used as title attribute if the attribute is present. The current attribute value is provided as interpolation %{value}.
• .cell_title.blank - Used as title attribute if the attribute is blank.

Base class for table cell views.

Inside sub classes the name of the column options are available as this.options.column. Override the update method to populate the element.

this.attribute.attributeTranslation("cell_title");
// Looks for keys of the form:
// <table_view_translation_key_prefix>.<column_attribute>.cell_title

A table cell using the row model's value of the column attribute as text. If attribute value is empty, use most specific default available.

Render a inputs on multiple tabs.

Base class for views used as valueView for file type meta data attributes.

Switch between different views using tabs.

Helpers for setting up attribute bindings.

Helpers functions for working with CSS modules.

// MyView.module.css

    .addButton {}

    // MyView.js

    import Marionette from 'marionette';
    import {cssModulesUtils} from 'pageflow/ui';

    import styles from './MyView.module.css';

    export const MyView = Marionette.ItemView({
      template: () => `
        <button class=${styles.addButton}></button>
      `,

      events: cssModulesUtils.events(styles, {
        'click addButton': () => console.log('clicked add button');
      })
    });

// MyView.module.css

    .container {}

    // MyView.js

    import Marionette from 'marionette';
    import {cssModulesUtils} from 'pageflow/ui';

    import styles from './MyView.module.css';

    export const MyView = Marionette.ItemView({
      template: () => `
        <div class=${styles.container}></div>
      `,

      ui: cssModulesUtils.ui(styles, 'container'),

      onRender() {
        this.ui.container // => JQuery wrapper for container element
      }
    });

Helpers functions for handling translations.

Build editor Backbone models for tests.

import {factories} from 'pageflow/testHelpers';
import {PagedEntry} from 'editor/models/PagedEntry';

const entry = factories.entry(PagedEntry, {slug: 'some-entry'}, {
  entryTypeSeed: {some: 'data'},
  fileTypes: factories.fileTypes(f => f.withImageFileType()),
  filesAttributes: {
    image_files: [{id: 100, perma_id: 1, basename: 'image'}]
  }
});

Setup global state for testing Backbone editor components.

For some editor components like (some views or models) it's easier to depend on the global mutable state (available via the $state module alias) instead of injecting dependencies. This helper can be used to test these components in isolation.

Enable feature flags for the surrounding describe block.

Each beforeEach calls features.enable(scope, names), which both flips features.isEnabled to true for the given names and runs any functions registered via features.register for them. Each afterEach restores the set of enabled features to whatever was enabled before the helper was invoked, so suites do not leak state into each other.

Multiple calls within the same describe block (or across nested describes) compose: each call adds its own features on top of whatever previous useFakeFeatures calls already enabled.

import {useFakeFeatures} from 'pageflow/testHelpers';
import {features} from 'pageflow/frontend';

describe('...', () => {
  useFakeFeatures('frontend', ['commenting']);

  it('...', () => {
    expect(features.isEnabled('commenting')).toBe(true);
  });
});

Define translations to use in tests.

Multiple calls within the same describe block (or across nested describes) compose: each call's translations are merged on top of whatever previous useFakeTranslations calls already provided.

import {useFakeTranslations} from 'pageflow/testHelpers';
import I18n from 'i18n-js';

describe('...', () => {
  useFakeTranslations({
    'some.key': 'some translation'
  });

  it('...', () => {
    I18n.t('some.key') // => 'some translation'
  });
});

import {useFakeTranslations} from 'pageflow/testHelpers';
import I18n from 'i18n-js';

describe('...', () => {
  useFakeTranslations({
    'en.some.key': 'some text',
    'de.some.key': 'etwas Text'
  }, {multiLocale: true});

  it('...', () => {
    I18n.locale = 'de';
    I18n.t('some.key') // => 'etwas Text'
  });
});