Manual:Desenvolvendo extensões

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page Manual:Developing extensions and the translation is 100% complete.

Other languages:
العربية • ‎български • ‎Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎한국어 • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎سنڌي • ‎中文
Gnome-preferences-other.svg Extensões:Manual:Extensions DesenvolvimentoManual:Developing extensions Extensões de tagsManual:Tag extensions Funções do analisador sintáticoManual:Parser functions HooksManual:Hooks Páginas especiaisManual:Special pages SkinsManual:Skins Palavras mágicasManual:Magic words APIAPI:Extensions
Extensões do MediaWiki

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 MyExtension/MyExtension.php, 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 MyExtension/includes (embora as extensões Example e BoilerPlate não sigam essa convenção). Por exemplo, veja a extensão Semantic MediaWiki.
MyExtension/i18n/*.json
Armazena as informações de localização da extensão.
Originalmente, extensões eram feitas num só arquivo, e ainda é possível encontrar alguns exemplo deste estilo depreciado.

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[1] (A extensão BoilerPlate é bom ponto de partida para a sua extensão. Não deixe de conferir também a predefinição cookiecutter para extensões do 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.

Enquanto estiver programando, recomendamos que você desative o cache com as configurações $wgMainCacheTypeManual:$wgMainCacheType = CACHE_NONE e $wgCacheDirectoryManual:$wgCacheDirectory = false, ou você poderá não obter mensagens do sistema ou outras mudanças.

Configuração[edit]

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 LocalSettings.phpManual:LocalSettings.php, desta maneira:

wfLoadExtension( 'MyExtension' );

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:

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

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[edit]

O MediaWiki lista todas as extensões instaladas na página Special:Version. 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 $wgExtensionCreditsManual:$wgExtensionCredits 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:

{
	"name": "Example",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:Example",
	"description": "This extension is an example and performs no discernible function",
	"version": "1.5",
	"license-name": "GPL-2.0+",
	"type": "validextensionclass",
	"manifest_version": 1
}

Veja Manual:$wgExtensionCreditsManual:$wgExtensionCredits para mais detalhes sobre o quê esses campos fazem. Muitos deles são opcionais, mas preenchê-los por completo é uma boa prática. manifest_version refere-se à versão do esquema usado pelo arquivo extension.jsonextension.json. A única versão atualmente compatível é a 1ª (MediaWiki 1.26.x e 1.27.x).

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:

Gnome-preferences-other.svg Extensões:Manual:Extensions DesenvolvimentoManual:Developing extensions Extensões de tagsManual:Tag extensions Funções do analisador sintáticoManual:Parser functions HooksManual:Hooks Páginas especiaisManual:Special pages SkinsManual:Skins Palavras mágicasManual:Magic words APIAPI:Extensions

Tornando a extensão configurável pelos usuários[edit]

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.

Atenção Atenção: Para evitar vulnerabilidades do tipo register_globalsRegister globals, SEMPRE explicitamente defina todas as variáveis de configuração da sua extensão no arquivo de configuração dela. Códigos como if ( !isset( $wgMyLeetOption ) ) $wgMyLeetOption = somevalue; não previnem contra register_globals!

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

{
	"name": "BoilerPlate",
	"version": "0.0.0",
	"author": [
		"Your Name"
	],
	"url": "https://www.mediawiki.org/wiki/Extension:BoilerPlate",
	"descriptionmsg": "boilerplate-desc",
	"license-name": "MIT",
	"type": "other",
	"AutoloadClasses": {
		"BoilerPlateHooks": "BoilerPlate.hooks.php",
		"SpecialHelloWorld": "specials/SpecialHelloWorld.php"
	},
	"config": {
		"BoilerPlateEnableFoo": true
	},
	"callback": "BoilerPlateHooks::onExtensionLoad",
	"ExtensionMessagesFiles": {
		"BoilerPlateAlias": "BoilerPlate.i18n.alias.php"
	},
	"Hooks": {
		"NameOfHook": [
			"BoilerPlateHooks::onNameOfHook"
		]
	},
	"MessagesDirs": {
		"BoilerPlate": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.boilerPlate.foo": {
			"scripts": [
				"modules/ext.boilerPlate.js",
				"modules/ext.boilerPlate.foo.js"
			],
			"styles": [
				"modules/ext.boilerPlate.foo.css"
			]
		}
	},
	"ResourceFileModulePaths": {
		"localBasePath": "",
		"remoteExtPath": "BoilerPlate"
	},
	"SpecialPages": {
		"HelloWorld": "SpecialHelloWorld"
	},
	"manifest_version": 1
}

Preparando classes para carregamento automático[edit]

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 __autoload($classname).

Para usar o mecanismo de carregamento automático do MediaWiki, adicione algo ao campo AutoloadClassesManual:$wgAutoloadClasses. 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”):

{
	"AutoloadClasses": {
		"MyExtension": "MyExtension_body.php"
	}
}

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

Definindo hooks adicionais[edit]

Veja Manual:HooksManual:Hooks (em inglês).

Adicionando tabelas de bancos de dados[edit]

Atenção Atenção: Se sua extensão for usada em alguma wiki mantida pela WMF, siga o Guia de mudança de esquema (em inglês).

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

Configurando a localização[edit]

Veja:


Adicionando registros[edit]

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

Execução[edit]

A técnica para desenvolver a implementação depende de qual a parte do sistema do MediaWiki você deseja ampliar:

Veja também a página Extensions FAQExtensions FAQ e a Central do DesenvolvedorDeveloper hub.

Localização[edit]

Nota Nota: Enquanto estiver desenvolvendo, experimente desativar o cache com as configurações $wgMainCacheType = CACHE_NONE e $wgCacheDirectory = false, caso contrário suas mudanças nas mensagens do sistema poderão não ser exibidas.

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 <chave-idioma>.json[edit]

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

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

Armazenando a documentação das mensagens em qqq.json[edit]

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:

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

Definindo mensagens[edit]

  • 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.:
"mwe-upwiz-api-warning-was-deleted": "There was a file by this name, '$1', but it was deleted and you can not reupload the file. If your file is different, try renaming it."

Definindo a documentação das mensagens[edit]

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

"uploadwizard-desc": "Description of extension. It refers to [//blog.wikimedia.org/blog/2009/07/02/ford-foundation-awards-300k-grant-for-wikimedia-commons/ this event], i.e. the development was paid with this $300,000 grant."

Carregando o arquivo de localização[edit]

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

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

Usando wfMessage no PHP[edit]

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

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Usando mw.message no JavaScript[edit]

Também é possível usar funções de i18n no JavaScript. Veja Manual:Messages APIManual:Messages API (em inglês) para mais detalhes.

Tipos de extensões[edit]

Gnome-preferences-other.svg Extensões:Manual:Extensions DesenvolvimentoManual:Developing extensions Extensões de tagsManual:Tag extensions Funções do analisador sintáticoManual:Parser functions HooksManual:Hooks Páginas especiaisManual:Special pages SkinsManual:Skins Palavras mágicasManual:Magic words APIAPI:Extensions

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:
    • Special pagesManual:Special pages – Subclasses da classe SpecialPageManual:SpecialPage.php 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.
    • SkinsManual:Skins – 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 SkinTemplate do MediaWiki.
  • HooksManual:Hooks – 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.
  • Associações de funções em tagsManual:Tag extensionsTags do estilo 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 que incorpora objetos do Google, formulários de entrada de dados, feeds RSS e excertos de artigos wiki selecionados.
  • Palavras mágicasManual:Magic words – 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 Manual:Palavras mágicasManual:Magic words para mais informações.
    • VariávelManual:Variable – 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 {{PAGENAME}}Help:Variables e {{SITENAME}}Help:Variables 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.
    • Funções do analisador sintáticoManual:Parser functions{{functionname: argument 1 | argument 2 | argument 3...}}. 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.
  • Módulos da APIAPI:Extensions – É 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[edit]

Visite o portal de compatibilidade de extensões (em inglês) para manter sua extensão atualizada com as mudanças principais das versões futuras do MediaWiki, além de adicionar compatibilidade para versões antigas que ainda são populares.

Licença (em inglês)[edit]

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0+ (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide it's short name, e.g. "GPL-2.0+" or "MIT" adhering to the list of identifiers at spdx.org.

Publicando[edit]

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


O(A) desenvolvedor(a) que compartilhar seu código no MediaWiki ou no repositório de códigos do MediaWiki deve estar preparado para:

Comentários / Críticas / Revisões
Revisões e comentários de outros desenvolvedores acerca de, por exemplo, uso do framework, segurança, eficiência e usabilidade.
Ajustes
Outros desenvolvedores modificando suas submissões para melhorar ou simplificar seu código seguindo novas classes e métodos do framework, convenções de código e traduções.
Melhorias no acesso de administradores de wikis
Se você decidir expor seu código numa wiki, outro desenvolvedor poderá movê-lo para o repositório de códigos do MediaWiki para facilitar sua manutenção. Você também poderá solicitar acesso de desenvolvedor para continuar mantendo-o.
Versões futuras por outros desenvolvedores
Novas ramificações do seu código sendo criadas por outros desenvolvedores no momento em que novas versões do MediaWiki forem lançadas.
Mesclar seu código em outras extensões com propósitos idênticos ou semelhantes — incorporando os melhores recursos de cada extensão.
Crédito
Crédito pelo seu trabalho será preservado em versões futuras — incluindo em extensões mescladas.
Da mesma forma, você deve creditar os desenvolvedores de extensões cujo código foi tomado por você — especialmente ao realizar uma mescla.

Desenvolvedores que não estiverem de acordo com as ações acimas não devem implantar seus códigos diretamente no MediaWiki ou em seu repositório de códigos. Ainda te motivamos a criar uma página de sumário para a sua extensão na wiki para informar as pessoas sobre sua extensão, e onde baixá-la. Experimente adicionar a predefinição {{Extension exception/pt-br}} na sua extensão para solicitar que outros desenvolvedores evitem de modificar seu código, embora não há garantias que seu código não será atualizado para fins de segurança ou compatibilidade. Use o quadro de avisos de problemas atuais (em inglês) se você perceber que um desenvolvedor violou o espírito das ações acima mencionadas ao editar sua extensão.


Implementando e registrando[edit]

Consulte Review queueReview queue (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 database table and field registrationdatabase table and field registration.

Documentação de ajuda[edit]

Forneça uma documentação de ajuda de domínio público para os recursos providos por sua extensão. Ajuda:CirrusSearchHelp:CirrusSearch é um bom exemplo disso. Forneça aos usuários uma ligação à documentação pela função addHelpLink()Manual:Special pages#Help page.

Fornecendo suporte ou colaboração[edit]

Desenvolvedores de extensões devem abrir uma conta no PhabricatorPhabricator 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[edit]

Referências (em inglês)[edit]

  1. mailarchive:wikitech-l/2011-August/054839.html