Amélioration de la révision des contributions/Nouveaux filtres pour la révision des contributions/Comment implémenter un filtre

From mediawiki.org
This page is a translated version of the page Edit Review Improvements/New filters for edit review/How to implement a filter and the translation is 100% complete.

Produit et architecture

D'abord, il faut poser quelques questions au sujet du produit et de l'architecture :

  • But et effets du filtre - tenez compte de l'experience de l'utilisateur et des cas d'utilisation. Ensemble, cela va vous permettre de décider ce que le filtre doit faire, et vous donner la manière de le décrire.
  • Choisir un texte - vous aurez besoin d'une étiquette (label) et d'une description (description), qui seront placées comme indiqué sur l'image User registration. Ces deux chaînes doivent être concises. Si vous créez un nouveau groupe, vous aurez aussi besoin d'un titre de groupe (group title); vous pouvez aussi spécifier (facultatif) le texte What's This? (qu'est-ce ?) pour fournir davantage d'informations concernant le groupe.

Auditeur

Déclarez un auditeur qui va écouter sur l'accroche ChangesListSpecialPageStructuredFilters . Cela vous donnera accès à $special, une instance de ChangesListSpecialPage utilisée ci-dessous.

Groupe

D'abord, choisissez si vous voulez créer un ChangesListStringOptionsFilterGroup ou un ChangesListBooleanFilterGroup . ChangesListStringOptionsFilterGroup est meilleur si vous avez beaucoup d'options, elles ne sont naturellement pas exprimées comme des filtres cachés initialement (hideanons - cachés et anonymes), et/ou leur couverture n'est pas totale (une couverture totale signifie que toutes les cases d'un groupe sont cochées et c'est la même chose que s'il n'y en avait aucune). ChangesListBooleanFilterGroup est meilleur pour les filtres habituellement masqués (comme hideanons), ou les filtres qui peuvent être exprimés simplement en utilisant ce concept.

Si vous créez un nouveau groupe, créez un objet pour cela. 'name' est un identifiant interne. Néanmoins, pour ChangesListStringOptionsFilterGroup, il est aussi utilisé en tant que paramètre d'URL. Sinon (voir ci-dessus) :

$group = new ChangesListBooleanFilterGroup(
    [
        'name' => 'groupname',
        'title' => 'myextension-rcfilters-groupname-title',
        
        'filters' => [
            // Each element of 'filters' is an array using the format
            // passed to the ChangesListBooleanFilter constructor
        ],
    ]
);

ou :

$group = new ChangesListStringOptionsFilterGroup(
    [
        'name' => 'groupname',
        'title' => 'myextension-rcfilters-groupname-title',
        'default' => 'foo,bar',
        
        'filters' => [
            // Each element of 'filters' is an array using the format
            // passed to the ChangesListStringOptionsFilter constructor
        ],
        
        'isFullCoverage' => true, // see explanation above for how to choose this value,
        'queryCallable' => function (
            $specialPageClassName,
            IContextSource $context,
            IDatabase $dbr,
            array &$tables,
            array &$fields,
            array &$conds,
            array &$query_options,
            array &$join_conds,
            array $selectedValues
        ) {
            // selectedValues is an array of the values the user chose.
            // Add necessary tables, fields, and conditions to implement your database condition.
        }
    ]
);

Par ailleurs, vous devez ensuite enregistrer le groupe avec :

$special->registerFilterGroup( $group );

Vous pouvez facultativement inclure des informations pour la fenêtre popup What's this ? (whatsThisHeader, whatsThisBody, whatsThisUrl, et whatsThisLinkText - voir l'image en vignette). A la place, utilisez ceci si vous devez accéder à un groupe existant (par exemple, défini par le noyau) :

$group = $special->getFilterGroup( 'existinggroup' );

Filtres

Indépendamment du fait que vous ayez créé un groupe, vous pouvez vouloir ajouter des filtres aux nouveaux groupes ou aux groupes existants.

Si tous les filtres appartiennent à un groupe que vous créez, vous devez mettre les définitions dans le paramètre filters du constructeur du groupe; ce qui les classera pour vous. Pour ajouter des filtres à des groupes préexistants, suivez les intructions ci-dessous.

Il existe actuellement deux types de filtres, ChangesListBooleanFilter et ChangesListStringOptionsFilter. Chacun d'eux ne va uniquement dans le groupe correspondant à son type. 'name' est utilisé comme identificateur et il apparaît aussi dans l'URL. Utilisez :

$filter = new ChangesListBooleanFilter(
    [
		'name' => 'hidesomething',
		'group' => $group,
		'label' => 'myextension-rcfilters-groupname-hidesomething-label',
		'description' => 'myextension-rcfilters-groupname-hidesomething-desc',
		'showHideSuffix' => 'myextension-rcfilters-groupname-showhidesomething',
		'default' => false, // true to hide by default, false not to hide by default
		
		// Adjust priority as needed to order your filters where you wish, or use the
		// 'filters' parameter of the group constructor, which handles this.
		'priority' => -1,
		
		'queryCallable' => function ( $specialClassName, $ctx, $dbr, &$tables, &$fields, &$conds,
		    &$query_options, &$join_conds ) {

			// Add necessary tables, fields, and conditions to implement your database condition.
		},
		'cssClassSuffix' => 'something',
		'isRowApplicableCallable' => function ( $ctx, $rc ) {
            // Return true if the $rc row (part of the result set) is controlled by this filter.
            // E.g. if this filter hides logged inusers, and $rc is an action taken
            // by a logged inuser.
		},
    ]
);

ou :

$filter = new ChangesListStringOptionsFilter(
    [
		'name' => 'choice',
		'group' => $group,
		'label' => 'myextension-rcfilters-groupname-choice-label',
		'description' => 'myextension-rcfilters-groupname-choice-desc',
		
		// Adjust priority as needed to order your filters where you wish, or use the
		// 'filters' parameter of the group constructor, which handles this.
		'priority' => -1,
		
		'cssClassSuffix' => 'something',
		'isRowApplicableCallable' => function ( $ctx, $rc ) {
            // Return true if the $rc row (part of the output) is controlled by this filter.
            // E.g. if this filter shows log actions, and $rc is a log action.
		},
    ]
);

Vous n'avez plus rien à faire, une fois que le filtre est construit.