Configurator plugin API (cfr)

This module suite provides a user interface for object composition.

The abbreviation "cfr" stands for "Configurator", which is the object type doing most of the work in this system.

It is the API behind Renderkit, where it allows to combine front-end components into large nested compositions.

Idea

CfrPlugin allows to expose atomic behavior objects as "plugins", which can be integrated in various subsystems in Drupal.

All you need is a simple annotation, e.g. @CfrPlugin("myPlugin", "My plugin"), which can be on a class or on a static method.

Modules using this API

To be used in combination with e.g.

• Entity display plugin, which can replace or enhance your entity view modes, views fields, views row plugins, and more.
• Entity display for Field UI, which allows to insert EntDisP entries in entity view modes, and can replace your Display suite custom fields.
• List format,
• Cfr block,
• Cfr Operation, to run operations from the UI.
• Renderkit, which contains many interfaces and implementations, many of them annotated as plugins.
• Cfr Plugin Preset, which allows to store full or partial plugin configurations, and export them with features.

The API currently only exists for Drupal 7, but is arguably more powerful and flexible than the Drupal 8 plugin API.

Demo and screencast

Screencast: https://www.youtube.com/watch?time_continue=1&v=AejsIbZO2MI

To quickly try yourself, you can install entdisp_example.

Using the plugins

To use any plugins, you need to enable an integration module like entdisp or listformat.

This gives you field formatters, views plugins and more based on those plugins.

Writing your own plugins: Basics

As a developer, all you need to do is:

• Create a module.
• Add an src/ folder within this module, and follow the conventions about PSR-4 like for Drupal 8 modules.
• Implement hook_cfrplugin_info() and let it call return cfrplugindiscovery()->moduleFileScanPsr4(__FILE__);.
• Write your own class implementing one of the interfaces in renderkit.
  Put a "@CfrPlugin" annotation on top of the class, like this:

  /**
   * @CfrPlugin("pluginMachineName", "Human-readable label")
   */
  class MyEntityDisplay implements EntityDisplayInterface {..}
  

Writing your own plugins: Details

With cfrplugin, every interface is automatically a plugin type.
Every implementation can be declared to be a plugin, by associating it with a machine name (id) and a label.

An "implementation" can be one of the following:

• a class that implements the plugin type's interface
• a static method that returns an object implementing the type's interface.
• a static method that returns such a configurator object. Typically the class that holds this static method should implement the plugin type's interface, so that cfrplugindiscovery can determine the plugin type.
• a class that implements Drupal\cfrapi\Configurator\ConfiguratorInterface, with a ->confGetValue() method that returns an instance of the plugin type's interface.

Plugins are registered by implementing hook_cfrplugin_info(), and returning a nested associative array of plugin definitions keyed by the plugin type (interface name) and the plugin id.

It is recommended to organize your classes with PSR-4, annotate the plugins (class or static method) with @CfrPlugin(..) in the doc comment, and then call return cfrplugindiscovery()->moduleFileScanPsr4(__FILE__); from within hook_cfrplugin_info().

More about this in the README.md file.

Modules within the "cfr" package

This module package contains multiple modules.
They are packed together to allow for a shared version history and module page.
One reason to split them was that each has different composer dependencies.

For the most part, you don't need to care which of these modules does what. You probably want to enable all of them.

Note: A module named "cfr" does not exist!

Installation with drupal-composer

There are different ways to use Composer to download Drupal 7 module packages and 3rd party dependencies required by them.
One well-documented solution is https://github.com/drupal-composer/drupal-project/tree/7.x (you need the 7.x version!).

Starting from there, you can now require the metapackages shipped with cfr like so:

composer require drupal/cfrplugin:~2.0

Download additional modules:

composer require drupal/entdisp drupal/listformat drupal/cfrpreset

Download all recommended modules at once:

composer require donquixote/d7-cfr-recommended

Enable the newly downloaded modules:

cd web
drush en -y entdisp listformat entdisp_example cfrblock cfrpreset cfrop entdispfieldui

Installation with composer_manager + alternatives

You will need Composer manager, Alternatives and for this to work.

Usually, you will enable all modules within this package.

You will probably use this in combination with other modules like entdisp or listformat. Thanks to the dependencies in those modules, enabling those will trigger the changes you need.

E.g.

drush dl cfr  # this package needs dedicated download command
drush en -y entdisp  # trigger download and enabling of everything you need

Drupal 8 ?

Working on it!

Move to github / Composer / Packagist?

There are plans to move major parts of this API to github and packagist, so that they become independent of Drupal. This will allow to integrate this with other frameworks.

In the current version, many components have a hard dependency on Drupal's form API. The next version will change that, so that it can be integrated with other form APIs, e.g. Symfony.