├── .gitignore ├── README.md ├── SUMMARY.md ├── book.json ├── browsing.md ├── contributing.md ├── core ├── file-systems.md ├── file_and_image.md ├── limitations.md └── wysiwyg.md ├── embedding.md ├── modules ├── crop │ ├── Implementation_examples.md │ ├── architecture.md │ ├── images │ │ └── architecture.png │ └── intro.md ├── dropzonejs │ └── intro.md ├── embed │ └── intro.md ├── entity_browser │ ├── architecture.md │ ├── configuration.md │ ├── creating_browser_through_ui.md │ ├── display-iframe.png │ ├── display-modal.png │ ├── displays.md │ ├── images │ │ ├── architecture.png │ │ ├── seldisplay_grid.png │ │ ├── seldisplay_list.png │ │ ├── seldisplay_table.png │ │ ├── tab_button.png │ │ ├── tab_dropdown.png │ │ └── tab_tabs.png │ ├── inline_entity_form.md │ ├── intro.md │ ├── op2-widget-configuration.png │ ├── select-entity-form-on-widget-creation.png │ ├── select-entity-type-and-bundle.png │ ├── selection-display-multi-step-1.png │ ├── selection-display-multi-step-2.png │ ├── selection-display-multi-step-3.png │ ├── selection-display-multi-step-4.png │ ├── selection-display-multi-step-5.png │ ├── selection-display-multi-step-6a.png │ ├── selection-display-multi-step-6b.png │ ├── selection-display-multi-step-7.png │ ├── selection_displays.md │ ├── widget-selection-dropdown.png │ ├── widget-selection-tabs.png │ ├── widget-upload.png │ ├── widget-view.png │ ├── widget_selectors.md │ ├── widgets.md │ ├── wizard_step_1.png │ ├── wizard_step_5a.png │ ├── wizard_step_5b.png │ └── wizard_step_5c.png ├── entity_embed │ └── intro.md ├── fallback_formatter │ └── intro.md ├── field_formatter │ ├── images │ │ ├── step_1.png │ │ ├── step_10.png │ │ ├── step_11.png │ │ ├── step_12.png │ │ ├── step_13.png │ │ ├── step_2.png │ │ ├── step_3.png │ │ ├── step_4.png │ │ ├── step_5.png │ │ ├── step_6.png │ │ ├── step_7.png │ │ ├── step_8.png │ │ └── step_9.png │ └── intro.md ├── file_browser │ ├── images │ │ ├── step_1.png │ │ ├── step_2.png │ │ └── step_3.png │ └── intro.md ├── file_checker │ └── intro.md ├── file_entity │ └── intro.md ├── flysystem │ ├── flysystem_filefield.png │ └── intro.md ├── image_effects │ └── intro.md ├── image_widget_crop │ ├── images │ │ ├── step_1.png │ │ ├── step_10.png │ │ ├── step_11.png │ │ ├── step_12.png │ │ ├── step_13.png │ │ ├── step_14.png │ │ ├── step_15.png │ │ ├── step_16.png │ │ ├── step_17.png │ │ ├── step_2.png │ │ ├── step_3.png │ │ ├── step_4.png │ │ ├── step_5.png │ │ ├── step_6.png │ │ ├── step_7.png │ │ ├── step_8.png │ │ └── step_9.png │ └── intro.md ├── intro.md ├── media │ ├── add_dailymotion_video.jpg │ ├── add_document.jpg │ ├── add_document_widget.png │ ├── add_gallery.jpg │ ├── add_image.jpg │ ├── add_image_extension.jpg │ ├── add_image_type.jpg │ ├── add_instagram.jpg │ ├── add_media_items.jpg │ ├── add_tweet.jpg │ ├── add_video.png │ ├── adding-media-items.md │ ├── configuration.md │ ├── display_embed.png │ ├── embed_button.png │ ├── embed_button_settings.png │ ├── embed_media.png │ ├── embedding-media.md │ ├── entity_browsers.png │ ├── gallery_select_modal.jpg │ ├── installation.md │ ├── intro.md │ ├── media-entity-browsers.md │ ├── media_library.jpg │ ├── modify_image_display.png │ └── user_media_library.jpg ├── media_entity │ ├── audio.md │ ├── auto_name.md │ ├── basic_usage.md │ ├── create_bundle.md │ ├── create_view_mode.md │ ├── developers_documentation.md │ ├── embeddable_video.md │ ├── image.md │ ├── images │ │ ├── auto_name │ │ │ └── auto_name_01.png │ │ ├── create_bundle │ │ │ ├── step_1.png │ │ │ ├── step_2.png │ │ │ └── step_3.png │ │ ├── create_viewmode │ │ │ ├── viewmode_01.png │ │ │ └── viewmode_02.png │ │ ├── instagram │ │ │ ├── step_1.png │ │ │ ├── step_10.png │ │ │ ├── step_11.png │ │ │ ├── step_12.png │ │ │ ├── step_13.png │ │ │ ├── step_14.png │ │ │ ├── step_2.png │ │ │ ├── step_3.png │ │ │ ├── step_4.png │ │ │ ├── step_5.png │ │ │ ├── step_6.png │ │ │ ├── step_7.png │ │ │ ├── step_8.png │ │ │ └── step_9.png │ │ ├── media_gallery.png │ │ └── twitter │ │ │ ├── step_1.png │ │ │ ├── step_10.png │ │ │ ├── step_11.png │ │ │ ├── step_12.png │ │ │ ├── step_13.png │ │ │ ├── step_14.png │ │ │ ├── step_15.png │ │ │ ├── step_16.png │ │ │ ├── step_17.png │ │ │ ├── step_2.png │ │ │ ├── step_3.png │ │ │ ├── step_4.png │ │ │ ├── step_5.png │ │ │ ├── step_6.png │ │ │ ├── step_7.png │ │ │ ├── step_8.png │ │ │ └── step_9.png │ ├── instagram.md │ ├── intro.md │ ├── metadata_handling.md │ ├── slideshow.md │ ├── twitter.md │ └── type_providers.md ├── media_pinkeye │ └── intro.md └── url_embed │ └── intro.md ├── roadmap.md └── status.md /.gitignore: -------------------------------------------------------------------------------- 1 | /_book 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Drupal 8 Media Guide 2 | 3 | ##Introduction 4 | 5 | This guide provides and overview of the approach to Media in Drupal 8. 6 | 7 | The Drupal Media Team has set an ambitious [goal](roadmap.md) of ensuring Drupal offers best media solution available in any web framework. 8 | 9 | We still have a ways to go to achieve that goal, but this guide will help you to understand our [Roadmap](roadmap.md) and [Module Status](modules/intro.md). 10 | 11 | As discussed in the [Roadmap](roadmap.md) and throughout this Guide, the Media Team has worked collaboratively to separate Media functionality into several independent modules that can be used together based as appropriate. Over time we'll be adding examples of how these modules can be integrated. 12 | 13 | We also hope that this guide will help you understand best practices and get started using media in your Drupal 8 project today. 14 | 15 | ## Getting Involved 16 | 17 | The Drupal Media team is actively seeking contributions and new team members. There are many ways to get involved, including helping with funding, project management communications, documentation, testing and development. Submit edits to this guide at the [GitHub repository](https://github.com/drupal-media/d8-guide). Please check out our [Contributing](contributing.md) page for full details. 18 | 19 | ##Using this Guide 20 | 21 | As mentioned above, Media for Drupal 8 is undergoing a re-architecture into individual components. For example, the Media Browser functionality is being developed into the **Entity Browser** module and embedding media in WYSIWYG is being developed into the **Entity Embed** module. 22 | 23 | While not all of these components are complete you can still do a lot with what's done. This Guide includes a [Module Status](status.md) section which provide an overview of the ecosystem, and then more detailed guides for each of the available modules: 24 | 25 | * [Crop API](modules/crop/intro.md) 26 | * [DropzoneJS](modules/dropzonejs/intro.md) 27 | * [Embed API](modules/embed/intro.md) 28 | * [Entity Embed](modules/entity_embed/intro.md) 29 | * [Entity Browser](modules/entity_browser/intro.md) 30 | * [Fallback Formatter](modules/fallback_formatter/intro.md) 31 | * [Field Formatter](modules/field_formatter/intro.md) 32 | * [File Checker](modules/file_checker/intro.md) 33 | * [File Entity](modules/file_entity/intro.md) 34 | * [Flysystem](modules/flysystem/intro.md) 35 | * [Image Effects](modules/image_effects/intro.md) 36 | * [Image Widget Crop](modules/image_widget_crop/intro.md) 37 | * [Media Entity](modules/media_entity/intro.md) 38 | * [Media](modules/media/intro.md) 39 | * [URL Embed](modules/url_embed/intro.md) 40 | 41 | 42 | ### Troubleshooting 43 | 44 | If you have trouble understanding any part of the documentation, please notify those of us who work on this section by [creating an issue](https://github.com/drupal-media/d8-guide/issues) and clearly explain what you don't understand and why - we're happy to hear from you, your contribution helps everyone at Drupal! 45 | 46 | ### Thank You Aaron 47 | 48 | [Aaron Winborn](http://aaronwinborn.com/) ([aaron](https://www.drupal.org/u/aaron)) exemplified the best aspect of the Drupal community and open source contribution. Without his kindness, generosity, humility, and dedication, the Media modules and many many others would not have been possible. This module and all Drupal Media team efforts are in dedication to Aaron and all he has done for our community. 49 | 50 | Read more about Aaron at his [community spotlight](https://www.drupal.org/node/2444367) and the new [Aaron Winborn Award](https://www.drupal.org/aaron-winborn-award). 51 | 52 | You will be missed, *friend*. 53 | 54 | ## License 55 | 56 | Creative Commons License 57 | 58 | This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. 59 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | * [Media Documentation](README.md) 4 | * [Roadmap](roadmap.md) 5 | * [Status](status.md) 6 | * [Contributing](contributing.md) 7 | * [Drupal 8 Core](core/file-systems.md) 8 | * [File and Image Fields](core/file_and_image.md) 9 | * [WYSIWYG](core/wysiwyg.md) 10 | * [Limitations](core/limitations.md) 11 | * [Browsing](browsing.md) 12 | * [Embedding](embedding.md) 13 | * [Modules](modules/intro.md) 14 | * [Entity Browser](modules/entity_browser/intro.md) 15 | * [Architecture](modules/entity_browser/architecture.md) 16 | * [Displays](modules/entity_browser/displays.md) 17 | * [Widgets](modules/entity_browser/widgets.md) 18 | * [Widget Selectors](modules/entity_browser/widget_selectors.md) 19 | * [Selection displays](modules/entity_browser/selection_displays.md) 20 | * [Creating a browser trough the UI](modules/entity_browser/creating_browser_through_ui.md) 21 | * [Configuration file structure](modules/entity_browser/configuration.md) 22 | * [Inline entity form integration](modules/entity_browser/inline_entity_form.md) 23 | * [DropzoneJS](modules/dropzonejs/intro.md) 24 | * [Embed API](modules/embed/intro.md) 25 | * [Entity Embed](modules/entity_embed/README.md) 26 | * [Button configuration](entity_embed/button.md) 27 | * [WYSIWYG configuration](entity_embed/formats.md) 28 | * [Embedding an entity using WYSIWYG](entity_embed/wysiwyg.md) 29 | * [<drupal-entity> HTML tag specification](entity_embed/tag_specification.md) 30 | * [Extending](entity_embed/INTEGRATION.md) 31 | * [Events and hooks](entity_embed/events_hooks.md) 32 | * [Custom data attributes](entity_embed/data_attributes.md) 33 | * [Display plugins](entity_embed/display_plugins.md) 34 | * [URL Embed](modules/url_embed/intro.md) 35 | * [File Entity](modules/file_entity/intro.md) 36 | * [File Entity Browser](modules/file_browser/README.md) 37 | * [Media Entity](modules/media_entity/intro.md) 38 | * [Creating a media bundle](modules/media_entity/create_bundle.md) 39 | * [Creating a view mode](modules/media_entity/create_view_mode.md) 40 | * [Basic Usage](modules/media_entity/basic_usage.md) 41 | * [Automatic name for media entities](modules/media_entity/auto_name.md) 42 | * [Type Providers](modules/media_entity/type_providers.md) 43 | * [Image](modules/media_entity/image.md) 44 | * [Audio](modules/media_entity/audio.md) 45 | * [Slideshow](modules/media_entity/slideshow.md) 46 | * [Embedable video](modules/media_entity/embeddable_video.md) 47 | * [Twitter](modules/media_entity/twitter.md) 48 | * [Instagram](modules/media_entity/instagram.md) 49 | * [Metadata handling](modules/media_entity/metadata_handling.png) 50 | * [Developers documentation](modules/media_entity/developers_documentation.md) 51 | * [Crop API](modules/crop/intro.md) 52 | * [Architecture](modules/crop/architecture.md) 53 | * [Implementation examples](modules/crop/Implementation_examples.md) 54 | * [ImageWidgetCrop](modules/image_widget_crop/intro.md) 55 | * [Fallback Formatter]((modules/fallback_formatter/intro.md) 56 | * [Field formatter](modules/field_formatter/intro.md) 57 | * [File checker](modules/file_checker/intro.md) 58 | * [Flysystem](modules/flysystem/intro.md) 59 | * [Image Effects](modules/image_effects/intro.md) 60 | * [Media](modules/media/intro.md) 61 | * [Installation](modules/media/installation.md) 62 | * [Adding media items](modules/media/adding-media-items.md) 63 | * [Configuration](modules/media/configuration.md) 64 | * [Embedding media](modules/media/embedding-media.md) 65 | * [Media entity browsers](modules/media/media-entity-browsers.md) 66 | -------------------------------------------------------------------------------- /book.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "Drupal 8 Media Guide", 3 | "description": "Definitive guide on how to integrate and develop with Drupal Media.", 4 | "repository": { 5 | "type": "git", 6 | "url": "https://github.com/drupal-media/d8-guide" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /browsing.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /contributing.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | The Drupal Media Team has been growing over the last few years and gradually gaining momentum. We are always looking for new team members to help moving things forward and there are many ways to get involved, including helping with funding, project management communications, documentation, testing and development. 4 | 5 | ##Funding 6 | 7 | *FPO/TBA - This content needs to be written, see our [Contributing](contributing.md) section get involved.* 8 | 9 | 10 | ##Documentation 11 | 12 | You can also contribute directly on our [guide repository](https://github.com/drupal-media/d8-guide/issues) by editing the files through the [GitHub](https://github.com/) interface directly in your browser. Alternatively, you can clone the repository and edit the guide in your favorite text editor or in the official [GitBook desktop app](https://www.gitbook.com/editor). 13 | 14 | All contributions are welcome and greatly appreciated. 15 | 16 | 17 | ##Organizing & Project Management 18 | 19 | *FPO/TBA - This content needs to be written, see our [Contributing](contributing.md) section get involved.* 20 | 21 | 22 | ##Module Development 23 | 24 | *FPO/TBA - This content needs to be written, see our [Contributing](contributing.md) section get involved.* 25 | 26 | 27 | ##Testing & Feedback 28 | 29 | 30 | *FPO/TBA - This content needs to be written, see our [Contributing](contributing.md) section get involved.* 31 | 32 | 33 | 34 | -------------------------------------------------------------------------------- /core/file-systems.md: -------------------------------------------------------------------------------- 1 | # File systems 2 | 3 | Drupal 8 ships with three file systems by default: public, private, and temporary. But it also includes the ability for any number of custom file systems to be used, including remote file systems. 4 | 5 | ## Why use a remote file system? 6 | 7 | Drupal modules like [media_entity](https://www.drupal.org/project/media_entity) and [file_entity](https://www.drupal.org/project/file_entity) catalog your media, and keep information about it inside Drupal. But in most cases, they aren't the actual media themselves. Commonly, the actual media are files stored on a server, not entities in Drupal's database. The [media_entity](https://www.drupal.org/project/media_entity) and [file_entity](https://www.drupal.org/project/file_entity) modules offer fieldable entities, to which a 'file' field is usually added which stores the location of the file and thereby enables Drupal to serve it up to your website's visitor. 8 | 9 | In the simplest scenario, the files live on your webserver, and Drupal's core 'file' field type can both upload them and serve them up. However, large collections of media files (especially audio or video) can take up a huge amount of storage space - 30 hours of video might need a Terabyte of storage. Storing a Terabyte on a webserver is very expensive (if you could even find a web host that offered it). This is because web hosting servers are optimized for fast response to page requests, while for simple file storage there are cheaper alternatives. Most people with large media collections therefore usually choose to store them off their webserver at a more cost-effective location, such as a cheaper server or a cloud storage service like [AmazonS3](https://aws.amazon.com/s3/). 10 | 11 | ## Remote file system options 12 | * [Amazon S3](https://aws.amazon.com/s3/) 13 | * [Flysystem](../modules/flysystem/README.md) 14 | -------------------------------------------------------------------------------- /core/file_and_image.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](../contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /core/limitations.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](../contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /core/wysiwyg.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](../contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /embedding.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /modules/crop/Implementation_examples.md: -------------------------------------------------------------------------------- 1 | # Implementation Example 2 | 3 | ## Create 4 | 5 | This code shows how to create a crop entity and set all positions. 6 | 7 | ```php 8 | $values = [ 9 | 'type' => my_crop_type, 10 | 'entity_id' => fid_of_file, 11 | 'entity_type' => 'file', 12 | 'uri' => uri_of_file, 13 | 'x' => 150, 14 | 'y' => 150, 15 | 'width' => 50, 16 | 'height' => 50, 17 | ]; 18 | 19 | // Save crop. 20 | /** @var \Drupal\crop\CropInterface $crop */ 21 | $crop = \Drupal::service->get('entity.manager')->getStorage('crop')->create($values); 22 | $crop->save(); 23 | ``` 24 | 25 | ## Update 26 | 27 | Since Crop is an entity it is possible to modify its properties using "->set()" & "->save()" methods. 28 | 29 | ```php 30 | /** @var \Drupal\crop\CropInterface $crop */ 31 | $crop = \Drupal::service->get('entity.manager') 32 | ->getStorage('crop') 33 | ->loadByProperties([ 34 | 'type' => CropTypeName, 35 | 'uri' => 'fileURI', 36 | ]); 37 | 38 | $crop->set($field_key, $value, TRUE)->save(); 39 | ``` 40 | 41 | ## Delete 42 | 43 | Crop can be deleted using standard Entity API function. 44 | 45 | ```php 46 | /** @var \Drupal\crop\CropInterface $crop */ 47 | $crop = \Drupal::service->get('entity.manager') 48 | ->getStorage('crop') 49 | ->loadByProperties([ 50 | 'type' => CropTypeName, 51 | 'uri' => 'fileURI', 52 | ]); 53 | 54 | $crop->delete(); 55 | ``` 56 | -------------------------------------------------------------------------------- /modules/crop/architecture.md: -------------------------------------------------------------------------------- 1 | # Architecture 2 | 3 | Diagram shows basic architecture of Crop. 4 | 5 | ![Crop architecture](images/architecture.png) 6 | 7 | ## Components 8 | 9 | ### Entity 10 | 11 | - **Crop** is entity that stores various information related to the crop area. 12 | - **CropType** is Crop entity bundle. 13 | 14 | ###Plugin 15 | 16 | - **CropEffect** applies crop to the image using information from the crop entity. 17 | 18 | The "Manual Crop Effect" effect uses two parameters, *uri* and *crop_type* to get crop associated with the image. 19 | 20 | - **"uri"** is an important property because it is the only contextual information available when you apply the effect (manual crop) to the image. 21 | - **"crop_type"** makes linking between Crop entity and image possible, and it makes the difference between several crop types on the same image. 22 | 23 | *Limitation:* 24 | Due to limitations in Drupal core we're currently not able to handle the case where one image would have several crops of the same crop type. The oldest crop will be used in such case. 25 | 26 | See [Crop API supports multiple issues](https://www.drupal.org/node/2617818) for more information. 27 | 28 | ## Focus on properties of crop entity 29 | 30 | Crop entity base fields (explained): 31 | 32 | - **type** This is the machine name of the corresponding crop type used by this entity, it works exactly like as "Node" and "NodeType". 33 | - **entity_id** ID of the entity crop relates to. "fid" when entity is a file. 34 | - **entity_type** This is the type of crop on which the entity is linked. 35 | - **uri** URI of the image that is cropped. 36 | - **x** Position of top left corner of the crop area on x-axis. 37 | - **y** Position of top left corner of the crop area on y-axis. 38 | - **width** Width of the crop area. 39 | - **height** Height of the crop area. 40 | -------------------------------------------------------------------------------- /modules/crop/images/architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/crop/images/architecture.png -------------------------------------------------------------------------------- /modules/crop/intro.md: -------------------------------------------------------------------------------- 1 | # Crop API 2 | 3 | The [Crop API](https://www.drupal.org/project/crop) provides storage for all cropping solution. It is able to handle crops based on region and focal point concepts. 4 | 5 | Examples of possible use cases: 6 | - Storing a crop area (cropping approach) or a reference point (Focal point approach). 7 | - Ability to handle different areas via an entity (Crop) and bundle (Crop Type) for storing different information linked to crop entities. 8 | 9 | ## Configuration 10 | 11 | This is API module. In order to crop your images you need a UI module. First such (sandbox) module is [Image widget crop](https://www.drupal.org/sandbox/woprrr/2571403). 12 | 13 | ## Technical details 14 | 15 | Initial discussion can be found on [manual crop issue queue](https://www.drupal.org/node/2368945). 16 | 17 | ## Development 18 | 19 | We use Github pull request workflow. In order to contribute to the module please [create a pull request](https://github.com/drupal-media/crop/compare) and cross-link it with the [relevant drupal.org issue](https://www.drupal.org/project/issues/crop). 20 | 21 | ## Maintainers 22 | - [Janez Urevc (@slashrsm)](https://drupal.org/user/744628) 23 | -------------------------------------------------------------------------------- /modules/dropzonejs/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/embed/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/entity_browser/architecture.md: -------------------------------------------------------------------------------- 1 | # Architecture 2 | 3 | Diagram shows basic architecture of Entity browser. 4 | 5 | ![Entity browser architecture](images/architecture.png) 6 | 7 | ## Components 8 | 9 | - **Entity browser:** Config entity that stores entire configuration for a given EB instance, provides communication interface to other systems, implements any business logic and glues all pieces of the system together. 10 | - **Display:** Plugins that bring EB into different contexts in UI: entity_embed uses modal implementation; a field widget could use EB in an iFrame; a system that pushes content to 3rd party systems could use a standalone form to select entities that need to be pushed over; ... 11 | - **Widget:** Plugins that provide different ways of selecting content (views, custom form, entity form, uploader, field widgets, ...). 12 | - **Widget selector:** Plugins that define how different widgets are displayed and selected. Can be tabs, dropdown, buttons, ... 13 | - **Selection display:** Plugin that handles display and logic around currently selected entities (before they are actually sent over). Can be something as a grid of rendered entities that were selected - allows user to go into different widgets and select entities in multiple steps or something very simple that pushes entities over as soon as something is selected on one of the widgets. 14 | -------------------------------------------------------------------------------- /modules/entity_browser/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration file structure 2 | 3 | Entity browsers are configuration entities that can be created [either by the site builder on the UI](creating_browser_through_ui.md) or imported from YAML configuration files. 4 | 5 | If you are using a module that provides default or example configuration, these will be in the .yml files and will have the following structure (example ``` entity_browser.browser.field_files.yml``` from the example sub-module): 6 | 7 | 8 | ```yaml 9 | name: test_files 10 | label: 'Test entity browser for files' 11 | display: iframe 12 | display_configuration: 13 | width: 650 14 | height: 500 15 | link_text: 'Select entities' 16 | selection_display: no_display 17 | selection_display_configuration: { } 18 | widget_selector: tabs 19 | widget_selector_configuration: { } 20 | widgets: 21 | a4ad947c-9669-497c-9988-24351955a02f: 22 | settings: 23 | view: files_entity_browser 24 | view_display: entity_browser_1 25 | uuid: a4ad947c-9669-497c-9988-24351955a02f 26 | weight: 1 27 | label: 'Files listing' 28 | id: view 29 | 735d146c-a4b2-4327-a057-d109e0905e05: 30 | settings: 31 | upload_location: 'public://' 32 | uuid: 735d146c-a4b2-4327-a057-d109e0905e05 33 | weight: 0 34 | label: 'Upload files' 35 | id: upload 36 | 37 | ``` 38 | 39 | The above configuration defines an entity browser that: 40 | - is displayed in an iFrame 650px by 500px in size, 41 | - is displayed when the user clicks on "Select entities" link, 42 | - has no selection display, 43 | - displays widgets as tabs, 44 | - comes with two widgets: 45 | - a "file upload" widget that uploads files in the public:// directory, 46 | - a "view" browsing/selection widget that uses the display "entity_browser_1" of the view "files_entity_browser". 47 | 48 | 49 | - **name:** Unique machine name. 50 | - **label:** Human readable name. 51 | - **display:** ID of display plugin to be used. 52 | - **display_configuration:** Display specific configuration. Depends on the display plugin used. See schema definitions provided by individual plugins (grep for "entity_browser.browser.display.*" in configuration schema yaml files). 53 | - **selection_display:** ID of selection display plugin to be used. 54 | - **selection_display_configuration:** Selection display specific configuration. Depends on the selection display plugin used. See schema definitions provided by individual plugins (grep for "entity_browser.browser.selection_display.*" in configuration schema yaml files). 55 | - **widget_selector:** ID of widget selector plugin to be used. 56 | - **widget_selector_configuration:** Widget selector specific configuration. Depends on the widget selector plugin used. See schema definitions provided by individual plugins (grep for "entity_browser.browser.widget_selector.*" in configuration schema yaml files). 57 | - **widgets**: List of widgets to be used (keyed by UUID). Structure of individual entry: 58 | - **id:** ID of widget plugin. 59 | - **label:** Human readable name. 60 | - **weight:** Weight. Widgets are ordered ascending by wight. 61 | - **uuid:** Unique widget UUID. Must match the key. 62 | - **settings:** Widget specific configuration. Depends on the widget plugin used. See schema definitions provided by individual plugins (grep for "entity_browser.browser.widget.*" in configuration schema yaml files). 63 | -------------------------------------------------------------------------------- /modules/entity_browser/creating_browser_through_ui.md: -------------------------------------------------------------------------------- 1 | 2 | ### Creating a Browser with the multi-step Wizard 3 | 4 | 5 | The Entity Browser module allows the creation of highly configurable browsers through the UI. Also, an overview of the existing browsers is available at the URL: 6 | 7 | ``` /admin/config/content/entity_browser ``` 8 | 9 | Make sure you have the permission ```administer entity browsers``` in order to access this page and create / edit the browsers. 10 | 11 | In order to create a new Entity Browser, click on **Add Entity Browser** or visit directly the URL ```/admin/config/content/entity_browser/add``` to access the multi-step wizard that will guide you through the process of creating / editing a browser. 12 | 13 | Note that, although not required for Entity Browser to work, you need to install the [ctools module](https://www.drupal.org/project/ctools) if you want to be able to use the Wizard and create / edit the browsers using these wizard pages. 14 | 15 | ![](wizard_step_1.png) 16 | 17 | On this first step, you will need to indicate the main characteristics of the Entity Browser: 18 | * Give it a Label 19 | * Which [Display](displays.md) plugin to use 20 | * Which [Widget Selector](widget_selectors.md) plugin to use 21 | * Which [Selection Display](selection_displays.md) plugin to use 22 | 23 | Depending on the options selected here, the following steps will present different configuration options, specific for each plugin type. 24 | 25 | The information introduced in the following 3 steps: 26 | * Display 27 | * Widget selector 28 | * Selection display 29 | 30 | will be used to configure each of these specific plugins, and you can find more documentation about the options available on each case in the pages of this book dedicated to each plugin type: 31 | * [Displays](displays.md) 32 | * [Widget Selectors](widget_selectors.md) 33 | * [Selection Displays](selection_displays.md) 34 | 35 | The last step (**Widgets**) is where you define the widgets you want to include in your browser and their order of appearance (if more than one): 36 | 37 | ![](wizard_step_5a.png) 38 | 39 | You need to select a widget type on the dropdown **Add widget plugin**. Depending on the modules you have installed, different options may be available on this select list: 40 | 41 | ![](wizard_step_5b.png) 42 | 43 | After selecting a widget type, a new row is added to the list and you can configure the specific widget settings, if any. 44 | 45 | ![](wizard_step_5c.png) 46 | 47 | After adding and configuring the widgets you need, you can (optionally) re-order them by dragging the table rows. 48 | Click on **Finish** to conclude the wizard operation and save the Entity Browser. 49 | 50 | -------------------------------------------------------------------------------- /modules/entity_browser/display-iframe.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/display-iframe.png -------------------------------------------------------------------------------- /modules/entity_browser/display-modal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/display-modal.png -------------------------------------------------------------------------------- /modules/entity_browser/displays.md: -------------------------------------------------------------------------------- 1 | # Displays 2 | 3 | **Display** plugins are responsible for presenting the entity browser to the end user (editor), in different contexts. Contrib or custom modules can provide new display plugins or extend existing ones. 4 | 5 | The base [Entity Browser](https://drupal.org/project/entity_browser) module provides the following display plugins out of the box: 6 | 7 | ### iFrame 8 | 9 | An entity browser configured to use an **iFrame** type of display will have the browser widgets embedded into the current page, inside an iframe element. 10 | 11 | An example of what this configuration defines is shown in the following image: 12 | 13 | ![](display-iframe.png) 14 | 15 | The standard configuration options for this type are: 16 | - **Width** - The width of the iFrame element 17 | - **Height** - The height of the iFrame element 18 | - **Link text** - The label to use on the display submit button 19 | - **Auto-open** - Whether the display should open automatically or if the end user needs to click on a link to launch the display. 20 | 21 | ### Modal 22 | 23 | An entity browser configured to use a **Modal** type of display with load the browser widgets in a modal window, as you can see in the following picture: 24 | 25 | ![](display-modal.png) 26 | 27 | The standard configuration options for this type are: 28 | - **Width** - The width of the modal window 29 | - **Height** - The height of the modal window 30 | - **Link text** - The label to use on the display submit button 31 | 32 | ### Standalone 33 | 34 | The **Standalone** display type allows the definition of a specific URL to host the Entity Browser, being accessible independently of other content / entities. This option is quite unlikely to be used in the most common use-cases of media handling, but you might find it useful if you need to build a system that only selects / creates entities for another system (for example a 3rd party content processor) who is the actual responsible for dealing with them. 35 | 36 | The only configuration option for this type is: 37 | - **Path** - The URL where the standalone form should be accessible 38 | 39 | -------------------------------------------------------------------------------- /modules/entity_browser/images/architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/architecture.png -------------------------------------------------------------------------------- /modules/entity_browser/images/seldisplay_grid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/seldisplay_grid.png -------------------------------------------------------------------------------- /modules/entity_browser/images/seldisplay_list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/seldisplay_list.png -------------------------------------------------------------------------------- /modules/entity_browser/images/seldisplay_table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/seldisplay_table.png -------------------------------------------------------------------------------- /modules/entity_browser/images/tab_button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/tab_button.png -------------------------------------------------------------------------------- /modules/entity_browser/images/tab_dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/tab_dropdown.png -------------------------------------------------------------------------------- /modules/entity_browser/images/tab_tabs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/images/tab_tabs.png -------------------------------------------------------------------------------- /modules/entity_browser/inline_entity_form.md: -------------------------------------------------------------------------------- 1 | # Inline Entity Form 2 | 3 | Entity Browser integrates with the module [Inline Entity Form](https://drupal.org/project/inline_entity_form) (through the **entity_browser_entity_form** submodule). There are two ways the two modules can be combined: 4 | 5 | ## Using Entity Browser to create new entities, as well as browsing the existing ones 6 | 7 | Entity Browser comes with an **"Entity form"** widget that uses the **"Inline Entity Form"** form element to build entity creation forms. This allows users to create new entities of any type from inside of an arbitrary entity browser. 8 | 9 | To configure this option, [follow the previous instructions](creating_browser_through_ui.md) to create an Entity Browser (or modify an existing one provided by an example module), and configure the widget (last step) the following way: 10 | 11 | 1- Go to the Widget step on the multi-setp wizard, which will be at the URL: 12 | ```/admin/config/content/entity_browser/{your_browser_name}/widgets?js=nojs ``` 13 | 14 | 2- On the dropdown **"Add widget plugin"**, select **"Entity form"** 15 | 16 | ![](select-entity-form-on-widget-creation.png) 17 | 18 | 3- Once the widget is added, go to the corresponding row and configure the entity types and bundles you will allow the users to create using this widget. 19 | 20 | ![](select-entity-type-and-bundle.png) 21 | 22 | In the previous example, when the editor selects this widget on the Entity Browser (by selecting the corresponding tab, dropdown, etc), the form to create a "Media" entity (in the "Audio" bundle) will be presented as an inline form. 23 | 24 | 25 | ## New entities with IEF, but browse existing with Entity Browser 26 | 27 | Entity Browser can inject itself into Inline Entity Form and replace standard autocomplete textfield that is used to reference existing entities from IEF. 28 | 29 | This allows site builders to create nicer and more powerful experience for content creators. The in-form creation of new entities will keep being handled by the Inline Entity Form, but we are extending it to allow the browsing experience of existing entities to be done through a custom EB widget. 30 | 31 | To configure this option, please follow these steps: 32 | 33 | 1- Go to your entity **"Manage Form Display"** configuration page, where you can configure the widgets of your entity_reference field. For example, if you have the field in the "page" content type, this will be available at the URL: 34 | `/admin/structure/types/manage/page/form-display` 35 | 36 | 2- Choose **"Inline entity form - Complex"** as primary widget to your field 37 | 38 | 3- Click on the gear to open the widget settings: 39 | 40 | ![](op2-widget-configuration.png) 41 | 42 | Make sure you have the option **"Alow users to add existing {entity_type}"**. 43 | 44 | 4- Select on the dropdown **"Entity Browser"** the browser you want to use as a browsing widget. Note that at this point you will need to have previously created a browser. If you don't have any browser created yet, please refer to the [instructions on creating one](creating_browser_through_ui.md). 45 | -------------------------------------------------------------------------------- /modules/entity_browser/intro.md: -------------------------------------------------------------------------------- 1 | # Entity Browser 2 | 3 | The [Entity Browser](https://drupal.org/project/entity_browser) module provides a very flexible and generic entity browsing and selecting tool. It can be used in any context where one needs to select any number of entities and do something with them. 4 | 5 | Examples of few possible use cases: 6 | - powerful entity reference widget, 7 | - embedding entities into WYSIWYG, 8 | - you name it! 9 | 10 | Entity Browser comes with an example module (modules/example in main repo) which can be used as a starting point. It comes with some example configuration and shows how Entity Browser can be used as a field widget for Entity Reference fields. 11 | 12 | Other good examples or modules that showcase what you can do with the Entity Browser concept are: 13 | 14 | ### File Entity Browser 15 | 16 | If your need is to work only with images/files, the module [File Entity Browser](https://drupal.org/project/file_browser) is a very good starting point to get up and running with Entity Browser to provide nice content creation experiences and re-usability of core files/images. It also allows you to bulk upload images using a Drag & Drop zone, using the [dropzonejs](../dropzonejs/intro.md) library. 17 | 18 | ### Media Entity Browser 19 | 20 | Similarly to the File Entity Browser, the [Media Entity Browser](https://drupal.org/project/media_entity_browser) module is intended to be a good starting point for browsing Media Entities, with some theming to improve the content authoring experience. 21 | 22 | ### Content Browser 23 | 24 | Similarly to the previous example, the [Content Browser](https://drupal.org/project/content_browser) module is intended to be a tool for selecting nodes on your site, and provides out of the box a nicely configured browser with some theming and fine-tuning. 25 | 26 | ### Lightning 27 | 28 | One level beyond, the [lightning](https://www.drupal.org/project/lightning) is a full Drupal distribution that aims to create great editorial / authoring experiences, and makes an extensive use of Entity Browser and its possible integrations. 29 | 30 | 31 | 32 | ## Development 33 | 34 | We use Github pull request workflow. In order to contribute to the module please [create a pull request](https://github.com/drupal-media/entity_browser/compare) and cross-link it with the [relevant drupal.org issue](https://www.drupal.org/project/issues/entity_browser). 35 | 36 | ## Roadmap to 8.x-1.0 version 37 | 38 | Most up to date information about the current focus and relevant tasks/issues can be seen in the [roadmap META issue](https://www.drupal.org/node/2576683). 39 | 40 | ## Maintainers 41 | - Janez Urevc ([@slashrsm](https://github.com/slashrsm)) https://drupal.org/user/744628 42 | - Primož Hmeljak ([@primsi](https://github.com/primsi)) https://drupal.org/user/282629 43 | -------------------------------------------------------------------------------- /modules/entity_browser/op2-widget-configuration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/op2-widget-configuration.png -------------------------------------------------------------------------------- /modules/entity_browser/select-entity-form-on-widget-creation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/select-entity-form-on-widget-creation.png -------------------------------------------------------------------------------- /modules/entity_browser/select-entity-type-and-bundle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/select-entity-type-and-bundle.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-1.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-2.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-3.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-4.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-5.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-6a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-6a.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-6b.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-6b.png -------------------------------------------------------------------------------- /modules/entity_browser/selection-display-multi-step-7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/selection-display-multi-step-7.png -------------------------------------------------------------------------------- /modules/entity_browser/selection_displays.md: -------------------------------------------------------------------------------- 1 | # Selection displays 2 | 3 | The **selection display** plugins provide a way for the end user (editor) to deal with the entities that are in process of being selected, but before confirming the operation. You can think of it as a sort of "temporary storage" for the entities that are being "retrieved" by the Entity Browser, while the user is using the browser. 4 | 5 | As with the other plugins, contrib and custom modules can extend and provide additional plugins of this type. 6 | 7 | The **Entity Browser** module provides the following **selection display** plugins: 8 | 9 | 10 | ### No selection display 11 | 12 | This option is the simplest alternative, when you do not want your Entity Browser to provide any mechanism to deal with the temporary "selection area" of the entities being retrieved by the browser. 13 | 14 | 15 | ### Multi-step selection display 16 | 17 | This is the option you might want to use in the most flexible or complex media handling workflows. The **multi-step selection display** allows the editor to use different widgets sequentially in order to populate a **selection set** and these entities being selected will be visible in the **selection** area. 18 | 19 | This workflow can be better understood in the following images: 20 | 21 | 1) Nothing is selected, the **selection set** is empty 22 | 23 | ![](selection-display-multi-step-1.png) 24 | 25 | 2) Upload 2 images using the widget, there is now an option to add these 2 to the current selection 26 | 27 | ![](selection-display-multi-step-2.png) 28 | 29 | 3) Add these 2 images to the selection 30 | 31 | ![](selection-display-multi-step-3.png) 32 | 33 | 4) Let's select now some existing images from the media library 34 | 35 | ![](selection-display-multi-step-4.png) 36 | 37 | 5) Let's upload another image with the first widget (upload) 38 | 39 | ![](selection-display-multi-step-5.png) 40 | 41 | 6) We can then manually re-order the selection to suit our needs, if necessary 42 | 43 | ![](selection-display-multi-step-6a.png) 44 | 45 | ![](selection-display-multi-step-6b.png) 46 | 47 | 7) We can finally confirm the operation to use the content of our selection display in our field 48 | 49 | ![](selection-display-multi-step-7.png) 50 | 51 | 52 | The **multi-step** selection display provides the following configuration options: 53 | - **Entity type** - The type of the entity being selected. Not all display plugins will need this, and will be ignored if the display being in charge of displaying it on the selection area do not need this information. 54 | - **Entity display plugin** - The plugin responsible for rendering the visualization of the entity inside the selection area. 55 | - **Select button text** - The label to use on the submit button of the selection area 56 | 57 | 58 | 59 | ### View selection display 60 | 61 | This type of selection display can use **an arbitrary view** to be used as "selection area", with all the flexibility that a custom-made view can bring to your browser. 62 | 63 | The only requirement you need to pay attention to when using this option is that your view needs to have a Contextual Filter that receives entities IDs, with multiple-valued arguments (for instance: "12,45,22,938") enabled. 64 | 65 | There are some known limitations of this display type: 66 | - If a given entity is selected twice, it will be displayed only once. 67 | - The view used as selection display will generally not respect the order of the selected entities. 68 | These are all limitations of the views system, in core. 69 | 70 | In order to create an Entity Browser with this type of selection display, the steps to follow are: 71 | 72 | 1) Create a view that showing entities (or any representation of entities you would need) and make sure that this view is configured to accept as **Contextual Filter** the main ID of the entity (**NID** for nodes, **UID** for users, etc). 73 | 74 | 2) When creating the Browser through the wizard, select **View selection display** on the dropdown of the first step. 75 | 76 | 3) Indicate the view and display names in the fourth step of the wizard: 77 | - **View : view display** - The view name and display name to be used to show the entities in the selection area during the selection. 78 | 79 | 80 | 81 | #### Examples of selection displays that could be built with a custom view: 82 | 83 | 84 | 85 | #### Grid 86 | ![Grid selection display](images/seldisplay_grid.png) 87 | 88 | #### Table 89 | ![Table selection display](images/seldisplay_table.png) 90 | 91 | #### List 92 | ![List selection display](images/seldisplay_list.png) 93 | -------------------------------------------------------------------------------- /modules/entity_browser/widget-selection-dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/widget-selection-dropdown.png -------------------------------------------------------------------------------- /modules/entity_browser/widget-selection-tabs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/widget-selection-tabs.png -------------------------------------------------------------------------------- /modules/entity_browser/widget-upload.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/widget-upload.png -------------------------------------------------------------------------------- /modules/entity_browser/widget-view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/widget-view.png -------------------------------------------------------------------------------- /modules/entity_browser/widget_selectors.md: -------------------------------------------------------------------------------- 1 | # Widget selectors 2 | 3 | The **Widget selector** plugins define how multiple widgets of the same Entity Browser should be presented on the user interface. 4 | 5 | For example, a site builder could create an Entity Browser containing 2 widgets: "Media Gallery" (a view) and "Create new media" (an entity form), and the mechanism to change between these two widgets is defined in the **widget selector** plugin configuration. 6 | 7 | The [Entity Browser](https://drupal.org/project/entity_browser) base module defines the following **widget selector** plugins: 8 | 9 | 10 | ### Dropdown 11 | 12 | 13 | ![](widget-selection-dropdown.png) 14 | 15 | 16 | ### Tabs 17 | 18 | ![](widget-selection-tabs.png) 19 | 20 | ### Single widget 21 | 22 | When configured to use the **Single widget** selection type, the Entity Browser will show **only the first** of the available widgets, and is naturally suitable for those situations where it makes sense to have only one widget available in the browsing experience. 23 | 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /modules/entity_browser/widgets.md: -------------------------------------------------------------------------------- 1 | # Widgets 2 | 3 | **Widget** plugins represent the main functionality of the Entity Browser, providing a tool for the end user to browse/view/create/select the specific content he/she is looking for. 4 | 5 | The [Entity Browser](https://drupal.org/project/entity_browser) base module provides a set of widget plugins, and contrib / custom modules can extend this list providing additional widgets. 6 | 7 | The widgets available on the Entity Browser module out of the box are: 8 | 9 | ### File Upload 10 | 11 | This is the standard file upload widget from drupal. 12 | 13 | ![](widget-upload.png) 14 | 15 | 16 | The only configuration option for this type is: 17 | - **Upload location** - The path where the files will be uploaded to. Defaults to ```public://``` 18 | 19 | 20 | ### Views 21 | 22 | The **View** widget plugin allows the end user to navigate / browse though an arbitrary view and select a given content from this list of results. The site builder can select which view to use on this widget, and any properly configured view (see the "[creating a browser](creating_browser_through_ui.md)" section for more info) can be used here. 23 | 24 | ![](widget-view.png) 25 | 26 | 27 | The only configuration option for this type is: 28 | - **View : View display** - The name of the view and display that should be used in this widget 29 | 30 | 31 | 32 | ### Entity form (when using the "Entity Browser IEF" submodule) 33 | 34 | If you have enabled the module **Entity Browser IEF** then you will be able to use also the **Entity form** widget, which will allow the creation of an arbitrary entity inside the Entity Browser. This widget will open the entity creation form inside the browser, and users can then mix the selection of the existing entities with the creation of new ones in the same "browsing / selecting" operation. 35 | 36 | You can find more information about the integration between **Entity Browser** and **Inline Entity Form** on [its specific chapter](inline_entity_form.md) of this guide. 37 | 38 | 39 | 40 | ### Widgets provided by other contrib modules 41 | 42 | You can find on the [project page](https://drupal.org/project/entity_browser) a list of modules that provide additional widgets. Some examples are: 43 | - [Media entity image](https://drupal.org/project/media_entity_image) - File upload 44 | - [File Entity Browser](https://drupal.org/project/file_browser) - Bulk file upload, with DropzoneJS integration 45 | - [Content Browser](https://drupal.org/project/content_browser) - Content view (nodes) 46 | - Etc 47 | 48 | 49 | [TODO: Document and take snapshots of the above examples] 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | -------------------------------------------------------------------------------- /modules/entity_browser/wizard_step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/wizard_step_1.png -------------------------------------------------------------------------------- /modules/entity_browser/wizard_step_5a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/wizard_step_5a.png -------------------------------------------------------------------------------- /modules/entity_browser/wizard_step_5b.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/wizard_step_5b.png -------------------------------------------------------------------------------- /modules/entity_browser/wizard_step_5c.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/entity_browser/wizard_step_5c.png -------------------------------------------------------------------------------- /modules/entity_embed/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/fallback_formatter/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/field_formatter/images/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_1.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_10.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_11.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_12.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_13.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_2.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_3.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_4.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_5.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_6.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_7.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_8.png -------------------------------------------------------------------------------- /modules/field_formatter/images/step_9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/field_formatter/images/step_9.png -------------------------------------------------------------------------------- /modules/field_formatter/intro.md: -------------------------------------------------------------------------------- 1 | # Field Formatter 2 | 3 | [Field Formatter](https://www.drupal.org/project/field_formatter) module adds formatters for entity reference fields to output only a specific field. This module provides two formatters: *Field formatter with inline settings* and *Field formatter from view display*. 4 | 5 | ## Installation 6 | 7 | 1. Download [Field Formatter](https://www.drupal.org/project/field_formatter) from [Drupal.org](https://www.drupal.org/node/2328797/release). 8 | 2. Install it in the [usual way](https://www.drupal.org/documentation/install/modules-themes/modules-8). 9 | 10 | ## Usage 11 | 12 | 1. Create entity reference field: 13 | * On `admin/structure` choose **Content types**. 14 | 15 | ![Step 1](images/step_1.png) 16 | * Choose content type entity reference field should be added to, for example: *Article*, and click **Manage fields**. 17 | 18 | ![Step 2](images/step_2.png) 19 | * Click **+ Add field**. 20 | 21 | ![Step 3](images/step_3.png) 22 | * From **References** dropdown menu choose **Other**, fill the *Label* and click **Save and continue**. 23 | 24 | ![Step 4](images/step_4.png) 25 | * Choose **Type of item to reference**, for example: *Content*, and click **Save field settings**. 26 | 27 | ![Step 5](images/step_5.png) 28 | * Select which content types you want to reference in **Reference type section**, for example: *Article*, and click **Save settings**. 29 | 30 | ![Step 6](images/step_6.png) 31 | 2. Choose field formatter for your entity reference field: 32 | * Open *Manage display* page for the selected content type (in our case *Article*). 33 | 34 | ![Step 7](images/step_7.png) 35 | * Choose which formatter you want to use on your entity reference field, *Field formatter with inline settings* or *Field formatter from view display*. 36 | 37 | ![Step 8](images/step_8.png) 38 | * In formatter settings define which field from the referenced entity you want to display in your article. 39 | 40 | ![Step 9](images/step_9.png) 41 | * You also need to configure View mode if you're using *Field formatter from view display* 42 | * Click **Update** and then **Save**. 43 | 44 | ![Step 10](images/step_10.png) 45 | 3. Create a new node (in our case *Article*) with entity reference field: 46 | * In `admin/content` click **+ Add content**. 47 | 48 | ![Step 11](images/step_11.png) 49 | * Choose node to create (in our case *Article*). 50 | 51 | ![Step 12](images/step_12.png) 52 | * Fill *Title* and all the other fields, for your entity reference field choose entity (or in our case *Article*) you want to reference and click **Save and publish**. 53 | 54 | ![Step 13](images/step_13.png) 55 | * The chosen field from referenced entity is displayed on the saved article page. 56 | -------------------------------------------------------------------------------- /modules/file_browser/images/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/file_browser/images/step_1.png -------------------------------------------------------------------------------- /modules/file_browser/images/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/file_browser/images/step_2.png -------------------------------------------------------------------------------- /modules/file_browser/images/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/file_browser/images/step_3.png -------------------------------------------------------------------------------- /modules/file_browser/intro.md: -------------------------------------------------------------------------------- 1 | # File Entity Browser 2 | 3 | The [File Entity browser](https://www.drupal.org/project/file_browser) module provides a default [Entity Browser](https://www.drupal.org/project/entity_browser) that lets you browse and select your files in a nice-looking, mobile-ready [Masonry](http://masonry.desandro.com/) based interface, and upload files using the [Dropzonejs](https://www.drupal.org/project/dropzonejs) module. This module uses Entity browser to provide nice content creation experience and re-usability of core files. 4 | 5 | ## Requirements 6 | 7 | 1. [Entity Browser](https://www.drupal.org/project/entity_browser) 8 | 2. [Dropzonejs](https://www.drupal.org/project/dropzonejs) 9 | 10 | ## Installation 11 | 12 | 1. Download [Entity Browser](https://www.drupal.org/project/entity_browser) from Drupal.org. 13 | 2. Download [Dropzonejs](https://www.drupal.org/project/dropzonejs) from Drupal.org and follow the install instructions on that page 14 | 3. Download [File browser](https://www.drupal.org/node/2600630/release) and run [bower](http://bower.io/) install from the file_browser directory 15 | 16 | ## Usage 17 | 18 | The File Entity browser module creates custom block type with the entity reference field on it. That entity reference field uses entity browser to attach images to that block. It demonstrates how custom blocks work and how entity browser can be used to improve media-related experience. 19 | 20 | ### Creating File Browser custom block 21 | 22 | 1. On `/structure/block/block-content` click **+Add custom block**: 23 | 24 | ![Step 1](images/step_1.png) 25 | 26 | 2. Choose **File Browser** custom block type: 27 | 28 | ![Step 2](images/step_2.png) 29 | 30 | 3. Add desired custom block name and upload files to add to your block and click **Save**: 31 | 32 | ![Step 3](images/step_3.png) 33 | 34 | 4. At the end just click Save at the bottom of the page and your File Browser custom block is ready to be used on any region from the Block layout page. 35 | 36 | 37 | ## Supporting organizations 38 | - [Acquia](https://www.drupal.org/marketplace/acquia) 39 | -------------------------------------------------------------------------------- /modules/file_checker/intro.md: -------------------------------------------------------------------------------- 1 | #Introduction 2 | 3 | The purpose of File Checker is to verify that files managed by Drupal actually 4 | exist at the location where Drupal believes they are. 5 | 6 | In a perfect Drupal world your server filesystem and its correspoding entries in 7 | Drupal's files table are 100% synchronized. But what if parts of your file system 8 | have been corrupted due to some disk failure? Or one of your modules messed up 9 | your database and files? Or your deploy script went beserk? Well, then this module 10 | will help you to monitor and find out which files are out of sync. 11 | 12 | It offers the following features: 13 | 14 | * You can check all files immediately through the UI or using drush. 15 | * You can schedule regular checking of all files, triggered by cron or drush. 16 | * You can check specific files whenever file entities are created or updated. 17 | * A warning is logged if a file does not exist at the uri of the file entity. 18 | * Missing files are marked as missing and listed in a view. 19 | * It works with files stored locally or remotely. 20 | * It should work with any quantity of files. 21 | 22 | WARNING! Once you have started file checking, File checker cannot be 23 | uninstalled. 24 | 25 | #User Interface 26 | 27 | The File checker UI is at admin/config/media/file-system/file-checker. 28 | 29 | If you press "Check files now" a bulk file checking will start, using 30 | Drupal's Batch API. A progress bar will be displayed showing the proportion of 31 | files checked so far. You will need to keep the browser window open, and not 32 | navigate away, until checking is finished. 33 | 34 | You can view missing files at admin/config/media/file-system/file-checker/missing. 35 | 36 | 37 | #Background File Checking 38 | 39 | Checking files on remote servers can take a few seconds for each file, and so 40 | checking from the UI becomes impractical when you have many files. Background 41 | file checking solves this problem, and also allows for automated monitoring of 42 | your filesystem's health. 43 | 44 | If background checking is under way, you can see its progress and cancel from the UI. 45 | 46 | Background checking divides one run of checking all files into many small executions, 47 | to prevent performance problems if any one execution lasts too long. A typical setup 48 | is for a new execution to be scheduled every 60 seconds, and for each execution 49 | to last 50 seconds. Each execution will check as many files as it can in its time. 50 | When there are no more files to check, the run comes to an end. 51 | 52 | Given this, controlling background checking from drush or cron involves 2 stages: 53 | * starting, which sets up a run of checking all files. You might schedule this to 54 | happen once each night. 55 | * executing, which actually checks files. You might schedule this to happen every 56 | minute, all the time. If checking has not been started, then executions simply do 57 | nothing and immediately stop. Every run must have at least 2 executions, no matter 58 | how few files are on your system. If you have many remote files, you may need hundreds 59 | of executions. Executions are sequential, so they cannot happen in parallel. 60 | 61 | Out of the box, there are 2 ways to run background checking: Drush and Ultimate Cron. 62 | 63 | #Drush Commands 64 | 65 | ```drush file-checking-start``` 66 | Starts background file checking. 67 | 68 | ```drush file-checking-execute 50``` 69 | Checks files for 50 seconds. 70 | 71 | ```drush file-checking-cancels``` 72 | Cancels background file checking. 73 | 74 | Setting up the following in crontab on Linux should cause file checking to 75 | run at 2am each night until all files are checked: 76 | 77 | ``` 78 | 0 2 * * * drush file-checking-start 79 | * * * * * drush file-checking-execute 50 80 | ``` 81 | 82 | 83 | 84 | #Ultimate Cron 85 | 86 | The contrib module Ultimate Cron allows for many ways to control and launch 87 | Drupal cron jobs. File checker provides configuration for 2 cron jobs 88 | that should appear at admin/config/system/cron/jobs when Ultimate Cron is 89 | installed. By default they work the same as the drush commands described 90 | above, but you can edit them in the Ultimate Cron UI to change when they run. 91 | You will need to make sure that Ultimate Cron itself is triggered every 92 | minute, if you want these cron jobs to be triggered at this frequency 93 | by Ultimate Cron. 94 | 95 | #Checking on File Entity Changes 96 | 97 | You can configure File checker to check files whenever file entity is 98 | created or has its uri changed. To do this, use the settings UI at 99 | admin/config/media/file-system/file-checker. 100 | 101 | If you choose 'Immediately' then files will be checked as soon as 102 | they are saved, which may hold up the user experience for a few seconds. 103 | 104 | If you choose 'Later', then files will be placed in a Drupal queue, and 105 | checked the next time Drupal's main cron runs and processes its queues. 106 | 107 | 108 | #Recommended modules 109 | 110 | * Various monitoring modules would allow you to receive an email notification 111 | if missing files were detected. 112 | 113 | * Ultimate Cron to trigger background file checking. 114 | -------------------------------------------------------------------------------- /modules/file_entity/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/flysystem/flysystem_filefield.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/flysystem/flysystem_filefield.png -------------------------------------------------------------------------------- /modules/flysystem/intro.md: -------------------------------------------------------------------------------- 1 | # Flysystem 2 | 3 | The [Flysystem](https://www.drupal.org/project/flysystem) module is the first remote storage solution to be available for Drupal 8 (and it's also recently available in D7). It uses the [Flysystem PHP library](http://flysystem.thephpleague.com/), a modern filesystem abstraction designed to allow for the easy swapping of one filesystem with another. The Flysystem library is gaining widespread adoption in the PHP world, and is the default filesystem layer in the Laravel framework. Incorporating it in a Drupal project is an example of the "getting off the island" or "proudly invented elsewhere" philosophies often discussed for Drupal 8 - making use of the work done in the wider PHP community rather than struggling to reinvent everything from scratch. 4 | 5 | Flysystem is made available in Drupal 8 by the [Flysystem module](https://www.drupal.org/project/flysystem). Currently through its adapter modules it offers the following storage types: 6 | * Local 7 | * (s)FTP 8 | * ZIP 9 | * Dropbox 10 | * Rackspace 11 | * Amazon S3 12 | It's relatively easy to implement new adapters, and more are becoming available all the time. 13 | 14 | When joined with a flysystem adapter module, the flysystem module offers four things: 15 | * a syntax to define the access details for the remote storage location in Drupal's settings.php. 16 | * a storage setting for Drupal's core file field. 17 | * access to the Flysystem API so you can execute standard file system operations (read, write, list, etc.) on your remote storage from your custom code. 18 | * a synchronisation UI that enables you to manually synchronise local and remote storage locations. 19 | 20 | # Simple remote storage with Flysystem 21 | 22 | Firstly, install Flysystem module and an adapter module e.g. Flysystem_dropbox 23 | 24 | Secondly, specify the remote storage location in Drupal's settings.php 25 | 26 | ```php 27 | $schemes = [ 28 | 'dropboxexample' => [ 29 | 'driver' => 'dropbox', 30 | 'config' => [ 31 | 'token' => '#my-dropbox-token#', 32 | 'client_id' => #my-dropbox-email-id#, 33 | 'prefix' => '[/dropbox subdirectory]', // Optional. 34 | ], 35 | ], 36 | ] 37 | $settings['flysystem'] = $schemes; 38 | ``` 39 | 40 | * Choose Flysystem location as the storage for a Drupal file field 41 | 42 | ![Flysystem storage for a file field](flysystem_filefield.png) 43 | 44 | If you upload a file in Drupal using that file field, it will then be stored on your remote location, not on the web server where Drupal runs. 45 | 46 | When the file field is rendered by Drupal (e.g. because the content or media entity having that file field is requested by a site visitor) then the file will be served up to your visitor, exactly as if it were stored on your server. All the Drupal field formatters, theming, etc. work exactly as normal. 47 | 48 | ## File access control 49 | 50 | Flysystem storage works like private files in drupal 8. It restricts access to the original files and lets Drupal and its modules control access to the files. 51 | 52 | Instead of rendering a URL directly to a file at its location (e.g. https://mybucket.s3.amazonaws.com/myfile.mp3), it renders instead a URL on your webserver (e.g. http://mywebserver.com/system/files/myfile.mp3). Requests to this URL are intercepted by Drupal, which uses its standard and configurable access control logic to decide whether or not to return the file or an "Access denied" message. 53 | 54 | By default when using a file field, anyone who can access the entity to which the file field is attached will be able to access the file at its URL. If they logout or have their permissions changed, they won't be able to access the file even if they made a copy of its URL. 55 | 56 | The situation is slightly more complicated with images - [see here for more](https://www.drupal.org/node/2541116). 57 | 58 | ## Bandwidth 59 | 60 | One issue to be aware of with Flysystem is that as it is not handing out a direct URL to the third party server, your web server is still involved in each request, and so there may be bandwidth or traffic implications for your web server if you serve up a lot of media. 61 | @Todo: better information on this matter. 62 | -------------------------------------------------------------------------------- /modules/image_effects/intro.md: -------------------------------------------------------------------------------- 1 | # Image Effects 2 | 3 | The [Image Effects](https://www.drupal.org/project/image_effects) module provides a suite of additional image effects that can be added to image styles, and UI components that can be used in the image effects configuration forms. 4 | 5 | ## Effects provided: 6 | 7 | - Automatically corect orientation 8 | - Brightness 9 | - Collor Shift 10 | - Strip meatadata 11 | - Watermark 12 | 13 | ## Image effects UI components 14 | 15 | Components provided here are ported from earlier versions of the Textimage module. 16 | - Form API element for color selection 17 | - Pluggable color selectors - HTML color element, Farbtastic 18 | - Pluggable image selectors - Basic, Dropdown 19 | - Pluggable font selectors - Basic, Dropdown 20 | 21 | -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_1.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_10.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_11.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_12.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_13.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_14.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_15.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_16.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_17.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_2.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_3.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_4.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_5.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_6.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_7.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_8.png -------------------------------------------------------------------------------- /modules/image_widget_crop/images/step_9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/image_widget_crop/images/step_9.png -------------------------------------------------------------------------------- /modules/image_widget_crop/intro.md: -------------------------------------------------------------------------------- 1 | # ImageWidgetCrop module 2 | 3 | [ImageWidgetCrop](https://www.drupal.org/sandbox/woprrr/2571403) provides an interface for using the features of the [Crop API](https://www.drupal.org/project/crop). This widget provide an UX for use a crop on all fields images. This module have particularity to purpose capability to crop the same image by 'Crop type' configured. It's very usefull for editorial sites or media management sites. 4 | 5 | ## Try me 6 | 7 | You can Test ImageWidgetCrop in action directly with the sub-module, "ImageWidgetCrop example" to test different usecases of this module. 8 | 9 | ## Requirements 10 | 11 | 1. [Crop API](https://www.drupal.org/project/crop) 12 | 13 | ## Installation 14 | 15 | 1. Download [Crop API](https://www.drupal.org/node/2376659/release) from Drupal.org. 16 | 2. Download [ImageWidgetCrop](https://github.com/woprrr/image_widget_crop) from GitHub. 17 | 3. Install both Crop API and ImageWidgetCrop in the [usual way](https://www.drupal.org/documentation/install/modules-themes/modules-8). 18 | 19 | ## Usage 20 | 21 | 1. Create a Crop Type 22 | * On `admin/structure` choose **Crop types** 23 | ![Step 1](images/step_1.png) 24 | * Click on **+ Add crop type** 25 | ![Step 2](images/step_2.png) 26 | * Add Name, Description and Aspect Ratio for your crop type and click **Save crop type** 27 | ![Step 3](images/step_3.png) 28 | 2. Create an Image Style 29 | * On `admin/structure/config` choose **Image styles** 30 | ![Step 4](images/step_4.png) 31 | * Click on **+ Add image style** 32 | ![Step 5](images/step_5.png) 33 | * Add Image style name and click **Create new style** 34 | ![Step 6](images/step_6.png) 35 | * Choose Manual crop effect and click **Add** 36 | ![Step 7](images/step_7.png) 37 | * Choose your Crop Type, to apply your crop selection, and click **Add effect** 38 | ![Step 8](images/step_8.png) 39 | 3. Create an Image field 40 | * On desired content type (i.e. Basic page), on `admin/structure/types`, click on **Manage fields** 41 | ![Step 9](images/step_9.png) 42 | * Click on **+ Add field** 43 | ![Step 10](images/step_10.png) 44 | * Choose **Image**, add label and click **Save and continue** 45 | ![Step 11](images/step_11.png) 46 | 4. In form display of your page, on `admin/structure/types/manage/page/form-display`, set the widget for your field to ImageWidgetCrop 47 | ![Step 12](images/step_12.png) 48 | and select your crop types in the Crop settings list and click **Update** and then **Save**. You can configure the widget to create different crops on each crop types. For example, if you have an editorial site, you need to display an image on different places. With this option, you can set an optimal crop zone for each of the image styles applied to the image. 49 | ![Step 13](images/step_13.png) 50 | 5. On Manage display of your page, on `admin/structure/types/manage/page/display`, set the display formatter Image 51 | ![Step 14](images/step_14.png) 52 | and choose your image style and click **Update** and then **Save** 53 | ![Step 15](images/step_15.png) 54 | 6. Add an image with your widget to your content and crop your picture, by crop types used for this image 55 | ![Step 16](images/step_16.png) 56 | ![Step 17](images/step_17.png) 57 | 58 | ## ImageWidgetCrop Code Quality 59 | 60 | * [SensioLabsInsight](https://insight.sensiolabs.com/projects/0e2f44af-6837-4772-b3e0-c373faa95ae6) 61 | * [Scrutinizer](https://scrutinizer-ci.com/g/woprrr/image_widget_crop/?branch=8.x-1.x) 62 | * [Travis-ci](https://travis-ci.org/woprrr/image_widget_crop) 63 | -------------------------------------------------------------------------------- /modules/intro.md: -------------------------------------------------------------------------------- 1 | #D8 Media Modules 2 | 3 | There is a substantial amount of media functionality available in Drupal 8 today. This section of the guide provides a brief summary of the functionality delivery by each module and its current status. 4 | 5 | ## D8 Core Functionality 6 | 7 | In Drupal 8 core, As in D7 core, there is out of the box support for files, images and basic media functionality. That said, rich media experiences in Drupal are generally built using the contributed modules listed below. 8 | 9 | 10 | ## D8 Contrib Modules 11 | 12 | As discussed in the introduction to this guide, the Drupal 8 Media ecosystem includes several independent but interoperable/pluggable Media modules. 13 | 14 | The modules are intended to be used together as needed in order to provide as basic or advanced a media solution as is needed for a particular Drupal project. 15 | 16 | 17 | ###D8 Media Storage Modules 18 | 19 | * [**File Entity:**](file_entity/intro.md) provides interfaces for storing and managing files, which extends core file entity e.g., allowing for file fields, types, display modes, etc. ([d.o](https://www.drupal.org/project/file_entity)) 20 | * *Latest Status:* Beta 21 | 22 | 23 | * [**Media Entity:**](media_entity/intro.md) an alternate approach to media storage in Drupal, which doesn't directly extend core file entity, and creates a new entity type to be served as a base for other modules (providers) to build upon and define their own media types. ([d.o](https://www.drupal.org/project/media_entity)) 24 | * *Latest Status:* Stable (general availability) release 25 | 26 | 27 | * [**Flysystem:**](flysystem/intro.md) provides a bridge to use Flysystem as Drupal stream wrappers ([d.o](https://www.drupal.org/project/flysystem)) 28 | * *Latest Status:* Alpha 29 | 30 | 31 | ###D8 Media UI Modules 32 | 33 | * **Content Browser:** provides a nice content creator/editor experience for browsing and selecting existing content (nodes). It is built upon the [Entity Browser](modules/entity_browser/intro.md) module, improving the UI and providing a pre-configured browser out-of-the-box. ([d.o](https://www.drupal.org/project/content_browser)) 34 | * *Latest Status:* Alpha 35 | 36 | 37 | * [**Crop API:**](crop/intro.md) an API for image cropping that is intended to be used with a related API module such as [Image Widget Crop]( https://www.drupal.org/project/image_widget_crop) ([d.o](https://www.drupal.org/project/crop)) 38 | * *Latest Status:* Stable (general availability) release 39 | 40 | 41 | * [**DropzoneJS:**](dropzonejs/intro.md) provides "drag & drop" file uploads with image previews ([d.o](https://www.drupal.org/project/dropzonejs)) 42 | * *Latest Status:* Alpha 43 | 44 | 45 | * [**Embed API:**](embed/intro.md) a framework module to embed things using the Drupal 8 WYSIWYG editor ([d.o](https://www.drupal.org/project/embed)) 46 | * *Latest Status:* RC (release candidate) 47 | 48 | 49 | * [**Entity Browser:**](entity_browser/intro.md) enables the creation of user-friendly browsers that can be used for selecting entities (file, image, media entities, etc). ([d.o](https://www.drupal.org/project/entity_browser)) 50 | * *Latest Status:* Alpha 51 | 52 | 53 | * [**Entity Embed:**](entity_embed/intro.md) allows any entity to be embedded within a text area using a WYSIWYG editor. ([d.o](https://www.drupal.org/project/entity_embed)) 54 | * *Latest Status:* Beta 55 | 56 | 57 | * [**File Entity Browser:**](file_browser/intro.md) provides a nice content creator/editor experience for uploading files (implementing [Dropzonejs](https://www.drupal.org/project/dropzonejs)) and browsing/selecting files (implementing [Entity Browser](modules/entity_browser/intro.md)). ([d.o](https://www.drupal.org/project/file_browser)) 58 | * *Latest Status:* Alpha 59 | 60 | 61 | * [**Image Widget Crop:**](image_widget_crop/intro.md) provides an interface for using the features of the [Crop API](https://www.drupal.org/project/crop) ([d.o](https://www.drupal.org/project/image_widget_crop)) 62 | * *Latest Status:* Stable (general availability) release 63 | 64 | 65 | * **Media Entity Browser:** provides a nice content creator/editor experience for browsing and selecting existing media entities. It is built upon the [Entity Browser](modules/entity_browser/intro.md) module, improving the UI and providing a pre-configured browser out-of-the-box. ([d.o](https://www.drupal.org/project/media_entity_browser)) 66 | * *Latest Status:* TBA 67 | 68 | 69 | * [**URL Embed:**](url_embed/intro.md) allows embedding of external URLs using the Drupal 8 WYSIWYG or link fields ([d.o](https://www.drupal.org/project/url_embed)) 70 | * *Latest Status:* TBA 71 | 72 | 73 | ###D8 Media Display Modules 74 | 75 | * [**Fallback Formatter:**](fallback_formatter/intro.md) a field formatter that attempts multiple formatters for displaying file and applies the first one that returns output ([d.o](https://www.drupal.org/project/fallback_formatter)) 76 | * *Latest Status:* Stable (general availability) release 77 | 78 | 79 | * [**Field Formatter:**](field_formatter/intro.md) provides a field formatter that can attempt multiple formatters and the first one that returns output wins. ([d.o](https://www.drupal.org/project/field_formatter)) 80 | * *Latest Status:* Stable (general availability) release 81 | 82 | * **Media Expire:** This module enables you to unpublish your media entites automatically by setting an expire field. ([d.o](https://www.drupal.org/project/media_expire)) 83 | * *Latest Status:* Alpha 84 | 85 | ###D8 Media Feature Modules 86 | 87 | * **[Media:](media/intro.md)** full featured media module for Drupal 8 which depends on other D8 modules to provide functionality. This module comes with lot of configuration files to provide most of the basic features. ([d.o](https://www.drupal.org/project/media)) 88 | * *Latest Status:* TBA 89 | 90 | 91 | * [**Media Pinkeye:**](media_pinkeye/intro.md) one of the "full-featured" media solutions for Drupal 8. It's goal is to provide basic media features and experience (WordPress parity) ([d.o](https://www.drupal.org/project/media_pinkeye)) 92 | * *Latest Status:* TBA 93 | 94 | 95 | **NOTE**: The "Latest Status" information was last updated on **October, 11th, 2016**. You are encouraged to visit each module page to get potentially more updated information on its status. -------------------------------------------------------------------------------- /modules/media/add_dailymotion_video.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_dailymotion_video.jpg -------------------------------------------------------------------------------- /modules/media/add_document.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_document.jpg -------------------------------------------------------------------------------- /modules/media/add_document_widget.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_document_widget.png -------------------------------------------------------------------------------- /modules/media/add_gallery.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_gallery.jpg -------------------------------------------------------------------------------- /modules/media/add_image.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_image.jpg -------------------------------------------------------------------------------- /modules/media/add_image_extension.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_image_extension.jpg -------------------------------------------------------------------------------- /modules/media/add_image_type.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_image_type.jpg -------------------------------------------------------------------------------- /modules/media/add_instagram.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_instagram.jpg -------------------------------------------------------------------------------- /modules/media/add_media_items.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_media_items.jpg -------------------------------------------------------------------------------- /modules/media/add_tweet.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_tweet.jpg -------------------------------------------------------------------------------- /modules/media/add_video.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/add_video.png -------------------------------------------------------------------------------- /modules/media/adding-media-items.md: -------------------------------------------------------------------------------- 1 | # Adding media items 2 | 3 | To add media items to your drupal site, visit media/add. Here you can simply choose the type of media item and upload. 4 | 5 | ![](/modules/media/add_media_items.jpg) 6 | 7 | ## Images 8 | 9 | Visit media/add/image to upload media items of image type. Enter all the details and upload the image file. By default images of only png, gif, jpg and jpeg types are permitted. Read the next article to know about how to modify the allowed extension types. 10 | 11 | Once the image is uploaded, you can open the 'Crop Image' section to crop the uploaded image. Once done, click on 'Save and publish' to publish the image. 12 | 13 | ![](/modules/media/add_image.jpg) 14 | 15 | ## Videos 16 | 17 | Visit media/add/video to upload media items of video type. Enter the title for the video and the url. By default only Vimeo and YouTube URLs are supported. Read the next article to find out how to add support for more providers. 18 | 19 | ## ![](/modules/media/add_video.png)Gallery 20 | 21 | Creating galleries is really simple with the media module. Go to media/add/gallery and enter the title of the gallery. Then select the media items to be included in the gallery by click on "Select media" in the slides section. Choose the items from the media library or upload new items by clicking on the "Upload images" or "Add video" tab. 22 | 23 | _Note: A gallery can contain media items of all types except the gallery type itself. _ 24 | 25 | ![](/modules/media/gallery_select_modal.jpg) 26 | 27 | ![](/modules/media/add_gallery.jpg) 28 | 29 | Click on "Save and Publish" button to create the gallery. 30 | 31 | ## Documents 32 | 33 | Media module supports uploading and handling of a large type of documents file. Go to media/add/document and upload the document. By default the supported types are txt,pdf, doc, docx, odf, ods, odt, otp, ots, ott, odp, ppt, pptx, rtf, xls, xlsx and csv. 34 | 35 | To know about how to add more types and file type icons, please read the next article. 36 | 37 | ![](/modules/media/add_document.jpg) 38 | 39 | ## Instagram post 40 | 41 | Media module supports the embedding and handling of the instagram posts out of the box. To add instagram posts, visit media/add/instagram. Here enter the title and a valid instagram URL to add the Instagram post to your Drupal website. Refer to the image below to see the sample URL. 42 | 43 | ![](/modules/media/add_instagram.jpg) 44 | 45 | ## Tweets 46 | 47 | Adding tweets are a simple process using the media module. Open media/add/tweet and enter a valid title and tweet URL. Refer the below image to see the sample URL. 48 | 49 | ![](/modules/media/add_tweet.jpg) 50 | 51 | -------------------------------------------------------------------------------- /modules/media/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | In this article we will look at how to configure various media item settings to suit your needs. 4 | 5 | ## Adding more video providers 6 | 7 | Media module uses video\_embed\_field which by default supports YouTube and vimeo videos. There are a lot of other modules available which provide support for some of the most common video websites. The complete list of modules can be found at: https://www.drupal.org/project/video\_embed\_field. 8 | 9 | For example, to add Dailymotion videos to your website, just enable the video\_embed\_dailymotion module\(The name of the module can be found on the video\_embed\_field module page\). Once the module is enabled, simply visit media/add/video and start adding dailymotion videos. 10 | 11 | ![](/modules/media/add_dailymotion_video.jpg) 12 | 13 | ## Enabling more image types 14 | 15 | Suppose you want to enable support for some image type which is not provided by default. You can edit the image field settings and include your extension as well. 16 | 17 | **Note: To change settings of any media bundle you need to visit admin/structure/media and modify the settings.** 18 | 19 | Below are the exact steps you need to follow in order to enable support for a different image type. 20 | 21 | 1. Visit admin/structure/media and in the Image dropdown, click on 'Manage fields'. 22 | ![](/modules/media/add_image_type.jpg) 23 | 2. Now click on Edit for field\_image. 24 | 3. In the 'Allowed File extensions' field add your field type and save the field. 25 | ## ![](/modules/media/add_image_extension.jpg) 26 | 27 | 28 | ## Enabling support for more document types 29 | 30 | To enable support for more document types, you need to follow similar steps as mentioned in the last section and add file extensions to field\_document. The URL for the same should be admin/structure/media/manage/document/fields/media.document.field\_document 31 | 32 | Add the desired extension in the 'Allowed file extensions' field and save. You should now be able to add files of the new type. 33 | 34 | Optionally, if you also want to add a field icon for the new type, you need to follow the below steps: 35 | 36 | 1. Find out the mime type of the file extension for which you want to add the icon. 37 | 38 | 2. Replace the slash \(/\) in the mime type with a hyphen \(-\). This should be the name of your icon file. For example: If the mime type of the type is application/zip, the name of the icon should be application-zip.png. 39 | 40 | 3. Copy the icon fileto the directory sites/default/files/media-icons/generic. 41 | 42 | 4. The file should now use new icon. 43 | 44 | ## Configuring display of the media items 45 | 46 | Drupal makes it really simple to modify the display of the media items. Go to the page admin/structure/media/manage/MEDIA\_BUNDLE\_NAME/display to modify display of any media bundle. 47 | 48 | For example, suppose you don't want to display the created at date for the image files in the media library. Below are the steps you need to follow: 49 | 50 | 1. Open admin/structure/media/manage/image/display 51 | 52 | 2. Click on 'Media Library' above the page breadcrumbs. 53 | ![](/modules/media/modify_image_display.png) 54 | 3. Change the format for the Created field to Hidden. 55 | 4. Now open the media library \(admin/content/media\) and the created at field for the images media items won't be visible. 56 | 57 | You can also rearrange the display of the field and change the formats on this page. 58 | -------------------------------------------------------------------------------- /modules/media/display_embed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/display_embed.png -------------------------------------------------------------------------------- /modules/media/embed_button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/embed_button.png -------------------------------------------------------------------------------- /modules/media/embed_button_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/embed_button_settings.png -------------------------------------------------------------------------------- /modules/media/embed_media.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/embed_media.png -------------------------------------------------------------------------------- /modules/media/embedding-media.md: -------------------------------------------------------------------------------- 1 | # Embedding media items 2 | 3 | By default the media module provides embedding functionality for all text format with a wysiwyg editor. Go to node/add and click on any type. In the text editor, an icon for media embed should now be visible. Refer to the below image if you aren't able to find the icon: 4 | 5 | ![](/modules/media/embed_button.png) 6 | 7 | In the modal which now opens, select the media item and click on 'Select media' button. 8 | 9 | ![](/modules/media/embed_media.png) 10 | 11 | In the next modal, choose the appropriate value for 'Display as' field \(Choose 'media library' if you are unsure\) and click on embed. 12 | 13 | ![](/modules/media/display_embed.png) 14 | 15 | ## Configuring the embed button 16 | 17 | **Modifying embed properties:** 18 | 19 | Suppose you want to allow only certain media bundles which can be embedded or if you want to restrict embedding to a particular display plugin, then you need to modify the embed button properties. Here are the steps you need to follow: 20 | 21 | 1. Go to Configuraton > Text editor embed buttons. 22 | 23 | 2. Click on edit on the media embed button. 24 | 25 | 3. Here you can change all the properties as required. 26 | 27 | 28 | ![](/modules/media/embed_button_settings.png) 29 | 30 | **Changing the position of embed button:** 31 | 32 | Suppose you want to change the placement of the media embed button in the editor, you can follow these steps: 33 | 34 | 1. Go to Configuration > Text format and editors 35 | 36 | 2. Click 'Configure' on the text format for which you want to change the position of the media embed button 37 | 38 | 3. In the Toolbar Configuration section, change the position of the embed buttons in the Active toolbar. 39 | 40 | 4. Click on 'Save Configuration' 41 | 42 | 43 | -------------------------------------------------------------------------------- /modules/media/entity_browsers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/entity_browsers.png -------------------------------------------------------------------------------- /modules/media/gallery_select_modal.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/gallery_select_modal.jpg -------------------------------------------------------------------------------- /modules/media/installation.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | Installation of the media module is really straight forward. All it requires is installation of the dependent modules and libraries. 4 | 5 | 1. Change your directory to the Drupal root directory. 6 | 2. Create a folder for libraries and enter into it by typing: 7 | ``` 8 | $ mkdir libraries 9 | $ cd libraries 10 | ``` 11 | 12 | 3. Download the required libraries from github by typing: 13 | 14 | ``` 15 | $ git clone https://github.com/dinbror/blazy.git 16 | $ git clone https://github.com/fengyuanchen/cropper.git 17 | $ git clone https://github.com/enyo/dropzone.git 18 | $ git clone https://github.com/kenwheeler/slick.git 19 | ``` 20 | 21 | 4. Navigate to the root directory and download the required modules 22 | ``` 23 | $ cd .. 24 | $ drush en dropzonejs entity_browser entity_embed image_widget_crop inline_entity_form media_entity_document media_entity_image media_entity_instagram media_entity_slideshow media_entity_twitter slick_media video_embed_field -y 25 | ``` 26 | 27 | 5. Navigate to the modules directory, clone the media module and enable it. 28 | 29 | 6. ``` 30 | $ cd modules 31 | $ git clone https://github.com/drupal-media/media.git 32 | $ drush en media -y 33 | ``` 34 | 35 | 36 | ## Basic Usage 37 | 38 | Now that the media module is enabled, you can start using its features. 39 | 40 | ### Global Media library 41 | 42 | Visit admin/content/media to access the global media library. Here you would be able to filter, sort and see through the media items uploaded by all the users of your site. You can easily add more items by clicking on the "Add media button" above the filters. 43 | 44 | ![](/modules/media/media_library.jpg) 45 | 46 | ### User media library 47 | 48 | To access the media items uploaded by any user, simply visit the url user/USER\_ID/media. For example, to access the media items by a user with user id 1, visit user/1/media. 49 | 50 | ![](/modules/media/user_media_library.jpg) 51 | 52 | 53 | 54 | 55 | 56 | -------------------------------------------------------------------------------- /modules/media/intro.md: -------------------------------------------------------------------------------- 1 | # Media 2 | 3 | The [Media](https://github.com/drupal-media/media) module is a full featured module which adds numerous media features to Drupal 8. It prepackages the configuration of other independent modules and provides a convenient starting point for users. 4 | 5 | Included features: 6 | 7 | * Media bundles for images, videos, gallery, document, Instagram and twitter, 8 | * Embedding of media items in the wysiwyg editor, 9 | * Global and user media library, 10 | * Cropping functionality for uploaded images. 11 | 12 | It requires the following modules to work: 13 | 14 | * [**Media Entity:**](../media_entity/intro.md) It is required by media entity sub-modules for the base media entity which is provided by this module. 15 | * [**Media Entity Image:**](../media_entity/image.md) It is required by the image media bundle. 16 | * [**Video Embed Field:**](https://www.drupal.org/project/video_embed_field) It is required by the video media bundle. 17 | * [**Media Entity Slideshow:**](../media_entity/slideshow.md) It is required by the gallery media bundle. 18 | * [**Media Entity Document:**](../media_entity/document.md) It is required by the document media bundle. 19 | * [**Media Entity Instagram:**](../media_entity/instagram.md) It is required by the Instagram media bundle. 20 | * [**Media Entity Twitter:**](../media_entity/twitter.md) It is required by the twitter media bundle. 21 | * [**Slick media:**](https://www.drupal.org/project/slick_media) It is required to display the gallery items using the [Slick carousel](http://kenwheeler.github.io/slick/). 22 | * [**Slick:**](https://www.drupal.org/project/slick) It is required by the slick media module. 23 | * [**Blazy:**](https://www.drupal.org/project/blazy) It is required by the slick module. 24 | * [**Entity Browser:**](../entity_browser/intro.md) It is required to provide entity browsers for the media files. 25 | * [**Dropzonejs:**](https://www.drupal.org/project/dropzonejs) It provides the drag and drop upload functionality of the media items using the [dropzone js library](http://www.dropzonejs.com/). 26 | * [**Image widget crop:**](https://www.drupal.org/project/image_widget_crop) It provides the cropping widget for the image files. Image media bundle files can be cropped using this module. 27 | * [**Crop:**](../crop/intro.md) It is required by the image\_widget\_crop module. 28 | * [**Entity Embed:**](https://www.drupal.org/project/entity_embed) It is required for the embedding of media items in the wysiwyg editor. 29 | * [**Embed:**](https://www.drupal.org/project/embed) It is required by the entity\_embed module. 30 | * [**Entity:**](https://www.drupal.org/project/entity) It is required by the media entity and its sub-modules. 31 | * [**Inline entity form:**](https://www.drupal.org/project/inline_entity_form) It is required by the Entity Browser IEF module. 32 | 33 | The media module also requires the following Javascript libraries: 34 | 35 | * [**Blazy:**](https://github.com/dinbror/blazy) It is required by the blazy module. 36 | * [**Cropper:**](https://github.com/fengyuanchen/cropper) It is required by the image\_widget\_crop module. 37 | * [**Dropzone:**](https://github.com/enyo/dropzone) It is required by the dropzonejs module. 38 | * [**Slick:**](https://github.com/kenwheeler/slick/) It is required by the slick module. 39 | 40 | ## Development 41 | 42 | We use Github pull request workflow. In order to contribute to the module please [create a pull request](https://github.com/drupal-media/media/compare). 43 | 44 | ## Maintainers 45 | 46 | * Janez Urevc \([@slashrsm](https://github.com/slashrsm)\) [https://drupal.org/user/744628](https://drupal.org/user/744628) 47 | * Tadej Baša \([@paranojik](https://github.com/paranojik)\) [https://www.drupal.org/u/paranojik](https://www.drupal.org/u/paranojik) 48 | * Vijay Nandwani \([@isthegeek](https://github.com/isthegeek)\) [https://www.drupal.org/u/royal121](https://www.drupal.org/u/royal121) 49 | 50 | -------------------------------------------------------------------------------- /modules/media/media-entity-browsers.md: -------------------------------------------------------------------------------- 1 | # Media entity browsers 2 | 3 | Media module uses [entity\_browser](/modules/entity_browser/intro.md) to manage media select modals. List of the available entity browsers can be found at admin/config/content/entity\_browser. By default the media module comes with three entity browsers: 4 | 5 | * **Gallery media library:** It provides an entity browser to select media items for creating a new gallery. 6 | * **Media embed:** It provides an entity browser for selecting media files to embed in the wysiwyg editor. 7 | * **Media library:** It provides a general entity browser with a media library which can be used for custom content types. 8 | 9 | ![](/modules/media/entity_browsers.png) 10 | 11 | ## Customizing entity browser 12 | 13 | **Adding more widgets to the entity browser** 14 | 15 | While selecting the media items for the gallery, an entity browser called gallery\_media\_library is used. Suppose in this modal you want to add a tab for uploading document files. You need to add an entity browser widget for it. You need to follow these steps: 16 | 17 | 1. Go to Configuration > Entity Browsers 18 | 2. Click on Edit for gallery\_media\_library 19 | 3. Go to the widgets section 20 | 4. In the 'add widget plugin' dropdown, select 'Entity form' 21 | 5. Fill in the appropriate details and click on Finish. 22 | 23 | ![](/modules/media/add_document_widget.png) 24 | 25 | -------------------------------------------------------------------------------- /modules/media/media_library.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/media_library.jpg -------------------------------------------------------------------------------- /modules/media/modify_image_display.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/modify_image_display.png -------------------------------------------------------------------------------- /modules/media/user_media_library.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media/user_media_library.jpg -------------------------------------------------------------------------------- /modules/media_entity/audio.md: -------------------------------------------------------------------------------- 1 | # Audio 2 | 3 | Implements media entity resource provider for local audio files. 4 | 5 | Project page: (https://drupal.org/project/media_entity_audio) 6 | -------------------------------------------------------------------------------- /modules/media_entity/auto_name.md: -------------------------------------------------------------------------------- 1 | ## Using the "automatic name" functionality for your media entities 2 | 3 | As with any entity in drupal, all media entities need to have a human-readable label attached to each instance created. The media_entity module autommatically creates a base-field for this, called "Media name". 4 | 5 | If you want your editors to be able to input / edit this value manually on each entity, you don't need to do anything, aside from probably configuring some of the field widget settings on the form, such as textfield size, placeholder, etc. These settings can be configured at the URL: ``` admin/structure/media/manage/{your-bundle-name}/form-display ``` 6 | 7 | ![Step 1](images/auto_name/auto_name_01.png) 8 | 9 | On the other hand, if you do not want to expose this to be created / modified for each entity, the module provides an "**automatic label**" functionality. This actually happens each time a media entity is being saved without a manual value introduced. In order to take advantage of this, just disable / hide the name field from the entity form configuration (on the same URL indicated above), and your entities will be created with a default name / label. 10 | 11 | Note that each type provider (media bundle) is requested to provide a sensible default name, according to each media type characteristics. For example, the "image" type provider will probably provide a default name based on the image filename, or the "twitter" bundle will provide a default name based on the tweet's author / tweet ID. 12 | 13 | If the provider type does not indicate any bundle-specific name to be used as default and a media 14 | entity is created without name, the media_entity module will use the following pattern: 15 | ``` media:{bundle_name}:{uuid} ``` 16 | -------------------------------------------------------------------------------- /modules/media_entity/basic_usage.md: -------------------------------------------------------------------------------- 1 | # Basic usage 2 | 3 | 4 | 5 | ## Creating media items manually 6 | 7 | In order to manually create some media entities go to ``` /media/add ``` and choose the bundle you are interested in. 8 | 9 | You will then see the entity form, as defined in ``` /admin/structure/media/manage/{bundle-name}/form-display ```. Fill up all the fields and save the entity. 10 | 11 | 12 | ## Using the pre-defined media gallery 13 | 14 | The **Media entity** module comes with a pre-defined list of media items created on your site. You can find it on the URL ``` /admin/content/media ```. 15 | 16 | ![](images/media_gallery.png) 17 | 18 | Like many other administrative lists of content on your site, this page is a view and can be modified going to the Views administration page, under Structure -> Views. 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /modules/media_entity/create_bundle.md: -------------------------------------------------------------------------------- 1 | ## Creating a Media bundle 2 | * On `admin/structure` choose **Media bundles**. 3 | 4 | ![Step 1](images/create_bundle/step_1.png) 5 | * Click on **+ Add media bundle**. 6 | 7 | ![Step 2](images/create_bundle/step_2.png) 8 | * Fill *Label*, *Description* and *Type provider fields* for your media bundle and click **Save media bundle**. 9 | 10 | NOTE: if you have not installed any other [provider module](type_providers.md) yet, the only bundle you will be able to create is the "**Generic media**" bundle, with no media-specific functionality. 11 | 12 | ![Step 3](images/create_bundle/step_3.png) 13 | 14 | * Once created, you can use your bundle as if it were a new "content type", adding fields to it, managing the form or the view display, etc. 15 | 16 | ## Bundle settings specific to each provider 17 | 18 | Please note that each provider will probably allow you to define some bundle-specific settings, such as a source field for your media, some metadata mapping to some custom fields, etc. You will find more information about the provider-specific settings on each submodule's chapter on this manual. 19 | -------------------------------------------------------------------------------- /modules/media_entity/create_view_mode.md: -------------------------------------------------------------------------------- 1 | # Creating a new viewmode 2 | 3 | As with any other entity in drupal, when it comes to render the rendering it in different contexts, you might want to have specific viewmodes / form modes available. 4 | 5 | To create a new viewmode, go to Structure -> Display modes -> View modes -> Add new view mode (or visit the URL: ``` /admin/structure/display-modes/view/add ``` ) 6 | 7 | Select "Media" and then give a name to your new viewmode. 8 | 9 | ![Step 1](images/create_viewmode/viewmode_01.png) 10 | 11 | Go back to Structure -> Media bundles, select "**Manage display**" on your custom bundle, and then make sure you enable the new viewmode in "Custom display settings", at the bottom of the page, and click "Save". 12 | 13 | ![Step 2](images/create_viewmode/viewmode_02.png) 14 | -------------------------------------------------------------------------------- /modules/media_entity/developers_documentation.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written / expanded. 2 | 3 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. -------------------------------------------------------------------------------- /modules/media_entity/embeddable_video.md: -------------------------------------------------------------------------------- 1 | # Embeddable videos 2 | 3 | Embeddable video support is provided by video_embed_field. Install the 4 | video_embed_media sub-module to enable the integration. This will add a new 5 | media provider, tailored for storing videos embedded from 3rd party video 6 | hosting websites. 7 | 8 | Project page: (https://drupal.org/project/video_embed_field) 9 | 10 | ## Supported video providers 11 | 12 | This module currently support the following video sources out of the box and 13 | provided by contrib: 14 | 15 | - YouTube and Vimeo (packaged with the module) 16 | - Facebook 17 | - Vine 18 | - Dailymotion 19 | - Instagram 20 | - Ted 21 | - AOL 22 | - Metacafe 23 | - MySpace 24 | - Rutube 25 | - Youku 26 | - Dreambroker 27 | - Vidyard 28 | - Brightcove 29 | 30 | ## Upgrading from media_entity_embeddable_video 31 | 32 | Make sure you take a backup of your database and test upgrading locally before 33 | doing anything in production. 34 | 35 | If you would like to move from media_entity_embeddable_video, you can do so by 36 | installing video_embed_media (see above). This module will automatically 37 | convert any of the legacy media types to the one provided by video_embed_field. 38 | 39 | After this is complete and you've verified everything works as expected, it's 40 | safe to uninstall media_entity_embeddable_video. 41 | -------------------------------------------------------------------------------- /modules/media_entity/image.md: -------------------------------------------------------------------------------- 1 | # Image 2 | 3 | Implements media entity resource provider for local images. 4 | 5 | Project page: (https://drupal.org/project/media_entity_image) 6 | 7 | ## Usage 8 | 9 | You can find a video tutorial about using Media Entity Image by Marcos Cano at [https://www.youtube.com/watch?v=vOv8pmv5i2U](https://www.youtube.com/watch?v=vOv8pmv5i2U) 10 | 11 | ## Other extensions 12 | 13 | - [Entity browser](../entity_browser/intro.md): Provides entity browser 14 | widget that supports uploading [Media entity images](https://drupal.org/project/media_entity_image). 15 | - [DropzoneJS](https://drupal.org/project/dropzonejs): Extends entity browser [image 16 | upload widget](https://drupal.org/project/media_entity_image) with [DropzoneJS 17 | upload library](http://www.dropzonejs.com). 18 | -------------------------------------------------------------------------------- /modules/media_entity/images/auto_name/auto_name_01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/auto_name/auto_name_01.png -------------------------------------------------------------------------------- /modules/media_entity/images/create_bundle/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/create_bundle/step_1.png -------------------------------------------------------------------------------- /modules/media_entity/images/create_bundle/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/create_bundle/step_2.png -------------------------------------------------------------------------------- /modules/media_entity/images/create_bundle/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/create_bundle/step_3.png -------------------------------------------------------------------------------- /modules/media_entity/images/create_viewmode/viewmode_01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/create_viewmode/viewmode_01.png -------------------------------------------------------------------------------- /modules/media_entity/images/create_viewmode/viewmode_02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/create_viewmode/viewmode_02.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_1.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_10.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_11.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_12.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_13.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_14.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_2.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_3.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_4.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_5.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_6.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_7.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_8.png -------------------------------------------------------------------------------- /modules/media_entity/images/instagram/step_9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/instagram/step_9.png -------------------------------------------------------------------------------- /modules/media_entity/images/media_gallery.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/media_gallery.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_1.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_10.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_11.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_12.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_13.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_14.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_15.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_16.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_17.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_2.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_3.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_4.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_5.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_6.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_7.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_8.png -------------------------------------------------------------------------------- /modules/media_entity/images/twitter/step_9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drupal-media/d8-guide/af036de0fdc16f6909be0eb98995d50c1eb7a415/modules/media_entity/images/twitter/step_9.png -------------------------------------------------------------------------------- /modules/media_entity/instagram.md: -------------------------------------------------------------------------------- 1 | # Instagram 2 | 3 | [Media Entity Instagram](https://drupal.org/project/media_entity_instagram) implements media entity resource provider for Instagram photos and videos. 4 | 5 | ## Requirements 6 | 7 | 1. [Media Entity](https://www.drupal.org/project/media_entity) 8 | 9 | ## Installation 10 | 11 | 1. Download [Media Entity](https://www.drupal.org/project/media_entity) from Drupal.org. 12 | 2. Download [Media Entity Instagram](https://drupal.org/project/media_entity_instagram) from Drupal.org. 13 | 3. Install both Media Entity Instagram and Media Entity in the [usual way](https://www.drupal.org/documentation/install/modules-themes/modules-8). 14 | 15 | ## Usage 16 | 17 | 1. Follow the instructions about [creating a media bundle](create_bundle.md) 18 | 19 | 2. Create an Instagram link field on a Media bundle: 20 | * On media bundles overview page choose **Manage fields** on created **Instagram** bundle. 21 | 22 | ![Step 1](images/instagram/step_1.png) 23 | * Click on **+ Add field**. For a storage type choose **Link**, fill a *Label* field and click **Save and continue**. 24 | 25 | ![Step 2](images/instagram/step_2.png) 26 | * Return to the bundle configuration and set "Field with source information" to use this new field. 27 | 28 | ![Step 3](images/instagram/step_3.png) 29 | * On media bundles overview page choose **Manage display** on created **Instagram** bundle and select **Instagram embed** for the newly created field (*Instagram link* in our case) and then **Save**. 30 | 31 | ![Step 4](images/instagram/step_4.png) 32 | 3. Create a Media entity: 33 | * On `admin/content/media` click on **+ Add media**. 34 | 35 | ![Step 5](images/instagram/step_5.png) 36 | * Fill *Media name*, *Instagram link* fields similarly as it is displayed below and click **Save**. 37 | 38 | ![Step 6](images/instagram/step_6.png) 39 | 40 | **Note:** Validation will fail if incorrect Instagram URL is provided and this also works with embed codes and plaintext fields, not just link field. 41 | * The created Instagram media entity is saved. 42 | 43 | ![Step 7](images/instagram/step_7.png) 44 | 4. Add an entity (media) reference field on a content type: 45 | * On desired content type (i.e. Article), on `admin/structure/types`, click on **Manage fields**. 46 | 47 | ![Step 8](images/instagram/step_8.png) 48 | * Click on **+ Add field**. 49 | 50 | ![Step 9](images/instagram/step_9.png) 51 | * From **References** menu choose **Other**, fill the *Label* and click **Save and continue**. 52 | 53 | ![Step 10](images/instagram/step_10.png) 54 | * Choose **Media** for **Type of item to reference** and click **Save field settings**. 55 | 56 | ![Step 11](images/instagram/step_11.png) 57 | * Select **Instagram** bundle in **Reference type section** and click **Save settings**. 58 | 59 | ![Step 12](images/instagram/step_12.png) 60 | 5. Open Manage display of your content type (in our case *Article*): 61 | * Select **Rendered entity** for the newly created field (*Entity media reference*) and then **Save**. 62 | 63 | ![Step 13](images/instagram/step_13.png) 64 | 6. Create a new article with embedded Instagram post: 65 | * For an **Instagram reference** field choose a created entity Instagram entity. 66 | 67 | ![Step 14](images/instagram/step_14.png) 68 | * The Instagram posts are displayed on the saved article page. 69 | 70 | ## Maintainers 71 | - Janez Urevc ([@slashrsm](https://github.com/slashrsm)) (https://drupal.org/u/slashrsm) 72 | - Malina Randrianavony ([@designesse](https://github.com/designesse/)) (https://www.drupal.org/u/designesse) 73 | 74 | ## Get in touch 75 | - http://groups.drupal.org/media 76 | - IRC: #drupal-media @ Freenode 77 | -------------------------------------------------------------------------------- /modules/media_entity/intro.md: -------------------------------------------------------------------------------- 1 | # About Media entity 2 | 3 | ## Basic concepts 4 | 5 | Media entity provides a 'base' entity for media. This is a very basic entity which can reference to all kinds of media-objects (local files, YouTube videos, Tweets, Instagram photos, ...). Media entity provides a relation between Drupal and the media resource. You can reference to/use this entity within any other Drupal entity. 6 | 7 | This module attempts to provide the base storage component for the Drupal 8 media ecosystem. 8 | 9 | Once installed, a new entity type will be available (type: "media"). 10 | Please note that the different "types" of entities (known as "bundles") will be provided by other contrib modules (see further on this manual). 11 | The main media_entity module only defines the base API for other modules to build their own bundle-specific logic on the top of it. 12 | 13 | Project page: (https://drupal.org/project/media_entity) 14 | 15 | ## Dependencies 16 | 17 | - Drupal core (>= 8.1.0) 18 | - [Entity](https://drupal.org/project/entity) (>= 8.x-1.0-alpha3) 19 | 20 | ## Maintainers 21 | - Janez Urevc ([@slashrsm](https://github.com/slashrsm)) (https://drupal.org/u/slashrsm) 22 | - Primož Hmeljak ([@primsi](https://github.com/primsi)) (https://drupal.org/u/primsi) 23 | - Nguyễn Hải Nam (@jcisio) (https://drupal.org/u/jcisio) 24 | - Boris Gordon (@boztek) (https://drupal.org/u/boztek) 25 | 26 | ## Get in touch 27 | - (http://groups.drupal.org/media) 28 | - IRC: #drupal-media @ Freenode 29 | -------------------------------------------------------------------------------- /modules/media_entity/metadata_handling.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written / expanded. 2 | 3 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 4 | -------------------------------------------------------------------------------- /modules/media_entity/slideshow.md: -------------------------------------------------------------------------------- 1 | # Slideshow 2 | 3 | Implements media entity resource provider for slideshows of images, videos, ... 4 | 5 | Project page: (https://drupal.org/project/media_entity_slideshow) 6 | -------------------------------------------------------------------------------- /modules/media_entity/twitter.md: -------------------------------------------------------------------------------- 1 | # Media Entity Twitter 2 | 3 | [Media Entity Twitter](https://www.drupal.org/project/media_entity_twitter) provides Twitter integration for [Media entity module](https://www.drupal.org/project/media_entity) (i.e. media type provider plugin). 4 | 5 | ## Requirements 6 | 7 | 1. [Media Entity](https://www.drupal.org/project/media_entity) 8 | 9 | ## Installation 10 | 11 | 1. Download [Media Entity](https://www.drupal.org/node/2099473/release) from Drupal.org. 12 | 2. Download [Media Entity Twitter](https://www.drupal.org/node/2352799/release) from Drupal.org. 13 | 3. Install both Media Entity and Media Entity Twitter in the [usual way](https://www.drupal.org/documentation/install/modules-themes/modules-8). 14 | 15 | ## Usage 16 | 17 | ### Without Twitter API 18 | 19 | If you need just to embembed tweets you can use this module wihout using Twitter's API. That will give you access to the fields available from the url/embed code: id and user. 20 | 21 | 1. Follow the instructions about [creating a media bundle](create_bundle.md) 22 | 23 | 2. Create a Twitter link field on a Media bundle 24 | * On media bundles overview page choose **Manage fields** on created **Twitter** bundle. 25 | 26 | ![Step 4](images/twitter/step_4.png) 27 | * Click on **+ Add field**. For a storage type choose **Link** (for URL) or **Text (plain)** (for embed code), fill a *Label* field and click **Save and continue**. 28 | 29 | ![Step 5](images/twitter/step_5.png) 30 | 3. Return to the bundle configuration and set "Field with source information" to use this new field. 31 | 32 | ![Step 6](images/twitter/step_6.png) 33 | 4. Create a Media entity 34 | * On `admin/content/media` click on **+ Add media** 35 | 36 | ![Step 7](images/twitter/step_7.png) 37 | * Fill *Media name* and *Twitter url link* fields similarly as it is displayed below and click **Save**. 38 | 39 | ![Step 8](images/twitter/step_8.png) 40 | * The created Twitter media entity is saved. 41 | 42 | ![Step 9](images/twitter/step_9.png) 43 | 5. Add an entity (media) reference field on a content type 44 | * On desired content type (i.e. Article), on `admin/structure/types`, click on **Manage fields** 45 | 46 | ![Step 10](images/twitter/step_10.png) 47 | * Click on **+ Add field** 48 | 49 | ![Step 11](images/twitter/step_11.png) 50 | * From **References** menu choose **Other**, fill the *Label* and click **Save and continue** 51 | 52 | ![Step 12](images/twitter/step_12.png) 53 | * Choose **Media** for **Type of item to reference** and click **Save field settings** 54 | 55 | ![Step 13](images/twitter/step_13.png) 56 | * Select **Twitter** bundle in **Reference type section** and click **Save settings** 57 | 58 | ![Step 14](images/twitter/step_14.png) 59 | 9. Create a new article with embedded Twitter posts 60 | * For an **Twitter reference** field choose a created entity Twitter entity. 61 | 62 | ![Step 15](images/twitter/step_15.png) 63 | * The Twitter post is displayed on the saved article page. 64 | 65 | ### With Twitter API 66 | 67 | If you need to get other fields, you will need to use Twitter's API. 68 | 69 | **IMPORTANT:** beware that there is limit on the number of request that can be made for free. [Read more](https://dev.twitter.com/rest/public) 70 | 71 | To get this working follow the steps below: 72 | 73 | 1. Download and enable [composer_manager](https://www.drupal.org/project/composer_manager) 74 | 2. Run the module's init.php script on the command line (`php scripts/init.php` from inside the composer_manager module directory) 75 | 3. Run `composer drupal-update` from the root of your Drupal directory 76 | 4. Create a twitter app on the twitter [developer site](https://dev.twitter.com/apps/) 77 | 5. Enable read access for your twitter app 78 | 6. Grab your access tokens from the twitter developer site 79 | 7. In your Twitter bundle configuration set "Whether to use Twitter api to fetch tweets or not" to "Yes"" and paste in the "Consumer key", "Consumer secret", "Oauth access token" and the "Oauth access token secret". 80 | 81 | ![Step 16](images/twitter/step_16.png) 82 | 8. If you want to store the fields that are retrived from Twitter you should create appropriate fields on the created media bundle (image, content and retweet_count by repeating **Step 2** from "Without Twitter API" section and map these fields to the fields provided by Twitter.php. 83 | 84 | **NOTE:** At the moment there is no GUI for that, so the only method of doing that for now is via CMI. 85 | 86 | This whould be an example of that (the field_map section): 87 | 88 | ``` 89 | uuid: 834c7564-894f-4d5e-9808-8b1785322099 90 | langcode: en 91 | status: true 92 | dependencies: 93 | module: 94 | - media_entity_twitter 95 | id: twitter 96 | label: Twitter 97 | description: 'The media bundle for twitter posts.' 98 | type: twitter 99 | type_configuration: 100 | source_field: field_twitter_url_link 101 | use_twitter_api: '1' 102 | consumer_key: YOUR_CONSUMER_KEY 103 | consumer_secret: YOUR_CONSUMER_SECRET 104 | oauth_access_token: YOUR_OAUTH_ACCESS_TOKEN 105 | oauth_access_token_secret: YOUR_OAUTH_ACCESS_TOKEN_SECRET 106 | field_map: 107 | source: field_twitter_url_link 108 | content: field_tweet_content 109 | image: field_tweet_image 110 | retweet_count: field_tweet_count 111 | ``` 112 | 9. After you add fields on your media bundle (in this example these fields are: field_tweet_content, field_tweet_image and field_tweet_count) and import your yml structure (on `admin/config/development/configuration/single/import`) to correspond to your media bundle created in **Step 1** in "Without Twitter API" section, only thing you need to do is to fill **Twitter URL Link** field in your Media entity created in **Step 4** in "Without Twitter API" section and all the other fields will be automatically filled with proper values when saving Media entity. 113 | 114 | ![Step 17](images/twitter/step_17.png) 115 | 116 | ## Sponsors 117 | 118 | - [www.examiner.com](http://www.examiner.com/) 119 | 120 | ## Maintainers 121 | - Janez Urevc ([@slashrsm](https://github.com/slashrsm)) (https://drupal.org/u/slashrsm) 122 | - Primož Hmeljak ([@primsi](https://github.com/primsi)) (https://drupal.org/u/primsi) 123 | 124 | ## Get in touch 125 | - http://groups.drupal.org/media 126 | - IRC: #drupal-media @ Freenode 127 | -------------------------------------------------------------------------------- /modules/media_entity/type_providers.md: -------------------------------------------------------------------------------- 1 | # Media provider modules 2 | 3 | There are already several media provider modules that extend the 4 | functionality of Media entity and provide specific bundles: 5 | 6 | - [Image](image.md) 7 | - [Audio](audio.md) 8 | - [Slideshow](slideshow.md) 9 | - [Video embed field](video_embed_field.md) 10 | - [Twitter](twitter.md) 11 | - [Instagram](instagram.md) 12 | - [Document](document.md) 13 | - [Slideshare](slideshare.md) 14 | - [Video (local)](video_local.md) 15 | - [Tumblr](tumblr.md) 16 | - [Facebook](facebook.md) 17 | - [Audio embed field (sandbox)](audio_embed_field.md) 18 | 19 | 20 | ## Other modules that integrate with media entity 21 | 22 | - [Entity browser](https://drupal.org/project/entity_browser): Provides entity browser 23 | widget that supports uploading [Media entity images](https://drupal.org/project/media_entity_image). 24 | - [DropzoneJS](https://drupal.org/project/dropzonejs): Extends entity browser [image 25 | upload widget](https://drupal.org/project/media_entity_image) with [DropzoneJS 26 | upload library](http://www.dropzonejs.com). 27 | - [Slick media](https://drupal.org/project/slick_media): Provides integration 28 | between [Slick carousel](https://drupal.org/project/slick) and Media entity. Slick media allows richer slideshows/carousel 29 | with a mix of text, image and video. 30 | - [Brightcove](https://github.com/dawehner/media_entity_brightcove) 31 | 32 | -------------------------------------------------------------------------------- /modules/media_pinkeye/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /modules/url_embed/intro.md: -------------------------------------------------------------------------------- 1 | FPO/TBA 2 | 3 | This section of the Media Guide needs to be written. 4 | 5 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. 6 | 7 | -------------------------------------------------------------------------------- /roadmap.md: -------------------------------------------------------------------------------- 1 | # Drupal Media Roadmap 2 | 3 | This section of the Guide outlined the strategy behind Media in Drupal 8, and our the goals and milestones on our roadmap. 4 | 5 | ## D8 Strategy 6 | 7 | Media is a tough problem to solve in a CMS\/Framework like Drupal. In prior versions of Drupal, our solution relied on an overall Media Module that provided most of the functionality, which was then supported by several sub-modules or alternative solutions \(see the the [D7 Background](background.md) section for a full summary\). 8 | 9 | For Drupal 8, the various contributors have worked collaborative to take different approach that separates Media functionality into several independent modules that can be used together based as appropriate. There is an overall module called [Media](/modules/media/intro.md) that prepackages the configuration of certain of the above independent modules for a convenient starting point. 10 | 11 | Apart from delivering great functionality, this strategy for D8 aims to allow for more collaboration, a faster release cycle, and greater flexibility in selecting which functionality\/modules are needed for a given project. Overall, this should make Media in Drupal easier to use, both for developers, site builders, as well as content editors and other end users. 12 | 13 | ## Long Term Goals 14 | 15 | The Drupal Media Team has set an ambitious goal of making Drupal the best media handling solution available in any web framework. 16 | 17 | If we succeed in accomplishing this goal, ideally the approach and lessons learned can be useful for other open source web frameworks too \(such as [Wordpress](http://wordpress.org), [Django](https://www.djangoproject.com/), [Phoenix](http://www.phoenixframework.org), and others\). 18 | 19 | We still have a long way to go to achieve that goal. However, the plans below will help you to understand the roadmap that we're following to achieve that goal, and the [Status](status.md) section of this Guide will keep you up-to-date on our progress along that roadmap. 20 | 21 | ## Milestones 22 | 23 | ### Plans for Media in D8.0 \(RC.1\) 24 | 25 | _TBA\/FPO - Transfer and udpate content from Hackpad roadmap_ 26 | 27 | ### Plans for Media in D8.x \(or RC.x D9\) 28 | 29 | _TBA\/FPO - Transfer and update content from Hackpad roadmap_ 30 | 31 | -------------------------------------------------------------------------------- /status.md: -------------------------------------------------------------------------------- 1 | This section of the Media Guide needs to be written. 2 | 3 | See our [Contributing](contributing.md) section of the Guide to find out how to get involved and help out. --------------------------------------------------------------------------------