Manual:Developing extensions/pt-br



A cada extensão consta de três partes:


 * 1) Configuração
 * 2) Execução
 * 3) Localização

Uma mera extensão consiste de três arquivos, um para cada parte:


 * MyExtension/extension.json: Armazena as instruções de configuração. O nome do arquivo deve ser “extension.json” (Nas versões anteriores ao MediaWiki 1.25, as instruções de configuração ficavam num arquivo, nomeado de acordo com a extensão. Várias extensões ainda são compatíveis com aquelas versões neste arquivo PHP).
 * MyExtension/MyExtension_body.php: Armazena o código para a execução da extensão. O nome de arquivo “MyExtension_body.php” é convencional, porém não obrigatório. Caso sua extensão seja complexa, envolvendo vários arquivos PHP, siga a convenção para colocar seu código de implantação num subdiretório  (embora as extensões Example e BoilerPlate não sigam essa convenção). Por exemplo, veja a extensão SemanticMediaWiki.
 * MyExtension/i18n/*.json: Armazena as informações de localização da extensão.

Ao desenvolver uma extensão, substitua “MyExtension” (como encontrado acima) pelo nome da sua extensão. Use nomes em UpperCamelCase no diretório e no(s) arquivo(s) PHP; essa é a convenção geral para nomes de arquivos (A é um bom ponto de partida para a sua extensão. Você também pode considerar usar MWStew para gerar o seu gabarito de extensão. Também confira o Predefinição Cookiecutter para extensões MediaWiki no GitHub.)

As três partes de uma extensão, configuração, execução e localização, bem como os tipos de extensões, licenciamento, e publicação estão todos descritos nas seguintes seções desta página.

Configuração
O seu objetivo em desenvolver a configuração é consolidá-la para que os usuários que instalarem sua extensão não precisem fazer nada além de incluir o arquivo de configuração no arquivo, desta maneira:

Se você deseja fazer com que sua extensão seja configurável pelo usuário, defina e documente alguns parâmetros de configuração. A configuração deve estar desta maneira:

Para alcançar essa simplicidade, seu arquivo de configuração deve efetuar várias tarefas (descritas detalhadamente nas seguintes seções):


 * registrar qualquer manipulador de mídia, função ao analisador sintático, página especial, marcação personalizada de XML e/ou viariável que sua extensão usar;
 * definir e/ou validar quaisquer variáveis de configuração definidos por você para a sua extensão;
 * preparar as classes usadas pela sua extensão para carregamento automático;
 * determinar quais partes da sua configuração devem ser feitas imediatamente e quais precisam estar em modo de espera até o núcleo do MediaWiki ter sido inicializado e configurado;
 * definir hooks adicionais necessários pela sua extensão;
 * criar ou verificar tabelas de banco de dados requeridas pela sua extensão; e
 * configurar a localização para a sua extensão.

Registrando recursos com o MediaWiki
O MediaWiki lista todas as extensões instaladas na página. Por exemplo, é possível ver todas as extensões instaladas nesta wiki na página Special:Version. É bom certificar-se de que a sua extensão também esteja listada naquela página. Para isso, será necessário adicionar um registro em para cada manipulador de mídia, função ao analisador sintático, página especial, marcação personalizada de XML e viariável que sua extensão usar. O registro parecerá assim:

Veja para mais detalhes sobre o quê esses campos fazem. Muitos deles são opcionais, mas preenchê-los por completo é uma boa prática. refere-se à versão do esquema usado pelo arquivo. A partir de agora (janeiro de 2018) as versões disponíveis são 1 e 2. Ver aqui para a documentação sobre este recurso.

Além do registro acima, você também deve fazer um “hook” do seu recurso com o MediaWiki. O texto acima apenas configura a página Special:Version. A maneira com a qual você fará isso depende do tipo da sua extensão. Para mais detalhes, veja a documentação para cada tipo de extensão:

Tornando a extensão configurável pelos usuários
Caso queira que os usuários possam configurar sua extensão, será necessário fornecer uma ou mais variáveis de configuração. É uma boa ideia dar um nome único para cada variável. Também devem ser seguidas as convenções para nomes do MediaWiki (ex.: variáveis globais devem começar com $wg).

Por exemplo, se sua extensão se chamar “Extensãozinha que não faz nada de mais”, tente nomear todas as suas variáveis de configuração para começarem com $Eqnfndm ou $EQNFNDM. As suas escolhas não importam desde que nenhuma extensão do núcleo do MediaWiki comece as variáveis dessa maneira e que você tenha feito um bom trabalho em verificar se nenhuma das extensões publicadas começam as variáveis dessa maneira. Os usuários não ficarão tão felizes em ter de escolher entre a sua e outras extensões pelo fato de você ter usado os mesmos nomes que as outras.

Uma outra boa ideia é incluir uma documentação completa de quaisquer variáveis de configuração nas suas notas de instalação.

Aqui há um exemplo da extensão BoilerPlate que pode ser usado como ponto de partida:

Preparando classes para carregamento automático
Caso escolha ter de usar classes para implementar sua extensão, o MediaWiki fornece um mecanismo simplificado para auxiliar o PHP em encontrar o arquivo-fonte onde sua classe está localizada. Na maioria dos casos, isso deverá eliminar a necessidade de escrever seu próprio método.

Para usar o mecanismo de carregamento automático do MediaWiki, adicione algo ao campo. A chave para cada adição é o nome da classe; o valor é o arquivo armazenador da definição da classe. Para uma extensão de uma só classe, a classe tem geralmente o mesmo nome que a extensão. Dessa maneira, sua seção de carregamento automático deve parecer assim (nesse exemplo, a extensão se chama “MyExtension”):

O nome do arquivo é relativo ao diretório onde se encontra o arquivo extension.json.

Definindo hooks adicionais
Veja (em inglês).

Adicionando tabelas de bancos de dados
Se sua extensão precisar adicionar suas próprias tabelas de bancos de dados, use o hook. Veja a página do manual para mais informações de uso.

Configurando a localização
Veja:
 * Localização (resumo)
 * Localização (em detalhe)
 * Namespaces

Adicionando registros
No MediaWiki, todas as ações dos usuários numa wiki são rastreadas para transparência e colaboração. Veja (em inglês) para adicionar registros.

Execução
A técnica para desenvolver a implementação depende de qual a parte do sistema do MediaWiki você deseja ampliar:
 * Marcação wiki: Extensões que ampliam as marcações wiki tipicamente contêm um código que define e implementa marcações personalizadas de XML, funções do analisador sintático e variáveis.
 * Relatórios e administração: Extensões que adicionam capacidades administrativas e de relato geralmente as fazem adicionando páginas especiais. Para mais informações, veja (em inglês).
 * Automação de artigos e integridade: Extensões que aumentam a integração entre o MediaWiki e sua base de dados de suporte ou verificam artigos por recursos de integridade tipicamente adicionam funções a um dos vários hooks que afetam o processo de criação, edição, renomeação e apagamento de artigos. Para mais informações sobre estes hooks e como anexar seu código a eles, veja  (em inglês).
 * Aparência e experiência: Extensões que fornecem uma nova aparência e experiência ao MediaWiki são agrupadas em temas. Para mais informações sobre como desenvolver seus próprios temas, veja e  (esse último em inglês).
 * Segurança: Extensões que limitam seus usos a certos usuários devem ser integradas com o sistema de permissões próprio do MediaWiki. Para saber mais sobre este sistema, veja (em inglês). Algumas extensões também permitem que o MediaWiki use de mecanismos de autenticação externos. Para mais informações, veja . Ademais, se sua extensão tentar limitar leitores em certos artigos, por favor, confira os truques discutidos em  (em inglês).

Veja também a página  e a.

Localização
Se você deseja que sua extensão seja usada em wikis com leitores multilíngues, será necessário adicionar compatibilidade a localizações na sua extensão.

Armazenando mensagens em .json
Armazene as definições de mensagens em arquivos de localização JSON, um para cada chave de idioma em que sua extensão será traduzida. As mensagens serão salvas com uma chave de mensagem e a mensagem, usando o formato padrão JSON. Todo id de mensagem deve estar em letras minúsculas e sem espaços. Um exemplo pode ser encontrado na extensão MobileFrontend. A seguir, outro exemplo de um pequeno arquivo JSON (neste caso, en.json):

en.json

Armazenando a documentação das mensagens em qqq.json
A documentação das chaves das mensagens pode ser armazenada num arquivo JSON com o código qqq. Uma documentação do exemplo acima pode ser:

qqq.json:

Definindo mensagens

 * Atribua a cada mensagem um id único, em letras minúsculas e sem espaços; ex.: uploadwizard-desc
 * Defina uma mensagem para toda string de texto exibida aos usuários.
 * O MediaWiki é compatível com mensagens parametrizadas. Esse recurso deve ser usado quando uma mensagem for dependente de informações geradas enquanto é executada. Placeholders de parâmetros devem ser especificados com $n, onde n representa o índice do placeholder; ex.:

Definindo a documentação das mensagens
Cada mensagem definida precisa ter uma entrada de documentação de mensagem associada; ex. em qqq.json:

Carregando o arquivo de localização
Na sua rotina de configuração, defina a localização dos seus arquivos de mensagem; ex. no diretório i18n/:

Usando wfMessage no PHP
No seu código de configuração e implementação, substitua todo uso da mensagem com uma chamada para. Em classes que implementam a (assim como algumas subclasses das páginas especiais, por exemplo), pode-se usar. Exemplo:

Usando mw.message no JavaScript
Também é possível usar funções de i18n no JavaScript. Veja (em inglês) para mais detalhes.

Tipos de extensões
Extensões podem ser categorizadas baseando-se nas técnicas de programação usadas para torná-las efetivas. A maioria das extensões mais complexas usam mais de uma das seguintes técnicas:
 * Subclassing: O MediaWiki aceita que certos tipos de extensões sejam implementados como subclasses de uma classe-base fornecida pelo MediaWiki:
 *  – Subclasses da classe são usadas para construir páginas cujo conteúdo é dinamicamente gerado usando uma combinação do estado atual do sistema, parâmetros inseridos pelos usuários e consultas às bases de dados. Relatórios e formulários de inserção de dados podem ser gerados. São usadas tanto para propósitos administrativos quanto de relato.
 *  – Temas modificam a aparência e a experiência do MediaWiki alterando o código de exibição de páginas ao “subclassear” a classe do MediaWiki.
 *  – Uma técnica de injeção de código em PHP personalizado nos pontos principais do processador do MediaWiki. Eles são amplamente usados pelo analisador sintático, motor de localização e sistema de gerenciamento de extensões e páginas do MediaWiki.
 *  – Tags do estilo XML são associadas com uma função do PHP que retorna códigos em HTML. Não é necessário limitar-se na formatação do texto dentro das tags nem exibi-lo. Várias extensões do tipo tag usam o texto como parâmetros que guiam a geração de HTML que incorpora objetos do Google, formulários de entrada de dados, feeds RSS e excertos de artigos wiki selecionados.
 *  – Uma técnica para mapear uma variedade de strings de wikitexto num só id, associado a uma função. Variáveis e funções do analisador sintático usam dessa técnica. Todo o texto mapeado ao id será substituído com o valor retornado da função. O mapeamento entre as strings de texto e o id é armazenado no array $magicWords. A interpretação do id envolve um processo um tanto quanto complicado – veja para mais informações.
 *  – O termo variável é um equívoco. Elas são porções de wikitexto que se parecem com predefinições, porém não têm parâmetros e têm valores de código complexo atribuídos a elas. Marcações wiki padrão, como e  são exemplos de variáveis. Elas receberam esse nome da fonte do seu valor: uma variável PHP ou algo que pudesse ser atribuído a uma variável; ex.: uma string, um número, uma expressão ou um valor de retorno de uma função.
 *  – .  Semelhantes às extensões do tipo tag, funções do analisador sintático processam argumentos e retornam valores. Ao contrário de extensões do tipo tag, o resultado dessas funções é em wikitexto.
 *  – É possível adicionar módulos personalizados à API action, que pode ser invocada por JavaScript, robôs ou clientes terceiros.

Compatibilidade a outras versões do núcleo
Existem duas convenções comuns para suportar versões antigas do núcleo do MediaWiki:

Os mantenedores de extensão devem declarar com a  parâmetro da predefinição Extension  que convenção eles seguem.
 * Mestre: o ramo mestre da extensão é compatível com tantas versões antigas do núcleo quanto possível. Isso resulta em um fardo de manutenção (os hacks de compatibilidade com versões anteriores precisam ser mantidos por muito tempo e as mudanças na extensão precisam ser testadas com várias versões do MediaWiki), mas os sites que usam versões antigas do MediaWiki se beneficiam das funcionalidades recentemente adicionadas ao extensão.
 * Ramos de liberação: os ramos de liberação da extensão são compatíveis com ramos de núcleo correspondentes, p. Ex. Os sites que usam o MediaWiki 1.27 precisam usar o ramo REL1_27 da extensão. (Para extensões hospedadas em gerrit, esses ramos são criados automaticamente quando as novas versões do MediaWiki são lançadas.) Isso resulta em um código mais limpo e um desenvolvimento mais rápido, mas os usuários em versões do núcleo antigo não se beneficiam das correções de erros e dos novos recursos, a menos que sejam recados manualmente.

Publicando
Para categorizar e padronizar a documentação da sua extensão, veja. Para adicionar sua extensão nesta wiki:

Implementando e registrando
Se você pretende que sua extensão seja implantada em sites Wikimedia (incluindo, possivelmente, a Wikipédia), um escrutínio adicional é garantido em termos de desempenho e segurança. Consulte (em inglês).

Se sua extensão adicionar espaços nominais, você pode tentar registrar seus espaços nominais padrões; da mesma forma, se ela adicionar tabelas ou campos aos bancos de dados, experimente registrá-los em.

Documentação de ajuda
Forneça uma documentação de ajuda de domínio público para os recursos providos por sua extensão. é um bom exemplo disso. Forneça aos usuários uma ligação à documentação pela função.

Fornecendo suporte ou colaboração
Desenvolvedores de extensões devem abrir uma conta no da Wikimedia e solicitar um novo projeto para a extensão. Isso fornece um canal público, onde os usuários podem relatar problemas e enviar extensões. Colabore também com os usuários e outros desenvolvedores para fazer triagem de bugs e para planejar mais recursos à sua extensão.

Ver também

 * – implementa alguns recursos de exemplo com extensas documentações.
 * – uma extensão clichê funcionando, útil como um ponto de partida para a sua extensão.
 * Leia a extensão Example, baseie seu código na extensão BoilerPlate.
 * cookiecutter-mediawiki-extension – uma predefinição para a ferramenta em Python Cookiecutter, que gera uma extensão BoilerPlate (com variáveis, etc.).
 * Permite que você avance rapidamente com a sua extensão. Pode também gerar a extensão BoilerPlate.
 * - copie alguns códigos delas.
 * – explica como sua extensão pode fornecer uma API para os clientes.
 * Melhores práticas para extensões
 * Melhores práticas para extensões
 * Melhores práticas para extensões
 * Melhores práticas para extensões
 * Melhores práticas para extensões