pt-br:Como usar Parâmetros
Cadastre-se e comece a Contribuir. Insira links da lista de Artigos.
Contents |
Introdução
Tags de Modelos são funções PHP que se pode inserir nos arquivos de temas WordPress e sim mostrar conteúdo dinâmico. E como funções PHP, as tags de modelos aceitam argumentos ou parâmetros. Parâmetros de Tags de Modelos são variáveis que você pode usar para mudar a saída de uma tag ou modificar sua ação de alguma forma. Pense em parâmetros como opções do usuário ou as configurações que permitem personalizar a forma como uma Tag de Modelo funciona.
No que diz respeito a parâmetros, Tags de Modelos WordPress vêm em três "sabores". Estes são descritos abaixo:
Tags sem Parâmetros
Algumas Tags de Modelos não tem nenhuma opção e portanto, não têm parâmetros que você pode passar para eles.
A Tags de Modelo [pt-br:Tags de Modelos/the_author_firstname | the_author_firstname()]] é um exemplo que não aceita parâmetros. Esta tag indica simplesmente o primeiro nome do autor de uma postagem. Tags sem parâmetros não devem ter nada entre a abertura da função e fechamento de colchetes (entre parênteses):
<?php the_author_firstname(); ?>
Tags com Funções Estilo PHP
Para as Tags de Modelo que podem aceitar parâmetros, algumas exigem que sejam no estilo PHP padrão. Para estas, os parâmetros são passados para uma função de tag, colocando um ou mais valores entre os parênteses da função, ou colchetes.
A tag bloginfo() aceita um parâmetro (conhecido como parâmtro de mostrar) que permite escolher qual informação do blog deve ser mostrada:
<?php bloginfo('name'); ?>
A tag wp_title() aceita dois parâmetros: o primeiro é sep ou separador e o segundo é echo ou parâmetro de mostrar:
<?php wp_title(' - ', TRUE); ?>
The first is enclosed in single-quotes and the second is not because the first is a string, and the second a boolean parameter. (See Tipos de Parâmetros for information on parameter types and how to use them.)
Important points to keep in mind for PHP function-style parameters:
- Some functions take multiple parameters.
- Multiple parameters are separated by commas.
- The order of parameters is important!
When passing parameters to a template tag's function, make sure you specify values for all parameters up to the last one you wish to modify, or the tag may not work as expected. For example, the template tag get_archives() has six parameters:
<?php get_archives('type', 'limit', 'format', 'before', 'after', show_post_count); ?>
To display the archives list the way you want, let's say you only need to modify the third (format) and fifth (after) parameters. To do this, you also need to make sure to enter default values for the first, second and fourth parameters, as well:
<?php get_archives('', '', 'custom', '', '<br />'); ?>
Notice the use of single-quotes to denote empty parameter values, which '' in this case '' forces defaults for those specific parameters. Be aware that defaults can be overwritten when passing empty parameters, as is the case of a parameter specifying a string of text, and there's no way to pass an empty boolean value. So check the documentation for a parameter's default, and when one is specified use it as your parameter value (also see Types of parameters for information on parameter types). The sixth parameter was left off; this is because WordPress uses the default for any remaining parameters left unspecified.
Make sure to follow the documentation for a template tag carefully, and place your parameters in the order the template function expects. Finally, to use the defaults for all parameters in a template tag, use the tag with no parameter values specified:
<?php get_archives(); ?>
Tags com Parâmetros Estilos Query-String
The last type of template tag makes use of what's called a query-string style to pass parameters to the tag. These provide a convenient 'wrapper' to tags which use the PHP function parameter style and have a relatively large number of parameters. For example, the template tag wp_list_cats() is a wrapper to list_cats(), a tag with eighteen parameters!
If you want to set the exclude parameter in list_cats() (seventeenth in the parameter list) and leave the rest at their defaults, you have to do this:
<?php list_cats(TRUE, 'All', 'ID', 'asc', '', TRUE, FALSE, FALSE, TRUE, TRUE, FALSE, '', '', FALSE, '', '', '10,11,12'); ?>
Or you can use wp_list_cats():
<?php wp_list_cats('exclude=10,11,12'); ?>
So query-string style tags are useful in that they let you change the values of just those parameters you require, without needing to provide values for all or nearly all of them. However, not all PHP function-style template tags have a query-string style equivalent. (Also note that names for tags that accept query-string style parameters usually start with a 'wp_' prefix, such as wp_list_cats(), but check the documentation on a tag to verify its method for accepting parameters, if any.)
The tag wp_list_authors() has six parameters, of which we set three here:
<?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>
First, all the parameters together are enclosed by either single or double quotes. Then each parameter is entered in the parameter=value format, while these are separated with an ampersand (&). Broken down, the tag as shown above states:
- Parameter show_fullname (a boolean type parameter) equals 1 (true).
- AND
- Parameter feed (a string type parameter) equals rss.
- AND
- Parameter optioncount (a boolean type parameter) equals 1 (true).
(See Types of parameters for information on parameter types and how to use them.)
Parameters in the query-string style do not have to be entered in a specific order. The only real concern is assuring parameter names are spelled correctly. If legibility is a problem, you can separate parameters with a space:
<?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>
You can also spread a query-string over several lines (note the specific format of enclosing each parameter/value pair in single quotes and a dot starting each new line):
<?php wp_list_authors(
'show_fullname=1'
.'&feed=rss'
.'&optioncount=1'
); ?>
There are a few limitations when using query-string style tags, among which you cannot pass certain characters, such as the ampersand or a quote mark (single or double). In those cases, you can use an associative array:
<?php $params = array( 'type' => 'postbypost',
'limit' => 5,
'format' => 'custom',
'before' => '<li>• ',
'after' => '</li>' );
wp_get_archives($params); ?>
Tipos de Parâmetros
There are three types of parameters you need to know about in regards to WordPress template tags: string, integer, and boolean. Each is handled a bit differently, as described below.
String
A string is a line of text, and is typically anything from a single character to several dozen words. A string parameter is often a selection from two or more valid options, as is the show parameter in bloginfo(). Otherwise, a string is intended as text to be displayed, such as the sep parameter in wp_title().
In tags which use the PHP function parameter style, string values should be enclosed in single (') or double (") quotation marks. If a single or double quote is required for part of your string, mix the marks (using double quotes to enclose the parameter if a single quote exists in your parameter value), or use the PHP escape character (a backslash: \), as the following does to assign single quotes for the before and after parameters in the_title():
<?php the_title('\'', '\''); ?>
Integer
An integer is a whole number (…, -2, -1, 0, 1, 2,…). Integer parameters are often used for date and archive based information, like the year and month parameters for the get_month_link() tag, or for specifying the numeric value of something on your blog, as one finds in the case of the id parameter in get_permalink().
When passed to a PHP function parameter style tag, integer values either in or out of quotes will be handled correctly. So the following examples are both valid:
<?php get_permalink('100'); ?>
<?php get_permalink(100); ?>
Boolean
Boolean são parâmetros que fornecem uma avaliação simples verdadeiro/falso.
Por exemplo a tag the_date() tem um parâmetro echo que pode ser TRUE ou FALSE como valor; se definir TRUE a data será mostrada, se usarFALSE a tag é obtida mas não mostrada e só poderá se mostrada usando outros códigos PHP.
Um parâmtro boolean pode ser em formato de número: 1 para TRUE, 0 para FALSE. Entre valores do tipo boolean, todos estes são equivalentes:
- 1 = TRUE = verdadeiro
- 0 = FALSE = falso
Entretanto, NÃO encapsule valores boolean entre aspas simples. Para query-string style tags, use valores (1 ou 0).
Todas as comunidades lusófonas também são bem-vindas! Adicione {{Codex-pt}} em seus artigos.
