WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

pt-br:Referência de Função/add post meta

Descrição

Adiciona um custom field (também chamado meta-data) para um post especifico ou post type. Um campo personalizado nada mais é que um campo de texto onde você pode inserir um valor para cada post.

É importante observar que se a chave que está sendo utilizada já existir uma outra chave será criada com o mesmo nome, a menos que o argumento $unique esteja marcado como true. Se você deseja atualizar o valor de um campo personalizado deve utilizar update_post_meta().

Como Usar

 <?php add_post_meta($post_id$meta_key$meta_value$unique); ?> 

Parâmetros

$post_id
(integer) (required) O ID do post para o qual o campo personalizado será adicionado.
Default: None
$meta_key
(string) (required) O nome do campo personalizado que será adicionado.
Default: None
$meta_value
(mixed) (required) O valor que deverá ser adicionado ao campo personalizado. Se for passada uma matriz ela será serializada em string.
Default: None
$unique
(boolean) (opcional) Se deseja ou não que a chave seja unica. Se utilizar true, to campo personalizado não será adicionado caso já exista um campo com a mesma chave.
Default: false

Retorno

(boolean) 
Boolean true, exceto se $unique se o ultimo argumento foi definido como true e já existe um campo personalizado com o mesmo nome, neste caso false é retornado.

Exemplos

Uso Padrão

<?php add_post_meta( 68, 'my_key', 47 ); ?>

Adicionando ou Editando um Campo Personalizado Exclusivo

Adiciona um novo campo personalizado se não existir um com a mesma chave ou atualiza o valor do campo personalizado caso ele exista.

 <?php add_post_meta( 7, 'fruit', 'banana', true ) || update_post_meta( 7, 'fruit', 'banana' ); ?>

O código abaixo terá o mesmo efeito:

<?php
// Adiciona ou atualiza um campo personalizado.
if ( ! update_post_meta (7, 'fruit', 'banana', true) ) { 
	add_post_meta(7, 'fruit', 'banana', true );	
}; 
?> 

Outros Exemplos

Adiciona o campo personalizado apenas se ainda não existir um com o mesmo nome:

<?php add_post_meta( 68, 'my_key', '47', true ); ?>

Adicionando vários campos personalizados, com o mesmo nome e valores diferentes '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.' ); ?>
...

Para um exemplo mais detalhado consulte a página post_meta Functions Examples.

Campos Personalizados Invisiveis

Se você estiver desenvolvendo temas ou plugins talvez não queira que o WordPress mostre os campos personalizados que armazenam informações importantes, para estes casos você pode criar campos personalizados utilizando "_" (underscore) no inicio do nome e ele não será listado.

Exemplo de uso:

<?php add_post_meta( 68, '_color', 'red', true ); ?>

O código acima vai adicionar um campo personalizado com o nome '_color' e o valor 'red' e este campo não será listado na tela de edição do post.

Caracteres de Escape

Como os valores dos campos personalizados são tratados com base na função stripslashes(), você precisa tomar cuidado com o escape do conteúdo \ characters. Leia mais sobre isso em: update_post_meta().

Código Fonte

add_post_meta() is located in wp-includes/post.php

Change Log

Since 1.5.0

Conteúdo Relacionado

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)

See also index of Function Reference and index of Template Tags.