From f4cb584c171725ae3948833098d4ee9bcea50a48 Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Wed, 14 Jan 2026 10:16:56 -0600 Subject: [PATCH 1/9] Enhance features documentation for Secure Custom Fields Expanded the features section to provide a comprehensive overview of Secure Custom Fields, including core features, content management, field types, developer tools, performance, security, compatibility, and extensibility. --- docs/features/index.md | 182 ++++++++++++++++++++++++++++++----------- 1 file changed, 134 insertions(+), 48 deletions(-) diff --git a/docs/features/index.md b/docs/features/index.md index 04b471b9..6aebe5aa 100644 --- a/docs/features/index.md +++ b/docs/features/index.md @@ -1,53 +1,139 @@ # Features -This section details all features available in Secure Custom Fields. +This section provides an overview of all features available in **Secure Custom Fields (SCF)**. +SCF offers full feature parity with ACF Pro while focusing on performance, security, and developer experience. + +--- ## Core Features -- [Post Types](post-types) - Create and manage custom post types -- [Fields](fields) - Available field types and their usage -- [API](api) - Programmatic access and integration - -## Feature Categories - -1. **Content Management** - - Custom post types - - Custom taxonomies - - Field groups - -2. **Field Types** - - Basic fields (text, textarea, etc.) - - Advanced fields (repeater, flexible content) - - Special fields (relationship, clone) - -3. **Developer Tools** - - API endpoints - - Hooks and filters - - Helper functions - -## Available Fields - -- [Accordion](fields/accordion) - Group fields into collapsible sections -- [Button Group](fields/button-group) - Select one option from a group of buttons -- [Checkbox](fields/checkbox) - Select one or more choices -- [Clone](fields/clone) - Duplicate and reuse existing field configurations -- [Color Picker](fields/color-picker) - Choose colors with a visual picker -- [Date Picker](fields/date-picker) - Select dates from a calendar -- [Date/Time Picker](fields/date-time-picker) - Select dates and times -- [Email](fields/email) - Input and validate email addresses -- [File](fields/file) - Upload and manage files -- [Flexible Content](fields/flexible-content) - Create flexible content layouts -- [Gallery](fields/gallery) - Manage collections of images -- [Google Map](fields/google-map) - Add location data with Google Maps -- [Group](fields/group) - Group fields together -- [Icon Picker](fields/icon-picker) - Select from available icons -- [Image](fields/image) - Upload and manage images -- [Link](fields/link) - Create links with titles and targets -- [Message](fields/message) - Display instructional text -- [Number](fields/number) - Input numeric values -- [oEmbed](fields/oembed) - Embed external content -- [Page Link](fields/page-link) - Link to internal content -- [Password](fields/password) - Securely input passwords -- [Post Object](fields/post-object) - Relate to other posts -- [Radio](fields/radio) - Select one choice from options -- [Range](fields/range) - Select a numeric value with a slider +- [Field Groups](field-groups) – Organize and manage custom fields +- [Location Rules](location-rules) – Control where field groups appear +- [Post Types](post-types) – Create and manage custom post types +- [Taxonomies](taxonomies) – Register and manage custom taxonomies +- [Options Pages](options-pages) – Create global settings pages +- [Blocks](blocks) – Build custom Gutenberg blocks powered by SCF fields +- [Conditional Logic](conditional-logic) – Show or hide fields dynamically +- [API](api) – Programmatic access via PHP and JavaScript + +--- + +## Content Management + +SCF provides flexible tools for structuring and managing content. + +- [Custom Post Types](post-types) +- [Custom Taxonomies](taxonomies) +- [Field Groups](field-groups) +- [Location Rules](location-rules) +- [Options Pages](options-pages) +- [Blocks](blocks) + +--- + +## Field Capabilities + +Beyond field types, SCF fields support advanced configuration options. + +- [Conditional Logic](conditional-logic) +- [Field Validation](validation) +- [Default Values](default-values) +- [Instructions & Messages](fields/message) +- [Field Wrapper Settings](field-wrapper) +- [Read-only & Disabled Fields](read-only-fields) + +--- + +## Field Types + +### Basic Fields + +- [Text](fields/text) +- [Textarea](fields/textarea) +- [Number](fields/number) +- [Email](fields/email) +- [Password](fields/password) +- [Range](fields/range) +- [Color Picker](fields/color-picker) +- [Date Picker](fields/date-picker) +- [Date/Time Picker](fields/date-time-picker) + +### Advanced Fields + +- [Repeater](fields/repeater) +- [Flexible Content](fields/flexible-content) +- [Group](fields/group) +- [Clone](fields/clone) + +### Relationship & Content Fields + +- [Post Object](fields/post-object) +- [Page Link](fields/page-link) +- [Link](fields/link) +- [Relationship](fields/relationship) +- [Taxonomy](fields/taxonomy) +- [User](fields/user) + +### Media & Special Fields + +- [Image](fields/image) +- [Gallery](fields/gallery) +- [File](fields/file) +- [oEmbed](fields/oembed) +- [Google Map](fields/google-map) +- [Icon Picker](fields/icon-picker) +- [Accordion](fields/accordion) +- [Button Group](fields/button-group) +- [Checkbox](fields/checkbox) +- [Radio](fields/radio) +- [Message](fields/message) + +--- + +## Developer Tools + +SCF is designed with developers in mind. + +- [PHP API](api/php) +- [JavaScript API](api/javascript) +- [Hooks & Filters](hooks) +- [Local JSON Sync](local-json) +- [Export & Import](export-import) +- [Register Fields via Code](register-fields) +- [REST API Compatibility](rest-api) + +--- + +## Performance & Security + +Secure Custom Fields focuses on clean, secure, and efficient execution. + +- Lightweight and optimized core +- Minimal admin assets loading +- Sanitized and escaped output +- Secure file handling +- Permission-based field access +- WordPress coding standards compliant + +--- + +## Compatibility + +SCF integrates seamlessly with the WordPress ecosystem. + +- Gutenberg and Classic Editor support +- WordPress REST API compatible +- WooCommerce friendly +- Multisite ready +- Theme and plugin agnostic + +--- + +## Extensibility + +Extend SCF to fit advanced or custom workflows. + +- [Custom Field Types](custom-field-types) +- [Third-Party Field Extensions](extensions) +- [Custom Field Renderers](rendering) +- [Developer Hooks](hooks) From 8d338e2d5179b914f941eb06d50ca480511f86cf Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Mon, 19 Jan 2026 12:40:47 -0600 Subject: [PATCH 2/9] Revise Checkbox field documentation for clarity Updated the Checkbox field documentation to enhance clarity and detail, including examples and best practices for use cases in a movie website context. --- docs/features/field/checkbox/index.md | 219 ++++++++++++++++++++++++-- 1 file changed, 207 insertions(+), 12 deletions(-) diff --git a/docs/features/field/checkbox/index.md b/docs/features/field/checkbox/index.md index 62b6fe2a..33b47692 100644 --- a/docs/features/field/checkbox/index.md +++ b/docs/features/field/checkbox/index.md @@ -1,18 +1,213 @@ # Checkbox Field -The Checkbox field allows users to select one or multiple choices from a set of options. It's ideal for situations where multiple selections are needed or when users need to toggle specific options on/off. +The **Checkbox** field allows editors to select one or multiple predefined values from a list of options. It is ideal for storing flexible, multi-value data while keeping the editing experience simple and controlled. -## Key Features +Throughout this document, examples are based on a **movie website**, where editors manage metadata such as genres, features, and content flags for films. -- Multiple option selection -- Toggle individual choices -- Customizable checkbox layout -- Flexible return format +--- -## Settings +## What is it? -- Choices - Define the available options -- Default Value - Set pre-selected options -- Layout - Choose between vertical or horizontal layout -- Allow Custom - Enable user-added choices -- Toggle All - Option to select/deselect all choices +The Checkbox field is a selectable input field that presents a list of choices, each with its own label and value. Editors can select **zero, one, or multiple options** depending on how the field is configured. + +Each selected option is stored as part of the field’s value and can be retrieved and used in templates, conditional logic, or integrations. + +--- + +## How does it work? + +When a Checkbox field is added to a field group: + +- SCF renders a list of checkboxes in the WordPress admin. +- Each checkbox represents a predefined choice (label → value). +- Editors can select multiple options simultaneously. +- The selected values are stored as an **array** (or a structured format, depending on settings). + +SCF automatically handles saving, sanitizing, and retrieving the selected values so developers can work with predictable data structures. + +--- + +## What is it for? + +Use the Checkbox field when: + +- Multiple attributes can apply at the same time. +- You want to restrict values to a known set. +- Content requires classification without using taxonomies. +- Field values drive conditional behavior in templates or UI. + +### Movie website use cases + +On a movie website, Checkbox fields are commonly used for: + +- **Movie genres** (Action, Drama, Comedy, Sci‑Fi) +- **Content flags** (Featured, Recommended, Editors’ Pick) +- **Audience suitability** (Kids Friendly, Violence, Mature Themes) +- **Distribution formats** (Streaming, Blu‑ray, Cinema Release) + +--- + +## Usage + +### Add a Checkbox field in the admin + +1. Go to **SCF → Field Groups**. +2. Create or edit a field group assigned to the **Movie** post type. +3. Click **Add Field**. +4. Select **Checkbox** as the field type. +5. Define the available **Choices**. +6. Configure layout and return options. +7. Save the field group. + +### Example: Movie genres + +**Choices** +``` +action : Action +drama : Drama +comedy : Comedy +scifi : Science Fiction +thriller : Thriller +``` + +### Field settings + +Key settings available for the Checkbox field: + +- **Choices** + Defines the available options (one per line or via array in code). + +- **Default Value** + Automatically preselects options for new movies. + +- **Layout** + Vertical (recommended for long lists) or horizontal. + +- **Toggle** + Adds a “Select All / Deselect All” control. + +- **Return Format** + - Value + - Label + - Both (array containing value and label) + +- **Allow Custom** + Allows editors to add custom values beyond predefined choices. + +### Best practices for movie data + +- Use **stable values** (`action`, `drama`) and human-friendly labels. +- Avoid enabling “Allow Custom” for genres to keep data consistent. +- Keep the list concise; use taxonomies if the list becomes large or global. +- Document how genres are used in filters or templates. + +--- + +## Next Steps + +- Combine Checkbox fields with conditional logic (e.g., show “Awards” section only if “Featured” is checked). +- Create standardized Checkbox sets for all movie-related content. +- Review existing movies when adding or removing options. +- Migrate to taxonomies if querying by genre becomes complex. + +--- + +## For Developers + +### Registering a Checkbox field for movies + +The following example registers a Checkbox field for selecting movie genres on a custom post type called `movie`. + +```php + 'group_movie_details', + 'title' => 'Movie Details', + 'fields' => array( + array( + 'key' => 'field_movie_genres', + 'label' => 'Genres', + 'name' => 'movie_genres', + 'type' => 'checkbox', + 'choices' => array( + 'action' => 'Action', + 'drama' => 'Drama', + 'comedy' => 'Comedy', + 'scifi' => 'Science Fiction', + 'thriller' => 'Thriller', + ), + 'layout' => 'vertical', + 'return_format' => 'value', + 'toggle' => 1, + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +### Rendering genres on a movie page + +In a theme template (e.g., `single-movie.php`), you can display the selected genres like this: + +```php + +
+

Genres

+
    + +
    • + +
+
+ Date: Mon, 19 Jan 2026 12:47:52 -0600 Subject: [PATCH 3/9] Enhance Button Group field documentation Expanded documentation for the Button Group field in SCF, detailing its features, usage, and best practices for both editors and developers. Included examples and code snippets for better understanding. --- docs/features/field/button-group/index.md | 250 +++++++++++++++++++++- 1 file changed, 239 insertions(+), 11 deletions(-) diff --git a/docs/features/field/button-group/index.md b/docs/features/field/button-group/index.md index ea4c38f9..40fd1431 100644 --- a/docs/features/field/button-group/index.md +++ b/docs/features/field/button-group/index.md @@ -1,17 +1,245 @@ # Button Group Field -The Button Group field provides a set of buttons where users can select one option from multiple choices. It offers a more visual and user-friendly alternative to radio buttons or select dropdowns. +The **Button Group** field in Secure Custom Fields (SCF) provides a clear and user-friendly way to select **one option from a predefined set**. It presents choices as clickable buttons instead of checkboxes or dropdowns, making selections faster, more visual, and less error‑prone. -## Key Features +This documentation uses a **movie website** as a real-world scenario, showing how Button Group fields can be applied effectively by both non-technical editors and developers. -- Visual button-style interface -- Single option selection -- Customizable button labels -- Clear visual indication of selected option +--- -## Settings +## What is it? -- Choices - Define the available options -- Default Value - Set the pre-selected option -- Return Format - Specify how the value should be returned -- Allow Null - Option to have no selection +The Button Group field is a **single-choice selection field**. Unlike Checkbox fields (which allow multiple selections), a Button Group allows **only one value to be selected at a time**. + +Each option is displayed as a button with a clear label, helping editors immediately understand available choices and current selection. + +Button Group fields store a **single value**, making them ideal for mutually exclusive states or modes. + +--- + +## How does it work? + +When a Button Group field is added to a field group: + +1. SCF displays all predefined options as clickable buttons. +2. Editors select exactly **one** option. +3. Selecting a button automatically deselects the others. +4. SCF stores the selected value in the database. +5. The value can later be retrieved and used in templates or logic. + +Because only one option can be stored, the returned value is always **predictable and consistent**, simplifying both editorial workflows and development. + +--- + +## What is it for? + +Use the Button Group field when content requires a **clear, exclusive choice**. + +### Ideal use cases + +- Selecting a single mode or state +- Choosing between layout or display variants +- Setting visibility or priority levels +- Replacing dropdowns where clarity is critical + +### Movie website examples + +On a movie website, Button Group fields are commonly used for: + +- **Movie status** + Upcoming · Now Showing · Archived + +- **Audience rating** + G · PG · PG-13 · R + +- **Primary format** + Streaming · Cinema · Blu-ray + +- **Highlight level** + Normal · Featured · Editor’s Pick + +These values are often used to control labels, badges, filters, or page behavior. + +--- + +## Usage + +### Adding a Button Group field (for editors) + +1. Go to **SCF → Field Groups**. +2. Create or edit a field group assigned to the **Movie** post type. +3. Click **Add Field**. +4. Select **Button Group** as the field type. +5. Define the available **Choices**. +6. Configure default value and return format. +7. Save the field group. + +Editors will see a row of buttons when editing a movie, with one active selection at all times. + +--- + +### Defining choices + +Each choice consists of a **stored value** and a **label**. + +Example (Movie Status): + +``` +upcoming : Upcoming +showing : Now Showing +archived : Archived +``` + +- The value (`upcoming`) is stored in the database. +- The label (`Upcoming`) is shown to editors. + +--- + +### Field settings explained + +#### Choices +Defines the available options. Button Groups work best with **small, focused sets** (typically 2–5 options). + +#### Default Value +Specifies which option is preselected for new content. This helps guide editors and avoids empty states. + +#### Return Format +Controls what is returned when retrieving the field: +- **Value** – returns the stored value (recommended) +- **Label** – returns the human-readable label +- **Both** – returns value and label together + +#### Layout +Controls how buttons are displayed: +- **Horizontal** (default and recommended) +- **Vertical** (useful for longer labels) + +--- + +### Best practices for editors + +- Choose the option that best represents the movie’s current state. +- Avoid changing values after publication unless intentionally updating behavior. +- Follow editorial guidelines to ensure consistency. +- If unsure which option to select, consult internal documentation. + +--- + +## Next Steps + +After implementing Button Group fields: + +- Use the selected value to display badges or labels. +- Apply conditional logic to adjust layouts or features. +- Combine with Checkbox fields for advanced configurations. +- Audit values periodically to ensure relevance. + +--- + +## For Developers + +### Registering a Button Group field for movies + +The following example registers a Button Group field for selecting a movie’s release status. + +```php + 'group_movie_status', + 'title' => 'Movie Status', + 'fields' => array( + array( + 'key' => 'field_movie_status', + 'label' => 'Release Status', + 'name' => 'movie_status', + 'type' => 'button_group', + 'choices' => array( + 'upcoming' => 'Upcoming', + 'showing' => 'Now Showing', + 'archived' => 'Archived', + ), + 'default_value' => 'upcoming', + 'return_format' => 'value', + 'layout' => 'horizontal', + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +--- + +### Rendering the Button Group value + +In a movie template (`single-movie.php`): + +```php + + + + + Date: Mon, 19 Jan 2026 12:52:24 -0600 Subject: [PATCH 4/9] Revise Checkbox field documentation for clarity Updated the Checkbox field documentation to clarify usage, examples, and best practices. Improved language for better understanding and consistency. --- docs/features/field/checkbox/index.md | 150 +++++++++++++++----------- 1 file changed, 88 insertions(+), 62 deletions(-) diff --git a/docs/features/field/checkbox/index.md b/docs/features/field/checkbox/index.md index 33b47692..7cdbee2c 100644 --- a/docs/features/field/checkbox/index.md +++ b/docs/features/field/checkbox/index.md @@ -1,16 +1,16 @@ # Checkbox Field -The **Checkbox** field allows editors to select one or multiple predefined values from a list of options. It is ideal for storing flexible, multi-value data while keeping the editing experience simple and controlled. +The **Checkbox** field allows users to select **one or multiple options** from a predefined list. It provides a flexible and intuitive way to assign multiple attributes to a piece of content, while maintaining structured and consistent data. -Throughout this document, examples are based on a **movie website**, where editors manage metadata such as genres, features, and content flags for films. +This documentation follows WordPress.org guidelines and is written for **both non-technical editors and developers**, using a **movie website** as a real-world example. --- ## What is it? -The Checkbox field is a selectable input field that presents a list of choices, each with its own label and value. Editors can select **zero, one, or multiple options** depending on how the field is configured. +The Checkbox field is a **multi-choice selection field**. Each option is displayed as an individual checkbox, allowing editors to select **any number of applicable values**, including none or all. -Each selected option is stored as part of the field’s value and can be retrieved and used in templates, conditional logic, or integrations. +Each selected option is stored as part of the field’s value and can later be retrieved and used in templates, conditional logic, or integrations. --- @@ -18,50 +18,73 @@ Each selected option is stored as part of the field’s value and can be retriev When a Checkbox field is added to a field group: -- SCF renders a list of checkboxes in the WordPress admin. -- Each checkbox represents a predefined choice (label → value). -- Editors can select multiple options simultaneously. -- The selected values are stored as an **array** (or a structured format, depending on settings). +1. SCF displays a list of checkboxes in the WordPress admin. +2. Each checkbox represents a predefined option. +3. Editors can select multiple options simultaneously. +4. The selected values are saved when the post is updated. +5. The values are returned in a structured format based on field settings. -SCF automatically handles saving, sanitizing, and retrieving the selected values so developers can work with predictable data structures. +SCF manages all data handling automatically, ensuring consistent behavior for both editors and developers. --- ## What is it for? -Use the Checkbox field when: +Use the Checkbox field when **multiple attributes can apply at the same time**. -- Multiple attributes can apply at the same time. -- You want to restrict values to a known set. -- Content requires classification without using taxonomies. -- Field values drive conditional behavior in templates or UI. +### Movie website examples -### Movie website use cases +On a movie website, Checkbox fields are ideal for: -On a movie website, Checkbox fields are commonly used for: +- **Movie genres** + Action, Drama, Comedy, Science Fiction, Thriller -- **Movie genres** (Action, Drama, Comedy, Sci‑Fi) -- **Content flags** (Featured, Recommended, Editors’ Pick) -- **Audience suitability** (Kids Friendly, Violence, Mature Themes) -- **Distribution formats** (Streaming, Blu‑ray, Cinema Release) +- **Content flags** + Featured, Award Winner, Editor’s Pick + +- **Audience notes** + Family Friendly, Contains Violence, Mature Themes + +- **Availability options** + Streaming Available, Cinema Release, Home Media + +These selections can later be used for filtering, labeling, or conditional display. + +--- + +## Key Features + +- Allows multiple selections +- Clear checkbox-based interface +- Customizable option labels +- Optional “Select All / Deselect All” toggle +- Structured and predictable stored values --- ## Usage -### Add a Checkbox field in the admin +### Adding a Checkbox field (for editors) 1. Go to **SCF → Field Groups**. -2. Create or edit a field group assigned to the **Movie** post type. +2. Create or edit a field group. 3. Click **Add Field**. 4. Select **Checkbox** as the field type. 5. Define the available **Choices**. 6. Configure layout and return options. -7. Save the field group. +7. Assign the field group to the desired location (for example, the Movie post type). +8. Save the field group. + +Editors will see a list of checkboxes when editing a movie. + +--- -### Example: Movie genres +## Settings -**Choices** +### Choices +Defines the available options. Each choice consists of a stored value and a label. + +Example (Movie Genres): ``` action : Action drama : Drama @@ -70,45 +93,46 @@ scifi : Science Fiction thriller : Thriller ``` -### Field settings - -Key settings available for the Checkbox field: - -- **Choices** - Defines the available options (one per line or via array in code). +### Default Value +Specifies which options are preselected for new content. -- **Default Value** - Automatically preselects options for new movies. +### Return Format +Controls how the value is returned: +- **Value** – returns stored values (recommended) +- **Label** – returns human-readable labels +- **Both** – returns both value and label -- **Layout** - Vertical (recommended for long lists) or horizontal. +### Layout +Controls how checkboxes are displayed: +- Vertical (recommended for readability) +- Horizontal (best for short lists) -- **Toggle** - Adds a “Select All / Deselect All” control. +### Toggle +Adds a **Select All / Deselect All** control, useful for long option lists. -- **Return Format** - - Value - - Label - - Both (array containing value and label) +### Allow Custom +Allows editors to add custom values not defined in the choices list. +Use with caution, as it reduces data consistency. -- **Allow Custom** - Allows editors to add custom values beyond predefined choices. +--- -### Best practices for movie data +## Best practices for editors -- Use **stable values** (`action`, `drama`) and human-friendly labels. -- Avoid enabling “Allow Custom” for genres to keep data consistent. -- Keep the list concise; use taxonomies if the list becomes large or global. -- Document how genres are used in filters or templates. +- Select only options that truly apply to the movie. +- Avoid using checkboxes as free-form notes. +- Follow established editorial guidelines. +- If unsure about an option, consult internal documentation. --- ## Next Steps -- Combine Checkbox fields with conditional logic (e.g., show “Awards” section only if “Featured” is checked). -- Create standardized Checkbox sets for all movie-related content. -- Review existing movies when adding or removing options. -- Migrate to taxonomies if querying by genre becomes complex. +After implementing Checkbox fields: + +- Use selected values to filter or group movie listings. +- Display visual badges based on selections. +- Combine with Button Group fields for mixed configurations. +- Review and clean up unused options periodically. --- @@ -128,8 +152,8 @@ add_action( 'acf/init', function () { acf_add_local_field_group( array( - 'key' => 'group_movie_details', - 'title' => 'Movie Details', + 'key' => 'group_movie_genres', + 'title' => 'Movie Genres', 'fields' => array( array( 'key' => 'field_movie_genres', @@ -162,9 +186,9 @@ add_action( 'acf/init', function () { } ); ``` -### Rendering genres on a movie page +--- -In a theme template (e.g., `single-movie.php`), you can display the selected genres like this: +### Rendering Checkbox values in a movie template ```php Date: Mon, 19 Jan 2026 12:55:45 -0600 Subject: [PATCH 5/9] Enhance Clone field documentation with detailed usage Expanded documentation on the Clone field, including usage, key features, best practices, and examples for both editors and developers. Enhanced clarity and detail for better understanding of functionality. --- docs/features/field/clone/index.md | 236 ++++++++++++++++++++++++++++- 1 file changed, 228 insertions(+), 8 deletions(-) diff --git a/docs/features/field/clone/index.md b/docs/features/field/clone/index.md index 74bb0c4a..49ceea80 100644 --- a/docs/features/field/clone/index.md +++ b/docs/features/field/clone/index.md @@ -1,17 +1,237 @@ # Clone Field -The Clone field allows you to reuse existing fields or field groups in multiple locations. This helps maintain consistency and reduces the need to recreate commonly used field configurations. +The **Clone** field allows you to **reuse existing fields or entire field groups** in multiple locations. It helps maintain consistency, reduce duplication, and centralize changes, making it especially valuable for large or long‑term projects. + +This documentation follows WordPress.org guidelines and is written for **both non-technical editors and developers**, using a **movie website** as a consistent real‑world example. + +--- + +## What is it? + +The Clone field is a **field reuse mechanism**. Instead of creating the same fields repeatedly, you can reference existing fields or field groups and display them wherever they are needed. + +Cloned fields: +- Share the same configuration as the original +- Stay synchronized when the original is updated +- Can optionally use prefixed labels and names to avoid conflicts + +This makes the Clone field ideal for enforcing standardized content structures. + +--- + +## How does it work? + +When a Clone field is added to a field group: + +1. You select one or more existing fields or field groups. +2. SCF renders those fields as if they were defined locally. +3. Any changes to the original field configuration are reflected everywhere it is cloned. +4. Values are stored and retrieved like normal fields, respecting prefixes if applied. + +From an editor’s perspective, cloned fields behave exactly like regular fields. From a developer’s perspective, they reduce maintenance and improve consistency. + +--- + +## What is it for? + +Use the Clone field when you want to **reuse common field sets** across multiple content types or sections. + +### Movie website examples + +On a movie website, Clone fields are commonly used for: + +- **SEO metadata** + Title override, meta description, social image + +- **Credits blocks** + Director, Producer, Cast, Runtime + +- **Media sections** + Poster image, trailer URL, gallery + +- **Call‑to‑action blocks** + Primary button text and link + +Instead of redefining these fields for every post type, they can be defined once and reused everywhere. + +--- ## Key Features -- Copy existing field configurations +- Reuse existing field configurations - Clone individual fields or entire field groups -- Prefix labels to avoid naming conflicts -- Maintain synchronized settings across cloned instances +- Maintain synchronized settings across all cloned instances +- Prefix labels to avoid editor confusion +- Prefix field names to prevent data conflicts +- Reduce duplication and long‑term maintenance cost + +--- + +## Usage + +### Adding a Clone field (for editors) + +1. Go to **SCF → Field Groups**. +2. Edit a field group. +3. Click **Add Field**. +4. Select **Clone** as the field type. +5. Choose the fields or field groups to clone. +6. Configure display and prefix settings. +7. Save the field group. + +Editors will see the cloned fields rendered inline, just like regular fields. + +--- ## Settings -- Select Fields - Choose which fields or groups to clone -- Display - Control how the cloned fields appear -- Prefix Label - Add a prefix to cloned field labels -- Prefix Name - Add a prefix to cloned field names +### Select Fields +Choose which existing fields or field groups should be cloned. Multiple selections are supported. + +### Display +Controls how cloned fields appear: +- **Seamless** – cloned fields appear as part of the current group +- **Grouped** – cloned fields are visually grouped together + +### Prefix Label +Adds a prefix to field labels (for example, “SEO: Title”), helping editors understand context. + +### Prefix Name +Adds a prefix to field names to avoid naming collisions when the same field is cloned multiple times. + +--- + +## Best practices for editors + +- Treat cloned fields like normal fields when editing content. +- Follow naming and labeling conventions provided by your team. +- Do not worry about configuration changes—those are managed centrally. +- If something looks duplicated, it is likely intentional reuse. + +--- + +## Next Steps + +After implementing Clone fields: + +- Identify other repeated field sets and refactor them into reusable groups. +- Standardize SEO, media, and CTA blocks across all movie content. +- Document shared field groups so editors understand their purpose. +- Periodically review cloned structures to ensure they remain relevant. + +--- + +## For Developers + +### Creating reusable field groups + +A common pattern is to define reusable field groups (for example, SEO fields) and then clone them where needed. + +```php + 'group_movie_seo', + 'title' => 'SEO Fields', + 'fields' => array( + array( + 'key' => 'field_seo_title', + 'label' => 'SEO Title', + 'name' => 'seo_title', + 'type' => 'text', + ), + array( + 'key' => 'field_seo_description', + 'label' => 'SEO Description', + 'name' => 'seo_description', + 'type' => 'textarea', + ), + ), + ) + ); +} ); +``` + +--- + +### Cloning the field group into a Movie post type + +```php + 'group_movie_content', + 'title' => 'Movie Content', + 'fields' => array( + array( + 'key' => 'field_clone_movie_seo', + 'label' => 'SEO', + 'name' => '', + 'type' => 'clone', + 'clone' => array( + 'group_movie_seo', + ), + 'display' => 'seamless', + 'prefix_label' => 1, + 'prefix_name' => 0, + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +--- + +### Retrieving cloned field values + +Cloned fields are retrieved exactly like normal fields: + +```php + Date: Mon, 19 Jan 2026 13:08:20 -0600 Subject: [PATCH 6/9] Enhance Color Picker field documentation Expanded documentation for the Color Picker field, detailing its features, usage, and best practices for both editors and developers. Added examples and clarified return formats. --- docs/features/field/color-picker/index.md | 206 +++++++++++++++++++++- 1 file changed, 200 insertions(+), 6 deletions(-) diff --git a/docs/features/field/color-picker/index.md b/docs/features/field/color-picker/index.md index 924fa4c1..99d927f6 100644 --- a/docs/features/field/color-picker/index.md +++ b/docs/features/field/color-picker/index.md @@ -1,17 +1,211 @@ # Color Picker Field -The Color Picker field provides an interactive interface for selecting colors. It supports both RGB and RGBA color formats and includes a visual color picker with opacity control. +The **Color Picker** field provides an interactive interface for selecting colors within the WordPress admin. It supports **RGB and RGBA** color formats, includes a visual picker with **opacity control**, and allows precise **HEX input**. This makes it ideal for design-related settings where visual accuracy and consistency matter. + +This documentation follows WordPress.org guidelines and is written for **both non-technical editors and developers**, using a **movie website** as a consistent real-world example. + +--- + +## What is it? + +The Color Picker field is a **single-value design field** that lets editors choose a color visually or by entering a color code. The selected color is stored in a standardized format and can be used to control styling, branding accents, or UI highlights across a site. + +Depending on configuration, the field can return: +- A color string (HEX or RGBA) +- A structured array +- An RGBA value with transparency + +--- + +## How does it work? + +When a Color Picker field is added to a field group: + +1. SCF displays a visual color picker in the WordPress admin. +2. Editors select a color using the picker or enter a HEX value manually. +3. (Optional) Editors adjust opacity if transparency is enabled. +4. The selected color is saved with the post. +5. The value is returned in the configured format and can be used in templates or styles. + +For editors, the experience is visual and intuitive. For developers, the output is predictable and easy to integrate. + +--- + +## What is it for? + +Use the Color Picker field when content needs **visual customization** without manual CSS editing. + +### Movie website examples + +On a movie website, Color Picker fields are commonly used for: + +- **Hero section accent color** +- **Genre badge colors** +- **Highlight color for featured movies** +- **Overlay color for trailers or posters** +- **Theme accents for special releases** + +These colors can be applied dynamically to enhance branding and visual storytelling. + +--- ## Key Features - Visual color selection interface - RGB and RGBA color support -- Opacity/transparency control +- Opacity / transparency control - Default color presets -- Hex color input +- Direct HEX color input +- Predictable output for templates and styles + +--- + +## Usage + +### Adding a Color Picker field (for editors) + +1. Go to **SCF → Field Groups**. +2. Create or edit a field group. +3. Click **Add Field**. +4. Select **Color Picker** as the field type. +5. Configure default and return options. +6. Assign the field group to the desired location (for example, the Movie post type). +7. Save the field group. + +Editors will see a color picker control when editing a movie. + +--- ## Settings -- Default Value - Set a default color -- Return Format - Choose between string, array, or rgba format -- Enable Opacity - Allow transparency selection +### Default Value +Sets a predefined color for new content. This helps maintain visual consistency. + +Example: +``` +#ff3d00 +``` + +### Return Format +Defines how the color value is returned: +- **String** – HEX or RGBA string (recommended for most cases) +- **Array** – structured data with color components +- **RGBA** – explicit RGBA value including opacity + +### Enable Opacity +Allows editors to control transparency using an opacity slider. +When enabled, RGBA values are returned. + +--- + +## Best practices for editors + +- Use colors consistently to represent meaning (e.g., red for featured). +- Avoid excessive color variation across similar content. +- Prefer default values unless a visual change is intentional. +- Use opacity sparingly to maintain readability. + +--- + +## Next Steps + +After implementing Color Picker fields: + +- Apply selected colors to badges, overlays, or UI elements. +- Combine with conditional logic (e.g., featured movies use custom colors). +- Standardize color usage across movie types. +- Document color meaning for editorial teams. + +--- + +## For Developers + +### Registering a Color Picker field for movies + +The following example registers a Color Picker field for selecting a highlight color on a `movie` post type. + +```php + 'group_movie_colors', + 'title' => 'Movie Visual Settings', + 'fields' => array( + array( + 'key' => 'field_movie_highlight_color', + 'label' => 'Highlight Color', + 'name' => 'movie_highlight_color', + 'type' => 'color_picker', + 'default_value' => '#ff3d00', + 'return_format' => 'string', + 'enable_opacity'=> 1, + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +--- + +### Rendering the color in a movie template + +```php + +
+ Featured Movie +
+ Date: Mon, 19 Jan 2026 14:38:52 -0600 Subject: [PATCH 7/9] Enhance Image field documentation with detailed features Expanded the documentation for the Image field to include additional features, usage instructions, and best practices for both editors and developers. --- docs/features/field/image/index.md | 228 +++++++++++++++++++++++++++-- 1 file changed, 217 insertions(+), 11 deletions(-) diff --git a/docs/features/field/image/index.md b/docs/features/field/image/index.md index 02349018..e9a74bc7 100644 --- a/docs/features/field/image/index.md +++ b/docs/features/field/image/index.md @@ -1,19 +1,225 @@ # Image Field -The Image field provides a dedicated interface for uploading and selecting images through the WordPress media library. It offers preview capabilities and multiple return format options. +The **Image** field provides a dedicated interface for uploading and selecting images through the WordPress media library. It offers preview capabilities, validation options, and multiple return formats, making it suitable for both simple image usage and advanced media-driven layouts. + +This documentation follows WordPress.org guidelines and is written for **both non-technical editors and developers**, using a **movie website** as a consistent real-world example. + +--- + +## What is it? + +The Image field is a **media selection field** that allows editors to upload or choose an image from the WordPress media library. Once selected, the image can be previewed directly in the editor and reused across templates or layouts. + +Depending on configuration, the Image field can return: +- An image **ID** +- An image **URL** +- A full **array** of image data (metadata, sizes, alt text) + +--- + +## How does it work? + +When an Image field is added to a field group: + +1. SCF displays an image selector connected to the WordPress media library. +2. Editors can upload a new image or select an existing one. +3. A preview thumbnail is shown in the editor. +4. Optional validation rules ensure correct image dimensions and file size. +5. The selected image is saved and returned in the configured format. + +For editors, the experience is visual and familiar. For developers, the output is structured and predictable. + +--- + +## What is it for? + +Use the Image field whenever content requires **visual representation**. + +### Movie website examples + +On a movie website, Image fields are commonly used for: + +- **Movie poster** +- **Hero background image** +- **Director or cast photos** +- **Featured banners** +- **Promotional artwork** + +Images selected through the Image field can be reused consistently across listings, single pages, and promotional sections. + +--- ## Key Features -- Media library integration -- Image preview -- Size restrictions -- Format validation -- Multiple return formats +- Full WordPress media library integration +- Live image preview in the editor +- Image dimension validation (width and height) +- File size restrictions +- Support for multiple return formats +- Controlled image source selection + +--- + +## Usage + +### Adding an Image field (for editors) + +1. Go to **SCF → Field Groups**. +2. Create or edit a field group. +3. Click **Add Field**. +4. Select **Image** as the field type. +5. Configure preview size and validation options. +6. Assign the field group to the desired location (for example, the Movie post type). +7. Save the field group. + +Editors will see an image upload/select control when editing a movie. + +--- ## Settings -- Preview Size - Thumbnail display size -- Library - Restrict to uploaded or all images -- Min/Max Width/Height - Image dimension limits -- File Size Restrictions - Control upload sizes -- Return Format - Array, URL, or ID +### Preview Size +Controls the thumbnail size shown in the editor preview (for example, `thumbnail`, `medium`, `large`). + +### Library +Restricts image selection: +- **All** – any image from the media library +- **Uploaded** – only images uploaded to the current post + +### Min / Max Width & Height +Defines minimum and maximum image dimensions to ensure consistent layouts. + +### File Size Restrictions +Limits the maximum allowed file size for uploads, helping with performance and storage control. + +### Return Format +Defines how the image value is returned: +- **Array** – full image data (recommended for flexibility) +- **URL** – direct image URL +- **ID** – attachment ID (best for performance and advanced usage) + +--- + +## Best practices for editors + +- Upload images at the recommended dimensions. +- Use descriptive alt text for accessibility. +- Avoid excessively large images to improve performance. +- Reuse existing images when possible to reduce duplication. + +--- + +## Next Steps + +After implementing Image fields: + +- Use consistent image sizes across movie content. +- Combine with Color Picker fields for visual theming. +- Add fallback images in templates for missing content. +- Audit media usage periodically to remove unused assets. + +--- + +## For Developers + +### Registering an Image field for movies + +The following example registers an Image field for selecting a movie poster on a `movie` post type. + +```php + 'group_movie_images', + 'title' => 'Movie Images', + 'fields' => array( + array( + 'key' => 'field_movie_poster', + 'label' => 'Movie Poster', + 'name' => 'movie_poster', + 'type' => 'image', + 'preview_size' => 'medium', + 'library' => 'all', + 'return_format' => 'id', + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +--- + +### Rendering the image in a movie template + +```php + +
+ +
+ Date: Mon, 19 Jan 2026 14:41:35 -0600 Subject: [PATCH 8/9] Enhance Date Picker field documentation Expanded documentation for the Date Picker field, detailing its features, usage, settings, best practices, and examples for both editors and developers. --- docs/features/field/date-picker/index.md | 224 ++++++++++++++++++++++- 1 file changed, 215 insertions(+), 9 deletions(-) diff --git a/docs/features/field/date-picker/index.md b/docs/features/field/date-picker/index.md index 92a48483..b3d55b1d 100644 --- a/docs/features/field/date-picker/index.md +++ b/docs/features/field/date-picker/index.md @@ -1,18 +1,224 @@ # Date Picker Field -The Date Picker field provides a calendar interface for selecting dates. It offers a user-friendly way to input and format dates consistently across your content. +The **Date Picker** field provides an interactive calendar interface for selecting dates within the WordPress admin. It ensures dates are entered consistently, displayed clearly to editors, and returned in predictable formats for developers. + +This documentation follows WordPress.org guidelines and is written for **both non-technical editors and developers**, using a **movie website** as a consistent real-world example. + +--- + +## What is it? + +The Date Picker field is a **single-value date input field** that allows editors to select a date from a visual calendar instead of typing it manually. + +By separating how a date is **displayed** from how it is **stored and returned**, the Date Picker field ensures: +- A user-friendly editing experience +- Consistent date formatting +- Reliable date handling in templates and logic + +--- + +## How does it work? + +When a Date Picker field is added to a field group: + +1. SCF displays a calendar input in the WordPress admin. +2. Editors choose a date using the calendar interface. +3. The selected date is shown in a human-readable format. +4. The value is stored internally according to the configured return format. +5. Developers retrieve the date in a predictable format for rendering or logic. + +Editors interact with dates visually, while developers work with standardized values. + +--- + +## What is it for? + +Use the Date Picker field whenever content is associated with a **specific date**. + +### Movie website examples + +On a movie website, Date Picker fields are commonly used for: + +- **Movie release date** +- **Premiere date** +- **Festival screening date** +- **Streaming availability date** +- **Limited-time promotions** + +Dates selected through the Date Picker field can be used for display, sorting, filtering, or conditional behavior. + +--- ## Key Features - Interactive calendar interface -- Customizable date formats -- Week starts on any day -- Restrict date ranges -- Multiple display formats +- Customizable display and return formats +- Configurable week start day +- Date range restrictions +- Multiple display formats for editors +- Predictable, structured date values + +--- + +## Usage + +### Adding a Date Picker field (for editors) + +1. Go to **SCF → Field Groups**. +2. Create or edit a field group. +3. Click **Add Field**. +4. Select **Date Picker** as the field type. +5. Configure display and return formats. +6. Assign the field group to the desired location (for example, the Movie post type). +7. Save the field group. + +Editors will see a calendar control when editing a movie. + +--- ## Settings -- Display Format - How the date appears to editors -- Return Format - How the date is stored/returned -- Week Starts On - Set first day of week -- First Day - Configure week start day +### Display Format +Controls how the date appears to editors in the admin interface. + +Example: +``` +d/m/Y +``` + +This setting affects **visual presentation only**. + +--- + +### Return Format +Defines how the date value is stored and returned to templates: +- **Formatted string** (e.g. `Y-m-d`) +- **Custom format** for integration needs + +Developers should choose a format that works well with sorting and comparisons. + +--- + +### Week Starts On +Sets which day the calendar week begins on (for example, Monday or Sunday). + +--- + +### First Day +Defines the first day shown in the calendar view. +This improves usability for editors in different regions. + +--- + +## Best practices for editors + +- Always select dates using the calendar, not manual input. +- Follow project conventions for date usage (release vs premiere). +- Double-check dates for time-sensitive content. +- Update dates carefully after publication. + +--- + +## Next Steps + +After implementing Date Picker fields: + +- Display formatted dates consistently across movie pages. +- Use dates for sorting upcoming or archived movies. +- Combine with conditional logic (e.g., hide content before release date). +- Standardize date formats across all content types. + +--- + +## For Developers + +### Registering a Date Picker field for movies + +The following example registers a Date Picker field for selecting a movie release date on a `movie` post type. + +```php + 'group_movie_dates', + 'title' => 'Movie Dates', + 'fields' => array( + array( + 'key' => 'field_movie_release_date', + 'label' => 'Release Date', + 'name' => 'movie_release_date', + 'type' => 'date_picker', + 'display_format' => 'd/m/Y', + 'return_format' => 'Y-m-d', + 'first_day' => 1, + ), + ), + 'location' => array( + array( + array( + 'param' => 'post_type', + 'operator' => '==', + 'value' => 'movie', + ), + ), + ), + ) + ); +} ); +``` + +--- + +### Rendering the date in a movie template + +```php + + + $today ) { + // Movie has not been released yet. +} +``` + +--- + +### Data integrity tips + +- Store dates in a sortable format such as `Y-m-d`. +- Always use WordPress date functions for localization. +- Avoid mixing date formats across fields. +- Document how dates are used in logic and templates. + +--- + +## Summary + +The Date Picker field provides a reliable and user-friendly way to manage dates in SCF. It simplifies date input for editors while giving developers consistent, predictable values. For movie websites and other time-based content, it is an essential tool for managing releases, events, and schedules. + +--- + +*Last updated: 2026-01-19* From f90107439d003a8d01fbb3c4ef2baeffdc73c831 Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Thu, 29 Jan 2026 16:19:45 -0600 Subject: [PATCH 9/9] Revise SCF loading instructions with guarded bootstrap Updated the instructions for loading the Secure Custom Fields plugin to include a guarded bootstrap method. This method prevents loading SCF twice if it's already active or installed as a standalone plugin. --- docs/welcome/installation.md | 66 ++++++++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md index 2e9da363..c52471ad 100644 --- a/docs/welcome/installation.md +++ b/docs/welcome/installation.md @@ -114,17 +114,69 @@ require_once plugin_dir_path(dirname(__FILE__)) . 'vendor/autoload.php'; #### Load Secure Custom Fields -Now you need to manually load the Secure Custom Fields plugin and define its paths. Adjust the paths according to the structure of your plugin or theme: +When SCF is installed via Composer, you usually bundle it inside your own plugin (for example in vendor/secure-custom-fields/). + +However, some sites may also have SCF installed as a normal WordPress plugin. +To avoid loading SCF twice, use a guarded bootstrap that: + +Does nothing if SCF is already loaded. + +Does nothing if the standalone SCF plugin is active. + +Otherwise loads your bundled copy from vendor/. ```php -if (! class_exists('ACF')) { - // Define the path and URL to the Secure Custom Fields plugin. - define('MY_SCF_PATH', plugin_dir_path(dirname(__FILE__)) . 'vendor/secure-custom-fields/'); - define('MY_SCF_URL', plugin_dir_url(dirname(__FILE__)) . 'vendor/secure-custom-fields/'); +/** + * Load bundled Secure Custom Fields (SCF) only if no external instance is active. + * + * Runs after all plugins are loaded to safely detect an existing SCF/ACF + * installation and prevent loading the embedded copy twice. + */ +function myplugin_scf_loader_bootstrap() { + + // If SCF/ACF is already loaded, stop. + if ( class_exists( 'ACF' ) ) { + return; + } - // Include the plugin main file. - require_once MY_SCF_PATH . 'secure-custom-fields.php'; + // Make sure plugin helper functions are available. + if ( ! function_exists( 'is_plugin_active' ) ) { + require_once ABSPATH . 'wp-admin/includes/plugin.php'; + } + + // Main file of the standalone SCF plugin. + $scf_plugin_file = 'secure-custom-fields/secure-custom-fields.php'; + + // If SCF is active as a normal plugin, let WordPress load it. + if ( function_exists( 'is_plugin_active' ) && is_plugin_active( $scf_plugin_file ) ) { + return; + } + + // Define paths to the bundled SCF copy. + if ( ! defined( 'MY_SCF_PATH' ) ) { + define( + 'MY_SCF_PATH', + plugin_dir_path( dirname( __FILE__ ) ) . 'vendor/secure-custom-fields/' + ); + } + + if ( ! defined( 'MY_SCF_URL' ) ) { + define( + 'MY_SCF_URL', + plugin_dir_url( dirname( __FILE__ ) ) . 'vendor/secure-custom-fields/' + ); + } + + // Load bundled SCF. + $scf_bootstrap = MY_SCF_PATH . 'secure-custom-fields.php'; + + if ( file_exists( $scf_bootstrap ) ) { + require_once $scf_bootstrap; + } } + +// Run after all plugins are loaded. +add_action( 'plugins_loaded', 'myplugin_scf_loader_bootstrap' ); ``` ⚠️ **Note:** Replace MY_SCF_PATH and MY_SCF_URL with constants that match your plugin/theme structure if necessary.