feat: Initial Claude skills for websimple-devops
This commit is contained in:
271
references/wp-acf.md
Normal file
271
references/wp-acf.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# WP ACF
|
||||
|
||||
Use this skill for Websimple WordPress projects that use Advanced Custom Fields.
|
||||
|
||||
Use `references/wp-theme-dev.md` for general PHP/theme structure, `references/wp-code-style.md` for PHPCS/PHPCBF, `references/wp-browser.md` for visual checks, and `references/wp-xdebug.md` for runtime debugging.
|
||||
|
||||
## Core principles
|
||||
|
||||
- Keep ACF configuration predictable, portable, and version-controlled.
|
||||
- Prefer clear field names that map naturally to template usage.
|
||||
- Keep field registration/ACF hooks under `includes/vendors/acf.php` or the existing ACF vendor/module file.
|
||||
- Keep rendering logic in templates and reusable data helpers under `includes/` when needed.
|
||||
- Avoid changing field keys, field names, return formats, or option names casually; these may affect stored content.
|
||||
|
||||
## Local JSON
|
||||
|
||||
ACF field group JSON definitions should live under the active theme's `acf-json/` directory.
|
||||
|
||||
- Keep ACF JSON files version-controlled.
|
||||
- Preserve the project's existing JSON directory if one exists.
|
||||
- For greenfield projects, use `acf-json/` at the theme root.
|
||||
- Ensure the `acf-json/` directory exists and is writable by WordPress.
|
||||
- Do not delete or regenerate ACF JSON files without checking the diff.
|
||||
|
||||
When local JSON is enabled, saving a field group, post type, taxonomy, or options page in wp-admin automatically creates or updates its JSON file. Do not tell the user to manually re-export JSON after normal dashboard saves; instead, remind them to review and commit the changed JSON file.
|
||||
|
||||
There is no expected per-field-group `json_sync` flag in Websimple conventions. ACF local JSON is controlled by ACF's global JSON setting and save/load paths. ACF defaults local JSON on and uses the active theme's `acf-json/` folder unless customized.
|
||||
|
||||
If PHP hooks customize ACF JSON paths, keep them in the ACF vendor/module file, e.g. `includes/vendors/acf.php`.
|
||||
|
||||
## Field group keys and filenames
|
||||
|
||||
For greenfield field groups, use deterministic field group keys instead of ACF's auto-generated group keys.
|
||||
|
||||
The field group key should match the JSON filename and describe what the group targets:
|
||||
|
||||
```text
|
||||
acf-json/group_post_project.json
|
||||
key: group_post_project
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
group_post_project # fields for the project custom post type
|
||||
group_page_home # fields for the home page/template
|
||||
group_options_site # site options fields
|
||||
group_taxonomy_sector # fields for the sector taxonomy
|
||||
```
|
||||
|
||||
ACF field keys inside the group may remain auto-generated. The deterministic-key convention applies primarily to field groups so JSON files stay organized and easy to find.
|
||||
|
||||
For existing projects with auto-generated field group keys, preserve them unless the user explicitly approves a cleanup/migration. Do not rename existing field group keys casually because synced JSON, database references, and editor workflows may depend on them.
|
||||
|
||||
## Synchronizing ACF JSON
|
||||
|
||||
For ACF 6.8+ with WP-CLI available, prefer the built-in ACF JSON CLI commands.
|
||||
|
||||
Safe inspection:
|
||||
|
||||
```bash
|
||||
wp acf json status
|
||||
wp acf json sync --dry-run
|
||||
```
|
||||
|
||||
Apply pending local JSON changes to the database:
|
||||
|
||||
```bash
|
||||
wp acf json sync
|
||||
```
|
||||
|
||||
Useful scoped variants:
|
||||
|
||||
```bash
|
||||
wp acf json sync --type=field-group
|
||||
wp acf json sync --key=group_post_project
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `wp acf json sync` modifies the database; run `--dry-run` first, especially outside local development.
|
||||
- The command syncs pending local JSON changes for ACF item types such as field groups, post types, taxonomies, and options pages.
|
||||
- If no items are pending, expect an “already in sync” style result.
|
||||
- Do not use a guessed `--all` flag; current ACF CLI sync defaults to all supported item types unless scoped with `--type` or `--key`.
|
||||
|
||||
If the project uses an older ACF/ACF PRO version without these commands:
|
||||
|
||||
1. Check the installed ACF version and whether an update is safe for the project.
|
||||
2. If updating is low-risk and explicitly approved, update ACF/ACF PRO first, then use the CLI workflow.
|
||||
3. Otherwise, use `references/wp-browser.md` to navigate wp-admin and sync from the ACF field group/admin screen.
|
||||
|
||||
For production or staging, ask before updating plugins or syncing database-backed ACF changes.
|
||||
|
||||
## Field group organization
|
||||
|
||||
Use field groups that reflect editorial concepts and template needs.
|
||||
|
||||
Common grouping patterns:
|
||||
|
||||
- page/template-specific fields;
|
||||
- reusable section/component fields;
|
||||
- site options;
|
||||
- post type-specific metadata;
|
||||
- taxonomy/user/menu-item metadata when needed.
|
||||
|
||||
Avoid dumping unrelated fields into a single large group. Prefer labels and instructions that make sense to editors.
|
||||
|
||||
## Field naming
|
||||
|
||||
Use stable, descriptive, snake_case field names.
|
||||
|
||||
Good examples:
|
||||
|
||||
```text
|
||||
hero_title
|
||||
hero_text
|
||||
hero_image
|
||||
cta_link
|
||||
featured_posts
|
||||
background_color
|
||||
```
|
||||
|
||||
Avoid vague names like `title_2`, `content_block`, or `misc` unless the existing project convention requires it.
|
||||
|
||||
Do not rename existing field names unless the user accepts the content migration risk.
|
||||
|
||||
## Return formats
|
||||
|
||||
Respect existing return formats. Changing them can break templates.
|
||||
|
||||
Common preferences:
|
||||
|
||||
- image fields: use the format already expected by the theme; arrays are useful when templates need alt/title/sizes;
|
||||
- link fields: arrays are usually practical for URL/title/target;
|
||||
- post object / relationship fields: know whether the field returns IDs or objects before using it;
|
||||
- true/false fields: handle empty/false explicitly.
|
||||
|
||||
When uncertain, inspect the field group JSON or runtime value before changing template code.
|
||||
|
||||
## Template usage
|
||||
|
||||
Prefer `get_field()` when the value needs escaping, conditionals, fallback handling, or reuse.
|
||||
|
||||
```php
|
||||
<?php $title = get_field( 'hero_title' ); ?>
|
||||
|
||||
<?php if ( $title ) : ?>
|
||||
<h1><?= esc_html( $title ); ?></h1>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
Use compact output tags with escaping, following `references/wp-theme-dev.md`:
|
||||
|
||||
```php
|
||||
<?= esc_html( get_field( 'eyebrow' ) ); ?>
|
||||
<?= wp_kses_post( get_field( 'intro' ) ); ?>
|
||||
```
|
||||
|
||||
Avoid `the_field()` for dynamic frontend output unless the value is known safe for the exact context. Prefer explicit escaping with `get_field()`.
|
||||
|
||||
For image arrays:
|
||||
|
||||
```php
|
||||
<?php $image = get_field( 'hero_image' ); ?>
|
||||
|
||||
<?php if ( $image ) : ?>
|
||||
<img
|
||||
src="<?= esc_url( $image['url'] ); ?>"
|
||||
alt="<?= esc_attr( $image['alt'] ?? '' ); ?>"
|
||||
>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
For link arrays:
|
||||
|
||||
```php
|
||||
<?php $link = get_field( 'cta_link' ); ?>
|
||||
|
||||
<?php if ( $link ) : ?>
|
||||
<a href="<?= esc_url( $link['url'] ); ?>" target="<?= esc_attr( $link['target'] ?: '_self' ); ?>">
|
||||
<?= esc_html( $link['title'] ); ?>
|
||||
</a>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
## Options pages
|
||||
|
||||
Keep ACF options-page registration in the ACF vendor/module file.
|
||||
|
||||
Use options pages for true site-wide settings, not content that belongs to a page, post, taxonomy, or theme template.
|
||||
|
||||
When reading option fields, make the option scope explicit:
|
||||
|
||||
```php
|
||||
<?php $phone = get_field( 'phone_number', 'option' ); ?>
|
||||
```
|
||||
|
||||
## Flexible content and repeaters
|
||||
|
||||
Keep flexible content layouts readable and component-oriented.
|
||||
|
||||
- Use layout names that map to template partials or sections.
|
||||
- Keep layout fields scoped to what the layout renders.
|
||||
- Avoid deeply nested repeaters/flexible fields unless there is a strong editorial reason.
|
||||
- For complex flexible content rendering, prefer dispatching to template parts instead of one giant template file.
|
||||
|
||||
The dispatch pattern depends on the theme. **Check whether the theme is a Kaliroots child theme first** (see `references/wp-kaliroots.md`) — Kaliroots has its own template lookup helpers and overriding them with generic WP dispatch fragments the resolution path.
|
||||
|
||||
For a **generic (non-Kaliroots) WordPress theme**:
|
||||
|
||||
```php
|
||||
<?php if ( have_rows( 'sections' ) ) : ?>
|
||||
<?php while ( have_rows( 'sections' ) ) : the_row(); ?>
|
||||
<?php get_template_part( 'templates/content/sections/' . get_row_layout() ); ?>
|
||||
<?php endwhile; ?>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
For a **Kaliroots child theme**, dispatch through the Kaliroots section helper so child/parent override resolution works correctly:
|
||||
|
||||
```php
|
||||
<?php if ( have_rows( 'sections' ) ) : ?>
|
||||
<?php while ( have_rows( 'sections' ) ) : the_row(); ?>
|
||||
<?= kaliroots_section_template( get_row_layout() ); ?>
|
||||
<?php endwhile; ?>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
In a Kaliroots project, the section partial then lives at `templates/content/sections/{layout-name}.php` and is located via Kaliroots' lookup pipeline — see `references/wp-kaliroots.md` for the helper set and naming rules.
|
||||
|
||||
Verify that the target partial exists before introducing either dispatch into an existing theme. If the project already uses a different established pattern, follow that — don't reorganize.
|
||||
|
||||
Inside the layout partial, use `get_sub_field()` (not `get_field()`) to read layout sub-fields, and escape at output:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$heading = get_sub_field( 'heading' );
|
||||
$image = get_sub_field( 'image' );
|
||||
?>
|
||||
<?php if ( $heading ) : ?>
|
||||
<h2><?= esc_html( $heading ); ?></h2>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
## Relationship and post object fields
|
||||
|
||||
Before using relationship/post object fields, confirm whether they return IDs or post objects.
|
||||
|
||||
- If using objects, restore global post state after setup.
|
||||
- If using IDs, use explicit IDs with WordPress APIs.
|
||||
- Avoid expensive relationship queries inside repeated templates when values can be prepared once.
|
||||
|
||||
## Refactoring workflow
|
||||
|
||||
1. Inspect the active theme, ACF plugin availability, existing ACF JSON path, and ACF-related include files.
|
||||
2. Inspect existing field group JSON before changing field names, keys, return formats, or locations.
|
||||
3. Keep PHP hooks/registration in the existing ACF module, usually `includes/vendors/acf.php`.
|
||||
4. Keep template output escaped explicitly with `get_field()` where practical.
|
||||
5. Make small, reversible changes.
|
||||
6. After wp-admin field group edits, inspect the automatically updated `acf-json/` diff.
|
||||
7. Run PHP lint/style checks via `references/wp-code-style.md` when PHP files changed.
|
||||
8. Smoke-test affected frontend/admin behavior with `references/wp-browser.md` when relevant.
|
||||
9. Inspect the diff, especially ACF JSON changes.
|
||||
|
||||
## Safety
|
||||
|
||||
- Do not rename existing field names or change return formats without calling out content/template impact.
|
||||
- Do not delete ACF JSON files without explicit approval.
|
||||
- Do not expose secrets from options pages or database values.
|
||||
- Do not assume `the_field()` output is safe; escape based on context.
|
||||
- Preserve the project's existing ACF structure when it is coherent.
|
||||
Reference in New Issue
Block a user