Codex

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

pt-br:Shortcode Gallery

O WordPress possui um recurso para mostrar imagens de seu site em posts ou páginas, sem que precise inserir cada imagem novamente na área de texto, este recurso se chama Galeria ou Galeria nativa do WordPress.

Por padrão, a galeria mostrará miniaturas das imagens com link para uma página com a imagem em tamanho inteiro ou links para tamanhos variados em alguns casos.

wp-gallery.jpg
A galeria de imagens nativa do WordPress mostra miniaturas de suas imagens


Para mostrar uma galeria em seu post ou página, antes de tudo é preciso enviar imagens para o seu site, essas imagens podem estar anexadas somente ao post ou página em questão ou não anexadas a nenhum post ou página, ambas podem ser mostradas através da galeria nativa.

  • Mídias anexadas são as mídias que estão atreladas a um post ou página em especial, isso acontece quando enviamos uma imagem durante a criação ou edição de uma publicação - post ou página. Uma mídia já anexada a uma publicação não pode ser anexada ao mesmo tempo em outra por padrão. Para anexar imagens, você precisa criar ou editar um post ou página e clicar no botão Adicionar Mídia no topo da área de texto. Veja sobre o Posts → Adicionar Novo ou Páginas → Adicionar Nova.
  • Mídias não anexadas são as mídias que foram enviadas para o site mas não estão atreladas a nenhuma publicação - post ou página. Isso acontece quando enviamos uma mídia sem estar editando ou criando uma publicação, por exemplo, acessando o Mídia → Adicionar Nova.

Parâmetros

As opções seguintes são suportadas através de parâmetros passados no shortcodes:

columns
o número de colunas. A galeria irá incluir uma tag de quebra no final de cada linha e calcular a largura da coluna conforme o caso. O valor padrão é 3. Se colunas é definido como 0, nenhuma quebra de linha será incluída. Por exemplo, para exibir uma galeria com 4 colunas:
[gallery columns="4"]
id
especifica a ID do post ou página. A galeria irá mostrar imagens que estão anexadas ao post/página. O padrão se nenhum ID for especificado, é mostrar as imagens anexadas ao post atual. Por exemplo, para exibir as imagens anexadas do post 123:
[gallery id="123"]
size
o tamanho da imagem a ser usada para a exibição de miniaturas. Os valores válidos são thumbnail (miniatura) , medium (médio), large (grande) e full (total). O padrão é thumbnail. O tamanho das imagens para "miniatura", "médio" e "grandes " podem ser configurados no painel de administração do WordPress em Configurações > Mídia. Por exemplo, para exibir uma galeria de imagens de média dimensão:
[gallery size="medium"]
ids
para informar IDs de várias imagens ao mesmo tempo, isto é, criar uma galeria com imagens somente das determinadas ID. Cada imagem enviada contém um número ID único que pode ser usado no shortcode, tanto as imagens anexadas quanto as que estão soltas, separe IDs por vírgula como segue:
[gallery ids="123, 146, 4452, 3355"]

Opções avançadas

orderby 
especifica a ordem para mostrar as miniaturas. O padrão é "menu_order ASC, ID ASC". "RAND" (aleatório) também é suportado.
itemtag 
nome da tag XHTML usada para envolver cada item da galeria. O padrão é "dl".
icontag 
o nome da tag XHTML usada para envolver cada ícone de miniatura na galeria. O padrão é "dt".
captiontag
o nome da tag XHTML usada para envolver cada legenda. O padrão é "dd". Por exemplo, para alterar a marcação usada na galeria para usar tags span div, p etc
link
você pode configurar o link apontar para o "arquivo" para cada imagem um link para o arquivo de imagem. O padrão é um link permanente para o anexo.
include
IDs de anexos separados por vírgula, [gallery include="23,39,45"] irá mostrar apenas as imagens com esses IDs.
exclude
IDs de anexo separados por vírgula, [gallery exclude="21,32,43"] exclui as imagens com esses IDs. Por favor note que include e exclude não podem ser usados juntos.
[gallery itemtag="div" icontag="span" captiontag="p" link="file"]

Inserindo o shortcode

Você já sabe que precisa ter imagens enviadas ao servidor de seu site para criar uma galeria e que estas podem estar anexas a posts ou páginas específicos ou estarem soltas, agora veja como mostrar galerias em suas publicações.

Para que o WordPress saiba que você quer mostrar uma galeria de imagens em um post ou página é preciso usar um shortcode na área de texto, isso vai informar ao WordPress que mostre uma galeria das imagens anexadas no post ou página que está editando, há 3 modos de se usar o shortcode:

Inserindo o shortcode manualmente

Tanto no modo Visual quanto Texto, apenas adicione o seguinte em seu post ou página:

 [gallery]

Você pode adicionar texto antes ou depois da área onde vai aparecer a galeria normalmente, mas por padrão a galeria não permite que flutue texto ao seu redor.

Inserindo o shortcode através de Inserir Mídia

A janela Inserir Mídia permite que você insira a galeria em seu post ou página com todas as opções do shortcode sem precisa adicioná-lo manualmente. Veja Inserindo Imagens em Posts e Páginas

Inserindo o shortcode no arquivo do tema

Você pode adicionar código à um arquivo de tema para que a galeria seja mostrada automaticamente, sem precisar inserir o shortcode na área de texto:

 <?php echo do_shortcode('[gallery opção="valor"]'); ?>

Ou:

 <?php
    $gallery_shortcode = '[gallery id="' . intval( $post->post_parent ) . '"]';
    print apply_filters( 'the_content', $gallery_shortcode );
 ?>

Veja sobre Hierarquia de Modelos Wordpress para saber em quais arquivos você pode usar esses códigos.

Inserindo o shortcode através de filtros

Notas sobre a galeria nativa

Não é possível gerar galerias de imagens que não estão anexas ou que não estão no seu servidor
ou seja, imagens que inserir no texto informando a URL, não podem ser processadas para gerar uma galeria. A galeria usa a miniatura da imagem, então imagens remotas também não têm miniatura (Imagem Destacada).
O tamanho usado na galeria é o que está definido como Miniatura
Para modificar o tamanho das imagens da galeria, modifique o tamanho definido para miniaturas em Configurações > Mídia, no item Tamanho da Miniatura. Observe que ao fazer isso, as minituras precisarão ser regeneradas. Isso é feito através de plugins externos.
Há plugins que adicionam recursos a galeria nativa
existem muitos plugins que adicionam recursos interessantes à galeria do WordPress ou às imagens anexadas ao post/página.

Links Externos

brasil-1.png
A documentação do WordPress em Português do Brasil.
Todas as comunidades lusófonas também são bem-vindas! Adicione {{Codex-pt}} em seus artigos.