Introduction to Scald contexts

Scald context (literally Scald display context) is the same as entity view mode. In fact, each Scald "normal" context (that will be defined later) generates a view mode for the Scald atom entity. Because view mode is the heart of entity rendering pipe, you should understand what Scald contexts are and what they do.

Each context is defined by a module (the "context provider") and that module takes the whole responsibility to render atoms in that context. By default, there are the "full" context, a few system contexts defined by Scald core (e.g. "title", "error", etc.), and three contexts defined by the Scald Dnd Library module ("Editor representation", "Preview representation" and "Library item"). Those contexts, excluding "full", are not entity view modes because the context providers decide not to render any fields with those contexts.

However, it is easy to create a new context as a view mode without coding. The Scald core has a UI (at admin/structure/scald) to create new contexts like the "full" one (which we called a "normal" context). Those contexts generate view modes whose display can be configured via Field UI's "Field display settings".

If you use Scald principally for images, then the natural question is "Where are my image styles?". In fact, a context or view mode is entity-type-wide. One context can be used for images, videos, audio and even multimedia galleries. Image styles do not automatically create contexts (even though there is a module that creates one context for every image style for convenience). You need to create a context for every format of the atom, then configure how each atom type (image, video...) is rendered in that context. For example you create a "thumbnail" context where you configure that image atom to use the "thumbnail" style as the transcoder. (Ignore this term for now, just know that it can be configured in the context settings page.) Instead of image style, you can use Picture's image group as the transcoder for responsive images.

So in every context, for every atom type, there are settings for the transcoder. There are also settings for the player. (It could be similar to theme, but the player is not exposed outside of Scald.) For images, again, you can choose either the normal player (IMG tag) or the HTML5 player (using FIGURE and FIGCAPTION tags). All those settings are for the atom "core".

Then come the fields. You can configure field display settings in each view mode ("normal" context). E.g. in the "full" view mode, you can configure the image atom to use the HTML5 player, and below the atom to display creation date, authors, tags, etc.

How about customizing the display of an atom? There are several choices:

  • Define your own context (without using Scald core UI). It's the most performant because in your context provider you bypass all Drupal core field display steps. However you have to code for many atom types, which might be not ideal.
  • Define your own player and use that player in the context for the specific atom type that you want to customize.
  • Use high level Drupal entity hooks, like hook_entity_view, hook_entity_view_alter, hook_scald_atom_view, hook_scald_atom_view_alter. This is where the atom "core" is already rendered by the player, so it could be the best place to e.g. add a link to the atom or wrap it with some markup.

Configuration

Display context is the heart of Scald; it is similar to entity view mode. In fact, each display context is a view mode, but there are two different settings pages:

  • View modes: use Field UI's "manage display" to configure the field display.
  • Display contexts: use Scald contexts page to configure how the atom itself is rendered (which transcoder/player is used).

Default context

The default context used when an atom is dropped into a textarea is sdl_editor_representation. It can be overridden with the variable dnd_context_default.

Context settings

You can create contexts with Scald core UI, or define new contexts in code in your module. The module that declares a context (a "context provider") is responsible for displaying it.

In the "Scald contexts" settings section you can:

  • Choose a transcoder: for image atoms it can be image styles or Picture groups.
  • Choose a player

Modifying context in CKEditor

Scald plays very nice with the CKEditor RTE, using the CKEditor module. By using this RTE, you will be able to modify context for your atoms just inside the Wysiwyg.

Video screencast : http://www.youtube.com/watch?v=ahVxLz17PUk

In order to achieve this, follow these steps :

  • For setting up the recommended CKEditor integration with widget support check the guide under CKEditor 4.3 Widget support
  • Create a dnd enabled text field on a content type.
  • Create a node with this dnd enabled field, drag and drop an atom into it, right click on it and chose "Edit Atom Properties"
  • Choose another available context for your atom, rather than the default one (editor representation)

Furthermore, you can play with context configuration at this url, even adding new contexts : /admin/structure/scald

Creating a context in code

Creating a context in code can be useful when more complex behavior is required by the display. You can find details about the implementation at General aspects of Scald core.

Altering the context list visible for the editor

The list of contexts appearing in the Wysiwyg editor's "Edit Atom Properties" dialog and on an Atom Reference which has context override enabled can be altered with a hook.

Example:

/**
 * Implements hook_scald_wysiwyg_context_list_alter().
 */
function [your_module]_scald_wysiwyg_context_list_alter(&$contexts) {
  foreach ($contexts as $context => $type) {
    // Make many of the scald-provided contexts unavailable to the user in ckeditor atom properties dialog.
    unset($contexts[$context]['media_library']);
    unset($contexts[$context]['file_representation']);
    unset($contexts[$context]['full']);
    unset($contexts[$context]['sdl_editor_representation']);
    // Make this (custom) context unavailable for all but the image, file and audio types.
    if($context != 'image' && $context != 'file' && $context != 'audio') {
      unset($contexts[$context]['side_image']);
    }
    // This (custom) context is only available for images.
    if($context != 'image') {
      unset($contexts[$context]['side_promo']);
    }
    // Rename this context's visible label in the dropdown.
    $contexts[$context]['full_width'] = t('Full Width (Default)');
  }
}
AttachmentSize
201311061707.png742 bytes

Comments

ivyclark’s picture

Edit:

Fyi, I've found the place to delete it, under Structure >Scald.

This displays the Atom types, provides link to Add Context, and a list of all contexts (including custom ones, with links to edit or delete them).

---------------------

Hi,
we've been creating and using contexts to accommodate the custom image styles in our project.
How do we delete the contexts that are no longer needed? I must be looking in the wrong place as I can't seem to find it.
And, is it possible to hide some contexts from the "Edit atom properties" context list based on roles?
Thanks :)

scotwith1t’s picture

Here's a sample implementation:

/**
 * Implements hook_scald_wysiwyg_context_list_alter().
 */
function [your_module]_scald_wysiwyg_context_list_alter(&$contexts) {
  foreach ($contexts as $context => $type) {
    // Make many of the scald-provided contexts unavailable to the user in ckeditor atom properties dialog.
    unset($contexts[$context]['media_library']);
    unset($contexts[$context]['file_representation']);
    unset($contexts[$context]['full']);
    unset($contexts[$context]['sdl_editor_representation']);
    // Make this (custom) context unavailable for all but the image, file and audio types.
    if($context != 'image' && $context != 'file' && $context != 'audio') {
      unset($contexts[$context]['side_image']);
    }
    // This (custom) context is only available for images.
    if($context != 'image') {
      unset($contexts[$context]['side_promo']);
    }
    // Rename this context's visible label in the dropdown.
    $contexts[$context]['full_width'] = t('Full Width (Default)');
  }
}
arne.olafson’s picture

from https://www.drupal.org/node/1990492#comment-10956569
For anyone struggling with this, the default context can be changed on a per-field basis:
Structure -> Content Types -> [type] -> Manage fields -> [field] -> Edit
There is a checkbox for Drag'n'Drop Enabled and Select boxes for Default and Fallback Scald contexts