Módulo:Testes/Gkiyoshinishimoto/Category handler/doc

Este módulo implementa a predefinição {{Teste/Gkiyoshinishimoto/Category handler}}. A predefinição para lidar com categorias ajuda outras predefinições a automatizar tanto a categorização quanto a supressão da categorização [en]. Para obter informações sobre como usar a predefinição para lidar com categorias em outras predefinições, consulte a documentação da predefinição. Continue lendo para obter informações sobre como usar o módulo para lidar com categorias em outros módulos Lua ou para obter informações sobre como exportar este módulo para outras wikis.

Uso a partir de outros módulos Lua

Quando não usar este módulo

Para os casos em que um módulo só precisa categorizar em, um dos espaços nomeados, "Principal" (artigos), "Ficheiro" (imagens) ou "Categoria", usar este módulo é um exagero. Em vez disso, você pode simplesmente obter um objeto de título usando mw.title.getCurrentTitle e verificar o campo nsText. Por exemplo:

local title = mw.title.getCurrentTitle()
if title.nsText == 'Ficheiro' then
    -- fazer algo
end

No entanto, se o seu módulo precisar categorizar em qualquer outro espaço nomeado, recomendamos que você use este módulo, pois ele fornece supressão de categorização adequada e facilita a seleção de como categorizar em espaços nomeados diferentes.

Espaços nomeados

Este módulo detecta e agrupa todos os diferentes espaços nomeados usados na Wikipédia em vários tipos. Esses tipos são usados como nomes de parâmetros neste módulo.

main = Espaço principal/artigo, como nos artigos normais da Wikipédia.

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

user, wikipedia, file ... = Os outros espaços nomeados exceto as páginas de discussão. Os nomes alternativos dos espaços nomeados também são aceitos. Consulte a tabela abaixo para obter a lista completa.

other = Quaisquer espaços nomeados que não foram especificados como um parâmetro para a predefinição. Consulte os exemplos abaixo.

Lista de possíveis parâmetros de espaços nomeados

(excluindo talk e other)

Espaço nomeado	Nome(s) alternativo(s)
main
usuário(a)	user, utilizador, usuário, usuária, utilizador(a), utilizadora
wikipédia	project, wikipedia, wp
ficheiro	file, imagem, arquivo, image
mediawiki
predefinição	template
ajuda	help
categoria	category
portal
livro
education program
timedtext
módulo	module
tópico	topic

Uso básico

Este módulo leva dois ou mais parâmetros. Aqui está um exemplo usando um programa "Hello world":

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Hello world!'
    local category = categoryHandler{
        '[[Categoria:Alguma categoria]]',
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

O exemplo acima usa as configurações padrões para o módulo que lida com categorias. Isso significa que o módulo de exemplo categorizará as páginas nos seguintes espaços nomeados:

main, file, help, category, portal e book

Mas ele não categorizará em nenhum outro espaço nomeado, por exemplo:

talk, user, wikipedia, mediawiki, template ...

E ele não categorizará em páginas da lista negra. (Consulte a seção Lista negra abaixo.)

A razão pela qual o módulo para lidar com categorias não categoriza em alguns dos espaços nomeados é que nesses espaços nomeados a maioria dos módulos e das predefinições são apenas demonstrados ou listados, não usados. Portanto, a maioria dos módulos e predefinições não devem ser categorizados nesses espaços nomeados.

Quaisquer módulos ou predefinições, destinados a um ou mais dos espaços nomeados onde esse módulo categoriza, podem usar a sintaxe básica mostrada acima.

Uso avançado

Este módulo recebe um ou mais parâmetros nomeados de acordo com os diferentes tipos de página listados na seção Espaços nomeados acima. Ao usar esses parâmetros, você pode especificar exatamente em quais espaços nomeados sua predefinição deve categorizar. Assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo destinado a artigos e páginas de discussão.'
    local category = categoryHandler{
        main = '[[Categoria:Alguma categoria 1]]', -- Categoriza no espaço principal (artigo)
        talk = '[[Categoria:Alguma categoria 2]]', -- Categoriza no espaço de discussão
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

O módulo acima categorizará apenas no espaço principal e de discussão. Mas não irá categorizar nas páginas "/arquivo", pois elas estão na lista negra. (Consulte a seção Lista negra abaixo.) E se você precisar demonstrar (discutir) o módulo em uma página de discussão, poderá alimentar "nocat='true'" para evitar que a predefinição a categorize. (Consulte a seção O parâmetro "nocat" abaixo.) Assim:

== Meu novo módulo ==
Ei pessoal, vocês viram meu novo módulo?
{{#invoke:Testes/Gkiyoshinishimoto/Meu módulo|main|nocat=true}}
Legal, não é?
--~~~~

Às vezes queremos usar a mesma categoria em vários espaços nomeados, então fazemos assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo usado em vários espaços nomeados.'
    local category = categoryHandler{
        main = '[[Categoria:Alguma categoria 1]]',
        [ 1 ] = '[[Categoria:Alguma categoria 2]]', -- Para os espaços de "ajuda" e "usuário"
        help = 1,
        user = 1,
        talk = '', -- Nenhuma categorização quando em páginas de discussão
        other = '[[Categoria:Alguma categoria 3]]', -- Para todos os outros espaços nomeados
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

No exemplo acima, usamos um parâmetro numerado para alimentar uma das categorias e, em seguida, dizemos a este módulo para usar esse parâmetro numerado tanto para o espaço ajuda quanto para usuário.

O módulo que lida com categorias compreende um número ilimitado de parâmetros numerados.

O parâmetro "other" define o que deve ser usado nos espaços nomeados restantes que não foram explicitamente alimentados com dados.

Observe o parâmetro "talk" vazio, mas definido. Isso impede que este módulo mostre o que foi alimentado ao parâmetro "other", quando no espaço de discussão.

O módulo que lida com categorias também possui um parâmetro chamado "all". Funciona assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo usado em todos os espaços nomeados.'
    local category = categoryHandler{
        all = '[[Categoria:Alguma categoria 1]]', -- Em todos os espaços nomeados
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

O exemplo acima categorizará em todos os espaços nomeados, mas não nas páginas da lista negra. Se você deseja demonstrar esse módulo em uma página, use "nocat=true" para evitar que a predefinição categorize.

Sugerimos evitar o parâmetro "all", já que os módulos e as predefinições devem preferencialmente ser categorizados apenas nos espaços nomeados que eles precisam.

O parâmetro "all" também pode ser combinado com os demais parâmetros. Assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo usado em todos os espaços nomeados'
    local category = categoryHandler{
        all = '[[Categoria:Alguma categoria 1]]', -- Categoriza em todos os espaços nomeados
        main = '[[Categoria:Alguma categoria 2]]', -- E adiciona isso quando no espaço principal
        other = '[[Categoria:Alguma categoria 3]]', -- E adiciona isso quando em todos os outros espaços nomeados
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

Se o módulo acima for colocado em um artigo, ele adicionará as categorias "Alguma categoria 1" e "Alguma categoria 2". Mas em todos os outros tipos de páginas, ele adicionará "Alguma categoria 1" e "Alguma categoria 3". Como mostra o exemplo, o parâmetro "all" funciona independentemente do restante dos parâmetros.

Subpáginas

O módulo para lidar com categorias entende o parâmetro "subpage". Assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo usado em todos os espaços nomeados.'
    local category = categoryHandler{
        subpage = 'no' -- Não categoriza quando em subpáginas
        wikipedia = '[[Categoria:Alguma categoria]]',
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

Se "subpage='no'", então este módulo não categorizará em subpáginas. Nas raras ocasiões em que você apenas deseja categorizar em subpáginas, use "subpage='only'". Se "subapge" estiver vazio ou indefinido, então este módulo categoriza tanto em páginas base quanto em subpáginas.

Lista negra

Este módulo possui uma lista negra das páginas e tipos de página onde as predefinições não devem categorizar automaticamente. Assim, as predefinuções que usam este metamódulo, por exemplo, não categorizarão nas páginas "/arquivo" e nas subpáginas de Wikipédia:Lista de predefinições.

Se você deseja que uma predefinição categorize em uma página da lista negra, insira "nocat = false" na predefinição ao colocá-la na página, ignorando assim a verificação da lista negra. Observe que este módulo só categoriza se tiver dados para o espaço nomeado. Por exemplo, se a sintaxe básica for usada (consulte Uso básico acima), mesmo que você defina "nocat = false" a predefinição não categorizará em uma página de discussão, pois não possui dados para páginas de discussão. Mas ela possui dados para o espaço de ajuda, portanto, em uma página de ajuda na lista negra, ela categorizará.

A lista negra está localizada na tabela de configuração "cfg.blacklist" próximo ao topo do código do módulo.

O parâmetro "nocat"

Este módulo entende o parâmetro "nocat":

• Se "nocat = true", então este módulo não categoriza.
• Se "nocat" for nil, então este módulo categoriza como de costume.
• Se "nocat = false", então este módulo categoriza mesmo quando em páginas da lista negra. (Consulte a seção Lista negra acima.)
• O parâmetro "nocat" também aceita nomes alternativos para "true" e "false" conforme definido por Módulo:Testes/Gkiyoshinishimoto/Yesno, por exemplo: "yes", "y", "true" e "1" para "true" e "no", "n", "false" e "0" para "false".

Os módulos e as predefinições que usam {{Teste/Gkiyoshinishimoto/Category handler}} devem encaminhar "nocat", para que eles também entendam "nocat". O código "nocat = frame.args.nocat" mostrado nos exemplos desta página faz isso.

O parâmetro "categories"

Para compatibilidade com versões anteriores, este módulo também entende o parâmetro "categories". Funciona da mesma forma que "nocat". Assim:

• Se "categories = false", então este módulo não categoriza.
• Se "categories" estiver vazio ou indefinido, então este módulo categoriza como de costume.
• Se "categories = true", então este módulo categoriza mesmo quando em páginas da lista negra.
• O parâmetro "categories" também aceita nomes alternativos para "true" e "false" conforme definido por Módulo:Testes/Gkiyoshinishimoto/Yesno, por exemplo: "yes", "y", "true" e "1" para true e "no", "n", "false" e "0" para "false".

O parâmetro "category2"

Para compatibilidade com versões anteriores, esta predefinição oferece suporte ao antigo parâmetro "category =". Mas o nome do parâmetro "category" já é usado neste módulo para alimentar os dados de categoria quando estiver no espaço de categoria. Então, em vez disso, esta predefinição usa "category2" para o uso semelhante ao de "nocat". Assim:

Se "category2 = "" (vazio, mas definido), ou "category2 = 'no'", ou se "category2" for alimentado com qualquer outro dado (exceto conforme descrito nos próximos dois pontos), então este módulo não categoriza.

• Se "category2" for indefinido ou se "category2 = '¬'", então este módulo categoriza como de costume.
• Se "category2 = 'yes'", então este módulo categoriza mesmo quando em páginas na lista negra.

Categorias e texto

Além das categorias, você pode alimentar qualquer outra coisa para este módulo, por exemplo, algum texto. Assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local result = 'Este é um módulo usado em páginas de discussão.'
    local category = categoryHandler{
        talk = '[[Categoria:Alguma categoria]]',
        other = '<p class="error">Este módulo só deve ser usado em páginas de discussão.</p>',
        nocat = frame.args.nocat -- Então "nocat=true/false" funciona
    }
    category = category or '' -- Verifica se não temos um valor nulo para a variável de categoria.
    return result .. category
end

return p

Quando o código do módulo acima for usado em algo que não seja uma página de discussão, ele ficará assim:

Este é um módulo usado em páginas de discussão.

Esse texto não aparecerá nas páginas da lista negra, portanto, não use esse método para mostrar informações importantes. Alimentar "nocat = 'true'" para o módulo oculta o texto, assim como suprime qualquer categorização.

O parâmetro "page"

Para fins de teste e demonstração, este módulo pode receber um parâmetro chamado "page". Assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local category = categoryHandler{
        main = 'Categoria:Alguma categoria',
        talk = 'Categoria:Categoria de discussão',
        nocat = frame.args.nocat, -- Então "nocat=true/false" funciona
        page = 'Usuário Discussão:Exemplo'
    }
    return category
end

return p

No código acima, de propósito, deixamos de fora os colchetes ao redor dos nomes das categorias para que possamos ver a saída na página. Não importa em que tipo de página o código acima é usado, ele retornará isso:

Categoria:Categoria de discussão

O parâmetro "page" faz com que este módulo se comporte exatamente como se estivesse naquela página. Até a lista negra funciona. O nome da página não precisa ser uma página existente.

Se o parâmetro "page" estiver vazio ou indefinido, o nome da página atual determinará o resultado.

Você pode fazer com que seu módulo também entenda o parâmetro "page". Isso significa que você pode testar como seu módulo categorizará em páginas diferentes, sem precisar editar essas páginas. Então faça assim:

p = {}
local categoryHandler = require( 'Módulo:Testes/Gkiyoshinishimoto/Category handler' ).main

function p.main( frame )
    local category = categoryHandler{
        main = 'Categoria:Alguma categoria',
        talk = 'Categoria:Categoria de discussão',
        nocat = frame.args.nocat, -- Então "nocat=true/false" funciona
        page = frame.args.page -- Para teste
    }
    return category
end

return p

Parâmetros

Lista de todos os parâmetros:

• Primeiro parâmetro posicional - para configurações padrão
• subpage = 'no' / 'only'
• 1, 2, 3 ...
• all = '[[Categoria:Alguma categoria']]' / 'Texto'
• main = 1, 2, 3 ... / '[[Categoria:Alguma categoria']]' / 'Texto'
• ...
• other = 1, 2, 3 ... / '[[Categoria:Alguma categoria']]' / 'Texto'
• nocat = frame.args.nocat / true / false / 'yes' / 'no' / 'y' / 'n' / 'true' / 'false' / 1 / 0
• categories = frame.args.categories / false / true / 'no' / 'yes' / 'n' / 'y' / 'false' / 'true' / 0 / 1
• category2 = frame.args.category or '¬' / 'no' / 'not defined' / '¬' / 'yes'
• page = frame.args.page / 'Usuário:Exemplo'

Observe que valores vazios para os parâmetros "main" ... "other" têm um significado especial (consulte os exemplos acima). O parâmetro "all" não entende parâmetros numerados, pois nunca deveria haver necessidade disso.

Exportando para outras wikis

Este módulo pode ser exportado para outras wikis alterando os valores de configuração na tabela "cfg". Todos os valores das variáveis são configuráveis, portanto, após os valores de configuração terem sido definidos, não haverá necessidade de alterar o código do módulo principal. Os detalhes de cada valor de configuração estão incluídos nos comentários do código do módulo. Além disso, este módulo requer que Módulo:Testes/Gkiyoshinishimoto/Namespace detect esteja disponível na wiki local.

Ver também

• {{Teste/Gkiyoshinishimoto/Category handler}} – para usar este módulo com predefinições, em vez de com módulos Lua.
• Supressão de categoria [en] – O guia de como fazer.
• Projeto Wiki Supressão de categoria [en] – O projeto wiki.
• Wikipédia:Domínio – Lista todos os espaços nomeados.