Predefinição:Category handler/doc

Esta é a metapredefinição {{Predefinição:!((:Predefinição:Category handler|category handlerPredefinição:))!}}.

Ela ajuda outras predefinições a automatizar ambas categorização e supressões de categoria.

Quando usada com suas configurações padrão esta predefinição previne auto-categorização em alguns espaços nominais e em algumas páginas onde geralmente não se quer categorização. Portanto, mesmo o mais simples dos usos: "{{category handler|[[Categoria:Alguma]]}}" faz com que a predefinição não categorize nos locais errados.

Esta predefinição torna fácil escolher em quais espaços nominais a predefinição categorizará ou não. E ela torna fácil usar diferentes categorias em diferentes espaços nominais, além de utilizar uma lista negra centralizada onde pode-se adicionar páginas e tipos de páginas onde predefinições nunca irão categorizar.

Quando não utilizar esta predefinição

Se uma predefinição só precisa categorizar no espaço nominal principal (artigos), ficheiros (imagens) ou categoria, então usar esta predefinição é um exagero. Então, ao invés disto utiliza uma das {{artigos e outros}}, {{ficheiros e outros}}, or {{categorias e outros}}. Mas se sua predefinição precisa categorizar em qualquer outro espaço nominal, então é recomendado utilizar esta predefinição, já que ela fornece a supressão de categorias propriamente dita, e torna fácil selecionar como categorizar em diferentes espaços nominais.

Espaços nominais

Esta predefinição detecta e agrupa todos diferentes espaços nominais usados na Wikihelp, em vários tipos. Estes tipos são usados como nomes de parâmetros nesta predefinição.

principal = Espaço principal/artigos, como nos artigos normais da Wikihelp.

discussão = Qualquer espaço de discussão, como nomes que terminam com "Discussão", "Usuário discussão:", "Ficheiro Discussão:" e assim por diante.

usuário, wikihelp, ficheiro, mediawiki, predefinição, ajuda, categoria, portal e livro = Outros espaços nominais excepto as páginas de discussão.

outro = Qualquer espaço nominal que não especificada como um parâmetro para a predefinição. Veja os exemplos abaixo.

Uso básico

Esta predefinição leva dois ou mais parâmetros. Aqui vão exemplos explicativos sobre o código completo para uma caixa de mensagem de artigo:

{{ambox
| texto = Esta é uma caixa usada em artigos.
}}{{category handler
| [[Category:Somecat]]
| semcat = {{{semcat|}}}   <!--Então "semcat=verdadeiro/falso" funciona-->
}}<noinclude>

{{documentação}}
</noinclude>

O exemplo acima usa as configurações padrão para {{category handler|...}}. Isto significa que a caixa vai categorizar nas páginas nos seguintes espaços nominais:

principal, ficheiro, ajuda, categoria, portal e livro

Mas não vai nos seguintes:

discussão, usuário, wikihelp, mediawiki e predefinição

E não vai categorizar nas páginas listadas na lista negra. (Veja a lista negra abaixo.)

A razão para esta predefinição não categorizar em alguns dos espaços nominais é que nestes espaços a maioria das predefinições são apenas demonstradas ou listadas, não usadas. Portanto a maioria das predefinições não devem categorizar estes espaços.

Qualquer predefinição que deve categorizar em um ou mais destes espaços deve utilizar a sintaxe básica mostrada abaixo.

Uso estendido

Esta predefinição utiliza um ou mais parâmetros para categorizar diferentes espaços nominais, como listadas na seção espaços nominais, acima. Ao usar um ou mais destes parâmetros, você pode escolher onde ocorrerá categorização. Deste modo:

{{mbox
| texto     = Esta é uma caixa para artigos e páginas de discussão.
}}{{category handler
| principal = [[Categoria:Alguma1]]   <!--Categorize no espaço principal (dos artigos)-->
| discussão = [[Categoria:Alguma2]]   <!--Categorize no espaço de discussão-->
| semcat    = {{{semcat|}}}           <!--Para que "semcat=sim" funciona-->
}}

A caixa acima só irá funcionar nos espaços principal e de discussão. Mas não irá categorizar nas páginas de /arquivo, já que elas estão na lista negra. (Veja a seção lista negra abaixo.) E se você precisa demonstrar (discutir) esta caixa em uma página de discussão, então você pode utilizar o parâmetro "semcat=sim" para evitar a categorização da página. (Veja seção semcat abaixo.) Deste modo:

== Minha nova predefinição ==
Olá, vocês já viram a minha nova predefinição?
{{mytemp|semcat=sim}}
Legal, né?
--~~~~

às vezes nós queremos utilizar a mesma categoria em vários espaços nominais, então para facilitar, lembre-se de fazer deste modo:

{{mbox
| texto = Esta caixa é utilizada em vários espaços nominais.
}}{{category handler
| principal = [[Categoria:Alguma1]]
| ajuda
| usuário   = [[Categoria:Alguma2]]  <!-- Para os espaços ajuda e usuário -->
| discussão = <!-- Sem categorias em páginas de discussão -->
| outro     = [[Categoria:Alguma3]]  <!--Para os outros espaços-->
| semcat    = {{{semcat|}}}          <!--para que "semcat=sim/não" funcione-->
}}

No exemplo acima nós utilizados o encadeamento de parâmetros para fornecer a mesma resposta para dois parâmetros, há ainda outra maneira de fazer isto, utilizando a numeração de parâmetros, que pode ser vista abaixo:

{{mbox
| texto     = Esta caixa é utilizada em vários espaços nominais.
}}{{category handler
| principal = [[Categoria:Alguma1]]
| 1         = [[Categoria:Alguma2]]  <!-- Para os espaços ajuda e usuário -->
| ajuda     = 1
| usuário   = 1
| discussão = <!-- Sem categorias em páginas de discussão -->
| outro     = [[Categoria:Alguma3]]   <!--Para os outros espaços-->
| semcat    = {{{semcat|}}}          <!--para que "semcat=sim/não" funcione-->
}}

Esta predefinição entende parâmetros numerados até 10.

O parâmetro outro define o que deve ser utilizado nos espaços restantes, que não foram especificados.

Perceba que o parâmetro vazio, mas definido, discussão foi enviado para o parâmetro outro, quando no espaço de discussão, e portanto será categorizado neste caso.

Esta predefinição também possui um parâmetro chamado todos, que funciona assim:

{{mbox
| texto     = Caixa usada em todos espaços.
}}{{category handler
| todos     = [[Categoria:Alguma1]]   <!--Sempre categorizar-->
| semcat    = {{{semcat|}}}           <!--para que "semcat=sim/não" funcione-->
}}

O exemplo acima irá categorizar sempre, menos nas páginas listadas na lista negra. Para demonstrar a predefinição você ainda pode utilizar "semcat=sim" para evitar a categorização.

Você deve evitar o parâmetro todos, já que predefinições jamais precisam categorizar em todos espaços nominais.

O parâmetro todos também pode ser usato em combinação com o resto deles. Deste modo:

{{mbox
| texto     = Em todos
}}{{category handler
| todos     = [[Categoria:Alguma1]]   <!--Sempre categorizar-->
| principal = [[Categoria:Alguma2]]   <!--Espaço principal (de artigos)-->
| outro     = [[Categoria:Alguma3]]   <!--Todos outros-->
| semcat    = {{{semcat|}}}           <!--para que "semcat=sim/não" funcione-->
}}

Se a caixa for colocada em um artigo, então ela irá adicionar as categorias 1 e 2. Mas em todos outros espaços, serão as categorias 1 e 3. Como o exemplo mostra, o parâmetro todos funciona independentemente dos outros parâmetros.

Subpáginas

A predefinição entende o parâmetro subpágina. Deste modo:

{{category handler
| subpágina = não                     <!--Não em subpáginas-->
| wikihelp = [[Categoria:Categoria1]]
| semcat    = {{{semcat|}}}           <!--para que "semcat=sim/não" funcione-->
}}

Caso "subpágina=não" a predefinição não irá categorizar em subpáginas. Para a rara ocasião em que você queira categorizar apenas subpáginas, use "subpágina=apenas". Se subpágina estiver vazio ou indefinido, a predefinição categorizará em ambos casos.

Lista negra

Esta predefinição possui uma lista negra de páginas e tipos de páginas em que predefinições não devem auto-categorizar. Predefinições que usarem esta metapredefinição, não irão, por sua vez, categorizar em páginas de /arquivo e nas subpáginas de Wikihelp:Lista de predefinições.

Se você quer que uma predefinição categorize em uma página na lista negra, então forneça "semcat = não" para a predefinição ao usá-la, porém isto é muito desaconselhável.

Lembre-se de que esta predeifnição somente categoriza espaços que foram fornecidos, então no uso básico acima, mesmo se você fornecer "semcat = não" a predefinição não irá categorizar em páginas de discussão, já que este comportamento não foi especificado. Mas ela possui informações para o espaço de ajuda, então nenhuma página na lista negra de ajuda irá categorizar.

Consulte a lista negra na sub-predefinição {{category handler/blacklist}}, para ver ou atualizar a lista.

O parâmetro "semcat"

Esta predefinição entende o parâmetro semcat:

• Caso "semcat = sim" a predefinição não categorizará.
• Caso semcat esta vazio ou indefinido, a predefinição categorizará normalmente.
• Caso "semcat = não" a predefinição categorizará até em páginas negras listadas. (Ver seção lista negra acima.)

Predefinições que utilizarem {{category handler|...}} devem encaminhar o parâmetro semcat para cá, para que ele possa ser utilizado. O código para iso é "semcat = {{{semcat|}}}", como exibido em todos exemplos anteriores.

O parâmetro "categoria2"

Para compatibilidade reversa, esta predefinição suporta o antigo parâmetro "categoria =". Mas o parâmetro "categoria" já é usado para fornecer nomes de categoria para o espaço de categorias. Então ao invés esta predefinição utiliza categoria2 para um uso similar ao semcat. Sendo assim:

• Caso "categoria2 = " (vazio, mas definido), ou "categoria2 = não", ou se receber outro valor (exceto nos dois casos seguintes), a predefinição não categoriza.
• Caso categoria2 não é definido ou "categoria = ¬", então a predefinição categoriza normalmente.
• Caso "categoria2 = sim" categoriza até em páginas negras listadas.

Ao adicionar esta predeifnição em uma predefiniçãoq eu já utiliza a lógica "categoria =", você deve fazer o seguinte para não quebrar nenhuma utilização pré-existente:

{{category handler
| [[Categoria:Alguma]]
| semcat    = {{{semcat|}}}          <!--para que "semcat=sim/não" funcione-->
| categoria = {{{categoria2|¬}}}     <!--para que "categoria2=" funcione-->
}}

Lembre-se que "¬" é necessário, ele ajuda a predefinição a detectar se o parâmetro esta definido mas vazio.

Categorias e texto

Além das categorias, você pode fornecer qualquer coisa a esta predefinição, por exemplo algum texto. Deste modo:

{{tmbox
| texto = Esta é uma caixa de mensagem para discussões.
}}{{category handler
| discussão = [[Categoria:Alguma]]
| outro = :::::Esta predefinição deve apenas ser utilizada em páginas de discussão.
| semcat = {{{semcat|}}}             <!--para que "semcat=sim/não" funcione-->
}}

Quando a predefinição acima for utilizada em qualquer lugar que não nas página de discussão, uma mensagem parecida com esta será mostrada (perceba o texto sob a baixa):

Esta predefinição deve apenas ser utilizada em páginas de discussão.

Este texto não aparecerá nas páginas da lista negra, então não use este método para mostrar informações importantes. Fornecer "semcat = claro" para a predefinição esconde o texto, já que ele suprime qualquer categoria.

O parâmetro "página"

Para demonstrações esta predefinição pode levar um parâmetro |página=. Deste modo:

{{category handler
| principal = Categoria:Alguma
| discussão = Categoria:Discute
| semcat = {{{semcat|}}}             <!--para que "semcat=sim/não" funcione-->
| página = Usuário Discussão:Exemplo
}}

No código acima nós deixamos de fora de propósito os colchetes ao redor dos nomes das categorias, para que possamos ver a saída do texto na página. Não importa em que tipo de página o código acima seja usado, o resultado será:

Categoria:Discute

O parâmetro página faz com que a predefinição se comporte exatamente como se estivesse naquela página. Mesmo se a lista negra estar ativa. O nome da página nem precisa existir realmente.

Se o parâmetro página estiver vazio ou indefinido, o nome da página atual é utilizado.

Você também pode fazer com que a sua predefinição entenda o parâmetro página. Isso significa que você pode testar como a sua predefinição vai categorizar diferentes páginas, sem ter que fazer as edições nestas páginas. Para tanto:

{{category handler
| principal = Categoria:Alguma
| discussão = Categoria:Discute
| semcat = {{{semcat|}}}             <!--para que "semcat=sim/não" funcione-->
| página = Usuário Discussão:Exemplo
}}

Parâmetros

Sintaxe de parâmetros:

{{category handler
| [[Categoria:Alguma]]
| subpágina  = não / apenas
| 1          =
...
| 10         =
| todos      = [[Categoria:Alguma]] / Texto
| principal  = 1 / ... / 10 / [[Categoria:Alguma]] / Texto
...
| outro      = 1 / ... / 10 / [[Categoria:Alguma]] / Texto

| semcat     = {{{semcat|}}} / não / sim
| categorias = {{{categories|}}} / não / sim
| categoria2 = {{{category|¬}}} / 'vazio' / não / 'indefinido' / ¬ / sim

| página     = {{{página|}}} / Usuário:Exemplo
}}

Lembre-se que valores vazios para os espaços nominais possuem um significado especial (vide exemplos). O parâmetro "todos" não entende parâmetros numerados, já que esta necessidade não deve existir.

Detalhes técnicos

A lista negra de supressão de categorias na sub-predefinição {{category handler/blacklist}} é utilizada para consultar ou atualizá-la.

Devido a seu processamento interno de parâmetros, esta predefinição usa a sub-predefinição {{category handler/numbered}}.

Para mais detalhes técnicos consulte a discussão.