最简字段插件使用说明

wptutor 最简字段插件使用说明已关闭评论 58 浏览量

# WP SimpleSet Fields Plugin - Complete Usage Guide

## Overview

WP SimpleSet Fields is a lightweight, flexible WordPress field framework that allows developers to easily create custom fields for theme options, post meta, and taxonomy meta. The plugin provides a simple API for adding various field types with minimal code.

## Installation

1. Upload the plugin folder to `/wp-content/plugins/`
2. Activate the plugin through the WordPress admin
3. The plugin automatically creates CSS and JavaScript dependencies

## Basic Usage

### Getting Started

The plugin uses a singleton pattern. Access the framework instance using:

```php
$framework = wp_field_framework();
```

### Adding Sections (Theme Options)

Before adding fields to theme options, you can organize them into sections:

```php
$framework->add_section([
    'id' => 'general',
    'title' => 'General Settings',
    'description' => 'Basic website configuration options',
    'icon' => 'dashicons-admin-generic', // Optional dashicon
    'priority' => 10 // Display order
]);
```

### Adding Fields

The `add_field()` method accepts an array of parameters:

```php
$framework->add_field([
    'id' => 'field_unique_id',
    'type' => 'text', // Field type
    'title' => 'Field Label',
    'description' => 'Help text for the field',
    'default' => 'default_value',
    'context' => 'theme_option', // Where the field appears
    'section' => 'general', // Section ID (for theme options)
    'post_type' => 'post', // For post meta fields
    'taxonomy' => 'category', // For term meta fields
    'options' => [] // For select, radio, multiselect fields
]);
```

## Field Types

### 1. Text Field

```php
$framework->add_field([
    'id' => 'site_tagline',
    'type' => 'text',
    'title' => 'Site Tagline',
    'description' => 'Enter your site tagline',
    'default' => 'Welcome to our website',
    'context' => 'theme_option'
]);
```

### 2. Textarea Field

```php
$framework->add_field([
    'id' => 'footer_text',
    'type' => 'textarea',
    'title' => 'Footer Text',
    'description' => 'Text to display in footer',
    'context' => 'theme_option'
]);
```

### 3. Select Dropdown

```php
$framework->add_field([
    'id' => 'layout_style',
    'type' => 'select',
    'title' => 'Layout Style',
    'options' => [
        'full-width' => 'Full Width',
        'boxed' => 'Boxed Layout',
        'sidebar-left' => 'Left Sidebar',
        'sidebar-right' => 'Right Sidebar'
    ],
    'default' => 'full-width',
    'context' => 'theme_option'
]);
```

### 4. Multi-Select

```php
$framework->add_field([
    'id' => 'featured_categories',
    'type' => 'multiselect',
    'title' => 'Featured Categories',
    'options' => [
        'tech' => 'Technology',
        'design' => 'Design',
        'business' => 'Business'
    ],
    'context' => 'theme_option'
]);
```

### 5. Radio Buttons

```php
$framework->add_field([
    'id' => 'color_scheme',
    'type' => 'radio',
    'title' => 'Color Scheme',
    'options' => [
        'light' => 'Light Theme',
        'dark' => 'Dark Theme',
        'auto' => 'Auto (System Preference)'
    ],
    'default' => 'light',
    'context' => 'theme_option'
]);
```

### 6. Checkbox

```php
$framework->add_field([
    'id' => 'enable_comments',
    'type' => 'checkbox',
    'title' => 'Enable Comments',
    'description' => 'Allow comments on blog posts',
    'context' => 'theme_option'
]);
```

### 7. Color Picker

```php
$framework->add_field([
    'id' => 'brand_color',
    'type' => 'color',
    'title' => 'Brand Color',
    'default' => '#007cba',
    'context' => 'theme_option'
]);
```

### 8. Image Upload

```php
$framework->add_field([
    'id' => 'site_logo',
    'type' => 'image',
    'title' => 'Site Logo',
    'description' => 'Upload your site logo',
    'context' => 'theme_option'
]);
```

### 9. File Upload

```php
$framework->add_field([
    'id' => 'user_manual',
    'type' => 'file',
    'title' => 'User Manual',
    'description' => 'Upload a PDF user manual',
    'context' => 'post_meta',
    'post_type' => 'product'
]);
```

### 10. Gallery

```php
$framework->add_field([
    'id' => 'product_gallery',
    'type' => 'gallery',
    'title' => 'Product Gallery',
    'description' => 'Select multiple images for the gallery',
    'context' => 'post_meta',
    'post_type' => 'product'
]);
```

### 11. Rich Text Editor

```php
$framework->add_field([
    'id' => 'about_content',
    'type' => 'rich_editor',
    'title' => 'About Content',
    'description' => 'Rich text content with formatting options',
    'context' => 'theme_option',
    'editor_settings' => [
        'textarea_rows' => 15,
        'media_buttons' => true,
        'teeny' => false
    ]
]);
```

### 12. Group Fields (Repeatable)

Group fields allow you to create repeatable sets of fields:

```php
$framework->add_field([
    'id' => 'team_members',
    'type' => 'group',
    'title' => 'Team Members',
    'description' => 'Add team member information',
    'context' => 'theme_option',
    'add_text' => 'Add New Member',
    'group_title' => 'Team Member',
    'fields' => [
        [
            'id' => 'name',
            'type' => 'text',
            'title' => 'Name',
            'default' => ''
        ],
        [
            'id' => 'position',
            'type' => 'text',
            'title' => 'Position',
            'default' => ''
        ],
        [
            'id' => 'bio',
            'type' => 'textarea',
            'title' => 'Biography',
            'default' => ''
        ],
        [
            'id' => 'photo',
            'type' => 'image',
            'title' => 'Photo'
        ],
        [
            'id' => 'active',
            'type' => 'checkbox',
            'title' => 'Currently Active'
        ]
    ]
]);
```

## Field Contexts

### Theme Options

Fields appear in the WordPress admin under Settings > Theme Options:

```php
$framework->add_field([
    'id' => 'header_logo',
    'type' => 'image',
    'title' => 'Header Logo',
    'context' => 'theme_option',
    'section' => 'general'
]);
```

### Post Meta Fields

Add custom fields to post edit screens:

```php
$framework->add_field([
    'id' => 'featured_video',
    'type' => 'text',
    'title' => 'Featured Video URL',
    'context' => 'post_meta',
    'post_type' => 'post' // Can be 'post', 'page', or custom post type
]);
```

### Taxonomy Meta Fields

Add fields to category, tag, or custom taxonomy edit screens:

```php
$framework->add_field([
    'id' => 'category_icon',
    'type' => 'image',
    'title' => 'Category Icon',
    'context' => 'term_meta',
    'taxonomy' => 'category'
]);
```

## Retrieving Field Values

### Theme Options

```php
// Get theme option value
$framework = wp_field_framework();
$logo_id = $framework->get_value('header_logo', 'theme_option');
$logo_url = wp_get_attachment_url($logo_id);
```

### Post Meta

```php
// Get post meta value
$framework = wp_field_framework();
$video_url = $framework->get_value('featured_video', 'post_meta', get_the_ID());

// Or use WordPress native function
$video_url = get_post_meta(get_the_ID(), 'featured_video', true);
```

### Term Meta

```php
// Get term meta value
$framework = wp_field_framework();
$icon_id = $framework->get_value('category_icon', 'term_meta', $term_id);

// Or use WordPress native function
$icon_id = get_term_meta($term_id, 'category_icon', true);
```

### Group Fields

```php
// Retrieve group field data
$team_members = $framework->get_value('team_members', 'theme_option');

if (!empty($team_members)) {
    foreach ($team_members as $member) {
        echo '<h3>' . esc_html($member['name']) . '</h3>';
        echo '<p>' . esc_html($member['position']) . '</p>';
        echo '<p>' . esc_html($member['bio']) . '</p>';
        
        if (!empty($member['photo'])) {
            echo wp_get_attachment_image($member['photo'], 'medium');
        }
        
        if (!empty($member['active'])) {
            echo '<span class="active-badge">Currently Active</span>';
        }
    }
}
```

## Helper Functions

### Gallery Display Function

The plugin includes a helper function for displaying galleries:

```php
// Display gallery in template
display_gallery('product_gallery', 'post_meta', get_the_ID());

// Or manually handle gallery
$gallery_ids = get_post_meta(get_the_ID(), 'product_gallery', true);
if ($gallery_ids) {
    $image_ids = is_string($gallery_ids) ? explode(',', $gallery_ids) : (array)$gallery_ids;
    foreach ($image_ids as $image_id) {
        echo wp_get_attachment_image($image_id, 'medium');
    }
}
```

## Complete Example

Here's a complete example showing how to set up various fields:

```php
// Add this to your theme's functions.php or a custom plugin

function setup_custom_fields() {
    $framework = wp_field_framework();
    
    // Add sections
    $framework->add_section([
        'id' => 'general',
        'title' => 'General Settings',
        'description' => 'Basic site configuration',
        'icon' => 'dashicons-admin-generic'
    ]);
    
    $framework->add_section([
        'id' => 'social',
        'title' => 'Social Media',
        'description' => 'Social media links and settings',
        'icon' => 'dashicons-share'
    ]);
    
    // Theme option fields
    $framework->add_field([
        'id' => 'site_logo',
        'type' => 'image',
        'title' => 'Site Logo',
        'description' => 'Upload your site logo',
        'context' => 'theme_option',
        'section' => 'general'
    ]);
    
    $framework->add_field([
        'id' => 'facebook_url',
        'type' => 'text',
        'title' => 'Facebook URL',
        'context' => 'theme_option',
        'section' => 'social'
    ]);
    
    // Post meta field
    $framework->add_field([
        'id' => 'post_subtitle',
        'type' => 'text',
        'title' => 'Post Subtitle',
        'context' => 'post_meta',
        'post_type' => 'post'
    ]);
    
    // Term meta field
    $framework->add_field([
        'id' => 'category_color',
        'type' => 'color',
        'title' => 'Category Color',
        'context' => 'term_meta',
        'taxonomy' => 'category'
    ]);
}

add_action('init', 'setup_custom_fields');
```

## Best Practices

1. **Use descriptive IDs**: Always use unique, descriptive field IDs
2. **Add descriptions**: Help users understand what each field does
3. **Set defaults**: Provide sensible default values
4. **Sanitization**: The plugin handles sanitization automatically
5. **Performance**: Field values are cached by WordPress
6. **Translations**: Use translation functions for user-facing text

## Styling and Customization

The plugin includes built-in CSS for proper field styling. Custom styles can be added via your theme's stylesheet or by enqueueing additional CSS.

## Browser Storage Limitation

Note: This plugin does not use localStorage or sessionStorage, making it compatible with various hosting environments and admin interfaces.

## Support and Troubleshooting

- Ensure proper WordPress permissions for users accessing custom fields
- Check that post types and taxonomies exist before adding fields
- Verify field IDs are unique across your implementation
- Use browser developer tools to debug JavaScript-related field issues

This plugin provides a solid foundation for adding custom fields to WordPress without the complexity of larger field frameworks, making it ideal for theme developers who need lightweight, reliable field management.