https://github.com/codad5/easy-metabox
Your wp metabox library
https://github.com/codad5/easy-metabox
Last synced: 9 months ago
JSON representation
Your wp metabox library
- Host: GitHub
- URL: https://github.com/codad5/easy-metabox
- Owner: codad5
- Created: 2025-02-08T17:17:14.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-08T18:14:19.000Z (about 1 year ago)
- Last Synced: 2025-02-08T18:24:49.950Z (about 1 year ago)
- Language: PHP
- Size: 30.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# EasyMetabox
EasyMetabox is a WordPress library that simplifies the creation and management of custom meta boxes for posts, pages, and custom post types. It provides an intuitive API for adding custom fields with various input types and handling their data.
## Core Features
- **Quick Edit Support:** Enables inline editing of custom post type fields directly from the post list table.
**Important:** Adding a field for Quick Edit using the `allow_quick_edit` option only works if you also add that field as a column in the post list table. To do this, use the appropriate filters (like `manage_{post_type}_posts_columns` and `manage_{post_type}_posts_custom_column`) to include the field in the table display.
- **WordPress Media Integration:** Provides a `wp_media` field type for seamless media uploads and management.
## Installation
Since this is a WordPress library, you can't use Composer directly unless your application compiles Composer dependencies. Here are the installation steps:
1. Download the source code from GitHub: [codad5/easy-metabox](https://github.com/codad5/easy-metabox)
2. Place the files in your WordPress plugin or theme directory.
3. Include the library in your code:
```php
require_once __DIR__ . '/path-to-easy-metabox/get-easy-metabox.php';
```
## Basic Usage
Here's a simple example of how to create a meta box:
```php
// Create a new meta box
$metabox = getEasyMetabox(
'my_meta_box', // Unique identifier
'Additional Information', // Meta box title
'post' // Post type
);
// Add fields
$metabox->add_field('author_email', 'Author Email', 'email');
$metabox->add_field('publish_date', 'Publish Date', 'date');
// Set up the meta box
$metabox->setup_actions();
```
## Available Field Types
- text
- textarea
- select
- checkbox
- radio
- number
- date
- url
- email
- tel
- password
- hidden
- color
- file
- wp_media
## Field Configuration
When adding fields, you can specify various options:
```php
$metabox->add_field(
'field_id', // Field ID
'Field Label', // Field Label
'text', // Field Type
[], // Options (for select, radio, checkbox)
[ // HTML attributes
'class' => 'my-class',
'required' => true,
'placeholder' => 'Enter value'
],
[ // Additional options
'allow_quick_edit' => true,
'default' => 'Default value'
]
);
```
## Quick Edit Support
To enable Quick Edit support for a field:
```php
$metabox->add_field(
'field_name',
'Field Label',
'text',
[],
[],
['allow_quick_edit' => true]
);
```
**Remember:** For the Quick Edit functionality to work, the field must also be added as a column in the post list table. You can do this by hooking into filters like `manage_{post_type}_posts_columns` to add the column and `manage_{post_type}_posts_custom_column` to output the field’s data. Without adding the field to the table, the Quick Edit option will not appear in your admin list.
## WordPress Media Integration
To add a media upload field:
```php
$metabox->add_field(
'image_field',
'Upload Image',
'wp_media',
[],
['multiple' => true] // Allow multiple file selection
);
```
## Retrieving Meta Values
```php
// Get a single field value
$value = $metabox->get_field_value('field_id');
// Get all meta values for a post
$all_meta = $metabox->all_meta($post_id);
```
## Complete Example
Here's a complete example showing how to create a meta box for a custom post type:
```php
'Products',
'singular_name' => 'Product',
'menu_name' => 'Products',
'add_new' => 'Add New',
'add_new_item' => 'Add New Product',
'edit_item' => 'Edit Product',
'new_item' => 'New Product',
'view_item' => 'View Product',
'search_items' => 'Search Products',
'not_found' => 'No products found',
'not_found_in_trash' => 'No products found in Trash'
);
$args = array(
'labels' => $labels,
'public' => true,
'publicly_queryable' => true,
'show_ui' => true,
'show_in_menu' => true,
'query_var' => true,
'rewrite' => array('slug' => 'products'),
'capability_type' => 'post',
'has_archive' => true,
'hierarchical' => false,
'menu_position' => 5,
'menu_icon' => 'dashicons-cart',
'supports' => array('title', 'editor', 'thumbnail')
);
register_post_type(PRODUCT_POST_TYPE, $args);
}
// Register the custom post type
add_action('init', 'register_product_post_type');
/**
* Create and configure the product meta box
*/
function add_product_metabox(): void {
global $product_metabox;
$product_metabox = getEasyMetabox('product_details', 'Product Details', PRODUCT_POST_TYPE);
$product_metabox->add_field('price', 'Price', 'number', [], [
'required' => true,
'min' => 0,
'step' => 0.01
]);
$product_metabox->add_field('category', 'Category', 'select', [
'electronics' => 'Electronics',
'clothing' => 'Clothing',
'books' => 'Books'
]);
$product_metabox->add_field('images', 'Product Images', 'wp_media', [], [
'multiple' => true
]);
$product_metabox->setup_actions();
}
add_action('admin_init', 'add_product_metabox');
**
* Handle saving the meta box data
*/
function save_product_meta($post_id): bool {
global $product_metabox;
try {
if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
return false;
}
if (!current_user_can('edit_post', $post_id)) {
return false;
}
return $product_metabox->save($post_id);
} catch (\Throwable $th) {
return false;
}
}
// Hook into saving the post type
add_action("save_post_" . PRODUCT_POST_TYPE, 'save_product_meta');
/**
* Optional: Display product meta data on the front end
*/
function display_product_meta($content) {
global $product_metabox;
// Only modify product post type content
if (!is_singular(PRODUCT_POST_TYPE)) {
return $content;
}
$post_id = get_the_ID();
$price = $product_metabox->get_field_value('price', $post_id);
$category = $product_metabox->get_field_value('category', $post_id);
$images = $product_metabox->get_field_value('images', $post_id, false); // false to get array of images
$meta_html = '
';
$meta_html .= 'Price: $' . esc_html($price) . '
';
$meta_html .= 'Category: ' . esc_html($category) . '
';
if (!empty($images)) {
$meta_html .= '';
foreach ($images as $image_url) {
$meta_html .= '%20.%20')
';
}
$meta_html .= '';
}
$meta_html .= '';
return $content . $meta_html;
}
// Add meta data to the content
add_filter('the_content', 'display_product_meta');
```
## Validation
The library includes built-in validation for field types. You can show admin errors by enabling them:
```php
$metabox->set_show_admin_error(true);
```
## Prefix Support
You can set a prefix for all field IDs:
```php
$metabox->set_prefix('my_prefix_');
```
## Custom Input Types
You can add custom input types:
```php
$metabox->set_input_type_html('custom_type', function($id, $data) {
// Return HTML string for custom input type
return "";
});
```
## License
This project is licensed under the GPL-2.0+ License.
## Author
Created by [Codad5](https://codad5.me)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.