README.md updated

juanma-wp · Jan 6, 2025 · bafd9fc · bafd9fc
1 parent c1982ee
commit bafd9fc
Show file tree

Hide file tree

Showing 31 changed files with 1,029 additions and 307 deletions.
diff --git a/README.md b/README.md
diff --git a/plugins/basic-block-translations-3df23d/README.md b/plugins/basic-block-translations-3df23d/README.md
@@ -1,6 +1,14 @@
-# Basic Block Translation 3df23d
+# Block Internationalization Implementation
 
-The goal of this example is to showcase how to use translations in a block.
+This example demonstrates how to implement internationalization (i18n) in WordPress blocks, enabling your blocks to be translated into different languages. Learn how to properly set up translation files and functions for both PHP and JavaScript components of your blocks.
+
+Key concepts covered:
+
+-   Translation function implementation
+-   Language file organization
+-   PHP and JavaScript i18n
+-   Translation loading process
+-   Text domain handling
 
 <!-- Please, do not remove these @TABLE EXAMPLES BEGIN and @TABLE EXAMPLES END comments or modify the table inside. This table is automatically generated from the data at _data/examples.json and _data/tags.json -->
 <!-- @TABLE EXAMPLES BEGIN -->
@@ -11,19 +19,103 @@ The goal of this example is to showcase how to use translations in a block.
 
 ## Understanding the Example Code
 
-Both the `edit.js` and `save.js` files import the `__` function `@wordpress/i18n` to apply translations to the texts used in the code.
+### Translation Implementation
+
+1. **JavaScript Translation**
+
+    - Import translation functions
+    - Apply translations to strings
+    - Handle dynamic content
+    - Manage text domains
+
+2. **PHP Translation**
+    - Register translation files
+    - Load language resources
+    - Configure text domains
+    - Handle script translations
+
+### Technical Components
+
+1. **JavaScript Side**
+
+    ```javascript
+    import { __ } from '@wordpress/i18n';
+
+    // Translation in edit component
+    function Edit() {
+    	return (
+    		<div>
+    			<h2>
+    				{ __( 'Translatable Title', 'basic-block-translations' ) }
+    			</h2>
+    			<p>
+    				{ __(
+    					'This text can be translated',
+    					'basic-block-translations'
+    				) }
+    			</p>
+    		</div>
+    	);
+    }
+    ```
+
+2. **PHP Side**
+    ```php
+    // Register translations for JavaScript
+    function setup_translations() {
+        wp_set_script_translations(
+            'basic-block-translations-editor-script',
+            'basic-block-translations',
+            plugin_dir_path(__FILE__) . 'languages'
+        );
+    }
+    add_action('init', 'setup_translations');
+    ```
+
+### Translation Structure
+
+1. **Language Files**
+
+    ```
+    languages/
+    ├── basic-block-translations.pot     # Template file
+    ├── basic-block-translations-es_ES.po # Spanish translations
+    ├── basic-block-translations-es_ES.mo # Compiled Spanish
+    └── ...                              # Other languages
+    ```
+
+2. **Translation Process**
+    - Extract translatable strings
+    - Create POT template
+    - Create language-specific PO files
+    - Compile to MO format
+
+### Best Practices
+
+-   Use translation functions consistently
+-   Provide meaningful text domains
+-   Include translator comments
+-   Maintain context information
+-   Keep strings translatable
 
--   The [`__` function](https://developer.wordpress.org/reference/functions/__/) receives the text and a namespace as parameters
--   At `index.php` we tell WordPress our JavaScript contains translations, using the `wp_set_script_translations()` function.
--   At `languages/` folder there are all the translations files (the source files and the `.mo` ones actually used to apply the translations)
+-   The [`__` function](https://developer.wordpress.org/reference/functions/__/) receives the
+    text and a namespace as parameters
+-   At `index.php` we tell WordPress our JavaScript contains translations, using the
+    `wp_set_script_translations()` function.
+-   At `languages/` folder there are all the translations files (the source files and the `.mo`
+    ones actually used to apply the translations)
 
-## Related resources
+## Related Resources
 
--   [Internationalization](https://developer.wordpress.org/block-editor/how-to-guides/internationalization/)
+-   [WordPress i18n Documentation](https://developer.wordpress.org/block-editor/how-to-guides/internationalization/)
+-   [Translation Functions](https://developer.wordpress.org/reference/functions/__/)
+-   [Script Translation Setup](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)
+-   [Language File Management](https://developer.wordpress.org/plugins/internationalization/)
+-   [Block Editor i18n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/)
 -   [`__()`](https://developer.wordpress.org/reference/functions/__/)
 -   [`wp_set_script_translations()`](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)
 
 ---
 
 > **Note**
-> Check the [Start Guide for local development with the examples](https://github.com/WordPress/block-development-examples/wiki/02-Examples#start-guide-for-local-development-with-the-examples)
+> Check the [Start Guide for local development with the examples](https://github.com/juanma-wp/block-development-examples/wiki/Examples#start-guide-for-local-development-with-the-examples)
diff --git a/plugins/basic-esnext-a2ab62/README.md b/plugins/basic-esnext-a2ab62/README.md
@@ -1,6 +1,14 @@
-### Block Development Examples - Basic Esnext a2ab62
+# Basic Block with ESNext and Build Process
 
-The goal of this example is to show how to create a basic block with ESNext and JSX syntax and a build process.
+This example demonstrates how to create a modern WordPress block using ESNext (modern JavaScript) and JSX syntax. It showcases the fundamental setup required for block development with a build process powered by `@wordpress/scripts`, which handles all the necessary tooling configuration.
+
+Key concepts covered:
+
+-   Modern JavaScript (ESNext) and JSX syntax usage
+-   Build process setup with `@wordpress/scripts`
+-   Basic block registration and rendering
+-   Static block implementation
+-   NPM scripts for development and production builds
 
 <!-- Please, do not remove these @TABLE EXAMPLES BEGIN and @TABLE EXAMPLES END comments or modify the table inside. This table is automatically generated from the data at _data/examples.json and _data/tags.json -->
 <!-- @TABLE EXAMPLES BEGIN -->
@@ -11,13 +19,64 @@ The goal of this example is to show how to create a basic block with ESNext and
 
 ## Understanding the Example Code
 
-This is a static block (check `src/save.js`) that requires a `build` version that can be registered as a block. To do that the `wp-scripts` provide very handy scripts such as `npm start` and `npm run build`.
+### Build Process
+
+1. **Development Mode**
+
+    - Uses `npm start` for development
+    - Provides hot reloading
+    - Generates source maps for debugging
+    - Watches for file changes
+
+2. **Production Build**
+    - Uses `npm run build` for production
+    - Optimizes and minifies code
+    - Generates production-ready assets
+    - Performs tree shaking
+
+### Block Implementation
+
+1. **Block Registration**
+
+    - Block metadata defined in `block.json`
+    - Registered using `registerBlockType`
+    - Uses modern ESNext syntax for cleaner code
+
+2. **Rendering**
+    - Static block implementation in `save.js`
+    - Uses JSX for template rendering
+    - Implements `useBlockProps` for block attributes
+
+### File Structure
+
+```
+src/
+├── edit.js      # Block editor component
+├── save.js      # Saved content component
+├── style.scss   # Frontend & editor styles
+├── editor.scss  # Editor-only styles
+├── block.json   # Block metadata
+└── index.js     # Block registration
+```
+
+### Best Practices
+
+-   Use ESNext features appropriately
+-   Follow WordPress coding standards
+-   Implement proper error handling
+-   Add meaningful comments
+-   Keep components modular
+
+## Related Resources
 
-## Related resources
+-   [Block Editor Handbook - Getting Started](https://developer.wordpress.org/block-editor/getting-started/)
+-   [ESNext Standard](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#esnext)
+-   [Block Registration API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/)
+-   [@wordpress/scripts Package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
+-   [Static vs Dynamic Blocks](https://developer.wordpress.org/block-editor/getting-started/fundamentals/#static-or-dynamic-rendering-of-a-block)
+-   [Block Metadata](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)
 
-- [Block Editor Handbook > Getting Started](https://developer.wordpress.org/block-editor/getting-started/)
-- [Block Editor Handbook > Fundamentals of Block Development > Static or Dynamic rendering of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/)
-- [Block Editor Handbook > Fundamentals of Block Development > Registration of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/)
+---
 
 > **Note**
-> Check the [Start Guide for local development with the examples](https://github.com/WordPress/block-development-examples/wiki/02-Examples#start-guide-for-local-development-with-the-examples)
+> Check the [Start Guide for local development with the examples](https://github.com/juanma-wp/block-development-examples/wiki/Examples#start-guide-for-local-development-with-the-examples)
diff --git a/plugins/block-dynamic-rendering-64756b/README.md b/plugins/block-dynamic-rendering-64756b/README.md
@@ -1,6 +1,14 @@
-# Block Dynamic Rendering 64756b
+# Dynamic Block Rendering Implementation
 
-The goal of this example is to showcase the implementation of blocks with dynamic rendering.
+This example demonstrates how to create WordPress blocks that render their content dynamically on the server side. Unlike static blocks, dynamic blocks generate their output at runtime, making them ideal for content that needs to be updated based on the latest data or server-side logic.
+
+Key concepts covered:
+
+-   Dynamic block rendering
+-   Server-side PHP rendering
+-   Block attribute handling
+-   WordPress render callback
+-   Real-time content generation
 
 <!-- Please, do not remove these @TABLE EXAMPLES BEGIN and @TABLE EXAMPLES END comments or modify the table inside. This table is automatically generated from the data at _data/examples.json and _data/tags.json -->
 <!-- @TABLE EXAMPLES BEGIN -->
@@ -11,13 +19,75 @@ The goal of this example is to showcase the implementation of blocks with dynami
 
 ## Understanding the Example Code
 
-Overview of the code in bullet point form.
+### Dynamic Rendering Implementation
+
+1. **Block Registration**
+
+    ```javascript
+    import { registerBlockType } from '@wordpress/blocks';
+    import { useBlockProps } from '@wordpress/block-editor';
+
+    registerBlockType( 'block-development-examples/dynamic-rendering', {
+    	edit: function Edit( { attributes, setAttributes } ) {
+    		const blockProps = useBlockProps();
+    		return (
+    			<div { ...blockProps }>
+    				<p>Editor View: Content will be rendered dynamically</p>
+    			</div>
+    		);
+    	},
+    	// No save function needed - rendering handled by PHP
+    	save: function () {
+    		return null;
+    	},
+    } );
+    ```
+
+2. **PHP Render Callback**
+
+Render Callback is defined via [a `render.php` file](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/) as defined on `block.json`
+
+### Technical Components
+
+1. **Block Configuration**
+
+    ```json
+    {
+    	"apiVersion": 2,
+    	"name": "block-development-examples/dynamic-rendering",
+    	"title": "Dynamic Rendering Block",
+    	"category": "widgets",
+    	"icon": "update",
+    	"description": "Block with dynamic server-side rendering.",
+    	"supports": {
+    		"html": false
+    	},
+    	"textdomain": "dynamic-rendering",
+    	"editorScript": "file:./index.js",
+    	"render": "file:./render.php"
+    }
+    ```
+
+2. **Block Registration Process**
+
+```php
+function block_dynamic_rendering_64756b___register_block() {
+	register_block_type( __DIR__ . '/build' );
+}
+add_action( 'init', 'block_dynamic_rendering_64756b___register_block' );
+```
+
+## Related Resources
 
-## Related resources
+-   [Fundamentals of Block Development](https://developer.wordpress.org/block-editor/getting-started/fundamentals/)
 
-Bulleted list of references
+-   [Dynamic Block Documentation](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/)
+-   [Server-Side Rendering](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/block-attributes-and-server-side-rendering/)
+-   [Block Attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)
+-   [WordPress Security](https://developer.wordpress.org/plugins/security/)
+-   [Block Registration](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/)
 
-----
+---
 
 > **Note**
-> Check the [Start Guide for local development with the examples](https://github.com/WordPress/block-development-examples/wiki/02-Examples#start-guide-for-local-development-with-the-examples)
+> Check the [Start Guide for local development with the examples](https://github.com/juanma-wp/block-development-examples/wiki/Examples#start-guide-for-local-development-with-the-examples) >