Custom Fields

Custom Fields allow you to sync WordPress post meta and ACF (Advanced Custom Fields) data to Shopify metafields, extending your content with structured data.

Overview

WordPress custom fields (post meta) and ACF fields can contain valuable structured data:

• Product references
• Call-to-action buttons
• Featured quotes
• Related content links
• Custom taxonomies
• Any structured data

Wash: Blog Manager maps this data to Shopify metafields, making it accessible in your Shopify theme.

How It Works

Data Mapping

WordPress Post Meta              Shopify Article Metafields
─────────────────────────────────────────────────────────────
_featured_product           →    wash.featured_product
_cta_button_text           →    wash.cta_text
_cta_button_url            →    wash.cta_url
reading_time               →    wash.reading_time

Supported Field Types

WordPress Type	Shopify Metafield Type	Notes
Text	Single line text	Up to 5,000 chars
Textarea	Multi-line text	Up to 5,000 chars
Number	Integer or Decimal	Configurable
True/False	Boolean	Yes/No values
URL	URL	Validated URL format
Email	Single line text	Email format
Date	Date	YYYY-MM-DD format
Date/Time	Date and time	ISO 8601 format
Image	File reference	Auto-uploaded
File	File reference	Auto-uploaded
Select	Single line text	Selected value
Checkbox	JSON	Array of values
Repeater	JSON	Array of objects
Group	JSON	Nested object

Enabling Custom Fields Sync

Step 1: Enable Feature

1. Go to Wash: Blog Manager > Settings
2. Find Custom Fields section
3. Toggle Enable Custom Fields Sync to On

Step 2: Create Field Mappings

1. Go to Wash: Blog Manager > Custom Fields
2. Click Add Field Mapping
3. Configure the mapping:

┌─────────────────────────────────────────────────────────────┐
│ Add Custom Field Mapping                                    │
├─────────────────────────────────────────────────────────────┤
│ WordPress Field                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Field Key: reading_time                                 │ │
│ │ Field Source: ● Post Meta  ○ ACF Field                  │ │
│ └─────────────────────────────────────────────────────────┘ │
│                                                             │
│ Shopify Metafield                                           │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Namespace: wash                                   │ │
│ │ Key: reading_time                                       │ │
│ │ Type: Integer                                           │ │
│ └─────────────────────────────────────────────────────────┘ │
│                                                             │
│ [Save Mapping]                                              │
└─────────────────────────────────────────────────────────────┘

Step 3: Create Metafield Definitions in Shopify

For each mapped field, create a definition:

1. Go to Shopify Admin > Settings > Custom data
2. Click Articles
3. Click Add definition
4. Configure to match your mapping

Step 4: Test Sync

1. Create a post with custom field data
2. Trigger sync
3. Verify metafield values in Shopify

Common Use Cases

Reading Time

Display estimated reading time on articles.

WordPress:

// Usually calculated automatically or via plugin
update_post_meta($post_id, 'reading_time', 5);

Mapping:

WordPress: reading_time → Shopify: wash.reading_time (Integer)

Liquid display:

{% if article.metafields.wash.reading_time %}
  <span class="reading-time">
    {{ article.metafields.wash.reading_time }} min read
  </span>
{% endif %}

Featured Product

Link articles to products.

WordPress (ACF):

Field: featured_product
Type: URL or Product ID

Mapping:

WordPress: featured_product → Shopify: wash.featured_product (Product reference)

Liquid display:

{% if article.metafields.wash.featured_product %}
  {% assign product = article.metafields.wash.featured_product.value %}
  <div class="featured-product">
    <img src="{{ product.featured_image | image_url: width: 200 }}">
    <h4>{{ product.title }}</h4>
    <a href="{{ product.url }}">Shop Now</a>
  </div>
{% endif %}

Call-to-Action

Custom CTA buttons on articles.

WordPress (ACF):

Field Group: Article CTA
├── cta_text (Text)
├── cta_url (URL)
└── cta_style (Select: primary, secondary, outline)

Mappings:

cta_text → wash.cta_text (Single line text)
cta_url → wash.cta_url (URL)
cta_style → wash.cta_style (Single line text)

Liquid display:

{% if article.metafields.wash.cta_text %}
  <a
    href="{{ article.metafields.wash.cta_url }}"
    class="cta-button cta-{{ article.metafields.wash.cta_style }}"
  >
    {{ article.metafields.wash.cta_text }}
  </a>
{% endif %}

Table of Contents

Sync generated table of contents.

WordPress:

// Generated from headings
$toc = [
  ['id' => 'intro', 'title' => 'Introduction', 'level' => 2],
  ['id' => 'getting-started', 'title' => 'Getting Started', 'level' => 2],
  ['id' => 'step-1', 'title' => 'Step 1', 'level' => 3],
];
update_post_meta($post_id, 'table_of_contents', json_encode($toc));

Mapping:

table_of_contents → wash.toc (JSON)

Liquid display:

{% assign toc = article.metafields.wash.toc.value %}
{% if toc %}
  <nav class="table-of-contents">
    <h4>Contents</h4>
    <ul>
      {% for item in toc %}
        <li class="toc-level-{{ item.level }}">
          <a href="#{{ item.id }}">{{ item.title }}</a>
        </li>
      {% endfor %}
    </ul>
  </nav>
{% endif %}

Working with ACF

ACF Field Groups

Wash: Blog Manager supports all ACF field types:

ACF Field Group: Article Settings
├── hero_type (Select)
│   └── Options: default, full-width, video
├── hero_video (URL)
├── sidebar_content (WYSIWYG)
├── related_posts (Relationship)
└── gallery (Gallery)

Repeater Fields

Repeater fields sync as JSON arrays:

ACF Structure:

faq_items (Repeater)
├── Row 1
│   ├── question (Text)
│   └── answer (Textarea)
├── Row 2
│   ├── question (Text)
│   └── answer (Textarea)

Synced JSON:

[
  {"question": "How does it work?", "answer": "..."},
  {"question": "What are the benefits?", "answer": "..."}
]

Liquid display:

{% assign faqs = article.metafields.wash.faq_items.value %}
{% if faqs %}
  <div class="faq-section">
    {% for faq in faqs %}
      <div class="faq-item">
        <h4>{{ faq.question }}</h4>
        <p>{{ faq.answer }}</p>
      </div>
    {% endfor %}
  </div>
{% endif %}

Flexible Content

Flexible content syncs as typed JSON:

[
  {"acf_fc_layout": "text_block", "content": "..."},
  {"acf_fc_layout": "image_block", "image": "...", "caption": "..."},
  {"acf_fc_layout": "quote_block", "quote": "...", "author": "..."}
]

Managing Field Mappings

View All Mappings

1. Go to Wash: Blog Manager > Custom Fields
2. See table of all mappings:

┌────────────────────────────────────────────────────────────────┐
│ Custom Field Mappings                                          │
├───────────────────┬──────────────────────┬──────────┬──────────┤
│ WordPress Field   │ Shopify Metafield    │ Type     │ Status   │
├───────────────────┼──────────────────────┼──────────┼──────────┤
│ reading_time      │ wash.reading   │ Integer  │ ✓ Active │
│ featured_product  │ wash.product   │ Product  │ ✓ Active │
│ cta_text          │ wash.cta_text  │ Text     │ ✓ Active │
│ cta_url           │ wash.cta_url   │ URL      │ ✓ Active │
└───────────────────┴──────────────────────┴──────────┴──────────┘

Edit Mapping

1. Click mapping row
2. Modify settings
3. Save changes

Delete Mapping

1. Click delete icon
2. Confirm deletion

Note: Deleting a mapping doesn't delete existing metafield data in Shopify.

Bulk Import

Import mappings from JSON:

{
  "mappings": [
    {
      "wordpress_key": "reading_time",
      "shopify_namespace": "wash",
      "shopify_key": "reading_time",
      "type": "integer"
    }
  ]
}

Troubleshooting

Field Not Syncing

Check:

• Mapping exists and is active
• Field has value in WordPress
• Field key matches exactly (case-sensitive)
• Metafield definition exists in Shopify

Type Mismatch Errors

Issue: Field value doesn't match Shopify metafield type Fix:

1. Check WordPress field value format
2. Verify Shopify metafield type matches
3. Use transformation if needed

JSON Parse Errors

Issue: Complex fields causing parse errors Check:

• Valid JSON format
• No special characters breaking JSON
• Size within limits (65,535 chars)

ACF Fields Not Detected

Check:

• ACF plugin is active
• Field group is assigned to posts
• Use correct field name (not label)

Best Practices

1. Use consistent naming - Match WordPress and Shopify keys when possible
2. Document mappings - Keep a reference of all field mappings
3. Test thoroughly - Verify each field type syncs correctly
4. Handle empty values - Use Liquid conditionals for optional fields
5. Consider performance - Don't sync unnecessary fields

---

Related Documentation

• Connection Settings
• Author Mapping
• Images and Files