Upgrade Your Drupal Skills
We trained 1,000+ Drupal Developers over the last decade.
See Advanced Courses NAH, I know EnoughAt Studio.gd we love the Drupal ecosystem and it became very important to us to give back and participate.
Today we're proud to announce a new module that we hope will help you !
Inline Entity Display module will help you handle the display of referenced entity fields directly in the parent entity.
For exemple if you reference a taxomony "Tags" to an Article node, you will be able directly in the manage display of the article to display tags' fields. It can become very usefull with more complex referenced entity like field collection for exemple.
VOIR LE MODULE : https://www.drupal.org/project/inline_entity_display
Features
- You can control, for each compatible reference field instances, if the fields from the referenced entities would be available as extra fields. Disabled by default.
- You can manage the visibility of the referenced entities fields on the manage display form. Hidden by default.
- View modes are added to represent this context and manage custom display settings for the referenced entities fields in this context {entity_type}_{view_mode} Example: "Node: Teaser" is used to render referenced entities fields, when you reference an entity into a node, and you view this node as a teaser if there are no custom settings for this view mode, fields are rendered using the default view mode settings.
- Extra data attributes are added on the default fields markup, so the field of the same entity can be identified.
Compatible with Field group on manage display form.
Compatible with Display Suite layouts on manage display form.
Requirements
- Entity API
- One of the compatible reference fields module.
Tutorials
simplytest.me/project/inline_entity_display/7.x-1.x
The simplytest.me install of this module will come automatically with these modules: entity_reference, field_collection, field_group, display suite.
VOIR LE MODULE : https://www.drupal.org/project/inline_entity_display
We are currently developping a similar module for Drupal 8 but more powerful and more flexible, Stay tuned !
Ressources
Migrate in Drupal 8
Migrate is now included in the Drupal core for making the upgrade path from 6.x and 7.x versions to Drupal 8.
Drupal 8 has two new modules :
Migrate: « Handles migrations »
Migrate Drupal : « Contains migrations from older Drupal versions. »
None of these module have a User Interface.
« Migrate » contains the core framework classes, the destination, source and process plugins schemas and definitions, and at last the migration config entity schema and definition.
« Migrate Drupal » contains implementations of destination, sources and process plugins for Drupal 6 and 7 you can use it or extend it, it's ready to use. But this module doesn't contain the configuration to migrate all you datas from your older Drupal site to Drupal 8.
The core provides templates of migration configuration entity that are located under each module of the core that needs one, under a folder named 'migration_templates' to find all the templates you can use this command in your Drupal 8 site:
To make a Drupal core to core migration, you will find all the infos here : https://www.Drupal.org/node/2257723 there is an UI in progress for upgrading.
A migration framework
Let have a look at each big piece of the migration framework :
Source plugins
Drupal provides an interface and base classes for the migration source plugin :
- SqlBase : Base class for SQL source, you need to extend this class to use it in your migration.
- SourcePluginBase : Base class for every custom source plugin.
- MenuLink: For D6/D7 menu links.
- EmptySource (id:empty): Plugin source that returns an empty row.
- ...
Process plugins
There is the equivalent of the D7 MigrateFieldHandler but this is not reduced to fields or to a particular field type.
Its purpose is to transform a raw value into something acceptable by your new site schema.
The method transform() of the plugin is in charge of transforming your $value or skipping the entire row if needed.
If the source property has multiple values, the transform() will happen on each one.
Drupal provides migration process plugin into each module of the core that needs it (for the core upgrade),
To find out which one and where it is located you can use this command :
Destination plugins
Destination plugins are the classes that handle where your data are saved in the new Drupal 8 sites schemas.
Drupal provides a lot of useful destination classes :
- DestinationBase : Base class for migrate destination classes.
- Entity (id: entity) : Base class for entity destinations.
- Config (id: config) : Class for importing configuration entities.
- EntityBaseFieldOverride (id: entity:base_field_override): Class for importing base field.
- EntityConfigBase : Base class for importing configuration entities.
- EntityImageStyle (id: entity:image_style): Class for importing image_style.
- EntityContentBase (id: entity:%entity_type): The destination class for all content entities lacking a specific class.
- EntityNodeType: (id: entity:node_type): A class for migrate node type.
- EntityFile (id: entity:file): Class for migrate files.
- EntityFieldInstance: Class for migrate field instance.
- EntityFieldStorageConfig: Class for migrate field storage.
- EntityRevision, EntityViewMode, EntityUser, Book...
- And so more…
Builder plugins:
"Builder plugins implement custom logic to generate migration entities from migration templates. For example, a migration may need to be customized based on the data that is present in the source database; such customization is implemented by builders." - doc API
This is used in the user module, the builder create a migration configuration entity based on a migration template and then add fields mapping to the process, based on the data in the source database. (@see /Drupal/user/Plugin/migrate/builder/d7/User)
Id map plugins:
"It creates one map and one message table per migration entity to store the relevant information." - doc API
This is where rollback, update and the map creation are handled.
Drupal provides the Sql plugin (@see /Drupal/migrate/Plugin/migrate/id_map/Sql) based on the core base class PluginBase.
And we are talking only about core from the beginning.
All the examples (That means docs for devs) are in core !
About now :
While there *almost* a simple UI to use migration in Drupal 8 for Drupal to Drupal, Migrate can be used for every kind of data input. The work is in progess for http://Drupal.org/project/migrate_plus to bring an UI and more source plugins, process plugins and examples. There already is the CSV source plugin and a pending patch for the code example. The primary goal of « migrate plus » is to have all the features (UI, Sources, Destinations.. ) of the Drupal 7 version.
Concrete migration
(migration with Drupal 8 are made easy)
I need to migrate some content with image, attached files and categories from custom tables in an external SQL database to Drupal.
To begin shortly :
- Drush 8 (dev master) and console installed.
- Create the custom module (in the code, I assume the module name is “example_migrate”):
$ Drupal generate:module
or create the module by yourself, you only need the info.yml file. - Activate migrate and migrate_plus tools
$ Drupal module:install migrate_tools
or
$ drush en migrate_tools - What we have in Drupal for the code example :
- a taxonomy vocabulary : ‘example_content_category’
- a content type ‘article’
- some fields: body, field_image, field_attached_files, field_category
- Define in settings.php, the connexion to your external database:
We are going to tell migrate source to use this database target. It happens in each migration configuration file, it’s a configuration property used by the SqlBase source plugin:
This is one of the reasons SqlBase has a wrapper for select query and you need to call it in your source plugin, like $this->select(), instead of building the query with bare hands.
N.B. Each time you add a custom yml file in your custom module you need to uninstall/reinstall the module for the config/install files to imports. In order to avoid that, you can import a single migration config file by copy/paste in the admin/config configuration synchronisation section.
The File migration
The content has images and files to migrate, I suppose in this example that the source database has a unique id for each file in a specific table that hold the file path to migrate.
We need a migration for the file to a Drupal 8 file entity, we write the source plugin for the file migration:
File: src/Plugin/migrate/source/ExampleFile.php
We have the source class and our source fields and each row generate a path to the file on my local disk.
But we need to transform our external file path to a local Drupal public file system URI, for that we need a process plugin. In our case the process plugin will take the external filepath and filename as arguments and return the new Drupal URI.
File: src/Plugin/migrate/process/ExampleFileUri.php
We need another process plugin to transform our source date values to timestamp (created, changed), as the date format is the same across the source database, this plugin will be reused in the content migration for the same purpose:
File: src/Plugin/migrate/process/ExampleDate.php
For the destination we use the core plugin: entity:file.
Now we have to define our migration config entity file, this is where the source, destination and process (field mappings) are defined:
File: config/install/migrate.migration.example_file.yml
We are done for the file migration, you can execute it with the migrate_tools (of the migrate_plus project) drush command:
The Term migration
The content has categories to migrate.
We need to import them as taxonomy term, in this example I suppose the categories didn't have unique ids, it is just a column of the article table with the category name…
First we create the source :
File: src/Plugin/migrate/source/ExampleCategory.php
And we can now create the migration config entity file :
File: config/install/migrate.migration.example_category.yml
This is done, to execute it :
The Content migration
The content from the source has an html content, raw excerpt, image, attached files, categories and the creation/updated date in the format Y-m-d H:i:s
We create the source plugin:
File: src/Plugin/migrate/source/ExampleContent.php
Now we can create the content migration config entity file :
File: config/install/migrate.migration.example_content.yml
Finally, execute it :
Group the migration
Thanks to migrate_plus, you can specify a migration group for your migration.
You need a to create a config entity for that :
File: config/install/migrate_plus.migration_group.example.yml
Then in your migration config yaml file, be sure to have the line migration_group next to the label:
So you can use the command to run the migration together, and the order of execution will depend on the migration dependencies:
I hope that you enjoyed our article.
Best regards,
For the example we are going to implement an area that will present some links and text in a custom way, not sure if it's really usefull, but that not the point of this article.
The Plugin system
For the first post on the plugins I will introduce briefly on the concept. For those that already been using Ctools plugins system, you already now about the plugin system purposes.
For those who doesn't know about it, the plugin system is a way to let other module implements her own use case for an existing features, think of Field formatter : provide your own render array for a particular field display, or Widget : provide your own form element for a particular field type, etc...
The plugin system has three base elements :
Plugin Types
The plugin type is the central controlling class that defines how the plugins of this type will be discovered and instantiated. The type will describe the central purpose of all plugins of that type; e.g. cache backends, image actions, blocks, etc.
Plugin Discovery
Plugin Discovery is the process of finding plugins within the available code base that qualify for use within this particular plugin type's use case.
Plugin Factory
The Factory is responsible for instantiating the specific plugin(s) chosen for a given use case.
Detailled informations : https://www.drupal.org/node/1637730
In our case Views is responsible of that implementations so we are not going further on that, let see now how to implement a plugin definition.
The Plugin definitions
The existing documentation on the plugin definitions are a little abstract for now to understand how it really works (https://www.drupal.org/node/1653532).
You have to understand simply that a Plugin in most case is a Class implementation, namespaced within the namespace of the plugin type, in our example this is : \Drupal\module_name\Plugin\views\area
So if I implement a custom views area Plugin in my module the class will be located under the location module_name/src/Plugin/views/area/MyAreaHandler.php
To know where to implement a plugin definition for a plugin type, you can in most case look at module docs, or directly in the source code of the module (looking at an example of a definition will be enough)
In most cases, the modules that implement a Plugin type will provide a base class for the plugins definitions, in our example views area provide a base class : \Drupal\views\Plugin\views\area\AreaPluginBase
Drupal provide also a base class, if you implement a custom Plugin type, for the Plugin definition : \Drupal\Component\Plugin\PluginBase
Your custom plugin definition class must also have annotation metadata, that is defined by the module that implement the plugin type, in our example : \Drupal\views\Annotation\ViewsArea
In the case of views you will also need to implement the hook_views_data() into module_name.views.inc file, there you will inform views about the name and metadata of your Area handler.
Hands on implementation
So we have a custom module let's call it module_name for the example :)
We will create the class that implements our plugin definition and we are gonna give it this Plugin ID : my_custom_site_area.
We save this file into module_name/src/Plugin/views/area/MyCustomSiteArea.php
Now we just have to implements the hook_views_data() and yes this is the end, you can use your awesome views area handler into any view and any area.
Define this hook into the file : module_name/module_name.views.inc
There is three types of configuration data :
The Simple Configuration API
-
Used to store unique configuration object.
-
Are namespaced by the module_name.
-
Can contain a list of structured variables (string, int, array, ..)
-
Default values can be found in Yaml : config/install/module_name.config_object_name.yml
-
Have a schema defined in config/schema/module_name.schema.yml
Code example :
The States
-
Not exportable, simple value that hardly depend of the environment.
-
Value can differ between environment (e.g. last_cron, maintenance_mode have different value on your local and on the production site)
The Entity Configuration API
-
Configuration object that can be multiple (e.g. views, image style, ckeditor profile, ...).
-
New Configuration type can be defined in custom module.
-
Have a defined schema in Yaml.
-
Not fieldable.
-
Values can be exported and stored as Yaml, can be stored by modules in config/install
Code example :
https://www.drupal.org/node/1809494
Store configuration object in the module :
Config object (not states) can be stored in a module and imported during the install process of the modules.
To export a config object in a module you can use the configuration synchronisation UI at /admin/config/development/configuration/single/export
Select the configuration object type, then the object, copy the content and store it in your custom module config/install directory following the name convention that is provided below the textarea.
You can also use the features module that is now a simple configuration packager.
If after the install of the module, you want to update the config object, you can use the following drush command :
Configuration override system
Remember the variable $conf in settings.php in D6/D7 for overriding variables.
In D8, you can also override variable from the configuration API:
You can also do overrides at runtime.
Example: getting a value in a specific languages :
Drupal provide a storage for override an module can specify her own way of override, for deeper informations look at :
https://www.drupal.org/node/1928898
Configuration schema
The config object of Config API and of the configuration entity API have attached schema defined in module_name/config/install/module_name.schema.yml
These schema are not mandatory, but if you want to have translatable strings, nor form configuration / consistent export, you must take the time to implement the schema for your configuration object. However if you don't want to, you can just implement the toArray() method in your entity config object class.
Example, docs and informations : https://www.drupal.org/node/1905070
Configuration dependencies calculation
Default is in the .info of the module that define the config object like in D6/D7
But config entity can implements calculateDependencies() method to provide dynamic dependencies depending on config entity values.
Think of Config entity that store field display information for content entities specific view modes, there a need to have the module that hold the fields / formatters in dependencies but these are dynamic depending on the content entity display.
More information : https://www.drupal.org/node/2235409
About Drupal Sun
Drupal Sun is an Evolving Web project. It allows you to:
- Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
- Facet based on tags, author, or feed
- Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
- View the entire article text inline, or in the context of the site where it was created
See the blog post at Evolving Web
