Display Suite
Display Suite allows you to take full control over how your content is displayed using a drag and drop interface.
ds
インストール
composer require 'drupal/ds:8.x-3.32'
概要
Display Suiteは、Drupalでコンテンツ、ユーザー、その他のEntityの表示を制御するための強力で柔軟な方法を提供します。コアのField UIを拡張し、サイト構築者がレイアウトの選択、カスタムFieldの作成、FieldテンプレートのField適用を通じてEntity表示をより細かく制御できるようにします。
Display Suiteを使用すると、コンテンツに異なるレイアウト（1〜4カラム、スタック、フルイドバリアント）を選択し、Fieldを異なるリージョンにドラッグ＆ドロップし、動的Field（Token、Twig、Block、CopyのField）を作成し、Fieldテンプレートで HTML マークアップ出力を制御できます。Viewsと統合し、交互ビューモード、グループ化、言語レンダリングを備えた高度なEntityの行スタイリングオプションを提供します。
Display Suiteは、DrupalコアのEntity表示システムの上に位置するレイヤーとして機能し、その設定をEntity view displayのサードパーティ設定として保存します。計算値、Block、またはカスタムコンテンツを表示できるカスタムDS Fieldを作成するための独自のPluginシステムを提供します。
Features
- Manage display画面でFieldをレイアウトリージョンに配置するためのドラッグ＆ドロップインターフェース
- 1、2、3、4カラムレイアウトを含む複数のビルトインレイアウト（スタック、フルイド、等幅バリアント付き）
- カスタムField作成：Token Field、Twig Field、Block Field、および既存のField定義を再利用するCopy Field
- 個々のFieldのマークアップ出力をラッパー、クラス、属性で制御するFieldテンプレート（Default、Minimal、Expert、Reset）
- 交互ビューモード、グループ化、delta Field、高度なレンダリング制御をサポートするDS Entity RowプラグインによるViews統合
- ビューモード間で表示設定をコピーするレイアウトクローン機能
- Display Suiteレンダリングを一時的に無効にする緊急モード
- リージョンとFieldのCSSクラス管理
- カスタムFieldでの動的コンテンツ用TokenおよびTwigサポート
- 登録済みレイアウトを使用するためのLayout Discovery統合
Use Cases
Creating a multi-column article layout
Use Display Suite to create a two or three column layout for article content types. Navigate to Admin > Structure > Content types > Article > Manage display, select a DS layout (e.g., Two column stacked), then drag your fields into the appropriate regions (header for title, left column for main content, right column for metadata like author and date, footer for tags). Save and view an article to see the new layout.
Adding a custom computed field
Create a Twig field at Admin > Structure > Display Suite > Fields > Add twig field. Name it 'Reading Time', select the 'Node' entity type, and enter Twig code like '{{ (entity.body.value|striptags|split(' ')|length / 200)|round }} min read'. This field can then be placed in any node display to show estimated reading time.
Embedding a block in entity display
Use a Block field to embed a block directly in your entity display. Go to Admin > Structure > Display Suite > Fields > Add block field, select a block (e.g., a Related Content view block or a custom block), then place this field in your entity's display like any other field.
Creating alternating teasers in Views
In a Views listing, use the DS Entity Row format and enable 'Alternating view mode'. Configure different view modes for odd and even rows (e.g., Teaser and Teaser Alternate) to create visual variety in content listings.
Controlling field markup with Expert template
Enable field templates in DS settings, then on Manage Display, click the settings gear for a field and select 'Expert' template. Configure outer wrappers (div, span, etc.), add custom classes like 'field-featured', set attributes, and add prefix/suffix HTML for complete control over field output.
Per-node view mode selection
Enable the DS Switch View Mode submodule, create multiple view modes for nodes (e.g., Full, Full with sidebar, Landing page), then when editing a node, use the 'Display settings' section to select which view mode should be used when viewing that specific node.
Cloning display configuration
After setting up a complex layout for one view mode, use the 'Clone layout' feature to copy it to another view mode. In Manage Display, when no layout is selected, choose a source view mode from the Clone layout dropdown to duplicate the configuration.
Tips
- Use the 'Disable layout CSS styles' option when your theme provides its own responsive grid system to avoid CSS conflicts.
- The Reset layout and Reset field template output content with minimal markup - useful when you want complete control via CSS/JS or when outputting to an API.
- Token fields are processed at render time, so they work well for dynamic content like 'Posted X time ago' or conditional content based on field values.
- Twig fields have access to the full entity object, making them powerful for complex computed displays without writing custom code.
- Copy fields let you reuse a DS field definition across multiple entity types without recreating it.
- The Expert field template supports token replacement in wrapper classes and attributes for dynamic styling based on entity data.
- Use ui_limit on custom fields to restrict them to specific bundles or view modes, keeping the Field UI cleaner.
- When debugging, DS Devel's Markup tab shows the actual HTML output, which is invaluable for theming and troubleshooting.
- The ds_classes_alter hook allows modules or themes to add context-aware CSS classes dynamically.
- DS stores configuration as third-party settings on entity view displays, making it fully exportable with core config management.
Technical Details
Admin Pages 9
/admin/structure/ds
Main Display Suite administration page listing all entity types and bundles. Provides quick access to manage display settings for each entity bundle.
/admin/structure/ds/settings
Configure global Display Suite settings including field template defaults, emergency mode, and class management options.
/admin/structure/ds/classes
Define custom CSS classes that can be applied to layout regions and fields on Manage Display pages.
/admin/structure/ds/fields
Manage custom Display Suite fields including Token fields, Twig fields, Block fields, and Copy fields.
/admin/structure/ds/fields/manage_token
Create a custom field that uses Token replacements to display dynamic content.
/admin/structure/ds/fields/manage_twig
Create a custom field using Twig template syntax for advanced dynamic content.
/admin/structure/ds/fields/manage_block
Create a custom field that renders a block plugin within entity displays.
/admin/structure/ds/fields/manage_copy
Create a field that copies the output of an existing Display Suite field.
/admin/structure/ds/emergency
Emergency controls to temporarily disable Display Suite rendering site-wide. Useful for debugging infinite loops or display issues.
権限 3
Hooks 7
hook_ds_fields_info_alter
Alter the DS field definitions before they are cached. Use to modify field properties or add new fields programmatically.
hook_ds_pre_render_alter
Alter the entity render array before DS processes it. Called before layout is applied.
hook_ds_layout_settings_alter
Alter layout settings when saving from the Field UI form.
hook_ds_layout_region_alter
Alter the available regions and region options on the Field UI display page.
hook_ds_label_options_alter
Alter the label display options available for fields.
hook_ds_classes_alter
Alter the list of CSS classes available for regions or fields.
hook_ds_views_row_render_entity
Advanced hook for controlling Views DS entity row rendering. Must enable 'Advanced view mode' in Views row settings.
Troubleshooting 7
After selecting a layout, you must save the Manage Display form. If fields disappear, they were moved to the first region - drag them to the appropriate regions and save again.
Use the Emergency mode at /admin/structure/ds/emergency to temporarily disable Display Suite. This often indicates a view embedded in an entity display that references the same entity.
DS fields only appear when a DS layout is selected. Ensure you've chosen a layout from the dropdown in the Layout settings on the Manage Display page.
Check the field's 'Limit field' setting. Ensure the bundle/view mode combination matches your configured limits (e.g., article|* for all article view modes).
Field templates must be enabled in Display Suite settings (/admin/structure/ds/settings). Check 'Enable field templates' and save.
Display Suite automatically disables itself when Layout Builder is enabled for a display. Disable Layout Builder in the entity display settings to use DS instead.
Some Views row options like 'Use view mode of display settings' require the DS Switch View Mode submodule to be enabled. Advanced view mode requires implementing hook_ds_views_row_render_entity().
Security Notes 4
- Token and Twig fields can output raw HTML. Ensure only trusted administrators have permission to create and edit these fields.
- The DS Extras 'Field permissions' feature adds granular access control but should be tested thoroughly as it creates permissions for all DS fields.
- Block fields render arbitrary blocks in entity context - verify blocks don't expose sensitive data when rendered in unexpected contexts.
- When using tokens in Expert field templates, be aware that user-controlled data could be injected if not properly sanitized.