NOTICE: This works fine in Drupal 7. For Drupal 8 please see https://www.drupal.org/node/2863420
Sometimes as a developer you need to provide your Drupal authors with the ability to choose different variations of a particular content object. For example, imagine you have a Callout paragraph bundle and you want the author to choose between a Dark or a Light colorscheme; if the user chooses Light, the font colors appear dark over a light background. To achieve this you need a dark or light class on the entity wrapper based on whichever the author chose; this would let you write CSS to target each color scheme. Using Display Suite this is an easy problem to solve and doesn’t require any preprocess code or other hand-coded solution.
Provide the Color Scheme Choice
To provide the choice to the author I typically use a select list. Here’s the field I’d add for this example:
Switch the View Mode to use Display Suite
For the class-setting to be available you must choose a Display Suite layout for the view mode you’d like to “class-ify”.
You should enable Full content and Tokens as shown here (I cut out the stuff in the middle; this vertical tab group should be at the bottom of the page when you’re on the Default view mode for the content type):
After you choose a Display Suite layout you’ll see additional vertical tabs (the one we’re hoping to see is “Custom classes”).
Define a New Class for Use in the Layout
Click the link to Manage region and field CSS classes, as shown here:
Use the Browse available tokens. link to see what tokens are available. For my example this is what I ended up using. You can use a friendly name, or omit it and just use the token value:
After you save this you’ll see a new option, which you should enable:
Test the Setup
Notice that we got the field’s display value, not the key. What you really want is the key like colorscheme-light (see second graphic above). To be able to do this you have to do one more thing.
Set Token Value for Field to use Key
Edit the Tokens view mode to set the Color scheme field format to Key instead of Default; make sure it isn’t hidden, too.
Test the Setup (again)
Now there is a class on the wrapper that we can use to style accordingly.
You’re Probably Thinking…
This took a while to setup, Adam! Once you’ve done it once it takes just a minute to do it to another content type or with another field. Also, it exposes you to another piece of Display Suite that could be beneficial to you in the future (notice you can set classes on fields too!).
If you are concerned with this approach you can certainly achieve the same with an entity preprocess hook.