Exibir código-fonte para Predefinição:Category handler/doc

{{Subpágina de documentação}}
<!-- Categorias no final desta página e links para outros idiomas no Wikidata -->
{{lua|Módulo:Category handler}}

Esta é a metapredefinição {{tlg|category handler}}.

Ela ajuda outras predefinições a automatizar ambas categorização e [[:en:Wikipedia:Category suppression|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: "<code><nowiki>{{category handler|[[Categoria:Alguma]]}}</nowiki></code>" 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 {{tl|artigos e outros}}, {{tl|ficheiros e outros}}, or {{tl|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 [[Wikihelp:Domínio|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:

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

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

O exemplo acima usa as configurações padrão para {{tlx|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 netra|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|espaços nominais]], acima. Ao usar um ou mais destes parâmetros, você pode escolher onde ocorrerá categorização. Deste modo:

<pre>
{{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-->
}}
</pre>

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|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 "<code>semcat=sim</code>" para evitar a categorização da página. (Veja seção [[#Semcat|semcat]] abaixo.) Deste modo:

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

à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:

<pre>
{{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-->
}}
</pre>

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:

<pre>
{{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-->
}}
</pre>

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:

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

O exemplo acima irá categorizar sempre, menos nas páginas listadas na lista negra. Para demonstrar a predefinição você ainda pode utilizar "<code>semcat=sim</code>" 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:

<pre>
{{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-->
}}
</pre>

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:

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

Caso "<code>subpágina=não</code>" a predefinição '''não''' irá categorizar em subpáginas. Para a rara ocasião em que você queira categorizar '''apenas''' subpáginas, use "<code>subpágina=apenas</code>". 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 "<code><nowiki>semcat = não</nowiki></code>" 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|uso básico]] acima, mesmo se você fornecer "<code>semcat = não</code>" 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 {{tl|category handler/blacklist}}, para ver ou atualizar a lista.

=== O parâmetro "semcat" ===

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

* Caso "<code>semcat = sim</code>" a predefinição ''não'' categorizará.
* Caso '''semcat''' esta vazio ou indefinido, a predefinição categorizará normalmente.
* Caso "<code>semcat = não</code>" a predefinição categorizará até em páginas negras listadas. (Ver seção [[#Lista negra|lista negra]] acima.)

Predefinições que utilizarem {{tlx|category handler|...}} '''devem''' encaminhar o parâmetro '''semcat''' para cá, para que ele possa ser utilizado. O código para iso é "<code><nowiki>semcat = {{{semcat|}}}</nowiki></code>", 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 "<code>categoria2 = </code>" (vazio, mas definido), ou "<code>categoria2 = não</code>", ou se receber outro valor (exceto nos dois casos seguintes), a predefinição '''não categoriza'''.
* Caso '''categoria2''' não é definido ou "<code>categoria = ¬</code>", então a predefinição categoriza normalmente.
* Caso "<code>categoria2 = sim</code>" categoriza até em páginas negras listadas.

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

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

Lembre-se que "<code>¬</code>" é 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:

<pre>
{{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-->
}}
</pre>

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):

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

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 "<code>semcat = claro</code>" 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 '''{{parâmetro|página}}'''. Deste modo:

<pre>
{{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
}}
</pre>

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á:

:{{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
}}

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:

<pre>
{{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
}}
</pre>

=== Parâmetros ===

Sintaxe de parâmetros:

<pre>
{{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
}}
</pre>

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 {{tl|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 {{tl|category handler/numbered}}.

Para mais detalhes técnicos consulte a [[Predefinição Discussão:category handler|discussão]].


== Ver também ==
[[Wikihelp:Domínio|Wikihelp:Espaços nominais]]

<includeonly>
[[Categoria:!Predefinições de manutenção]]
<!-- Categorias aqui e links para outros idiomas no Wikidata -->

</includeonly>