Allows any entity to be embedded using a WYSIWYG and text format.
PHP JavaScript Other
Latest commit a9f6ea8 Nov 3, 2016 @marcoscano marcoscano committed with slashrsm Issue #2819871 by marcoscano: Make it clear that Embed isn't compatib…
…le with Entity Browsers that use the 'Modal' display plugin
Permalink
Failed to load latest commit information.
config Issue #2736741 by Denchev: Treat each view mode in "Rendered entity" … Jul 7, 2016
css Increase the default width of entity browser Dec 4, 2015
js Issue #2760801 by Denchev, slashrsm: Rename data-entity-embed-setting… Aug 2, 2016
src Issue #2819871 by marcoscano: Make it clear that Embed isn't compatib… Nov 3, 2016
templates Issue #2712111 by paranojik, slashrsm, Dave Reid, Wim Leers: Fix Embe… Jun 9, 2016
tests CodeSnifer auto fixes. Sep 8, 2016
.gitignore Added .gitignore Jul 8, 2015
.travis-before-script.sh Renamed to .travis-before-script.sh. Aug 20, 2015
.travis.yml Allow PHP 7 failures for now. Aug 29, 2015
DEVELOPING.md Adding DEVELOPING.md. Apr 21, 2014
README.md Issue #2752221 by slashrsm, chishah92: Update module page information Sep 8, 2016
composer.json Remove composer dependencies for now. Aug 11, 2015
entity_embed.api.php Issue #2628234 by Wim Leers: Document why Entity Embed Display Plugin… Dec 8, 2015
entity_embed.info.yml Issue #2801403 by trobey: Include project namespace for module depend… Sep 19, 2016
entity_embed.install Issue #2760801 by Denchev, slashrsm: Rename data-entity-embed-setting… Aug 2, 2016
entity_embed.libraries.yml Increase the default width of entity browser Dec 4, 2015
entity_embed.module CodeSnifer auto fixes. Sep 8, 2016
entity_embed.routing.yml Issue #2678324 by akalam: Fixed dialog route did not use the ajax_bas… Apr 13, 2016
entity_embed.services.yml Issue #2760407 by Denchev, slashrsm, samuel.mortenson: Clean up Entit… Jul 12, 2016

README.md

Entity Embed Module

Travis build status Scrutinizer code quality

Entity Embed module allows any entity to be embedded using a text editor.

Requirements

Installation

Entity Embed can be installed via the standard Drupal installation process.

Configuration

  • Install and enable Embed module.
  • Install and enable Entity Embed module.
  • Go to the 'Text formats and editors' configuration page: /admin/config/content/formats, and for each text format/editor combo where you want to embed entities, do the following:
    • Enable the "Display embedded entities" filter for the desired text formats on the Text Formats configuration page.
    • Drag and drop the 'E' button into the Active toolbar.
    • If the text format uses the 'Limit allowed HTML tags and correct faulty HTML' filter, ensure the necessary tags and attributes were automatically whitelisted: <drupal-entity data-entity-type data-entity-uuid data-view-mode data-entity-embed-display data-entity-embed-display-settings data-align data-caption data-embed-button> appears in the 'Allowed HTML tags' setting. Warning: If you were using the module in very early pre-alpha stages you might need to add data-entity-id to the list of allowed attributes. Similarly, if you have been using the module in pre-beta stages, you need to white-list the data-entity-embed-settings attribute.
    • If you're using both the 'Align images' and 'Caption images' filters make sure the 'Align images' filter is run before the 'Caption images' filter in the Filter processing order section. (Explanation: Due to the implementation details of the two filters it is important to execute them in the right sequence in order to obtain a sensible final markup. In practice this means that the alignment filter has to be run before the caption filter, otherwise the alignment class will appear inside the tag (instead of appearing on it) the caption filter produces.)

Usage

  • For example, create a new Article content.
  • Click on the 'E' button in the text editor.
  • Enter part of the title of the entity you're looking for and select one of the search results.
  • If the entity you select is a node entity, for Display as you can choose one of the following options:
    • Entity ID
    • Label
    • Full content
    • RSS
    • Search index
    • Search result highlighting input
    • Teaser
  • The last five options depend on the view modes you have on the entity.
  • Optionally, choose to align left, center or right. Rendered Entity was available before but now the view modes are available as entity embed display plugins.

Embedding entities without WYSIWYG

Users should be embedding entities using the CKEditor WYSIWYG button as described above. This section is more technical about the HTML markup that is used to embed the actual entity.

Example:

<drupal-entity data-entity-type="node" data-entity-uuid="07bf3a2e-1941-4a44-9b02-2d1d7a41ec0e" data-entity-embed-display="entity_reference:entity_reference_entity_view" data-entity-embed-display-settings='{"view_mode":"teaser"}' />

Entity Embed Display Plugins

Embedding entities uses an Entity Embed Display plugin, provided in the data-entity-embed-display attribute. By default we provide four different Entity Embed Display plugins out of the box:

  • entity_reference:formatter_id: Renders the entity using a specific Entity Reference field formatter.
  • entity_reference:entity_reference_label: Renders the entity using the "Label" formatter.
  • file:formatter_id: Renders the entity using a specific File field formatter. This will only work if the entity is a file entity type.
  • image:formatter_id: Renders the entity using a specific Image field formatter. This will only work if the entity is a file entity type, and the file is an image.

Configuration for the Entity Embed Display plugin can be provided by using a data-entity-embed-display-settings attribute, which contains a JSON-encoded array value. Note that care must be used to use single quotes around the attribute value since JSON-encoded arrays typically contain double quotes.

The above examples render the entity using the entity_reference_entity_view formatter from the Entity Reference module, using the teaser view mode.