Codex tools: Log in
Languages: English • Español • 日本語 • (Add your language)
Contents |
add_post_meta adds a custom (meta) field to the specified post (or page).
If the $unique parameter is set to true and the specified meta key already exists, the function returns false and makes no changes; otherwise, it returns true.
<?php add_post_meta($post_id, $meta_key, $meta_value, $unique); ?>
<?php add_post_meta(68, 'my_key', 47); ?>
Adds a new field if the key doesn't exist, or updates the existing field. (UPDATE: If the fourth parameter of add_post_meta is set to true, the field will not be updated if it already exists (tested on WP 2.6.2). Use if (!update_post_meta(...)) add_post_meta(...)).
<?php add_post_meta(7, 'fruit', 'banana', true) or update_post_meta(7, 'fruit', 'banana'); ?>
If you wanted to make sure that there were no fields with the key "my_key", before adding it:
<?php add_post_meta(68, 'my_key', '47', true); ?>
To add several values to the key "my_key":
<?php add_post_meta(68, 'my_key', '47'); ?> <?php add_post_meta(68, 'my_key', '682'); ?> <?php add_post_meta(68, 'my_key', 'The quick, brown fox jumped over the lazy dog.'); ?> ...
For a more detailed example, go to the post_meta Functions Examples page.
If you are a plugin/theme developer and you are planning to use custom fields to store parameters related to your plugin or template, it is interesting to note that WordPress won't show keys starting with an "_" (underscore) in the custom fields list at the page/post editing page or when using the template the_meta() function. Depending on how you plan to use the meta data, you may want to hide the values from the the admin UI by prefixing their names with an underscore.
The following example:
<?php add_post_meta(68, '_color', 'red', true); ?>
will add a unique custom field with the key name "_color" and the value "red" but this custom field will not display in the page/post editing page.
In addition, when $meta_value is an array, it will not be display on the page/post editing page.
add_post_meta() is located in wp-includes/post.php
Custom Fields: the_meta(), get_post_meta(), add_post_meta(), update_post_meta(), delete_post_meta(), get_post_custom(), get_post_custom_values(), get_post_custom_keys() (See Also: post_meta Function Examples)
