www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/entity_embed/README.md

   1 # Entity Embed Module
   2
   3 [![Travis build status](https://img.shields.io/travis/drupal-media/entity_embed/8.x-1.x.svg)](https://travis-ci.org/drupal-media/entity_embed)
   4 [![Scrutinizer code quality](https://img.shields.io/scrutinizer/g/drupal-media/entity_embed/8.x-1.x.svg)](https://scrutinizer-ci.com/g/drupal-media/entity_embed)
   5
   6 [Entity Embed](https://www.drupal.org/project/entity_embed) module
   7 allows any entity to be embedded using a text editor.
   8
   9 ## Requirements
  10
  11 * Drupal 8
  12 * [Embed](https://www.drupal.org/project/embed) module
  13
  14 ## Installation
  15
  16 Entity Embed can be installed via the
  17 [standard Drupal installation process](http://drupal.org/node/895232).
  18
  19 ## Configuration
  20
  21 * Install and enable [Embed](https://www.drupal.org/project/embed) module.
  22 * Install and enable [Entity Embed](https://www.drupal.org/project/entity_embed)
  23   module.
  24 * Go to the 'Text formats and editors' configuration page: `/admin/config/content/formats`,
  25   and for each text format/editor combo where you want to embed entities,
  26   do the following:
  27   * Enable the "Display embedded entities" filter for the desired text formats
  28     on the Text Formats configuration page.
  29   * Drag and drop the 'E' button into the Active toolbar.
  30   * If the text format uses the 'Limit allowed HTML tags and correct
  31     faulty HTML' filter, ensure the necessary tags and attributes were
  32     automatically whitelisted:
  33     ```<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>```
  34     appears in the 'Allowed HTML tags' setting.
  35     *Warning: If you were using the module in very early pre-alpha
  36     stages you might need to add `data-entity-id` to the list of allowed
  37     attributes. Similarly, if you have been using the module in pre-beta stages,
  38     you need to white-list the `data-entity-embed-settings` attribute.*
  39   * If you're using both the 'Align images' and 'Caption images' filters make
  40     sure the 'Align images' filter is run before the 'Caption images' filter in
  41     the **Filter processing order** section. (Explanation: Due to the
  42     implementation details of the two filters it is important to execute them in
  43     the right sequence in order to obtain a sensible final markup. In practice
  44     this means that the alignment filter has to be run before the caption
  45     filter, otherwise the alignment class will appear inside the <figure> tag
  46     (instead of appearing on it) the caption filter produces.)
  47
  48 ## Usage
  49
  50 * For example, create a new *Article* content.
  51 * Click on the 'E' button in the text editor.
  52 * Enter part of the title of the entity you're looking for and select
  53   one of the search results.
  54 * If the entity you select is a node entity, for **Display as** you can choose
  55   one of the following options:
  56   * Entity ID
  57   * Label
  58   * Full content
  59   * RSS
  60   * Search index
  61   * Search result highlighting input
  62   * Teaser
  63 * The last five options depend on the view modes you have on the entity.
  64 * Optionally, choose to align left, center or right.
  65 **Rendered Entity** was available before but now the view modes are
  66  available as entity embed display plugins.
  67
  68 ## Embedding entities without WYSIWYG
  69
  70 Users should be embedding entities using the CKEditor WYSIWYG button as
  71 described above. This section is more technical about the HTML markup
  72 that is used to embed the actual entity.
  73
  74 ### Example:
  75 ```html
  76 <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"}' />
  77 ```
  78
  79 ## Entity Embed Display Plugins
  80
  81 Embedding entities uses an Entity Embed Display plugin, provided in the
  82 `data-entity-embed-display` attribute. By default we provide four
  83 different Entity Embed Display plugins out of the box:
  84
  85 - entity_reference:_formatter_id_: Renders the entity using a specific
  86   Entity Reference field formatter.
  87 - entity_reference:_entity_reference_label_: Renders the entity using
  88   the "Label" formatter.
  89 - file:_formatter_id_: Renders the entity using a specific File field
  90   formatter. This will only work if the entity is a file entity type.
  91 - image:_formatter_id_: Renders the entity using a specific Image field
  92   formatter. This will only work if the entity is a file entity type,
  93   and the file is an image.
  94
  95 Configuration for the Entity Embed Display plugin can be provided by
  96 using a `data-entity-embed-display-settings` attribute, which contains a
  97 JSON-encoded array value. Note that care must be used to use single
  98 quotes around the attribute value since JSON-encoded arrays typically
  99 contain double quotes.
 100
 101 The above examples render the entity using the
 102 _entity_reference_entity_view_ formatter from the Entity Reference
 103 module, using the _teaser_ view mode.