Skip to content

Commit ebc7c96

Browse files
racmanuelpriethor
racmanuel
and
priethor
authored
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. (#187)
* Add composer installation to docs/welcome * 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 * Update docs/welcome/installation.md let's not take for granted that readers are familiar with Composer Co-authored-by: Héctor <[email protected]> * Update docs/welcome/installation.md avoid potential conflicts between Composer and the built-in updater Co-authored-by: Héctor <[email protected]> * 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. * Update first-custom-field.md * Improve the documentation: update the guides on custom fields, post types, taxonomies, and options pages for greater clarity and consistency. * Update the section headers in the installation guide to improve the document’s clarity and structure. --------- Co-authored-by: Héctor <[email protected]>
1 parent 9a0314c commit ebc7c96

File tree

7 files changed

+747
-28
lines changed

7 files changed

+747
-28
lines changed

‎docs/tutorials/first-custom-field.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Creating Your First Custom Field
2+
3+
A beginner-friendly guide to adding custom fields using Secure Custom Fields (SCF).
4+
5+
**What is a custom field?**
6+
7+
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.
8+
9+
## Prerequisites
10+
11+
- SCF installed and activated
12+
- A post type (default or custom) where you'll attach your fields
13+
- Administrator access to WordPress
14+
15+
You can learn more about WordPress basics here:
16+
17+
- [Theme Basics](https://developer.wordpress.org/themes/basics/)
18+
- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/)
19+
20+
## 1. Access the Admin Panel
21+
22+
- Go to **SCF → Field Groups** in your WordPress admin menu.
23+
- Click **"Add New"** to create a new group of fields.
24+
25+
## 2. Basic Configuration
26+
27+
### Field Group Title
28+
29+
Give your field group a descriptive name, like `Movie Details` or `Product Specs`.
30+
31+
### Location Rules
32+
33+
Choose where this group should appear. For example:
34+
35+
- Post type is equal to `Movie`
36+
- Page template is `Product Page`
37+
38+
This ensures your fields appear only where you need them.
39+
40+
**Note:** This fine-grained control allows you to define SCF fields once and reuse them across different post types, templates, or components.
41+
42+
### Active
43+
44+
Make sure the field group is set to **Active** so it appears in the editor.
45+
46+
**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.
47+
48+
## 3. Adding Fields
49+
50+
To start building your custom field group, click the **"Add Field"** button.
51+
52+
Each field requires at least a few basic settings to work correctly. All other options are optional and can be used to improve the user experience in the editor.
53+
54+
---
55+
56+
### Minimum Required Settings
57+
58+
In the **General** tab, you must define the following:
59+
60+
- **Field Type**
61+
Specifies what kind of data the field will store (e.g., Text, Image, Number, Select).
62+
63+
- **Field Label**
64+
The human-readable name shown in the editor (e.g., “Movie Title”).
65+
66+
- **Field Name**
67+
A unique identifier used in the code (lowercase, no spaces; underscores or dashes allowed).
68+
69+
#### 📌 Example: Movie Fields
70+
71+
Let’s say you want to create a group of fields for movie entries. Here's how you could configure it:
72+
73+
| Field Label | Field Name | Field Type | Description |
74+
|------------------|------------------|------------|------------------------------------------|
75+
| Movie Title | `movie_title` | Text | Stores the name of the movie |
76+
| Director | `director` | Text | Stores the name of the director |
77+
| Release Year | `release_year` | Number | Stores the year the movie was released |
78+
| Poster Image | `poster` | Image | Upload an image file for the movie poster |
79+
80+
> 💡 These fields would be added one by one using the **Add Field** button, and each configured in the field editor panel.
81+
82+
---
83+
84+
## General Settings
85+
86+
Defines the field behavior and how it is stored:
87+
88+
- **Field Type**
89+
What kind of input this field accepts (text, image, number, etc.).
90+
91+
- **Field Label**
92+
The label shown to the user in the WordPress editor.
93+
94+
- **Field Name**
95+
The code-safe name used to retrieve the value in your templates or plugins.
96+
97+
- **Default Value**
98+
A pre-filled value shown if no value is entered.
99+
100+
---
101+
102+
## Validation Settings
103+
104+
Used to restrict and control the kind of data that can be entered:
105+
106+
- **Required**
107+
Makes the field mandatory.
108+
109+
- **Minimum / Maximum Values**
110+
For numeric or character-based fields. Useful for fields like `release_year`.
111+
112+
- **Allowed Characters / Pattern**
113+
Use a regular expression to restrict input format (e.g., only digits).
114+
115+
- **Custom Validation Message**
116+
Message shown if validation fails (e.g., “Please enter a valid year”).
117+
118+
---
119+
120+
## Presentation Settings
121+
122+
Controls the visual appearance of the field in the editor:
123+
124+
- **Placeholder Text**
125+
Example text shown inside the field input.
126+
127+
- **Instructions**
128+
Helper text shown below the field to guide users.
129+
130+
- **Wrapper Attributes**
131+
Custom HTML attributes like class or ID for styling or JavaScript.
132+
133+
- **Hide Label**
134+
Option to hide the field label (not recommended unless styled separately).
135+
136+
---
137+
138+
## Conditional Logic
139+
140+
Used to show or hide fields based on the value of other fields:
141+
142+
- **Enable Conditions**
143+
Activate conditional display rules for this field.
144+
145+
- **Condition Rules**
146+
Example: only show the “Director” field if “Content Type” equals “Movie”.
147+
148+
---
149+
150+
> ⚠️ **Note:** Some settings may not be available for all field types. The options shown will adapt depending on the field you're configuring.
151+
152+
---
153+
154+
### Final Step
155+
156+
Repeat this process to add as many fields as needed to your group. Once ready, you can assign this field group to a post type and start entering content!
157+
158+
## For Developers
159+
160+
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()`.
161+
162+
You can learn more about WordPress native custom fields here:
163+
164+
👉 [WordPress Native Custom Fields](https://developer.wordpress.org/plugins/metadata/custom-fields/)
165+
166+
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.

‎docs/tutorials/first-options-page.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Creating Your First Options Page
2+
3+
A step-by-step guide to building a global settings page using Secure Custom Fields (SCF).
4+
5+
---
6+
7+
## What is an options page?
8+
9+
An **options page** is a custom admin screen where you can store **site-wide settings** that are not tied to individual posts, pages, or taxonomies. These values are ideal for:
10+
11+
- Contact details (phone, email, address)
12+
- Social media links
13+
- Global theme settings (colors, toggles, logos)
14+
- Custom footer messages
15+
- Business hours
16+
17+
---
18+
19+
## How are these options related to themes?
20+
21+
Options pages let you **manage shared values** that appear across the theme — without editing code each time a change is needed.
22+
23+
### Example: Company Phone Number
24+
25+
Suppose you want to display the company’s phone number in both the header and footer:
26+
27+
1. Create an options page named `theme_options`.
28+
2. Add a text field called `phone_number`.
29+
3. Retrieve it in your classic theme like this:
30+
31+
```php
32+
<?php
33+
$phone_number = get_option('phone_number');
34+
echo $phone_number;
35+
?>
36+
```
37+
38+
> This approach works with **Classic Themes** (non-block themes) where PHP templates are used for rendering.
39+
40+
## Prerequisites
41+
42+
- SCF (Secure Custom Fields) installed and activated
43+
- Administrator access to WordPress
44+
- Basic understanding of WordPress admin
45+
46+
You can learn more about WordPress basics here:
47+
48+
- [Theme Basics](https://developer.wordpress.org/themes/basics/)
49+
- [Plugin Basics](https://developer.wordpress.org/plugins/plugin-basics/)
50+
51+
## 1. Access the Admin Panel
52+
53+
- Go to **Secure Custom Fields → Options Pages** in your WordPress admin sidebar.
54+
- Click **"Add New"** to create your options page.
55+
56+
## 2. Basic Configuration
57+
58+
Set up the following fields to define the behavior and placement of your options page:
59+
60+
### Basic Settings Panel
61+
62+
- **Page Title**: The title displayed at the top of the options page (e.g., `Site Settings`).
63+
- **Menu Slug**: A unique identifier for the page URL (e.g., `site-settings`).
64+
- **Parent Page**: Choose `No Parent` to create a standalone page or select a parent if it should appear as a submenu item.
65+
- **Advanced Configuration**: Enable to access additional options.
66+
67+
### Advanced Settings Panel
68+
69+
#### Visibility
70+
71+
- **Menu Title**: Label that appears in the WordPress admin menu.
72+
- **Menu Icon**: Choose an icon from Dashicons or upload a custom SVG or URL.
73+
- **Menu Position**: Controls the position of the item in the admin sidebar.
74+
- **Redirect to Child Page**: If enabled, this page redirects to its first child page automatically.
75+
76+
#### Description
77+
78+
- **Description**: A short description to help explain the purpose of this options page.
79+
80+
#### Labels
81+
82+
- **Update Button Label**: Text shown on the submit button (e.g., `Update Settings`).
83+
- **Updated Message**: Message displayed after saving the options.
84+
85+
#### Permissions
86+
87+
- **Capability**: Required capability to view/edit this page (default is `edit_posts`).
88+
89+
#### Data Storage
90+
91+
- **Storage Location**: Choose whether to store the data in the options table (default) or bind it to a specific post, user, or term.
92+
- **Custom Storage**: Use a specific post ID (e.g., `123`) or context string (e.g., `user_1`).
93+
- **Autoload Options**: Enable to automatically load these values when WordPress initializes — useful for performance.
94+
95+
Click **Save** to create the options page. Once saved, you can start adding custom fields as needed.
96+
97+
## 3. Adding Fields
98+
99+
Add fields just like you would for any post type or taxonomy.
100+
101+
### Common Fields to Add
102+
103+
- `company_name` — Company name (text)
104+
- `support_email` — Support contact email (email)
105+
- `emergency_alert_message` — Site-wide notice (textarea)
106+
- `global_logo` — Logo image (image upload)
107+
108+
Each of these fields will be accessible from any page or template.
109+
110+
## For Developers
111+
112+
Options pages provide a clean way to centralize configuration. In more advanced implementations, you can:
113+
114+
- Register multiple options pages for different sections (e.g., Branding, API Keys)
115+
- Use `get_option()` if working outside the SCF context
116+
- Integrate with theme customizers or other plugin logic
117+
118+
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.
119+
120+
👉 Learn more about the WordPress Settings API:
121+
[https://developer.wordpress.org/plugins/settings/settings-api/](https://developer.wordpress.org/plugins/settings/settings-api/)

0 commit comments

Comments
 (0)