From 30ee8a4b6825ab5850640f101452025c3793761b Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Tue, 1 Apr 2025 08:57:51 -0600 Subject: [PATCH 1/6] Add composer installation to docs/welcome --- docs/welcome/installation.md | 70 ++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md index d4741159..d5e876a9 100644 --- a/docs/welcome/installation.md +++ b/docs/welcome/installation.md @@ -27,6 +27,76 @@ Before installing, ensure your site meets these requirements: 3. Upload the plugin folder to `/wp-content/plugins/` 4. Activate through the WordPress admin interface +### Composer Installation + +This guide explains how to install and integrate the **Secure Custom Fields** plugin in your WordPress theme or plugin using Composer. + +Add the following configuration to your `composer.json` file: + +```json +{ + "repositories": [ + { + "type": "composer", + "url": "https://wpackagist.org" + } + ], + "extra": { + "installer-paths": { + "vendor/{$name}/": ["type:wordpress-plugin"] + } + }, + "require": { + "wpackagist-plugin/secure-custom-fields": "6.4.1" + }, + "config": { + "allow-plugins": { + "composer/installers": true + } + } +} +``` +Once the configuration is set, run the following command in your terminal to install the dependencies: +```shell +composer install +``` +or +```shell +composer i +``` +--- +### Add the Composer Autoloader +To ensure Composer dependencies are loaded correctly, add the following line in your plugin or theme: +```php +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: +```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/'); + + // Include the plugin main file. + require_once MY_SCF_PATH . 'secure-custom-fields.php'; +} +``` +⚠️ **Note:** Replace MY_SCF_PATH and MY_SCF_URL with constants that match your plugin/theme structure if necessary. + +### Done! +You have successfully installed and integrated Secure Custom Fields via Composer. You can now use it as you would with a normal installation, but with all the benefits of Composer-based dependency management. + +### Hide SCF Admin Menu and Updates + +```php +// Hide the SCF admin menu item. +add_filter( 'acf/settings/show_admin', '__return_false' ); + +// Hide the SCF Updates menu. +add_filter( 'acf/settings/show_updates', '__return_false', 100 ); +``` + ## Verification After installation: From 4399ef65f815e960ffb187d08993b4da3a80e100 Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Mon, 14 Apr 2025 09:17:26 -0600 Subject: [PATCH 2/6] docs: update SCF installation guide with Composer integration, benefits, and optional admin menu and update notification hiding docs: update SCF installation guide with Composer integration, benefits, and optional admin menu and update notification hiding --- docs/welcome/installation.md | 63 ++++++++++++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 6 deletions(-) diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md index d5e876a9..301ba9b9 100644 --- a/docs/welcome/installation.md +++ b/docs/welcome/installation.md @@ -26,10 +26,42 @@ Before installing, ensure your site meets these requirements: 2. Extract the plugin files 3. Upload the plugin folder to `/wp-content/plugins/` 4. Activate through the WordPress admin interface +--- ### Composer Installation -This guide explains how to install and integrate the **Secure Custom Fields** plugin in your WordPress theme or plugin using Composer. +To install and manage Secure Custom Fields in your WordPress theme or plugin, it is recommended to use Composer. + +This ensures that SCF is properly versioned, loaded automatically, and easy to update. + +### Why integrate **Secure Custom Fields (SCF)** with Composer? + +Integrating SCF using Composer offers several important advantages for the professional development of WordPress plugins and themes: + +- **Centralized dependency management:** + Composer allows you to declare, install, and update SCF easily along with other libraries needed in your project. + +- **Version control:** + You can lock a specific version of SCF in your `composer.json`, ensuring that all development and production environments use exactly the same version, avoiding unexpected errors. + +- **Simplified deployment and automation (CI/CD):** + Composer installs SCF automatically during deployment processes (`composer install`), eliminating the need to manually copy files. + +- **Automatic autoloading:** + Composer handles PHP class autoloading. Integrating SCF this way makes your code cleaner, safer, and PSR-4 compliant. + +- **Reduced repository size:** + By installing SCF as an external dependency, you avoid having redundant copies of the plugin in your project, keeping your repository lighter and easier to maintain. + +- **License compliance:** + Composer records the licenses of all dependencies used, which is very useful if you distribute your plugins or themes and need to meet legal or auditing requirements. + +- **Facilitates project changes:** + By managing SCF as a dependency, any theme or plugin can change its structure or installation system without affecting its functionality, ensuring greater flexibility and compatibility in development. + +--- + +### How to Load and Use **Secure Custom Fields (SCF)** with Composer Add the following configuration to your `composer.json` file: @@ -87,7 +119,11 @@ if (! class_exists('ACF')) { ### Done! You have successfully installed and integrated Secure Custom Fields via Composer. You can now use it as you would with a normal installation, but with all the benefits of Composer-based dependency management. -### Hide SCF Admin Menu and Updates +--- + +### Optional: Hide SCF Admin Menu and Updates + +If you want to hide the **Secure Custom Fields (SCF)** admin menu from the WordPress dashboard and prevent the plugin's update notifications from appearing, you can use the following code: ```php // Hide the SCF admin menu item. @@ -96,11 +132,26 @@ add_filter( 'acf/settings/show_admin', '__return_false' ); // Hide the SCF Updates menu. add_filter( 'acf/settings/show_updates', '__return_false', 100 ); ``` +#### What does this do? + +- **Hide Admin Menu:** + The first filter disables the SCF menu in the WordPress admin area, preventing users from accessing SCF field groups or settings. + +- **Hide Update Notifications:** + The second filter disables the SCF update notices, so users won't see update prompts for the plugin inside the admin dashboard. + +#### When should you use it? + +- If you are bundling SCF inside your plugin or theme and want to **control all the custom fields yourself** without allowing clients or users to modify them. +- If you want to **maintain full control** over SCF versions and updates to avoid compatibility issues caused by manual updates. + +> **Note:** Hiding updates means you are responsible for manually updating SCF when necessary to keep your project secure and compatible. + -## Verification +## Verify Your Installation After installation: -1. Navigate to Custom Fields in your admin menu -2. Verify you can access all plugin features -3. Create a test field group to ensure functionality +1. Navigate to **Secure Custom Fields** in your WordPress admin menu. +2. Verify that you can access all **Secure Custom Fields** plugin features. +3. Create a **test field group** to ensure that fields are saved and displayed correctly. From 1ae28e5b8063f90007d4a905a342f20cc8206598 Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Wed, 14 May 2025 10:38:13 -0600 Subject: [PATCH 3/6] Update docs/welcome/installation.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit let's not take for granted that readers are familiar with Composer Co-authored-by: Héctor <27339341+priethor@users.noreply.github.com> --- docs/welcome/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md index 301ba9b9..221b2282 100644 --- a/docs/welcome/installation.md +++ b/docs/welcome/installation.md @@ -79,7 +79,7 @@ Add the following configuration to your `composer.json` file: } }, "require": { - "wpackagist-plugin/secure-custom-fields": "6.4.1" + "wpackagist-plugin/secure-custom-fields": "^6.4" }, "config": { "allow-plugins": { From b5461fa34d2814dc2081c08fc31f6442d479fec5 Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Wed, 14 May 2025 10:38:55 -0600 Subject: [PATCH 4/6] Update docs/welcome/installation.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit avoid potential conflicts between Composer and the built-in updater Co-authored-by: Héctor <27339341+priethor@users.noreply.github.com> --- docs/welcome/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/welcome/installation.md b/docs/welcome/installation.md index 221b2282..9ca536e9 100644 --- a/docs/welcome/installation.md +++ b/docs/welcome/installation.md @@ -145,7 +145,7 @@ add_filter( 'acf/settings/show_updates', '__return_false', 100 ); - If you are bundling SCF inside your plugin or theme and want to **control all the custom fields yourself** without allowing clients or users to modify them. - If you want to **maintain full control** over SCF versions and updates to avoid compatibility issues caused by manual updates. -> **Note:** Hiding updates means you are responsible for manually updating SCF when necessary to keep your project secure and compatible. +> **Note:** Hiding updates means you are responsible for manually updating SCF when necessary to keep your project secure and compatible, but it also helps avoid potential conflicts between Composer and the built-in updater. ## Verify Your Installation From 0a7ba7ada04eb64d069f9e7a18ff4bfe9204f0fe Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Mon, 23 Jun 2025 11:35:49 -0600 Subject: [PATCH 5/6] Updates the documentation: Adds tutorials on creating post types, custom fields, taxonomies, and options pages, and improves guidance on the relationship between post types, taxonomies, and custom fields. --- docs/tutorials/first-custom-field.md | 78 +++++++++++ docs/tutorials/first-options-page.md | 96 ++++++++++++++ docs/tutorials/first-post-type.md | 150 +++++++++++++++++---- docs/tutorials/first-taxonomy.md | 128 ++++++++++++++++++ docs/welcome/how-content-works.md | 187 +++++++++++++++++++++++++++ docs/welcome/index.md | 1 + 6 files changed, 617 insertions(+), 23 deletions(-) create mode 100644 docs/tutorials/first-custom-field.md create mode 100644 docs/tutorials/first-options-page.md create mode 100644 docs/tutorials/first-taxonomy.md create mode 100644 docs/welcome/how-content-works.md diff --git a/docs/tutorials/first-custom-field.md b/docs/tutorials/first-custom-field.md new file mode 100644 index 00000000..7b0125b3 --- /dev/null +++ b/docs/tutorials/first-custom-field.md @@ -0,0 +1,78 @@ +# Creating Your First Custom Field + +A beginner-friendly guide to adding custom fields using Secure Custom Fields (SCF). + +**What is a custom field?** + +Custom fields let you add structured data to your content. With SCF, you can attach fields like text inputs, selects, image uploads, and more to your posts, pages, or custom post types. + +## Prerequisites + +- SCF installed and activated +- A post type (default or custom) where you'll attach your fields +- Administrator access to WordPress + +You can learn more about WordPress basics here: + +- [Theme Basics](https://developer.wordpress.org/themes/basics/) +- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/) + +## 1. Access the Admin Panel + +- Go to **Secure Custom Fields → Field Groups** in your WordPress admin menu. +- Click **"Add New"** to create a new group of fields. + +## 2. Basic Configuration + +#### Field Group Title + +Give your field group a descriptive name, like `Movie Details` or `Product Specs`. + +#### Location Rules + +Choose where this group should appear. For example: + +- Post type is equal to `Movie` +- Page template is `Product Page` + +This ensures your fields appear only where you need them. + +#### Active + +Make sure the field group is set to **Active** so it appears in the editor. + +## 3. Adding Fields + +Click **"Add Field"** to create your first field. For each field, configure: + +- **Label**: The visible name of the field (e.g., `Director`) +- **Field Name**: A unique identifier used in code (e.g., `director`) +- **Field Type**: Choose from text, textarea, number, image, checkbox, select, and more +- **Instructions**: Optional helper text to guide users +- **Required**: Whether this field must be filled in +- **Default Value** and **Placeholder**: Optional presets + +Repeat this process for as many fields as needed. + +## 4. Testing + +- Go to a post of the type you've targeted with the field group. +- You should now see your custom fields below the content editor. +- Fill in test data and save the post. +- Confirm the fields save and appear as expected. + +## Next Steps + +- Display the custom field values on the frontend using SCF template functions +- Use conditional logic or field groups to organize complex forms +- Combine with taxonomies or other field groups for richer structures + +## For Developers + +While Secure Custom Fields makes it easier to manage and display custom fields with a user-friendly interface, WordPress also includes native support for custom fields that can be managed programmatically using functions like `get_post_meta()` and `add_post_meta()`. + +You can learn more about WordPress native custom fields here: + +👉 [WordPress Native Custom Fields](https://developer.wordpress.org/plugins/metadata/custom-fields/) + +To access custom field values in your theme or plugin, use SCF functions you can learn more about SCF’s developer API in their official documentation. diff --git a/docs/tutorials/first-options-page.md b/docs/tutorials/first-options-page.md new file mode 100644 index 00000000..3498ccc0 --- /dev/null +++ b/docs/tutorials/first-options-page.md @@ -0,0 +1,96 @@ +# Creating Your First Options Page + +A step-by-step guide to building a global settings page using Secure Custom Fields (SCF). + +**What is an options page?** + +An options page is a custom admin screen where you can store site-wide settings that are not linked to individual posts, pages, or taxonomies. These values are useful for things like contact details, configuration values, or custom messages that may appear across your theme. + +## Prerequisites + +- SCF (Secure Custom Fields) installed and activated +- Administrator access to WordPress +- Basic understanding of WordPress admin and SCF interface + +You can learn more about WordPress basics here: + +- [Theme Basics](https://developer.wordpress.org/themes/basics/) +- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/) + +## 1. Access the Admin Panel + +- Go to **Secure Custom Fields → Options Pages** in your WordPress admin sidebar. +- Click **"Add New"** to create your options page. + +## 2. Basic Configuration + +Set up the following fields to define the behavior and placement of your options page: + +### Basic Settings Panel + +- **Page Title**: The title displayed at the top of the options page (e.g., `Site Settings`). +- **Menu Slug**: A unique identifier for the page URL (e.g., `site-settings`). +- **Parent Page**: Choose `No Parent` to create a standalone page or select a parent if it should appear as a submenu item. +- **Advanced Configuration**: Enable to access additional options. + +### Advanced Settings Panel + +#### Visibility + +- **Menu Title**: Label that appears in the WordPress admin menu. +- **Menu Icon**: Choose an icon from Dashicons or upload a custom SVG or URL. +- **Menu Position**: Controls the position of the item in the admin sidebar. +- **Redirect to Child Page**: If enabled, this page redirects to its first child page automatically. + +#### Description + +- **Description**: A short description to help explain the purpose of this options page. + +#### Labels + +- **Update Button Label**: Text shown on the submit button (e.g., `Update Settings`). +- **Updated Message**: Message displayed after saving the options. + +#### Permissions + +- **Capability**: Required capability to view/edit this page (default is `edit_posts`). + +#### Data Storage + +- **Storage Location**: Choose whether to store the data in the options table (default) or bind it to a specific post, user, or term. +- **Custom Storage**: Use a specific post ID (e.g., `123`) or context string (e.g., `user_1`). +- **Autoload Options**: Enable to automatically load these values when WordPress initializes — useful for performance. + +Click **Save** to create the options page. Once saved, you can start adding custom fields as needed. + +## 3. Adding Fields + +Add fields just like you would for any post type or taxonomy. + +### Common Fields to Add: + +- `company_name` — Company name (text) +- `support_email` — Support contact email (email) +- `emergency_alert_message` — Site-wide notice (textarea) +- `global_logo` — Logo image (image upload) + +Each of these fields will be accessible from any page or template. + +## Next Steps + +- Use options fields to manage design elements like footer text or banners +- Reference options globally to reduce repeated settings in CPTs or pages +- Combine with conditional logic to enable dynamic site-wide behavior + +## For Developers + +Options pages provide a clean way to centralize configuration. In more advanced implementations, you can: + +- Register multiple options pages for different sections (e.g., Branding, API Keys) +- Use `get_option()` if working outside the SCF context +- Integrate with theme customizers or other plugin logic + +Secure Custom Fields simplifies this process, but WordPress also offers a native way to register and manage options pages through the **Settings API**. This allows full control over settings registration, sanitization, and display via code. + +👉 Learn more about the WordPress Settings API: +[https://developer.wordpress.org/plugins/settings/settings-api/](https://developer.wordpress.org/plugins/settings/settings-api/) diff --git a/docs/tutorials/first-post-type.md b/docs/tutorials/first-post-type.md index 90c83c2a..3c1f128c 100644 --- a/docs/tutorials/first-post-type.md +++ b/docs/tutorials/first-post-type.md @@ -1,36 +1,140 @@ # Creating Your First Post Type -A step-by-step guide to creating a custom post type using Secure Custom Fields. +A step-by-step guide to creating a custom post type using Secure Custom Fields (SCF). + +**What is a custom post type?** + +In WordPress, a custom post type (CPT) is a content type like posts and pages, but customized to suit your specific needs. You can use CPTs to manage products, portfolios, testimonials, events, vehicles, and more—essentially any type of structured content that needs its own menu and fields. ## Prerequisites -- SCF installed and activated -- Administrator access to WordPress -- Basic understanding of WordPress concepts +- SCF installed and activated +- Administrator access to WordPress +- Basic understanding of WordPress concepts + +You can learn more about WordPress basics here: + +- [Theme Basics](https://developer.wordpress.org/themes/basics/) +- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/) + +## 1. Access the Admin Panel + +To begin creating your custom post type: + +- Go to **Secure Custom Fields → Post Types** in your WordPress admin menu. +- Click the **"Add New"** button to open the creation form. + +## 2. Basic Configuration + +These fields help you define how your post type will appear and behave: + +### Plural Label \* + +This is the name that will appear in the admin sidebar. For example, `Movies`. + +### Singular Label \* + +Used for individual entries. Example: `Movie`. + +### Post Type Key \* + +A technical identifier for WordPress to recognize this post type. Use lowercase letters and underscores only. Max 20 characters. Example: `movie`. + +### Taxonomies + +Choose existing taxonomies like **category** or **tags** if you want to group or filter your content. You can also select custom ones like **Brand** or **Color**. + +### Public + +Choose **Yes** to make your post type visible on the website and admin area. Choose **No** to keep it private. + +### Hierarchical + +Set to **Yes** if you want your items to be nested (like pages). Set to **No** for a flat list (like blog posts). + +### Advanced Configuration + +Enable this to unlock more advanced options, useful when you need more control over how your post type works. + +## 3. Advanced Settings + +These options let you customize deeper behaviors and labels. -## Steps +### Supports -1. **Access the Admin Panel** - - Navigate to Custom Fields → Post Types - - Click "Add New" +Select which features to enable when editing a post, such as: -2. **Basic Configuration** - - Enter a descriptive name - - Configure labels - - Set visibility options +- **Title**: Adds a title field +- **Editor**: Main content box +- **Featured Image**: Allow image upload +- **Comments**, **Author**, **Excerpt**, etc. -3. **Advanced Settings** - - Configure permalinks - - Set up taxonomies - - Define capabilities +### Description -4. **Testing** - - Save your post type - - Create a test post - - View on front end +A short explanation of what this post type is about. Helpful for organization. + +### Active + +Make sure this is set to **Yes** so your post type is registered and usable. + +### Labels + +These are the texts that WordPress shows throughout the dashboard. For example: + +- **Menu Name**: What appears in the sidebar +- **Add New Item**: Button to create a new entry +- **Edit Item**, **View Item**, **Search Items**, etc. + You can keep the default labels or customize them to your liking. + +### Visibility Options + +Control where your post type appears in the admin and site: + +- Show in dashboard menu +- Show in admin bar +- Show in appearance menus + +### Menu Icon and Position + +Choose an icon for your post type from the WordPress Dashicons set. Optionally, set its position in the sidebar. + +### Permalinks and URLs + +You can define how URLs will look for your post type: + +- **Slug**: A custom word for your URL (e.g., `/movie/`) +- Enable archive and pagination +- Optionally include RSS feeds + +### Permissions + +If needed, you can assign custom capabilities like `edit_movie` or `delete_movies`. Useful for advanced role control. + +### REST API Settings + +Enable this if you plan to use the post type with the block editor or external tools. + +- You can customize the API route, namespace, or controller class if needed. + +## 4. Testing + +Once everything is set up: + +- Click **Save** to register your post type. +- Go to the WordPress dashboard menu where your new post type now appears. +- Click **Add New** and create a test entry. +- Visit your website and check that it appears correctly on the frontend. ## Next Steps -- Add custom fields to your post type -- Configure archive displays -- Set up custom taxonomies +- Add custom fields to your post type via Secure Custom Fields +- Configure how archives and single templates are displayed in your theme +- Set up or register your own taxonomies for more organization + +## For Developers + +If you're a developer and prefer to register custom post types using code instead of the admin interface, you can refer to the official WordPress documentation: + +[How to Create Custom Post Types with Code](https://developer.wordpress.org/plugins/post-types/) + +This guide includes examples and explanations on using `register_post_type()` and other related functions. diff --git a/docs/tutorials/first-taxonomy.md b/docs/tutorials/first-taxonomy.md new file mode 100644 index 00000000..cae670ad --- /dev/null +++ b/docs/tutorials/first-taxonomy.md @@ -0,0 +1,128 @@ +# Creating Your First Taxonomy + +A step-by-step guide to creating a custom taxonomy using Secure Custom Fields (SCF). + +**What is a taxonomy?** + +A taxonomy in WordPress is a way to group content together. The most common examples are categories and tags. You can create your own custom taxonomies to organize your content in meaningful ways depending on your needs—for example, genres for movies, colors for products, or locations for rentals. + +## Prerequisites + +- SCF installed and activated +- Administrator access to WordPress +- Basic understanding of WordPress concepts + +You can learn more about WordPress basics here: + +- [Theme Basics](https://developer.wordpress.org/themes/basics/) +- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/) + +## 1. Access the Admin Panel + +To begin creating your custom taxonomy: + +- Go to **Secure Custom Fields → Taxonomies** in your WordPress admin menu. +- Click the **"Add New"** button to open the creation form. + +## 2. Basic Configuration + +#### Plural Label \* + +Name shown in admin menus and listings, e.g., `Genres`. + +#### Singular Label \* + +Used for individual terms. Example: `Genre`. + +#### Taxonomy Key \* + +A unique identifier. Use lowercase letters, underscores, or dashes only. Max 32 characters. Example: `genre`. + +#### Post Types + +Select the post types that will use this taxonomy. For example, Posts, Pages, or custom types like `product`, `vehicle`, etc. + +#### Public + +Choose **Yes** to make the taxonomy visible on your website and in the admin dashboard. + +#### Hierarchical + +Enable to allow parent-child terms (like categories). Disable for flat lists (like tags). + +#### Advanced Configuration + +Enable this to unlock advanced settings for developers or experienced users. + +## 3. Advanced Settings + +#### Sort Terms + +Controls whether the terms are stored in the order you assign them. + +#### Default Term + +Creates a default term that can’t be deleted, useful for fallback categorization. + +#### Description + +Brief summary of what the taxonomy represents. + +#### Active + +Make sure this is set to **Yes** so your taxonomy is usable. + +#### Labels + +Customize the texts shown in the WordPress admin: + +- Menu Label, Add New Item, Edit Item, View Item +- Parent Item (for hierarchical), Popular Items (for non-hierarchical) +- Messages for empty lists, instructions, tooltips, etc. + +#### Visibility Options + +Control where the taxonomy appears in the admin and frontend: + +- Show In UI, Show In Admin Menu +- Appearance Menu Support, Quick Edit, Admin Columns + +#### Meta Box + +Enable and configure how the taxonomy is displayed in the post editor. +You can define custom callbacks for display and sanitization if needed. + +#### Permalinks and URLs + +Customize how your taxonomy URLs will be structured: + +- Custom Slug, Include front prefix, Enable hierarchical URLs +- Publicly queryable, custom query variable + +#### Permissions + +Control who can manage, edit, assign, or delete terms. +You can set custom capabilities (e.g., `manage_categories`, `edit_posts`). + +## 4. Testing + +Once everything is configured: + +- Click **Save** to register your taxonomy. +- Go to one of the selected post types (e.g., Posts or Products). +- Try adding terms in the new taxonomy field. +- Make sure they appear correctly in the editor and on the frontend if public. + +## Next Steps + +- Add custom fields to your taxonomy terms using Secure Custom Fields +- Customize archive pages for your taxonomy terms in your theme +- Use the taxonomy in filters or menus for better navigation + +## For Developers + +If you're a developer and prefer to register custom taxonomies using code instead of the admin interface, you can refer to the official WordPress documentation: + +[How to Create Custom Taxonomies with Code](https://developer.wordpress.org/plugins/taxonomies/) + +This guide includes examples and explanations on using `register_taxonomy()` and other related functions. diff --git a/docs/welcome/how-content-works.md b/docs/welcome/how-content-works.md new file mode 100644 index 00000000..5578e7b2 --- /dev/null +++ b/docs/welcome/how-content-works.md @@ -0,0 +1,187 @@ +# Understanding the Relationship Between Post Types, Taxonomies, and Custom Fields + +In WordPress, the true power of content modeling comes from combining **Post Types**, **Taxonomies**, and **Custom Fields**. Together, these tools allow you to build virtually any kind of data structure your website needs — from a real estate listing manager to a recipe library or an online product catalog. + +This guide will help you understand how each element works, when to use them, and how they interact with each other in practical projects — using movies as our central example. + +## Prerequisites + +- SCF (Secure Custom Fields) installed and activated +- Administrator access to WordPress +- Basic understanding of WordPress concepts + +You can learn more about WordPress basics here: + +- [Theme Basics](https://developer.wordpress.org/themes/basics/) +- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/) + +## 1. Post Types + +Post types define **what kind of content** you're managing. WordPress includes `Posts` and `Pages` by default, but you can create custom types like `Movies`, `Events`, or `Products`. + +**When to create a custom post type:** + +- You want content that doesn’t belong under blog posts or pages +- You need a unique admin menu and editor for managing this content +- You want to separate things like `Movies` from standard posts + +**Example (Movies):** +Use a custom post type called `Movie` to store all individual movie entries. This gives you full control over how movies are edited, displayed, and organized independently from blog content. + +To learn how to create one, see: [Creating Your First Post Type](#) + +## 2. Taxonomies + +Taxonomies define **how content is grouped**. WordPress provides default taxonomies like `Categories` and `Tags`, but you can create your own — such as `Genres`, `Years`, or `Directors`. + +**When to create a custom taxonomy:** + +- You want to group or filter items based on shared traits +- You need hierarchical grouping (e.g., genre > sub-genre) +- You want users to navigate content by categories meaningful to them + +**Example (Movies):** +Create a taxonomy called `Genre` and attach it to the `Movie` post type. This lets users filter all movies tagged as `Action`, `Comedy`, or `Drama` — and even group them by sub-genres if hierarchical. + +To learn how to create one, see: [Creating Your First Taxonomy](#) + +## 3. Custom Fields + +Custom fields store **specific attributes** that aren’t covered by the title or content fields. They are great for metadata that belongs to one item. + +**When to use custom fields:** + +- You want to add structured data to your post type (e.g., text, numbers, images) +- You want each item to have unique values (not shared or grouped like taxonomies) + +**Example (Movies):** +Use custom fields to store each movie's `Director`, `Release Year`, `Duration`, `Trailer URL`, and `Poster Image`. These are all values unique to each movie and not ideal for filtering across many movies like taxonomies would be. + +To learn how to create one, see: [Creating Your First Custom Field](#) + +## 4. Why This Matters + +When used together, these three features form a powerful content management structure. Here’s how it looks in practice for a movie website: + +- A **Movie** post type +- With a **Genre** taxonomy (e.g., Action, Sci-Fi, Romance) +- And custom fields for: + + - `Director` + - `Duration` + - `Release Year` + - `Trailer URL` + +This enables you to: + +- Create a dedicated admin panel for movies +- Allow users to browse by genre +- Display rich details per movie on the frontend +- Build custom archive templates and filtering tools + +Whether you're building a streaming catalog, a film festival archive, or a movie blog — combining post types, taxonomies, and custom fields allows WordPress to adapt far beyond traditional blogs. + +--- + +### Real-World Example: Real Estate Website + +**Post Type:** `Property` + +Each property is its own entry, allowing the team to manage listings independently. + +**Taxonomies:** + +- `Property Type` (e.g., House, Apartment, Commercial) +- `Location` (e.g., City or Zone) + +**Custom Fields:** + +- `Price` +- `Bedrooms` +- `Bathrooms` +- `Square Footage` +- `Gallery` +- `Contact Email` + +This setup allows site visitors to: + +- Filter properties by type or location +- View detailed information per listing +- Submit inquiries directly from the property page + +--- + +### Real-World Example: User Check-In/Check-Out System + +**Post Type:** `User Visit` + +Each entry represents a single visit by a user. + +**Taxonomies:** + +- `Department` (to group visits by area) + +**Custom Fields:** + +- `User Name` +- `Check-In Time` +- `Check-Out Time` +- `Purpose of Visit` +- `Approved By` + +This setup enables admins to: + +- Track entry and exit logs +- Generate visit reports by department +- Display current on-site users if needed + +## Advanced Example: Relational Content with Bidirectional Fields + +In more complex systems, post types may need to relate to each other. You can use **bidirectional relationships** (also known as post-to-post relationships) to build powerful, interconnected structures. + +### Example: University Course Management System + +**Post Types:** + +- `Course` +- `Instructor` +- `Student` + +**Taxonomies:** + +- `Department` (e.g., Science, Arts) + +**Custom Fields:** + +- `Course`: + + - `Course Code` + - `Credits` + - `Instructor` (relationship to Instructor post) + - `Enrolled Students` (bidirectional relationship to Student posts) + +- `Instructor`: + + - `Full Name` + - `Assigned Courses` (bidirectional relationship to Course posts) + +- `Student`: + + - `Name` + - `Courses Enrolled` (bidirectional relationship to Course posts) + +This setup enables features like: + +- Displaying all students enrolled in a course +- Showing which instructor teaches each course +- Generating student dashboards with course schedules + +You can manage this using Secure Custom Fields with relationship-type fields. + +--- + +## Next Steps + +- [Learn how to create your first custom post type](../tutorials/first-post-type.md) +- [Explore how to build a custom taxonomy](../tutorials/first-taxonomy.md) +- [Add and manage custom fields with SCF](../tutorials/first-custom-field.md) diff --git a/docs/welcome/index.md b/docs/welcome/index.md index 08796347..1bf41469 100644 --- a/docs/welcome/index.md +++ b/docs/welcome/index.md @@ -6,6 +6,7 @@ This section helps you get up and running with Secure Custom Fields (SCF). Wheth - [Installation](installation) - How to install and activate SCF - [Quick Start](quick-start) - Create your first custom field group in minutes +- [How Content Works](how-content-works) - Understanding the Relationship Between Post Types, Taxonomies, and Custom Fields ## Documentation Sections From 2cb07815fb6fb84926be505dcfa668037c7db7bd Mon Sep 17 00:00:00 2001 From: Manuel Ramirez Coronel Date: Thu, 3 Jul 2025 13:09:21 -0600 Subject: [PATCH 6/6] Update first-custom-field.md --- docs/tutorials/first-custom-field.md | 81 ++++++++++++++++++++++------ 1 file changed, 65 insertions(+), 16 deletions(-) diff --git a/docs/tutorials/first-custom-field.md b/docs/tutorials/first-custom-field.md index 7b0125b3..2c46b1af 100644 --- a/docs/tutorials/first-custom-field.md +++ b/docs/tutorials/first-custom-field.md @@ -24,11 +24,11 @@ You can learn more about WordPress basics here: ## 2. Basic Configuration -#### Field Group Title +### Field Group Title Give your field group a descriptive name, like `Movie Details` or `Product Specs`. -#### Location Rules +### Location Rules Choose where this group should appear. For example: @@ -37,20 +37,75 @@ Choose where this group should appear. For example: This ensures your fields appear only where you need them. -#### Active +**Note:** This fine-grained control allows you to define SCF fields once and reuse them across different post types, templates, or components. + +### Active Make sure the field group is set to **Active** so it appears in the editor. +**Note:** Some features require the field group to be **enabled** and **exposed via the REST API**. To future-proof your configuration, we recommend setting **Show in REST** to `true` when creating your field groups. + ## 3. Adding Fields -Click **"Add Field"** to create your first field. For each field, configure: +Click **"Add Field"** to create your first field, configure: + +### Minimum required settings + +To create a functional custom field, you only need to define the following in the **General** tab: + +- **Field Type** (e.g., Text, Image, Select): Defines the kind of input +- **Field Label**: The name shown in the editor +- **Field Name**: A unique, code-friendly identifier (no spaces; dashes and underscores allowed) + +For example, you could create fields like: + +- **"Movie Title"** (`movie_title`) — a text field to store the name of the movie +- **"Director"** (`director`) — another text field to store the director's name +- **"Release Year"** (`release_year`) — a number field to store the release year + +> **Note:** All other settings are optional and provide extra control or visual customization. + +--- + +### 🔧 Full settings overview by tab + +### General + +Basic field definition and default behavior: + +- **Field Type** +- **Field Label** +- **Field Name** +- **Default Value** -- **Label**: The visible name of the field (e.g., `Director`) -- **Field Name**: A unique identifier used in code (e.g., `director`) -- **Field Type**: Choose from text, textarea, number, image, checkbox, select, and more -- **Instructions**: Optional helper text to guide users -- **Required**: Whether this field must be filled in -- **Default Value** and **Placeholder**: Optional presets +### Validation + +Rules to control what values are allowed: + +- **Required** +- **Minimum / Maximum Values** +- **Allowed Characters / Pattern** +- **Custom Validation Message** + +### Presentation + +Controls how the field appears in the editor: + +- **Placeholder Text** +- **Instructions** +- **Wrapper Attributes** +- **Hide Label** + +### Conditional Logic + +Display logic to control field visibility: + +- **Enable Conditions** +- **Condition Rules** + +> **Note:** Not all options appear for every field type. Each field may expose different settings depending on its nature. + +--- Repeat this process for as many fields as needed. @@ -61,12 +116,6 @@ Repeat this process for as many fields as needed. - Fill in test data and save the post. - Confirm the fields save and appear as expected. -## Next Steps - -- Display the custom field values on the frontend using SCF template functions -- Use conditional logic or field groups to organize complex forms -- Combine with taxonomies or other field groups for richer structures - ## For Developers While Secure Custom Fields makes it easier to manage and display custom fields with a user-friendly interface, WordPress also includes native support for custom fields that can be managed programmatically using functions like `get_post_meta()` and `add_post_meta()`.