際際滷

際際滷Share a Scribd company logo

Recipes! The Future of Drupal Site Building | Drupal CMS Launch | Toronto

Martin Anderson-Clutz
Martin Anderson-Clutz

Learn about Drupal's recipe system, the foundation for the brand new Drupal CMS.

1 of 49
Download to read offline
1 1 Recipes! The Future of Drupal Site Building
Martin Anderson-Clutz Senior Solutions Engineer Starshot Track Lead, Events Recipe @mandclu
Recipes! The Future of Drupal Site Building | Drupal CMS Launch | Toronto
Agenda Why recipes? 1 Live demo - lets turn up the heat! 2 Anatomy of a recipe 3 Applying recipes 4 Cooking up something great 5 4 What were working on 6 Live demo - lets get cooking!
Why recipes?
Distributions and install pro鍖les have some issues They are dif鍖cult to keep updated They cannot be added after starting your project They can't be mixed and matched with other sets of functionality They are hard to discover before you install Drupal The problem: 6
Recipes A lightweight way to quickly add con鍖guration to your site They can install modules but do not have any code of their own Composable from other Drupal recipes Applied to Drupal sites, they are not installed Easy to share Do not lock sites in The solution: 7
Recipes An easy way to adopt and implement community-provided best practices The solution: 8
9 9 Giveaway! An exclusive pair of Drupal 11 sunglasses!
10 Live demo!
Recipes Cookbook The Recipes Cookbook is a collection of contributed recipes. Get ideas and share ideas for: Site-starter recipes Functionality-speci鍖c recipes Recipe sets Add your own! What were working on 11
Anatomy of a recipe
con鍖g content composer.json recipes install con鍖g:import con鍖g:actions Anatomy of a recipe 13 recipe.yml recipes install con鍖g:import con鍖g:actions {}
14
Set type as drupal-recipe Add module, recipe, or theme dependencies Suggest recipes that users might want to apply Anatomy of a recipe 15 { "name": "fourkitchens/sous-paragraphs", "description": "A collection of recipes and configuration for Sous with Paragraphs.", "keywords": ["recipe", "Drupal recipes", "drupal recipe"], "type": "drupal-recipe", "require": { "fourkitchens/sous-content-types": "dev-main", "fourkitchens/sous-paragraph-types": "dev-main", "drupal/paragraphs_features": "^2.0@beta" }, "suggest": { "fourkitchens/editorial": "A default editorial workflow." } } composer.json
name description (optional) type (optional) Groups related Drupal recipes together. recipes (optional) List other recipes to be installed with it. Anatomy of a recipe 16 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types recipe.yml
install (optional) List modules or themes to install, if they are not already During the install, simple con鍖guration from the new modules are imported Anatomy of a recipe 17 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types install: - paragraphs_ee - paragraphs_features recipe.yml
con鍖g:import Import all available con鍖g from a module: * Specify which con鍖guration you want to import If you dont include instructions here, only simple con鍖g will be imported Anatomy of a recipe 18 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types install: - paragraphs_ee - paragraphs_features recipe.yml config: import: paragraphs_ee: '*' paragraphs_features: - paragraphs.paragraphs_type.cta
con鍖g:actions An action has 3 parts: 1. Con鍖guration entity id 2. The action: must be one that's declared for the entity type of the con鍖guration entity 3. Action arguments, depending on: a. number of arguments that the action takes, and b. whether the action is in the singular or plural form Anatomy of a recipe 19 name: 'Sous Emulsify' description: 'A recipe that installs Emulsify dependencies and sets Emulsify as the default theme.' type: 'Site' install: - components - emulsify - emulsify_tools config: actions: system.theme: simpleConfigUpdate: default: emulsify recipe.yml
simpleCon鍖gUpdate It can be used to make updates to any con鍖guration value createIfNotExists It can be used to conditionally create a con鍖g entity setComponent Add a component (e.g. 鍖eld) to a con鍖guration entity Anatomy of a recipe 20 create It can be used to create a con鍖g entity. setThirdPartySetting Allows the recipe author to set third-party settings values for any con鍖g entity that can have third-party settings Helpful for modules like Layout Builder and Scheduler that use these settings to provide or change functionality. Globally applicable entity actions And more!
grantPermissions Con鍖g entity type: role Allows you to grant permissions to a role addNodeTypes, addTaxonomyVocabularies Con鍖g entity type: work鍖ows Allows you to add bundles into your content moderation work鍖ow Anatomy of a recipe 21 addToAllBundles Con鍖g entity type: 鍖eld Allows you to add a 鍖eld to all content types If the 鍖eld already exists on a content type, it will skip that content type addItemToToolbar Con鍖g entity type: editor Allows you to add a button to a CKEditor5 toolbar Con鍖g entity actions And many more!
Add the same permission(s) to all user roles actions: user.role.*: grantPermissions: - 'access content' Affect every view display of every content type actions: core.entity_view_display.node.*.*: setComponent: name: 鍖eld_tags options: type: entity_reference_label Anatomy of a recipe 22 Change settings on every instance of a 鍖eld actions: 鍖eld.鍖eld.media.*.鍖eld_tags: simpleCon鍖gUpdate: foo: bar Create a view display (i.e., enabling a view mode) for every content type actions: core.entity_view_display.node.*.foo: createIfNotExists: # The contents of the view display here... Con鍖g entity wildcards
placeBlockInDefaultTheme, placeBlockInAdminTheme Con鍖g entity type: block Theme name determined programmatically Pass an array of regions with a fallback Use 鍖rst or last keywords for placement within region Anatomy of a recipe 23 Actions for blocks config: actions: block.block.powered_first_default: placeBlockInDefaultTheme: id: powered_first # The region accepts an array keyed by theme name. region: bootstrap: footer gesso: page_bottom olivero: footer_top # Fallback if no match found in the region array. default_region: content # Place before any blocks already in the region. position: first plugin: system_powered_by_block NEW in Drupal 11.1
#[ConfigAction( id: 'permissions_per_bundle', entity_types: ['user_role'], deriver: PermissionsPerBundleDeriver::class, )] final class PermissionsPerBundle implements ConfigActionPluginInterface, ContainerFactoryPluginInterface { // Class properties and methods. } Con鍖g actions API There are two sets of actions currently supported by the API: 1. Actions that can be applied to con鍖guration of any con鍖guration entity type 2. Actions declared for methods of speci鍖c con鍖guration entity types Created by adding PHP attributes to a method declaration Anatomy of a recipe 24
Idempotency You should be able to reapply a recipe to the same site an unlimited number of times Some con鍖g should be provided using con鍖g actions like createIfNotExists Will probably need testing Anatomy of a recipe 25 Keep granular Better to have a collection of recipes Apply other recipes that are dependencies Publish! Directly to Packagist, or to drupal.org as a general project Recipe best practices
26
27
Anatomy of a recipe 28 A Drupal recipe can have a content directory. All content in this directory will be created after the con鍖guration is installed. For this, functionality has been taken from the default_content module and added to core. Speci鍖cally, the functionality that imports the content 鍖les is being added to core. Currently if you want to generate the content 鍖les as YAML that are needed to make this work, you need to use the default_content module. Content image?
Anatomy of a recipe 29 Export content as YAML from a Drupal project using the default_content module Add those YAML 鍖les to the /content folder in the structure that default_content generates The content will be validated and imported when the recipe is applied Add content to a recipe image?
Applying recipes
How to apply a recipe Applying recipes 31
How to apply a recipe Applying recipes 32 > php core/scripts/drupal recipe core/recipes/standard -v > ddev exec -d /var/www/html/web php core/scripts/drupal recipe ../recipes/events > drush recipe ../recipes/events
Recipe runner order 1. Apply other recipes 2. Install modules and themes 3. Import speci鍖ed con鍖guration 4. Import provided con鍖guration 5. Apply con鍖guration actions 6. Import content Applying recipes 33
RECIPES in core Recipes are conceived as composable, with any given recipe often requiring a chain of other recipes. But there's little practical sense as yet of just how this would work, or of what recommended patterns might be. 34 Core install pro鍖les as sets of recipes The process of converting the standard, minimal, and umami install pro鍖les to recipes allowed us to discover how a set of recipes can be composed to give us a speci鍖c result.
RECIPES in core if a site that used Minimal initially applies any given recipe from Standard, it should end up with something new that is ready to use. article_content_type page_content_type feedback_contact_form basic_html_format_editor full_html_format_editor editorial_work鍖ow image_media_type document_media_type [and more] 35 What recipes make up Standard-the-Recipe?
Cooking up something great
Phase 1 of the roadmap is complete The phase one goal was to create the ability to apply an arbitrary recipe to a Drupal install. Phase two is now on the works! Cooking up something Great Released in Drupal 10.3 and 11 as an experimental API 37
Anatomy of a recipe 38 Recipe class to read recipe.yml and composer.json Enable a recipe to apply other recipes prior to by applied itself Create recipe runner to process drupal-recipe recipe.yml 鍖les to install listed drupal extensions without their con鍖guration entities Extend recipe runner to allow recipe.yml to select con鍖guration from installed modules The roadmap - phase 1 Extend recipe runner to create con鍖guration provided in the recipe's /con鍖g folder Add the ability to de鍖ne con鍖guration actions in recipes Extend recipe runner to create content provided in the recipe's /content folder Add con鍖guration actions API
Timeline of recipes DrupalCon Portland 2022: Dries presents the idea of starter templates to help ambitious site builders to quickly and easily build out solutions DrupalCon Prague 2022: Alex Pott demonstrates a proof of concept that harnesses yml 鍖les to extend what we already have in con鍖g to create a recipe 2024: After months of work and QA by many contributors, the Standard Drupal Pro鍖le as a recipe is completed May 2022 Jan 2025 2022 to 2024: The Con鍖g Actions API is added in order to allow us to manipulate con鍖g in various ways and has been evolving continuously 2024: Con鍖g validation is introduced, allowing us to roll back the recipe if the con鍖guration doesnt validate properly. 39 2024: Phase 1 is completed and the MR is created to add Recipes to core Phase 2 begins 2024: Minimal and Umami pro鍖les are also converted into recipes 2024: Drupal 11 is released, containing many more con鍖guration actions 2024: Drupal CMS development drives a variety of Recipes API improvements 2024: Drupal 11.1 and 10.4 released with numerous new Recipe capabilities
What were working on
Unpacking recipes Recipes might require dependencies to be installed. If a recipe is removed, its dependencies will be also removed. Unpacking recipes dependencies solves this issue. Applying recipes 41
Con鍖g validation When applying a recipe, there was no real promise that it would work. Even if a recipe dont blow up while being applied, it would just leave a mess. This is now solved with validating validatable con鍖guration. Creating con鍖g storage checkpoint before applying a recipe. What were working on 42
Making con鍖g actions more dynamic When you used to create recipes and needed to apply a certain action to multiple bundles, youd have to create multiple lines of the same action to the list of bundles. Now, thanks to the community, we are able to run more dynamic con鍖g actions to support wildcards. What were working on 43 user.role.*: grantPermissions: - 'access content' core.entity_view_display.node.*.*: removeComponent: links field.field.media.*.field_tags: setSettings: auto_create: false user.role.media_creator: grantPermissionsPerMediaType: - 'create %bundle media' - 'edit own %bundle media' - 'delete own %bundle media' field.storage.node.field_tags: instantiateOnAllBundles: label: Tags description: 'Add some tags here.
What were working on 44 Building UI for applying recipes Hosting recipes on Drupal.org Recipe discovery Drupal recipe testing The roadmap - phase 2 Recipe unpacking in Core Ensure that recipes cannot be applied in parallel Allow for user input before applying e.g. Google Maps API key
Recipe maintainer and end user documentation Documentation currently lives in gitlab. There is a lot of work to be done to get the documentation ready for maintainers and end users. This is a great way to start contributing to recipes What were working on 45 Graphic here?
46 Join the initiative
Get involved! Recipe maintainer and end user documentation needed Developers and testers wanted test coverage Recipes wanted #recipes in Drupal Slack Join us in Slack meetings every other Tuesday at 1600 UTC Join us at contrib day at DrupalCon Join the initiative 47
Bon app辿tit!
Questions? @mandclu mandclu@acquia.com

More Related Content

Recipes! The Future of Drupal Site Building | Drupal CMS Launch | Toronto

  • 2. Martin Anderson-Clutz Senior Solutions Engineer Starshot Track Lead, Events Recipe @mandclu
  • 4. Agenda Why recipes? 1 Live demo - lets turn up the heat! 2 Anatomy of a recipe 3 Applying recipes 4 Cooking up something great 5 4 What were working on 6 Live demo - lets get cooking!
  • 6. Distributions and install pro鍖les have some issues They are dif鍖cult to keep updated They cannot be added after starting your project They can't be mixed and matched with other sets of functionality They are hard to discover before you install Drupal The problem: 6
  • 7. Recipes A lightweight way to quickly add con鍖guration to your site They can install modules but do not have any code of their own Composable from other Drupal recipes Applied to Drupal sites, they are not installed Easy to share Do not lock sites in The solution: 7
  • 8. Recipes An easy way to adopt and implement community-provided best practices The solution: 8
  • 9. 9 9 Giveaway! An exclusive pair of Drupal 11 sunglasses!
  • 11. Recipes Cookbook The Recipes Cookbook is a collection of contributed recipes. Get ideas and share ideas for: Site-starter recipes Functionality-speci鍖c recipes Recipe sets Add your own! What were working on 11
  • 13. con鍖g content composer.json recipes install con鍖g:import con鍖g:actions Anatomy of a recipe 13 recipe.yml recipes install con鍖g:import con鍖g:actions {}
  • 14. 14
  • 15. Set type as drupal-recipe Add module, recipe, or theme dependencies Suggest recipes that users might want to apply Anatomy of a recipe 15 { "name": "fourkitchens/sous-paragraphs", "description": "A collection of recipes and configuration for Sous with Paragraphs.", "keywords": ["recipe", "Drupal recipes", "drupal recipe"], "type": "drupal-recipe", "require": { "fourkitchens/sous-content-types": "dev-main", "fourkitchens/sous-paragraph-types": "dev-main", "drupal/paragraphs_features": "^2.0@beta" }, "suggest": { "fourkitchens/editorial": "A default editorial workflow." } } composer.json
  • 16. name description (optional) type (optional) Groups related Drupal recipes together. recipes (optional) List other recipes to be installed with it. Anatomy of a recipe 16 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types recipe.yml
  • 17. install (optional) List modules or themes to install, if they are not already During the install, simple con鍖guration from the new modules are imported Anatomy of a recipe 17 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types install: - paragraphs_ee - paragraphs_features recipe.yml
  • 18. con鍖g:import Import all available con鍖g from a module: * Specify which con鍖guration you want to import If you dont include instructions here, only simple con鍖g will be imported Anatomy of a recipe 18 name: 'Sous Paragraphs' description: 'A collection of recipes and configuration for Sous with Paragraphs.' type: 'Site' recipes: - sous-content-types install: - paragraphs_ee - paragraphs_features recipe.yml config: import: paragraphs_ee: '*' paragraphs_features: - paragraphs.paragraphs_type.cta
  • 19. con鍖g:actions An action has 3 parts: 1. Con鍖guration entity id 2. The action: must be one that's declared for the entity type of the con鍖guration entity 3. Action arguments, depending on: a. number of arguments that the action takes, and b. whether the action is in the singular or plural form Anatomy of a recipe 19 name: 'Sous Emulsify' description: 'A recipe that installs Emulsify dependencies and sets Emulsify as the default theme.' type: 'Site' install: - components - emulsify - emulsify_tools config: actions: system.theme: simpleConfigUpdate: default: emulsify recipe.yml
  • 20. simpleCon鍖gUpdate It can be used to make updates to any con鍖guration value createIfNotExists It can be used to conditionally create a con鍖g entity setComponent Add a component (e.g. 鍖eld) to a con鍖guration entity Anatomy of a recipe 20 create It can be used to create a con鍖g entity. setThirdPartySetting Allows the recipe author to set third-party settings values for any con鍖g entity that can have third-party settings Helpful for modules like Layout Builder and Scheduler that use these settings to provide or change functionality. Globally applicable entity actions And more!
  • 21. grantPermissions Con鍖g entity type: role Allows you to grant permissions to a role addNodeTypes, addTaxonomyVocabularies Con鍖g entity type: work鍖ows Allows you to add bundles into your content moderation work鍖ow Anatomy of a recipe 21 addToAllBundles Con鍖g entity type: 鍖eld Allows you to add a 鍖eld to all content types If the 鍖eld already exists on a content type, it will skip that content type addItemToToolbar Con鍖g entity type: editor Allows you to add a button to a CKEditor5 toolbar Con鍖g entity actions And many more!
  • 22. Add the same permission(s) to all user roles actions: user.role.*: grantPermissions: - 'access content' Affect every view display of every content type actions: core.entity_view_display.node.*.*: setComponent: name: 鍖eld_tags options: type: entity_reference_label Anatomy of a recipe 22 Change settings on every instance of a 鍖eld actions: 鍖eld.鍖eld.media.*.鍖eld_tags: simpleCon鍖gUpdate: foo: bar Create a view display (i.e., enabling a view mode) for every content type actions: core.entity_view_display.node.*.foo: createIfNotExists: # The contents of the view display here... Con鍖g entity wildcards
  • 23. placeBlockInDefaultTheme, placeBlockInAdminTheme Con鍖g entity type: block Theme name determined programmatically Pass an array of regions with a fallback Use 鍖rst or last keywords for placement within region Anatomy of a recipe 23 Actions for blocks config: actions: block.block.powered_first_default: placeBlockInDefaultTheme: id: powered_first # The region accepts an array keyed by theme name. region: bootstrap: footer gesso: page_bottom olivero: footer_top # Fallback if no match found in the region array. default_region: content # Place before any blocks already in the region. position: first plugin: system_powered_by_block NEW in Drupal 11.1
  • 24. #[ConfigAction( id: 'permissions_per_bundle', entity_types: ['user_role'], deriver: PermissionsPerBundleDeriver::class, )] final class PermissionsPerBundle implements ConfigActionPluginInterface, ContainerFactoryPluginInterface { // Class properties and methods. } Con鍖g actions API There are two sets of actions currently supported by the API: 1. Actions that can be applied to con鍖guration of any con鍖guration entity type 2. Actions declared for methods of speci鍖c con鍖guration entity types Created by adding PHP attributes to a method declaration Anatomy of a recipe 24
  • 25. Idempotency You should be able to reapply a recipe to the same site an unlimited number of times Some con鍖g should be provided using con鍖g actions like createIfNotExists Will probably need testing Anatomy of a recipe 25 Keep granular Better to have a collection of recipes Apply other recipes that are dependencies Publish! Directly to Packagist, or to drupal.org as a general project Recipe best practices
  • 26. 26
  • 27. 27
  • 28. Anatomy of a recipe 28 A Drupal recipe can have a content directory. All content in this directory will be created after the con鍖guration is installed. For this, functionality has been taken from the default_content module and added to core. Speci鍖cally, the functionality that imports the content 鍖les is being added to core. Currently if you want to generate the content 鍖les as YAML that are needed to make this work, you need to use the default_content module. Content image?
  • 29. Anatomy of a recipe 29 Export content as YAML from a Drupal project using the default_content module Add those YAML 鍖les to the /content folder in the structure that default_content generates The content will be validated and imported when the recipe is applied Add content to a recipe image?
  • 31. How to apply a recipe Applying recipes 31
  • 32. How to apply a recipe Applying recipes 32 > php core/scripts/drupal recipe core/recipes/standard -v > ddev exec -d /var/www/html/web php core/scripts/drupal recipe ../recipes/events > drush recipe ../recipes/events
  • 33. Recipe runner order 1. Apply other recipes 2. Install modules and themes 3. Import speci鍖ed con鍖guration 4. Import provided con鍖guration 5. Apply con鍖guration actions 6. Import content Applying recipes 33
  • 34. RECIPES in core Recipes are conceived as composable, with any given recipe often requiring a chain of other recipes. But there's little practical sense as yet of just how this would work, or of what recommended patterns might be. 34 Core install pro鍖les as sets of recipes The process of converting the standard, minimal, and umami install pro鍖les to recipes allowed us to discover how a set of recipes can be composed to give us a speci鍖c result.
  • 35. RECIPES in core if a site that used Minimal initially applies any given recipe from Standard, it should end up with something new that is ready to use. article_content_type page_content_type feedback_contact_form basic_html_format_editor full_html_format_editor editorial_work鍖ow image_media_type document_media_type [and more] 35 What recipes make up Standard-the-Recipe?
  • 37. Phase 1 of the roadmap is complete The phase one goal was to create the ability to apply an arbitrary recipe to a Drupal install. Phase two is now on the works! Cooking up something Great Released in Drupal 10.3 and 11 as an experimental API 37
  • 38. Anatomy of a recipe 38 Recipe class to read recipe.yml and composer.json Enable a recipe to apply other recipes prior to by applied itself Create recipe runner to process drupal-recipe recipe.yml 鍖les to install listed drupal extensions without their con鍖guration entities Extend recipe runner to allow recipe.yml to select con鍖guration from installed modules The roadmap - phase 1 Extend recipe runner to create con鍖guration provided in the recipe's /con鍖g folder Add the ability to de鍖ne con鍖guration actions in recipes Extend recipe runner to create content provided in the recipe's /content folder Add con鍖guration actions API
  • 39. Timeline of recipes DrupalCon Portland 2022: Dries presents the idea of starter templates to help ambitious site builders to quickly and easily build out solutions DrupalCon Prague 2022: Alex Pott demonstrates a proof of concept that harnesses yml 鍖les to extend what we already have in con鍖g to create a recipe 2024: After months of work and QA by many contributors, the Standard Drupal Pro鍖le as a recipe is completed May 2022 Jan 2025 2022 to 2024: The Con鍖g Actions API is added in order to allow us to manipulate con鍖g in various ways and has been evolving continuously 2024: Con鍖g validation is introduced, allowing us to roll back the recipe if the con鍖guration doesnt validate properly. 39 2024: Phase 1 is completed and the MR is created to add Recipes to core Phase 2 begins 2024: Minimal and Umami pro鍖les are also converted into recipes 2024: Drupal 11 is released, containing many more con鍖guration actions 2024: Drupal CMS development drives a variety of Recipes API improvements 2024: Drupal 11.1 and 10.4 released with numerous new Recipe capabilities
  • 41. Unpacking recipes Recipes might require dependencies to be installed. If a recipe is removed, its dependencies will be also removed. Unpacking recipes dependencies solves this issue. Applying recipes 41
  • 42. Con鍖g validation When applying a recipe, there was no real promise that it would work. Even if a recipe dont blow up while being applied, it would just leave a mess. This is now solved with validating validatable con鍖guration. Creating con鍖g storage checkpoint before applying a recipe. What were working on 42
  • 43. Making con鍖g actions more dynamic When you used to create recipes and needed to apply a certain action to multiple bundles, youd have to create multiple lines of the same action to the list of bundles. Now, thanks to the community, we are able to run more dynamic con鍖g actions to support wildcards. What were working on 43 user.role.*: grantPermissions: - 'access content' core.entity_view_display.node.*.*: removeComponent: links field.field.media.*.field_tags: setSettings: auto_create: false user.role.media_creator: grantPermissionsPerMediaType: - 'create %bundle media' - 'edit own %bundle media' - 'delete own %bundle media' field.storage.node.field_tags: instantiateOnAllBundles: label: Tags description: 'Add some tags here.
  • 44. What were working on 44 Building UI for applying recipes Hosting recipes on Drupal.org Recipe discovery Drupal recipe testing The roadmap - phase 2 Recipe unpacking in Core Ensure that recipes cannot be applied in parallel Allow for user input before applying e.g. Google Maps API key
  • 45. Recipe maintainer and end user documentation Documentation currently lives in gitlab. There is a lot of work to be done to get the documentation ready for maintainers and end users. This is a great way to start contributing to recipes What were working on 45 Graphic here?
  • 47. Get involved! Recipe maintainer and end user documentation needed Developers and testers wanted test coverage Recipes wanted #recipes in Drupal Slack Join us in Slack meetings every other Tuesday at 1600 UTC Join us at contrib day at DrupalCon Join the initiative 47