D5 :: 3PS :: Example Modules :: Migrate Legacy Types

README.md

@@ -12,7 +12,7 @@ composer install
 
 ### Node.js Dependencies
 
-You need to have **npm** available in your node.js environment. And make sure to use **node version: 18.0.0 or later**.
+You need to have **npm** available in your node.js environment. Use **Node.js 20.18.1 or later** (required by transitive dependencies such as `undici@7.x`; Node `20.18.0` will fail `npm install` when `engine-strict` is enabled).
 
 For D5 modules only:
 ```
@@ -118,17 +118,17 @@ It will install dependencies for Divi 5 modules. For D4 modules, you need to run
 ### `npm run start`
 It will start the webpack compiler for development with watch mode. By default, it works for D5 modules. For D4 modules, you need to run `npm run start:divi-4`. You can also use `npm run start:all` to start both D5 and D4 modules.
 
-_Note: If you see error messages for divi packages related to `placeholderContent` in `npm run start` and `npm run start:all`, this is a known issue and it will be fixed once we update `divi-types` npm packages. You can continue developing despite the error messages._
+_Note: Divi Visual Builder type definitions are installed from scoped `@divi/*` npm packages (see [Release 5.1](https://dev.elegantthemes.com/docs/blog/release-5.1)). Install only the `@divi/*` packages your code imports; npm will pull related type dependencies as needed._
 
 ### `npm run build`
 It will build all JS and CSS assets for production. By default, it works for D5 modules. For D4 modules, you need to run `npm run build:divi-4`. You can also use `npm run build:all` to build assets for both Divi 5 and Divi 4 modules.
 
-_Note: If you see error messages for divi packages related to `placeholderContent` in `npm run build` and `npm run build:all`, this is a known issue and it will be fixed once we update `divi-types` npm packages._
+_Note: If TypeScript reports missing types for a `@divi/*` import, add that package to `devDependencies` in `package.json` and run `npm install`._
 
 ### `npm run reset-install`
 It will remove node_modules and reinstall all dependencies for D5 modules. For D4 modules, you need to run `npm run reset-install:divi-4`.
 
-_Note: If you are facing error for divi packages in `npm run install`, then you need to run `npm run reset-install` command._
+_Note: If you are facing errors for `@divi/*` packages in `npm run install`, run `npm run reset-install` to refresh `node_modules` and `package-lock.json`._
 
 ### `npm run zip`
 It will zip all assets and files without the `src` folder for distribution.

modules/D4Module/D4ModuleTrait/ModuleStylesTrait.php

@@ -15,7 +15,6 @@
 use ET\Builder\FrontEnd\Module\Style;
 use ET\Builder\Packages\Module\Layout\Components\StyleCommon\CommonStyle;
 use ET\Builder\Packages\Module\Options\Css\CssStyle;
-use ET\Builder\Packages\Module\Options\Text\TextStyle;
 
 trait ModuleStylesTrait {
 
@@ -67,15 +66,20 @@ public static function module_styles( $args ) {
 								'disabledOn'               => [
 									'disabledModuleVisibility' => $settings['disabledModuleVisibility'] ?? null,
 								],
+								'advancedStyles'           => [
+									[
+										'componentName' => 'divi/text',
+										'props'         => [
+											// Module root only — .example_d4_module_inner is reserved for Layout flex (see module.json styleProps.layout).
+											'selector'                => $order_class,
+											'attr'                    => $attrs['module']['advanced']['text'] ?? [],
+											'defaultPrintedStyleAttr' => $default_printed_style_attrs['module']['advanced']['text'] ?? [],
+										],
+									],
+								],
 							],
 						]
 					),
-					TextStyle::style(
-						[
-							'selector' => $order_class . ' .example_d4_module_inner',
-							'attr'     => $attrs['module']['advanced']['text'] ?? [],
-						]
-					),
 					// Set the `.example_d4_module_inner` element `position` to `relative` if the background image has parallax enabled.
 					CommonStyle::style(
 						[
@@ -88,7 +92,7 @@ public static function module_styles( $args ) {
 									return 'position: relative;';
 								}
 
-								return 'position: relative;';
+								return '';
 							},
 						]
 					),

modules/D4Module/D4ModuleTrait/RenderCallbackTrait.php

@@ -14,37 +14,38 @@
 
 // phpcs:disable ET.Sniffs.ValidVariableName.UsedPropertyNotSnakeCase -- WP use snakeCase in \WP_Block_Parser_Block
 
-use ET\Builder\Packages\Module\Module;
-use ET\Builder\Framework\Utility\HTMLUtility;
 use ET\Builder\FrontEnd\BlockParser\BlockParserStore;
-use ET\Builder\Packages\Module\Options\Element\ElementComponents;
+use ET\Builder\Framework\Utility\HTMLUtility;
+use ET\Builder\Packages\Module\Module;
+use ET\Builder\Packages\ModuleUtils\ChildrenUtils;
 
 trait RenderCallbackTrait {
 	use ModuleClassnamesTrait;
 	use ModuleStylesTrait;
 	use ModuleScriptDataTrait;
+
 	/**
 	 * Divi 4 module render callback which outputs server side rendered HTML on the Front-End.
 	 *
 	 * @since ??
 	 *
-	 * @param array          $attrs Block attributes that were saved by VB.
-	 * @param string         $content          Block content.
-	 * @param \WP_Block      $block            Parsed block object that being rendered.
-	 * @param ModuleElements $elements ModuleElements instance.
+	 * @param array          $attrs                       Block attributes that were saved by VB.
+	 * @param string         $content                     Rendered inner blocks (Elements children).
+	 * @param \WP_Block      $block                       Parsed block object that being rendered.
+	 * @param \ET\Builder\Packages\Module\Layout\Components\ModuleElements\ModuleElements $elements ModuleElements instance.
+	 * @param array          $_default_printed_style_attrs Optional. Passed by ModuleRegistration.
 	 *
 	 * @return string HTML rendered of D4 module.
 	 */
-	public static function render_callback( $attrs, $content, $block, $elements ) {
-		// Background component.
-		$background_component = ElementComponents::component(
-			[
-				'attrs'         => $attrs['module']['decoration'] ?? [],
-				'id'            => $block->parsed_block['id'],
+	public static function render_callback( $attrs, $content, $block, $elements, $_default_printed_style_attrs = [] ) {
+		$inner_blocks_html = $content;
 
-				// FE only.
-				'orderIndex'    => $block->parsed_block['orderIndex'],
-				'storeInstance' => $block->parsed_block['storeInstance'],
+		// Extract child module IDs from the block's innerBlocks.
+		$children_ids = ChildrenUtils::extract_children_ids( $block );
+
+		$module_styles_markup = $elements->style_components(
+			[
+				'attrName' => 'module',
 			]
 		);
 
@@ -55,24 +56,34 @@ public static function render_callback( $attrs, $content, $block, $elements ) {
 			]
 		);
 
-		// Content.
-		$content = $elements->render(
+		// Main content field (do not shadow $inner_blocks_html).
+		$richtext_content = $elements->render(
 			[
 				'attrName'          => 'content',
 				'childrenSanitizer' => 'et_core_esc_previously',
 			]
 		);
 
+		// Layout classes for inner container.
+		$layout_display_value = $attrs['module']['decoration']['layout']['desktop']['value']['display'] ?? 'flex';
+		$inner_classes        = HTMLUtility::classnames(
+			'example_d4_module_inner',
+			[
+				'et_flex_module' => 'flex' === $layout_display_value,
+				'et_grid_module' => 'grid' === $layout_display_value,
+			]
+		);
+
 		$inner_content = HTMLUtility::render(
 			[
 				'tag'               => 'div',
 				'attributes'        => [
-					'class' => 'example_d4_module_inner',
+					'class' => $inner_classes,
 				],
 				'childrenSanitizer' => 'et_core_esc_previously',
 				'children'          => [
 					$title,
-					$content,
+					$richtext_content,
 				],
 			]
 		);
@@ -98,7 +109,12 @@ public static function render_callback( $attrs, $content, $block, $elements ) {
 				'parentAttrs'         => $parent_attrs,
 				'parentId'            => $parent->id ?? '',
 				'parentName'          => $parent->blockName ?? '',
-				'children'            => $background_component . $inner_content,
+				'childrenIds'         => $children_ids,
+				'children'            => [
+					$module_styles_markup,
+					$inner_content,
+					$inner_blocks_html,
+				],
 			]
 		);
 	}

modules/DynamicModule/DynamicModuleTrait/ModuleStylesTrait.php

@@ -68,8 +68,10 @@ public static function module_styles( $args ) {
 									[
 										'componentName' => 'divi/text',
 										'props'         => [
-											'selector' => $order_class . ' .example_dynamic_module__inner',
-											'attr'     => $attrs['module']['advanced']['text'] ?? [],
+											// Module root only — __inner is reserved for Layout flex (see module.json styleProps.layout).
+											'selector'                => $order_class,
+											'attr'                    => $attrs['module']['advanced']['text'] ?? [],
+											'defaultPrintedStyleAttr' => $default_printed_style_attrs['module']['advanced']['text'] ?? [],
 										],
 									],
 								],

modules/DynamicModule/DynamicModuleTrait/RenderCallbackTrait.php

@@ -14,11 +14,10 @@
 
 // phpcs:disable ET.Sniffs.ValidVariableName.UsedPropertyNotSnakeCase -- WP use snakeCase in \WP_Block_Parser_Block
 
-use ET\Builder\Packages\Module\Module;
 use ET\Builder\FrontEnd\BlockParser\BlockParserStore;
 use ET\Builder\Framework\Utility\HTMLUtility;
-use ET\Builder\Packages\Module\Layout\Components\ModuleElements\ModuleElements;
-use ET\Builder\Packages\Module\Options\Element\ElementComponents;
+use ET\Builder\Packages\Module\Module;
+use ET\Builder\Packages\ModuleUtils\ChildrenUtils;
 
 trait RenderCallbackTrait {
 	use ModuleClassnamesTrait;
@@ -30,25 +29,24 @@ trait RenderCallbackTrait {
 	 *
 	 * @since ??
 	 *
-	 * @param array          $attrs    Block attributes that were saved by VB.
-	 * @param string         $content  Block content.
-	 * @param \WP_Block      $block    Parsed block object that being rendered.
-	 * @param ModuleElements $elements ModuleElements instance.
+	 * @param array          $attrs                       Block attributes that were saved by VB.
+	 * @param string         $content                     Rendered inner blocks (Elements children).
+	 * @param \WP_Block      $block                       Parsed block object that being rendered.
+	 * @param \ET\Builder\Packages\Module\Layout\Components\ModuleElements\ModuleElements $elements ModuleElements instance.
+	 * @param array          $_default_printed_style_attrs Optional. Passed by ModuleRegistration.
 	 *
 	 * @return string HTML rendered of Dynamic module.
 	 */
-	public static function render_callback( $attrs, $content, $block, $elements ) {
+	public static function render_callback( $attrs, $content, $block, $elements, $_default_printed_style_attrs = [] ) {
+		// Extract child module IDs from the block's innerBlocks.
+		$children_ids = ChildrenUtils::extract_children_ids( $block );
+
 		$post_heading_level = $attrs['postTitle']['decoration']['font']['font']['desktop']['value']['headingLevel'];
 		$posts_per_page     = $attrs['postItems']['innerContent']['desktop']['value']['postsNumber'];
 
-		$background_component = ElementComponents::component(
+		$module_styles_markup = $elements->style_components(
 			[
-				'attrs'         => $attrs['module']['decoration'] ?? [],
-				'id'            => $block->parsed_block['id'],
-
-				// FE only.
-				'orderIndex'    => $block->parsed_block['orderIndex'],
-				'storeInstance' => $block->parsed_block['storeInstance'],
+				'attrName' => 'module',
 			]
 		);
 
@@ -146,6 +144,16 @@ public static function render_callback( $attrs, $content, $block, $elements ) {
 		$parent       = BlockParserStore::get_parent( $block->parsed_block['id'], $block->parsed_block['storeInstance'] );
 		$parent_attrs = $parent->attrs ?? [];
 
+		// Layout classes for inner container.
+		$layout_display_value = $attrs['module']['decoration']['layout']['desktop']['value']['display'] ?? 'flex';
+		$inner_classes        = HTMLUtility::classnames(
+			'example_dynamic_module__inner',
+			[
+				'et_flex_module' => 'flex' === $layout_display_value,
+				'et_grid_module' => 'grid' === $layout_display_value,
+			]
+		);
+
 		return Module::render(
 			[
 				// FE only.
@@ -164,13 +172,14 @@ public static function render_callback( $attrs, $content, $block, $elements ) {
 				'parentAttrs'         => $parent_attrs,
 				'parentId'            => $parent->id ?? '',
 				'parentName'          => $parent->blockName ?? '',
+				'childrenIds'         => $children_ids,
 				'children'            => [
-					$background_component,
+					$module_styles_markup,
 					HTMLUtility::render(
 						[
 							'tag'               => 'div',
 							'attributes'        => [
-								'class' => 'example_dynamic_module__inner',
+								'class' => $inner_classes,
 							],
 							'childrenSanitizer' => 'et_core_esc_previously',
 							'children'          => [
@@ -179,6 +188,7 @@ public static function render_callback( $attrs, $content, $block, $elements ) {
 							],
 						]
 					),
+					$content,
 				],
 			]
 		);

modules/ModuleSettingsDemo/ModuleSettingsDemo.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Module: Module Settings Demo class.
+ *
+ * @package MEE\Modules\ModuleSettingsDemo
+ * @since ??
+ */
+
+namespace MEE\Modules\ModuleSettingsDemo;
+
+if ( ! defined( 'ABSPATH' ) ) {
+	die( 'Direct access forbidden.' );
+}
+
+use ET\Builder\Framework\DependencyManagement\Interfaces\DependencyInterface;
+use ET\Builder\Packages\ModuleLibrary\ModuleRegistration;
+use MEE\Modules\ModuleSettingsDemo\ModuleSettingsDemoTrait;
+
+/**
+ * Module Settings Demo dependency for field component demonstrations.
+ *
+ * @since ??
+ */
+class ModuleSettingsDemo implements DependencyInterface {
+	use ModuleSettingsDemoTrait\RenderCallbackTrait;
+
+	/**
+	 * Loads Module Settings Demo and registers front-end render callback.
+	 *
+	 * @since ??
+	 */
+	public function load() {
+		$module_json_folder_path = D5_EXTENSION_EXAMPLE_MODULES_JSON_PATH . 'module-settings-demo/';
+
+		add_action(
+			'init',
+			function() use ( $module_json_folder_path ) {
+				ModuleRegistration::register_module(
+					$module_json_folder_path,
+					[
+						'render_callback' => [ ModuleSettingsDemo::class, 'render_callback' ],
+					]
+				);
+			}
+		);
+	}
+}

modules/ModuleSettingsDemo/ModuleSettingsDemoTrait/CustomCssTrait.php

@@ -0,0 +1,25 @@
+<?php
+/**
+ * ModuleSettingsDemo::custom_css().
+ *
+ * @package MEE\Modules\ModuleSettingsDemo
+ * @since ??
+ */
+
+namespace MEE\Modules\ModuleSettingsDemo\ModuleSettingsDemoTrait;
+
+if ( ! defined( 'ABSPATH' ) ) {
+	die( 'Direct access forbidden.' );
+}
+
+trait CustomCssTrait {
+
+	/**
+	 * Custom CSS fields.
+	 *
+	 * @since ??
+	 */
+	public static function custom_css() {
+		return \WP_Block_Type_Registry::get_instance()->get_registered( 'example/module-settings-demo' )->customCssFields;
+	}
+}