Extensão:BetaFeatures

This page is a translated version of the page Extension:BetaFeatures and the translation is 75% complete.
Outdated translations are marked like this.
Manual de extensões do MediaWiki
BetaFeatures
Estado da versão: estável
Implementação Mídia, Hook , Banco de dados
Descrição Permite que outras extensões registrem seus recursos beta nas preferências do usuário
Autor(es) Mark Holmquist (MarkTraceurdiscussão)
Última versão 0.1 (Continous updates)
Política de
compatibilidade
Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki 1.25+
PHP 5.4+
Modifica o banco
de dados
Sim
Tabelas betafeatures_user_counts
Licença GNU GPL (Licença Pública Geral) 2.0 ou superior
Download Template:WikimediaDownload/gerritonly
Exemplo Special:Preferences#mw-prefsection-betafeatures
Special
  • $wgBetaFeatures
  • $wgBetaFeaturesAllowList
Quarterly downloads 42 (Ranked 98th)
Public wikis using 1,031 (Ranked 249th)
Para traduzir a extensão BetaFeatures, verifique sua disponibilidade no translatewiki.net
Problemas Tarefas em aberto · Relatar um bug

A extensão BetaFeatures permite que outras extensões do MediaWiki registrem seus recursos beta na lista de preferências do usuário na wiki. Ela utiliza da arquitetura já existente das preferências de usuário e de algumas poucas páginas especiais para cumprir seu propósito.

Instalação

  • Baixe e coloque o(s) arquivo(s) num diretório chamado BetaFeatures na sua pasta extensions/.
    Developers and code contributors should install the extension from Git instead, using:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/BetaFeatures
  • Adicione o seguinte código ao final do seu arquivo LocalSettings.php :
    wfLoadExtension( 'BetaFeatures' );
    
  • Execute o script de atualização que criará automaticamente as tabelas de banco de dados necessárias a essa extensão.
  • Configure conforme o necessário.
  •   Concluído – Navegue à página Special:Version em sua wiki para verificar se a instalação da extensão foi bem sucedida.

Usando os novos hooks em sua extensão

Usando essa extensão para dar suporte ao seu recurso beta é fácil. Registre um hook do tipo “GetBetaFeaturePreferences ” no seu arquivo extension.json — a sintaxe é quase idêntica ao hook GetPreferences , com algumas pequenas mudanças para ser compatível com o tipo de preferência necessário neste caso.

Na extension.json:

    "Hooks": {
        "GetBetaFeaturePreferences": "MediaWiki\\Extension\\MyExtension\\Hooks::onGetBetaFeaturePreferences"
    },

Na MyExtension/includes/Hooks.php:

namespace MediaWiki\Extension\MyExtension;
class Hooks {
    public static function onGetBetaFeaturePreferences( User $user, array &$betaPrefs ) {
        $extensionAssetsPath = MediaWikiServices::getInstance()
			->getMainConfig()
			->get( 'ExtensionAssetsPath' );
        $betaPrefs['myextension-awesome-feature'] = [
            // The first two are message keys
            'label-message' => 'myextension-awesome-feature-message',
            'desc-message' => 'myextension-awesome-feature-description',
            // Paths to images that represents the feature.
            // The image is usually different for ltr and rtl languages.
            // Images for specific languages can also specified using the language code.
            'screenshot' => array(
                'ru' => "$extensionAssetsPath/MyExtension/images/screenshot-ru.png",
                'ltr' => "$extensionAssetsPath/MyExtension/images/screenshot-ltr.png",
                'rtl' => "$extensionAssetsPath/MyExtension/images/screenshot-rtl.png",
            ),
            // Link to information on the feature - use subpages on mw.org, maybe?
            'info-link' => 'https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:MyExtension/MyFeature',
            // Link to discussion about the feature - talk pages might work
            'discussion-link' => 'https://www.mediawiki.org/wiki/Special:MyLanguage/Help_talk:Extension:MyExtension/MyFeature',
        ];
    }
}
Por enquanto, label-message, desc-message, info-link e discussion-link são requeridos. Certifique-se de usar todos eles!

Daí, é possível utilizar a função de conveniência fornecida pela BetaFeatures para conferir se o recurso foi ativado.

// SpecialMyExtension.php
class SpecialMyExtension extends SpecialPage {

    public function execute() {
        if ( BetaFeatures::isFeatureEnabled( $this->getUser(), 'my-awesome-feature' ) ) {
            // Implement the feature!
        }
    }
}

Também é possível utilizar um normal check nas preferências, mas não o faça contra valores booleanos (True/False) — utilize os valores da classe HTMLFeatureField.

// SpecialMyExtension.php
class SpecialMyExtension extends SpecialPage {

    public function execute() {
        if ( $this->getUser()->getOption( 'my-awesome-feature' ) === HTMLFeatureField::OPTION_ENABLED ) {
            // Implement the feature!
        }
    }
}

Pelo fato da classe BetaFeatures necessitar estar presente em todos os lugares, é possível utilizar a função de conveniência em qualquer hook, página especial, etc. Apenas tenha em mente os possível problemas de performance ou de cache que poderão vir com essas mudanças.

Caso você também deseje utilizar sua extensão sem a BetaFeatures, certifique-se que ela não existe:

if (
    !ExtensionRegistry::getInstance()->isLoaded( 'BetaFeatures' )
    || \BetaFeatures::isFeatureEnabled( $user, 'my-awesome-feature' )
) {
    // Implement the feature!
}

Configuração

A variável de configuração $wgBetaFeaturesWhitelist pode ser utilizada para limitar quais recursos betas são exibidos nas preferências. Por padrão, a variável é nula, e todos os recursos beta são exibidos.

Se ela for utilizada, para que um recurso beta seja exibido nas preferências, ele necessitará ser listado na whitelist. Essa variável aceita um arranjo de strings. Cada string deve ser o nome do recurso beta conforme especificado na definição passada ao onGetBetaFeaturePreferences(). Por exemplo, no código acima, o nome do recurso beta é myextension-awesome-feature, então ele deveria ser adicionado ao arranjo $wgBetaFeaturesWhitelist na configuração da sua wiki:

$wgBetaFeaturesWhitelist = [
        'myextension-awesome-feature' 
];

Uso avançado

Quer ver algo bem legal?

Inscrição automática em grupos

Neste exemplo, registramos uma preferência de “auto-inscrição” — se o usuário ativá-la e novos recursos serem lançados para um certo grupo, o usuário será automaticamente “inscrito” a esses recursos (ou seja, serão ativados).

// MyExtensionHooks.php
class MyExtensionHooks {

    static function getPreferences( $user, &$prefs ) {
        global $wgExtensionAssetsPath;

        $prefs['my-awesome-feature-auto-enroll'] = array(
            // The first two are message keys
            'label-message' => 'beta-feature-autoenroll-message',
            'desc-message' => 'beta-feature-autoenroll-description',
            // Link to information on the feature - use subpages on mw.org, maybe?
            'info-link' => 'https://wwww.mediawiki.org/wiki/Special:MyLanguage/MyFeature',
            // Link to discussion about the feature - talk pages might work
            'discussion-link' => 'https://www.mediawiki.org/wiki/Talk:MyFeature',
            // Enable auto-enroll for this group
            'auto-enrollment' => 'my-awesome-feature-group',
        );

        $prefs['my-awesome-feature'] = array(
            // The first two are message keys
            'label-message' => 'beta-feature-message',
            'desc-message' => 'beta-feature-description',
            // Paths to images that represents the feature.
            // The image is usually different for ltr and rtl languages.
            // Images for specific languages can also specified using the language code.
            'screenshot' => array(
                'ru' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-ru.png",
                'ltr' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-ltr.png",
                'rtl' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-rtl.png",
            ),
            // Link to information on the feature - use subpages on mw.org, maybe?
            'info-link' => 'https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:MyExtension/SomeFeature',
            // Link to discussion about the feature - talk pages might work
            'discussion-link' => 'https://www.mediawiki.org/wiki/Extension_talk:MyExtension/SomeFeature',
            // Add feature to this group
            'group' => 'my-awesome-feature-group',
        );
    }
}

Gerenciamento de dependências

A seguir, definiremos um recurso de gerenciamento de dependências. Para fazer isso, primeiro registramos o nome do hook o qual desejamos utilizar para isso com o hookGetBetaFeatureDependencyHooks ”, e aí registramos um hook daquele tipo que confira dependências, retornando true ou false.

// MyExtension.php
$wgAutoloadClasses['MyExtensionHooks'] = __DIR__ . '/MyExtensionHooks.php';
Hooks::register( 'GetBetaFeaturePreferences', 'MyExtensionHooks::getPreferences' );
Hooks::register( 'GetBetaFeatureDependencyHooks', 'MyExtensionHooks::getDependencyCallbacks' );
Hooks::register( 'CheckDependenciesForMyExtensionFeature', 'MyExtensionHooks::checkDependencies' );
// MyExtensionHooks.php
class MyExtensionHooks {

    static function getPreferences( $user, &$prefs ) {
        global $wgExtensionAssetsPath;

        $prefs['my-awesome-feature'] = array(
            // The first two are message keys
            'label-message' => 'beta-feature-message',
            'desc-message' => 'beta-feature-description',
            // Paths to images that represents the feature.
            // The image is usually different for ltr and rtl languages.
            // Images for specific languages can also specified using the language code.
            'screenshot' => array(
                'ru' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-ru.png",
                'ltr' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-ltr.png",
                'rtl' => "$wgExtensionAssetsPath/MyExtension/images/screenshot-rtl.png",
            ),
            // Link to information on the feature - use subpages on mw.org, maybe?
            'info-link' => 'https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:MyExtension/SomeFeature',
            // Link to discussion about the feature - talk pages might work
            'discussion-link' => 'https://www.mediawiki.org/wiki/Extension_talk:MyExtension/SomeFeature',
            // Mark as dependent on something
            'dependent' => true,
        );
    }

    static function getDependencyCallbacks( &$depHooks ) {
        $depHooks['my-awesome-feature'] = 'CheckDependenciesForMyExtensionFeature';
        return true;
    }

    static function checkDependencies() {
        $dependenciesMet = false;
        // Do some fancy checking and return the result
        return $dependenciesMet;
    }
}

É possível usar e abusar disso para desabilitar os recursos na wiki, caso estejam marcados como dependências. Mas isso parece bem rudimentar, não? Pare, sabemos que você quer fazer isso!

Banco de dados

Há uma tabela de dados definida e usada pela BetaFeatures, que é a betafeatures_user_counts. Entretanto, você poderá ser confundir se tentar utilizá-la localmente.

Usamos a fila de trabalhos (job queue) para executar atualizações nessa tabela após o cache expirar (TTL de 30 minutos). Se sua wiki estiver configurada para executar trabalhos a cada request, isso fará com que uma request a cada 30 minutos seja muuuuuito lenta, mas o resto será relativamente rápido. Se você configurar sua wiki para executar trabalhos através do cron, as coisas serão muito mais rápidas.

Troubleshootings

Usage counts

The usage counts might not reflect exactly the number of users having some beta features activated at this precise moment. These should be interpreted as approximate numbers.

This number is computed by a job, which could be delayed or long-running. In the past, there was also a 30-minutes cache on these figures.

Ver também