Drupal Modules: The One Percent — Configuration Split (video tutorial) NonProfit Tue, 11/29/2016 - 17:04 7

Here is where we look at Drupal modules running on less than 1% of reporting sites. Today we'll look at Configuration Split, a module which allows you to export only the D.8x configuration you want to production. More information can be found http://nuvole.org/blog/2016/nov/28/configuration-split-first-beta-release-drupal-ironcamp.

Hacking DrupalCon: A Behind the Scenes Look at the Event Design and Planning Process Spela Tue, 11/29/2016 - 21:58

Ever wonder what goes into a conference or other business event that participants will gush about (in a good way) for years? After an event of these mythical proportions, participants walk away raving about the food, the speakers, the social events, the aura, and the list goes on ...

But pulling off such an event is no easy feat. Thus, I decided to speak with Lead DrupalCon Coordinator Amanda Gonser to find out how she manages to make sure the DrupalCon event design is flawless and fits into the overall event planning process seamlessly.

(This video may cause unexpected bursts of laughter. If you cannot laugh in your current environment, please scroll down for the written version.)

We normally share  our financial statements in posts about public board meetings, since that is the time when board members approve the statements. However, I wanted to give this quarter’s update its own blog post. We’ve made many changes to improve our sustainability over the last few months and I am fully embracing our value of communicating with transparency by giving insight into our progress.

First, a word of thanks

We are truly thankful for all the contributions that our community makes to help Drupal thrive. Your contribution comes in the form of time, talent, and treasure and all are equally important. Just as contributing code or running a camp is critical, so is financial contribution.

The Drupal Association is able to achieve its mission to unite the community to build and promote Drupal thanks to those who buy DrupalCon tickets and sponsor the event, our Supporters and Members, Drupal.org sponsors, and talent recruiters who post jobs on Drupal Jobs.

We use these funds to maintain Drupal.org and it’s tooling so the community can build and release the software and so technical evaluators can learn why Drupal is right for them through our new marketing content. It also funds DrupalCon production so we can bring the community together to level up skills, accelerate contribution, drive Drupal business, and build stronger bonds within our community. Plus, it funds Community Cultivation Grants and DrupalCon scholarships, removing financial blockers for those who want to do more for Drupal. And of course, these funds pay staff salaries so we have the right people on board to do all of this mission work.

I also want to thank our board members who serve on the Finance Committee, Tiffany Farris (Treasurer), Dries Buytaert, Jeff Walpole, and Donna Benjamin. They provide financial oversight for the organization, making sure we are the best stewards possible for the funds the community gives to us. I also want to thank Jamie Nau of Summit CPA, our new CFO firm. Summit prepares our financial statements and forecasts and is advising us on long term sustainability.

Q3 Financial Statements

A financial statement is a formal record of the financial activities of the Drupal Association. The financial statements present information in a structured way that should make it easy to understand what is happening with the organization's finances.

Once staff closes the books each month, Summit CPA prepares the financial statement, which the finance committee reviews and approves. Finally, the full Drupal Association Board approves the financial statements. This process takes time, which is why Q3 financials are released in Q4.

You can find the Q3 financial statements here. They explain how The Association used its money in July, August, and September of this year. It takes a little financial background to understand them, so Summit CPA provides an executive summary and they set KPIs so it is clear how we are doing against important financial goals.

The latest executive summary is at the beginning of the September financial statement. In short, it says we are sustainable and on the right path to continue improving our financial health.

“We are working on building an adequate cash reserve balance. As of September a cash balance of $723K is 14% of twelve-months of revenue. Summit recommends a cash reserve of 15%-30% of estimated twelve-month revenue. Since Drupal’s revenue and expenditures drastically fluctuate from month to month [due to DrupalCon] a cash reserve goal closer to 30% is recommended.

Through August we have achieved a Net Income Margin of 4% and a Gross Profit Margin 33%. Our goal is to increase the Net Income Margin to over 10% during the next year.”
- Summit CPA

Improving our sustainability will continue to be an imperative through 2017, so the Association can serve its mission for generations to come. Financial health improvements will be achieved by the savings we gain over time from the staff reductions we did this summer. Another area of focus is improving our programs’ gross margins.

You can expect to see the Q4 2016 financials in Q1 2017. You can also expect to see our 2017 budget and operational focus. We are certainly excited (and thankful) for your support and we look forward to finding additional ways to serve this amazing community in 2017.

Have you ever been asked to log into a website while you are viewing a page? And after doing so you get redirected to some page other than the one you were reading? This is an obvious and rather common usability problem. When this happens people lose track of what they were doing and some might not even bother to go back. Let's find out how to solve this in Drupal 8.

In a recent project a client wisely requested exactly that: whenever a user logs into the site, redirect them to the page they were before clicking the login link. This seemed like a very common request so we looked for a contrib module that provided the functionality. Login Destination used to do it in Drupal 7. Sadly the Drupal 8 version of this module does not provide the functionality yet.

Other modules, and some combinations of them, were tested without success. Therefore, we built Login Return Page. It a very small module that just does one thing and it does it well: it appends destination=/current/page to all the links pointing to /user/login effectively redirecting users to the page they were viewing before login. The project is waiting to be approved before promoting it to full project.

Have you had a similar need? Are there other things you are requested to do after login? Please share them in the comments.

We have been loving learning Drupal 8’s theming system over the last year.  Drupal 8 core now uses the Twig template engine, which is a fast, flexible, and secure system that allows use to create the markup needed for the modern web.

What you can do with Drupal core’s Twig is pretty great, but the Drupal community always brings so much more to the table after real world use.  We don’t use them all, all of the time, but have used many as our design and development needed.  Here are our favorite modules to help build out your Drupal themes.

Twig tweak

The Twig Tweak Drupal module gives Drupal 8 themers additional commonly needed functions and filters to use in templating:

• drupal_view: Pass arguments to views.
• drupal_block: Include a Drupal block.
• drupal_entity: Include a Drupal entity.
• drupal_field: Renders a field from a specific entity.
• drupal_token: Use token API to deliver data to your templates.
• drupal_config: Access and print configuration.
• token_replace: Place multiple tokens.
• preg_replace: The easiest way to alter their output.
• image_style: Provide either path or URI to original image.

It also allows for you to turn PHP filter back on, which isn't recommended, and is off by default.

Twig Field Value

The Twig Field Value Drupal module allows Drupal 8 themers to get partial data from field render arrays.  If you want to have control of the markup on your field’s label and/or value, you can.  If you want to choose the field’s text format, you can.  This great utility module gives us the following filters:

• field_label: Returns the field label value.
• field_value: Returns the render array of the field value(s) without the field wrappers.
• field_raw: Returns raw field properties value(s).
• field_target_entity: Returns the referenced entity object(s) of an entity reference field.

Twig Extensions

This handy Drupal 8 module adds support for the Twig Extensions library.  The library adds additional filters to Twig itself, and this module allows us to use them in Drupal.

• Text: Provides useful filters for text manipulation.
• I18n: Adds internationalization support via the gettext library.
• Intl: Adds a filter for localization of DateTime objects.
• Array: Provides useful filters for array manipulation.
• Date: Adds a filter for rendering the difference between dates.

Twig Extender

The Twig Extender Drupal module adds a plugin system to add new twig extensions.  It includes one filter (truncate), and one function (user_is_logged_in), and promises more in the future.  Looks very promising.

Themable forms

This simple, and extremely helpful Drupal 8 module adds theme suggestions for form elements.

• form-element--[form-id]--[element-type].html.twig
• form-element--form-id--[form-id].html.twig
• form-element--type--[element-type].html.twig
• form-element.html.twig

Twig Renderable

The Twig Renderable Drupal module is another module that adds Twig functions and filters, this time that work specifically with render arrays.

Function

• will_have_output('path', 'to', 'render', 'array')

Filters

• add_class(string|array $class)
• merge_attributes(array|\Drupal\Core\Template\Attribute $attributes)

Transliterate Twig Filter

This module adds a single Twig filter for transliterating diacritic strings. Transliteration is the conversion of a text from one script to another, and this module converts diacritic characters, those that have accents in them, to their normal counterparts.

The included example shows how it works:

{{ 'Hällo' | transliterate() }} becomes => Hallo

Responsive SVG

The Responsive SVG Drupal module that adds a Twig filter, with quite a few options for SVG Stacks.  SVG Stacks are like image sprites, where you have multiple images in one file, though these images are Scalable Vector Graphics.  Support for regular SVGs forthcoming.

Twig Xdebug

The Twig Xdebug Drupal module adds the ability to use Xdebug within Twig templates.  Add {{ breakpoint() }} into the template where you want to debug, and when the Xdebug processor reaches it, a separate file will open so you can inspect the variables up to that breakpoint. The key values you'll see at the breakpoint are:

• $context: Variables available to use in the template.
• $environment: Info about the Twig environment, including available functions.
• $arguments: You can also add arguments like {{ breakpoint(fields) }}.

Twig Clean Debug

This simple and handy module adds a Twig filter that removes the Twig debugging output, those informative HTML comments that let you know which templates are available, but they can also get in the way of what you are working on!

Update your template to use {{ content.field_image|clean_debug|raw }} when you are developing.  Remember to remove it before pushing to production though, it will error our if twig debug is not on!

Twig Link Attributes

The Twig Link Attribute Drupal module adds a Twig filter that allows you to add attributes to links, which also merges them with existing attributes.  Works well with the Menu Link Attributes module, but safely keeps some attributes in code, while Site builders and administrators can manage attributes in the UI.

Themers Little Helper

Similar to Twig Tweak, the Themers Little Helper (TLH) Drupal module adds a bunch of Twig filters and functions, and promises more!  The current release includes:

• base_url: the Base URl of the site.
• Wrap filter: {{ content.title_field|wrap('h3') }} for wrapping markup around fields.
• drupal_view: Embed a view direct in your template.
• drupal_block: Embed a block direct in your template.
• dump(variable): Support for the Vardumper module, which is faster than kint.

Component Libraries

Finally, the Components Libraries Drupal module allows you to register “component libraries” defined by your theme or module as Twig namespaces.  This means that you can specify a different directory, rather than a folder called “templates” for your Twig files.  This is lays the foundation for being able to use component based theming, where each aspect of the design is an individual piece, or component, and allowing integrating the external tools like Pattern Lab and KSS Node, which would also use this Twig templates for living style guides.

Happy theming!

FFW, the mega digital agency, is offering a free, two-hour course for business technology and marketing decision makers who want a compressed intro to Drupal with the added benefit of a live instructor.

The class focuses on Drupal’s core concepts so organizations can get the most out of the platform and avoid common mistakes. It’s designed to help smooth Drupal adoption by companies and organizations.

It's coming up on Thursday, December 08, 2016, from 1 PM to 3 PM EST.

Tags: acquia drupal planet

In a recent Drupal 8 project, one of the site's vocabularies had several thousand terms in it (representing airports), which caused its admin listing page to run out of memory before it could render. I wanted to solve this without affecting any other vocabularies on the site, and improve the listing itself along the way to be more useful, with filters to make searching it much easier. The original listing is not a view, and loads much more than it needs to. Here's the customised page for airports that I wanted to head towards:

Famous beach Copacabana and football are the most frequent associations when we think of South America. Well, there are plenty more things there, that's for sure. Drupal Camps are one of those. In our world tour we already touched continents like Europe, North America, Asia and Africa. In the exact same sequence are continents listed from one with the most Drupal Camps (Europe) to the one with the least Drupal Camps (Africa). We expected to find South America between Asia and Africa, but for the first time, we were wrong. Our assumptions were so wrong, that it was difficult to process… READ MORE

Let's see how and why to use a views display extender plugin.

In this series I will show you how to make use of the new Drupal 8 Plugin system, we begin with a simple example : the views area handler plugins.

Some notes about the new Configuration management system 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.

In this article will see how to use the Drupal migration framework to migrate custom sites to drupal 8.

Handle referenced entity fields directly in the parent entity

Controllers in Drupal 8 are the equivalent of hook_menu in Drupal 7. A controller lets you define a URL and what content or data should appear at that URL. If you’re like me, limiting access to my controllers is sometimes an afterthought. Limiting access is important because it defines who can and can’t see a page.

Controllers are defined in a YAML file called module_name.routing.yml. Access and permission rules are defined in the the module_name.routing.yml under _requirements. Most of the code examples will be from a module_name.routing.yml file added to my_module in the top level.

Note: There is a lot of existing documentation on how to create controllers in Drupal 8, so I won’t focus on that here.

I’ve outlined some of the most useful approaches for limiting access below. You can jump straight to the most relevant section using the following links: limit by permission, limit by role, limit by one-off custom code, limit by custom access service.

Limit by permission

In this case, a permission from the Drupal permissions page is given. Permissions can be found at /admin/people/permissions. Finding the exact permission name can be tricky. Look for module.permissions.yml files in the module providing the permission.

my_module.dashboard:
  path: 'dashboard'
  defaults:
    _controller: '\Drupal\my_module\Controller\DashboardController::content'
    _title: 'Dashboard'
  requirements:
    _permission: 'access content'

Key YAML definition:

_permission: 'THE PERMISSION NAME'

Limit by role

You can also limit access by role. This would be useful in cases where users of a specific role will be the only ones needing access to your controller. You can define user roles at /admin/people/roles.

my_module.dashboard:
  path: 'dashboard'
  defaults:
    _controller: '\Drupal\my_module\Controller\DashboardController::content'
    _title: 'Dashboard'
  requirements:
    _role: 'administrator'

Key YAML definition:

_role: 'THE ROLE NAME'

You can specify multiple roles using "," for AND and "+" for OR logic.

Limit by one-off custom code

In cases where you have custom access requirements, adding an access method to your controller might make sense. In this example, the page should not be viewed before a specified date.

my_module.dashboard:
  path: 'dashboard'
  defaults:
    _controller: '\Drupal\my_module\Controller\DashboardController::content'
    _title: 'Dashboard'
  requirements:
   _custom_access: '\Drupal\my_module\Controller\DashboardController::access

Key YAML definition:

_custom_access: '\Drupal\my_module\Controller\DashboardController::access

The access method in my controller would look like:

<?php
namespace Drupal\my_module\Controller;
 
use Drupal\Core\Access\AccessResult; 
use Drupal\Core\Controller\ControllerBase;
 
/**
 * Defines the Dashboard controller.
 */
class DashboardController extends ControllerBase { {
 
 /**
  * Returns content for this controller.
  */
 public function content() {
   $build = [];
   return $build;
 }
 
 /**
  * Checks access for this controller.
  */
 public function access() {
   // Don’t allow access before Friday, November 25, 2016.
   $today = date("Y-m-d H:i:s");
   $date = "2016-11-25 00:00:00";
   if ($date < $today) {
     // Return 403 Access Denied page.  
     return AccessResult::forbidden();
    }
    return AccessResult::allowed();
  }
}

Limit by custom access service

This is similar to having an access method in your controller, but allows the code to be reused across many controllers. This is ideal when you are doing the same access check across many controllers.

my_module.dashboard:
  path: 'dashboard'
  defaults:
    _controller: '\Drupal\my_module\Controller\DashboardController::content'
    _title: 'Dashboard'
  requirements:
    _custom_access_check: 'TRUE'

Key YAML definition:

_custom_access_check: 'TRUE'

Proving the _custom_access_check service requires creating two files in my_module.

my_module/my_module.services.yml (defines the Access service and where to find our Access class)

services:
  my_module.custom_access_check:
    class: Drupal\my_module\Access\CustomAccessCheck
    arguments: ['@current_user']
    tags:
      - { name: access_check, applies_to: _custom_access_check }

my_module/src/Access/CustomAccessCheck.php

<?php
namespace Drupal\my_module\Access;
 
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Routing\Access\AccessInterface;
use Drupal\Core\Session\AccountInterface;
 
/**
 * Class CustomAccessCheck.
 *
 * @package Drupal\my_module\Access
 */
class CustomAccessCheck implements AccessInterface {
 
  /**
   * A custom access check.
   *
   * @param \Drupal\Core\Session\AccountInterface $account
   *   Run access checks for the logged in user.
   */
  public function access(AccountInterface $account) {
    // User has a profile field defining their favorite color.
    if ($account->field_color->hasField() && !$account->field_color->isEmpty() && $account->field_color->getString() === 'blue') {
      // If the user's favorite color is blue, give them access.
      return AccessResult::allowed();
    }
    return AccessResult::forbidden();
  }
 
}

While the above covers some of the most useful ways to restrict access to a controller, there are additional options. Drupal.org has a couple of good resources including Structure of Routes and Access Checking on Routes.

Lightning is a base distribution maintained by Acquia. In this short blog post you will learn how to fix the dependency conflicts when trying to add DrupalConsole to a project using the Lightning distribution.

A response to Maxime: On Drupal and Drupal Commerce by Kris Vanderwater -- 28 November 2016

This blog was originally intended as a comment on Maxime's medium post. It got long, and I am loath to create content for mega-sites. As such, I responded with a post of my own, which is exactly what Maxime did to Robert Douglass' original Facebook post... I guess we all have our competing standards ;-)

In the last few weeks, there's been some controversy in the Drupal community. Acquia launched a major partnership with Magento, which has left some people wondering about the support for Drupal Commerce. There had already been some nervousness, because Drupal Commerce 2 has been slow to arrive in Drupal 8.

So, what's happening with Drupal Commerce?

First, I would recommend you read Dries' post on Acquia's plans for e-commerce.

Next, I'd highly recommend that you watch this video from Ryan Szarma, one of the lead developers of Drupal Commerce. This video was recorded at Drupal 8 Day. Ryan covers the history, architecture, and features of Drupal Commerce 2 on Drupal 8. There was a lot of interest in Ryan's presentation, with over 30 minutes of questions afterwards.

Solving one of Drupal 8 core's development and deployment work-flow issues.

One of the nice things that happened during Drupal Ironcamp in Prague last week was the first beta release of the Configuration Split that I started developing a few months ago.

As explained in the previous blog post about Configuration Split, the typical use case of Configuration Split is to be able to maintain a "development" configuration and a "production" configuration, where some of the modules or settings you use in development are not copied to production upon configuration export/import.

A typical use case

We assume that you have a production and development version of the same site and that they are aligned.

Step 1: Enable anything you need in development and work normally

In the development environment we enable Devel and UI modules enabled and we can create new content types, add fields and do all things we like to do while developing a Drupal site. Some of this configuration work is meant to go to the production site and some (e.g., the fact that Devel is enabled and related configuration) is not. We thus need to split our configuration.

Step 2: Create a split definition

Choose a name for your "local" configuration and select all the configuration you don't want to have on the live site (even though, if you wish, you can still share it with colleagues). This can include modules you would not want to be enabled or configuration that is for development only. The path here is a folder next to the normal config sync directory outside of the web root. In the example above, we are splitting out to a configuration set named "Development" the Devel, Fields UI, Views UI modules and the system.menu.devel configuration.

Step 3: Export your configuration with config_split

$ drush config-split-export

In the most basic use case we just replace config-export with config-split-export in our workflow. This exports the elements we selected above to ../config/dev and the rest (the configuration we want to deplay) to our "standard" configuration folder, in this case ../config/sync.

Step 4: Import the "clean" configuration in production

On all environments we use the configuration import of config_split:

$ drush config-split-import

So in our usual workflow we replace config-import with config-split-import

In order not to have different workflows for development and production we simply deactivate the split on production by overriding the configuration in settings.php on production: $config['config_split.config_split.development']['status'] = FALSE;

This will result in the split definition to be deactivated. And consequently the import will have the configuration blacklisted in the split removed and development modules deactivated.

What's new in the beta version

The following features are new or changed in the beta release:

• The drush command works and has some text to warn users to which directories configuration will be written to.
• The drupal console command is disabled, but there is a patch/branch you can use or help to make it functional again.
• Split entities now have a status and the default command only uses the active splits. Of course you can override that in settings.php as with almost all configuration.
• You can switch out the default config.storage.sync service in your services.yml file so that the default configuration sync UI uses the split import. Details are in the README.txt file.

More information and acknowledgments

On Friday I gave a presentation about my favorite topic in Drupal: Configuration Management, attached here are the slides.

I wish to thank IronCamp participants and especially Swentel and mr.baileys who worked on patches, and I'd like to thank IronCamp organizers for a very well organized event where I met a lot of old and new friends. Swentel also took care of documenting more advanced use cases of Configuration Split on his blog.

For any further information see the module page and its issue queue.

Tags: Drupal PlanetDrupal 8Code Driven DevelopmentAttachments:  Configuration Management - slides Ironcamp Prague

REST API Explorations in Drupal 8 - Primer Body

This article assumes you are familiar with what RESTful is & what do we mean when we use the term REST API. Some of you might have already worked with RESTful Web Services module in D7, it exposes all entity types as web services using REST architecture. Drupal 8 out of the box is RESTful with core support. All entities (provided by core + ones created using Entity API) are RESTful resources.

To explore the RESTful nature of Drupal 8, we will need to enable the following modules:

In Core

• HAL - Serializes entities using Hypertext Application Language.
• HTTP Basic Authentication - Provides the HTTP Basic authentication provider.
• RESTful Web Services - Exposes entities and other resources as RESTful web API
• Serialization - Provides a service for (de)serializing data to/from formats such as JSON and XML.

Contributed

• REST UI - Provides a user interface to manage REST resources.

RESTful Resources

Every entity in D8 is a resource, which has an end point. Since, its RESTful, the same end-point is used for CRUD (Create, Read, Update, Delete) operations with different HTTP verbs. Postman is an excellent tool to explore / test RESTful services.  Drupal 8 allows you to selectively choose & enable a REST API. e.g., we can choose to expose only nodes via a REST API & not other entities like users, taxonomy, comments etc.

After enabling REST_UI module we can see list of all RESTful resources at /admin/config/services/rest. In addition to ability to choose the entity one can enable, we can also choose the authentication method per resource & enable specific CRUD operations per resource.

Let us take a look at what the REST APIs for User entity would be after we save the configuration in the above screenshot.

User

POST

http://domain.com/entity/user?_format=hal_json

{
 "_links": {
   "type": {
     "href": "http://domain.com/rest/type/user/user"
   }
 },
 "name": {
   "value":"testuser"
 },
 "mail":{
   "value":"[email protected]"
 },
 "pass":{
   "value":"testpass"
 },
 "status": {
   "value": 1
 }
}

Header

X-CSRF-Token: Get from http://domain.com/rest/session/token
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Basic (hashed username and password)

Note: Drupal 8 doesn't allow anonymous user to send a POST on user resource. It is already fixed in 8.3.x branch but for now we can pass the credentials of the user who have permission to create users. If you are interested in taking a deeper look at the issue, you can follow https://www.drupal.org/node/2291055.

Response: You will get a user object with "200 OK" response code

 

PATCH

http://domain.com/user/{uid}?_format=hal_json

{
 "_links": {
   "type": {
     "href": "http://domain.com/rest/type/user/user"
   }
 },
 "pass":[{"existing":"testpass"}],
 "mail":{
   "value":"[email protected]"
 }
}

Note: Now as user have permission to update his own profile so we can pass current user's credentials in authentication header.

Response: You will get "204 No Content" in response code.

 

GET

http://domain.com/user/{uid}?_format=hal_json

Response: You will get a user object with "200 OK" response code.

 

DELETE

http://domain.com/user/{uid}?_format=hal_json

Response: You will get "204 No Content" in response code.

RESTful Views and Authentication

Drupal 8 also allows us to export views as a REST service. It allows you to use all the available authentication mechanism in views itself.

JSON API Module

JSON API module provides a new format called "api_json" which is soon becoming the de-facto standard for Javascript Frontend frameworks, If you plan to use completely de-coupled Drupal with frontend framework like Angular / React / Ember then its worth a look. To read more about JSON API you can visit the site.

SUMIT MADAN Mon, 11/28/2016 - 15:56

Written on November 28, 2016 - 11:01

From the Configuration split project page: "The Drupal 8 configuration management works best when importing and exporting the whole set of the sites configuration. However, sometimes developers like to opt out of the robustness of CMI and have a super-set of configuration active on their development machine and deploy only a subset. The canonical example for this is to have the devel module installed or having a few block placements or views in the development environment and then not export them into the set of configuration to be deployed, yet still being able to share the development configuration with colleagues."

This small utility module for Drupal 8 allows you to exactly achieve this use case (and many others). I will cover two common scenarios, explaining how to configure your site and which commands you need to run:

1. Have (development/ui) modules installed on your dev environment, uninstalled on production
2. Have modules installed on your production environment, but not on development

I've also recorded a screencast in which I configure and run all the commands explained underneath. The best way in the end is to play around with the module itself of course.

Configuration split 101

Configuration split exposes a configuration entity which controls what you want to split off. Currently you can

• blacklist modules: any configuration that this module owns will automatically be blacklisted too.
• blacklist configuration: settings or configuration entities. These will be removed from the active sync directory.
• graylist configuration: settings or configuration entities. These will not be removed if they are in the active sync directory, but also not exported if they are not there yet. I won't cover this functionality in this article post, that will be for another time.

After you configured one or more configurations split entities, you can use the drush commands to export and import configuration, based on one or more of those config entities. When it comes to exporting configuration, you can not use the existing drush core command (config-export / cex). Using drush config-import (cim) or the UI to import may still be used, but this depends on your setup. Drupal Console commands are under revision.

Each config split entity defines the directory in which the splitted configuration will live in case there are some. Not all modules define configuration, so there's a possibility that this directory is empty after you do an export.

An important technical aspect is that the module does not interfere with the active configuration but instead filters on the import/export pipeline. What simple happens is this: just before the actual writing, it will check the configuration and remove any entries that you don't want to be there. Then your active configuration is written away. Config that doesn't belong into the active configuration will be moved to separate directory. On import, the opposite happens: it will merge settings back in and set modules to the installed state just before core configuration then starts importing.

Last, but not least: you can swap the config.storage.sync service so that the synchronize screen will use the config split config entities for importing. More information is in the README file and in the video.

Scenario 1: modules installed on dev, not on production

Step 1

After you installed the module, go to 'admin/config/development/configuration/config-split' and click on 'Add configuration split'. Naming is important, so we'll enter 'Dev split' as the name for this configuration. We'll also create a directory called 'sync-dev-split'. Now toggle the modules that you don't want to have installed on production. In this case, we're going to blacklist Devel, Devel Kint, Field UI, Views UI and database logging. Additionally, also toggle system.menu.devel. This configuration is owned by the system module, so there's no dependency on the devel module. There's no problem having this config on your production site though, so it's not required to blacklist it.

Optionally, you can also blacklist the configuration split module because it doesn't necessarily have to be installed on production. We're not doing that here, because in the second scenario, we're building further on this one and we want to have it installed on the production environment as well.

Step 2

Go to your command line interface and run following command:

swentel@dev:/home/drupal/drupal-core$ drush csex --split=dev_split

The split option is not required, but when starting to work with the module, it helps you to know which config split will be used for this command. It's possible to override the status of any config split config entity so that eventually, you can omit the split option. Sadly enough, you don't get any feedback (yet), but after the command has run you should see various files in your sync-dev-split directory:

swentel@dev:/home/drupal/drupal-core$ ls sync-dev-split/
dblog.settings.yml  devel.settings.yml  field_ui.settings.yml  system.menu.devel.yml

Step 3

You can now commit your active sync and go to production. You don't necessarily have to put the sync-dev-live directory in your version control because production doesn't need to know about these files at all. Once you have pulled on production, go to the synchronize screen to verify what is staged. You will see that the setting files will be removed and core.extension will be changed uninstalling the development modules and installing configuration split. Since we only have one config split configuration, you can hit 'Import all' here or run drush config-import, (which is the drush core command). Note that if you don't use the UI, you can blacklist the configuration manager module as well.

You might wonder why we don't use the 'config-split-import' command from the module itself: this would import the active sync directory and also include the modules and settings again that we have blacklisted. And that's not what we want. This seems confusing at first, but ultimately, if this is your setup, you just keep on using the core / drush commands to import your staged configuration on production.

# This command can be used now, but not anymore further on when we will add scenario 2.
swentel@live:/home/drupal/drupal-core$ drush cim

Scenario 2: modules installed on production, not on dev

Step 1

This scenario builds further on the first one. Config split is now installed on our live website. Create a new config split configuration called 'Live split'. You will need a new directory for this second config split, so make sure it's there. On production we still want to log events and for that we're going to use the syslog module. Install the module, so that we can now blacklist it for the live split configuration.

Step 2

Go to your command line interface and run following commands:

swentel@live:/home/drupal/drupal-core$ drush csex --split=live_split

Again, no feedback here, but after the command has run you should see the syslog settings file in your sync-live-split directory:

swentel@live:/home/drupal/drupal-core$ ls sync-live-split/
syslog.settings.yml

Doing exports and imports on dev or live

From now on, if you want to import new settings whether it's on your dev or live environment, you can not use the drush core commands anymore. Use following commands:

# to export on your dev environment
swentel@dev:/home/drupal/drupal-core$ drush csex --split=dev_split
# to import on your dev environment
swentel@dev:/home/drupal/drupal-core$ drush csim --split=dev_split
# to export on your live environment
swentel@live:/home/drupal/drupal-core$ drush csex --split=live_split
# to import on your live environment
swentel@live:/home/drupal/drupal-core$ drush csim --split=live_split

The future

Please join us in the issue queue because there's still some work:

• Optimize the user interface and allow wildcards
• Add confirmation and feedback in the drush commands

Ultimately, this functionality should live in core. A core issue to discuss this is at https://www.drupal.org/node/2830300.