This file contains the readme information for the block. It is used to provide information about the block, its usage, and any other relevant details.{name} - {position}
{{/team_members}}
```
= How do I use conditionals? =
Use the `{{#if}}...{{/if}}` syntax. You can check if a field exists, equals a value, or doesn't equal a value:
```html
{{#if field}}
Content if field exists and is not empty
{{/if}}
{{#if status = active}}
Content if status equals "active"
{{/if}}
{{#if status != draft}}
Content if status is not "draft"
{{/if}}
{{#if featured}}
Featured content
{{#elseif popular}}
Popular content
{{#else}}
Regular content
{{/if}}
```
= How do I display image galleries? =
Gallery fields work the same as repeaters. Use `{{gallery_field}}` with image sub-fields like `{url}`, `{alt}`, `{caption}` to loop through all images.
Example:
```html
{{gallery}}
{{/gallery}}
```
= What types of ACF fields are supported? =
The block supports:
* **Simple fields**: text, textarea, number, email, url, wysiwyg, etc.
* **Group fields**: access sub-fields using colon notation `{group:subfield}`
* **Repeater fields**: loop through rows with `{{repeater}}...{{/repeater}}`
* **Gallery fields**: loop through images (exposes `{url}`, `{alt}`, `{caption}`, `{width}`, `{height}`, etc.)
* **Image fields**: automatically extracts the URL
* **Link fields**: extracts url, title, and target
* **True/False fields**: use with conditionals for show/hide logic
= Do I need Advanced Custom Fields installed? =
Yes, this block requires **Advanced Custom Fields** (free or PRO version) to be installed and activated. Without ACF, the block will display a message asking you to install it.
= Can I use HTML tags? =
Yes! You can use any HTML markup along with your ACF field tags. The block preserves your HTML structure while replacing the field tags with actual values. All HTML is sanitized using WordPress security functions.
= Can I nest repeaters or conditionals? =
Currently, nested repeaters and nested conditionals are not supported. However, you can use repeaters and conditionals at the same level and combine them with group fields for complex layouts.
= Does this work with ACF PRO features? =
Yes, the block works with both ACF free and PRO versions. It supports all standard field types including those exclusive to PRO like repeaters, flexible content (as repeaters), and gallery fields.
= Where can I get support? =
For support, please visit the plugin's support forum on WordPress.org or contact AgilePress directly.
== Screenshots ==
1. Block editor showing the sidebar settings panel with HTML content and ACF field tags
2. Inspector panel displaying the comprehensive syntax guide including conditionals
3. Frontend display with ACF values automatically replaced
4. Example of a repeater field loop displaying team members
5. Example of group field access for structured data
6. Gallery field loop displaying multiple images
7. Conditional content display based on field values
== Changelog ==
= 1.1.0 =
* Enhanced conditional syntax documentation
* Improved syntax guide clarity in the editor
* Updated documentation for if/elseif/else structure
* Minor bug fixes and improvements
= 1.0.0 =
* Initial public release
* Support for simple ACF field tags using `{field_name}` syntax
* Support for group fields using `{group:subfield}` syntax
* Support for repeater and gallery loops using `{{field}}...{{/field}}` syntax
* Support for conditional blocks using `{{#if}}...{{/if}}` syntax
* Conditional comparisons with `=` and `!=` operators
* Support for `{{#elseif}}` and `{{#else}}` in conditionals
* HTML content editor with comprehensive syntax guide
* Real-time preview in the editor with syntax highlighting
* Security: All output properly escaped following WordPress standards
* Compatibility: Works with ACF free and PRO versions
* Tested with WordPress 6.8 and PHP 8.x
== Usage Examples ==
**Example 1 - Simple field display:**
```html
{{/if}}
```
== Additional Information ==
**Security:**
All field values are properly escaped using WordPress security functions (`esc_html()`, `esc_url()`, `wp_kses_post()`) to prevent XSS attacks and ensure safe output.
**Performance:**
The block uses WordPress native functions and ACF's optimized field retrieval methods. Field values are processed server-side during render, ensuring optimal frontend performance.
**Compatibility:**
* WordPress 6.1+ (tested up to 6.9)
* PHP 7.0+ (tested up to 8.3)
* ACF free version 5.0+
* ACF PRO 5.0+
* Classic and Block themes
**Developer Notes:**
The block follows WordPress coding standards and uses proper namespacing (`agilepress_` prefix). All code is well-documented and follows best practices for WordPress plugin development.]]>This file contains metadata about the block including its name, title, category, icon, and other properties.\n
Location: {latitud}, {longitud}
\n"
}
},
"attributes": {
"content": {
"type": "string",
"default": ""
}
},
"supports": {
"html": false,
"anchor": true,
"align": true
},
"textdomain": "agilepress-content-block-for-acf",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css",
"render": "file:./render.php"
}]]>This file registers the block, specifies the edit and save functions, and loads the block's metadataThis file contains the edit function for the block which is responsible for rendering the block in the editor. {
setAttributes( { content: newContent } );
};
/**
* Basic sanitization to prevent XSS in the editor preview.
* Removes script tags and on* attributes.
*
* @param {string} html The raw HTML.
* @return {string} Sanitized HTML.
*/
const sanitizePreview = ( html ) => {
if ( ! html ) return '';
return html
.replace( /]*>([\s\S]*?)<\/script>/gim, '' ) // Remove scripts
.replace( /<[^>]+>/gim, ( tag ) => {
// Remove event handlers like onclick, onmouseover, etc. from tags
return tag.replace( /\son[a-z]+\s*=\s*['"]([^'"]*)['"']'/gim, '' );
} );
};
// Replace ACF tags with placeholder text for preview
const getPreviewContent = () => {
if ( ! content ) {
return '';
}
// 1. Sanitize first to prevent XSS in the editor
let preview = sanitizePreview( content );
// 2. Highlight conditional blocks
preview = preview.replace(
/\{\{#if ([^}]+)\}\}(.*?)(?:\{\{#elseif ([^}]+)\}\}(.*?))*(?:\{\{#else\}\}(.*?))?\{\{\/if\}\}/gs,
( match ) => {
return `
{ __(
'Add HTML content with ACF field tags in the sidebar settings.',
'agilepress-content-block-for-acf'
) }
) }
);
}]]>This file contains the save function for the block which is responsible for creating the static result of rendering the block on the client to display the saved result on the front end.This file contains styles for the block in the front end.This file contains styles for the block in the editor.This file contains the view function for the block which is responsible for rendering interactive behaviors of the block on the front end.This file contains the render callback function for the block, which is responsible for rendering the block content on the front end.
%2$s
',
get_block_wrapper_attributes(),
esc_html__( 'Advanced Custom Fields plugin is required.', 'agilepress-content-block-for-acf' )
);
}
/**
* Process ACF conditional blocks with {{#if}}...{{/if}} syntax
* Supports:
* - {{#if field}} - checks if field exists and is truthy
* - {{#if field = value}} - checks if field equals value
* - {{#if field != value}} - checks if field does not equal value
* - {{#elseif field}} - alternative condition
* - {{#else}} - fallback
*/
// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound -- Template variable, not a global
$agilepress_acf_block_processed = preg_replace_callback(
'/\{\{#if ([^}]+)\}\}(.*?)(?:\{\{#elseif ([^}]+)\}\}(.*?))*(?:\{\{#else\}\}(.*?))?\{\{\/if\}\}/s',
function( $matches ) use ( $agilepress_acf_block_post_id ) {
$condition = trim( $matches[1] );
$if_content = $matches[2];
$else_content = isset( $matches[5] ) ? $matches[5] : '';
// Parse condition: field, field = value, or field != value
$field_name = '';
$operator = 'exists';
$compare_value = '';
if ( strpos( $condition, '!=' ) !== false ) {
$parts = array_map( 'trim', explode( '!=', $condition, 2 ) );
$field_name = $parts[0];
$operator = '!=';
$compare_value = isset( $parts[1] ) ? $parts[1] : '';
} elseif ( strpos( $condition, '=' ) !== false ) {
$parts = array_map( 'trim', explode( '=', $condition, 2 ) );
$field_name = $parts[0];
$operator = '=';
$compare_value = isset( $parts[1] ) ? $parts[1] : '';
} else {
$field_name = $condition;
}
// Get field value
$field_value = get_field( $field_name, $agilepress_acf_block_post_id );
// Evaluate condition
$condition_met = false;
if ( 'exists' === $operator ) {
$condition_met = ! empty( $field_value );
} elseif ( '=' === $operator ) {
$condition_met = ( (string) $field_value === (string) $compare_value );
} elseif ( '!=' === $operator ) {
$condition_met = ( (string) $field_value !== (string) $compare_value );
}
return $condition_met ? $if_content : $else_content;
},
$agilepress_acf_block_content
);
/**
* Process ACF repeater/gallery loops with {{field_name}}...{{/field_name}} syntax
*/
// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound -- Template variable, not a global
$agilepress_acf_block_processed = preg_replace_callback(
'/\{\{([^}]+)\}\}(.*?)\{\{\/\1\}\}/s',
function( $matches ) use ( $agilepress_acf_block_post_id ) {
$field_name = trim( $matches[1] );
$template = $matches[2];
$field_value = get_field( $field_name, $agilepress_acf_block_post_id );
// Handle repeater fields.
if ( is_array( $field_value ) && ! empty( $field_value ) ) {
$output = '';
foreach ( $field_value as $row ) {
$row_output = $template;
// Determine if it's a gallery (image array) or a normal repeater.
$is_gallery = ( isset( $row['url'] ) && isset( $row['alt'] ) );
$row_output = preg_replace_callback(
'/\{([^}:]+)\}/',
function( $sub_matches ) use ( $row, $is_gallery ) {
$sub_field = trim( $sub_matches[1] );
$value = '';
if ( $is_gallery ) {
// Gallery logic: field names are keys of the image array.
if ( isset( $row[ $sub_field ] ) ) {
$value = $row[ $sub_field ];
}
} else {
// Repeater logic.
if ( isset( $row[ $sub_field ] ) ) {
$value = $row[ $sub_field ];
}
}
// Handle URL explicitly for security inside tags.
if ( 'url' === $sub_field || 'link' === $sub_field || ( is_array( $value ) && isset( $value['url'] ) ) ) {
$url_val = is_array( $value ) ? $value['url'] : $value;
return esc_url( $url_val );
}
// Return raw value (can be HTML). It will be sanitized by wp_kses_post at the end.
// If value is array/object and not handled above, return empty to avoid errors.
if ( is_array( $value ) || is_object( $value ) ) {
return '';
}
return $value;
},
$row_output
);
$output .= $row_output;
}
return $output;
}
return '';
},
$agilepress_acf_block_processed
);
/**
* Process ACF group fields with {group_name:sub_field_name} syntax
*/
// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound -- Template variable, not a global
$agilepress_acf_block_processed = preg_replace_callback(
'/\{([^}:]+):([^}]+)\}/',
function( $matches ) use ( $agilepress_acf_block_post_id ) {
$group_name = trim( $matches[1] );
$sub_field_name = trim( $matches[2] );
$group_value = get_field( $group_name, $agilepress_acf_block_post_id );
if ( is_array( $group_value ) && isset( $group_value[ $sub_field_name ] ) ) {
$field_value = $group_value[ $sub_field_name ];
if ( is_array( $field_value ) && isset( $field_value['url'] ) ) {
return esc_url( $field_value['url'] );
}
if ( is_string( $field_value ) || is_numeric( $field_value ) ) {
return $field_value; // Raw return, sanitized later.
}
}
// If field not found, return original string to avoid breaking CSS/JS that uses braces.
return $matches[0];
},
$agilepress_acf_block_processed
);
/**
* Replace simple ACF field tags with actual field values
*/
// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound -- Template variable, not a global
$agilepress_acf_block_processed = preg_replace_callback(
'/\{([^}:]+)\}/',
function( $matches ) use ( $agilepress_acf_block_post_id ) {
$field_name = trim( $matches[1] );
// Get the field value.
$field_value = get_field( $field_name, $agilepress_acf_block_post_id );
// If get_field returns null, the field does not exist in ACF.
// We return the original match to avoid breaking CSS/JS {curly braces}.
if ( null === $field_value ) {
return $matches[0];
}
// Handle array returns (like Image or Link objects).
if ( is_array( $field_value ) ) {
if ( isset( $field_value['url'] ) ) {
return esc_url( $field_value['url'] );
} elseif ( isset( $field_value['value'] ) ) {
return $field_value['value'];
}
return '';
}
if ( false !== $field_value ) {
return $field_value; // Raw return, sanitized later.
}
return '';
},
$agilepress_acf_block_processed
);
// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound
$agilepress_acf_block_wrapper_attributes = get_block_wrapper_attributes();
?>
>
]]>This file contains the block registration code in the form of a single block plugin.
