Jump to content

Meta:AddMe/v2

From Meta, a Wikimedia project coordination wiki

AddMe is a gadget that allows users to endorse or vote on a proposal, project, or idea. The basic concept is instead of asking users to edit the source of a wiki page to show their support, we can offer an intuitive interface and ensure the comments are consistently formatted. This is different than DiscussionTools and other comment-related tools in that AddMe has a single call to action and is specifically designed for voting or adding comments to a section of a page, usually in a list format.

In this documentation, "project" refers to one or more collection of pages that share the same system for endorsing and voting. For example, the Community Wishlist Survey and the Wikimedia Grants program where {{support}} templates are used.

Overview

[edit]

AddMe is designed to be highly flexible and cover many use cases.

Features

[edit]
  • Comments automatically include the user's signature.
  • Comments can be configured to be prefixed with some content, such as a {{support}} template.
  • Comments can be configured to go on a page different than the user is viewing.
  • Allows comments to appear after saving without leaving or reloading the page, even if the comment was placed on a transcluded subpage.
  • Can be installed on any wiki.
  • Fully translatable

Components

[edit]

Adding a new project

[edit]

The following instructions require administrator rights. If you instead would like to request a project be added, use the talk page or make an edit request on the talk page of the page you're unable to edit.

AddMe button

[edit]

Users endorse an idea or proposal using the AddMe button. Here we'll create it, and later configure AddMe to act when its clicked.

In its most basic form, the button needs to have the addme-button CSS class, and the |data-addme-project= attribute that matches corresponding key in the configuration. Established projects may want to put the AddMe button in a template, for example how Probox is used in grant proposals.

Here is a basic example that allows users to add a comment to the bottom of the same page the button is on:

<span class="mw-ui-button mw-ui-progressive addme-button" data-addme-project="wikimedia-grants">Endorse</span>

In the Community Wishlist Survey, proposals each have their own subpage, and many of them are transcluded on one parent page from which users can vote on them. In this case, we need the AddMe button to add votes to a different page than the one the user is viewing, depending on which button was used. To do this, we use the |data-addme-page= attribute:

<span class="mw-ui-button mw-ui-progressive addme-button" data-addme-project="wishlist-survey" data-addme-page="Community Wishlist Survey 2022/Wikidata/My proposal">Support</span>

In short, if the page might be transcluded, always use the data-addme-page attribute.

To prevent abuse, the specified page must be a subpage of the current page.

Configuration

[edit]

The configuration page takes is in the form of JSON and allows you to control functionality of individual projects. Each project should have its own key, with the desired options as the value. The available options along with their defaults are as follows:

Option Type Description Default value
page string Which page to post the comment to. If null, AddMe uses the current page, or the value of the data-addme-page attribute of the AddMe button. null
section-anchor string The element ID of the section of the page where the comment should be post the comment to. null
max-section-level integer Maximum level of section to process; used to help prevent putting comments in the wrong place if there are multiple sections with the same title. null
prepend-content string Wikitext to prepend before the comment, such as a {{support}} template. This should also include the desired list item, such as * (bulleted list) or # (numbered list). *
skip-dup-check boolean Whether to skip checking if the user has already commented on the page. false
require-login boolean Whether to restrict use of AddMe to logged-in users. true
remove-content-regex string Regular expression used to removed unwanted content from the comment. This generally should look for whatever prepend-content adds, such as a {{support}} template, otherwise the comment would include two support templates. null
edit-summary string The summary to use for the edit that adds the comment. null
error-report-page string Support venue to link to when there are unrecoverable errors. Meta talk:AddMe

Messages

[edit]

The messages page defines the messages used in the AddMe interface. Just as with the configuration, it is in the form of JSON, keyed by project name. However since we want to make the messages translatable with Extension:Translate, the content model is actually wikitext. Hence, it's important to make sure the syntax is valid. AddMe will show an error if the page cannot be parsed as JSON.

Note that you only need to add messages that you wish to override. The available messages and their defaults are as follows:

Key Description Default
title Shown in the header of the AddMe popup. Endorse this project
description Shown above the textarea. Why do you support this project?
feedback Success message shown after the user's comment has been saved. Thank you for adding your endorsement!
body Message shown beneath the textarea, usually telling the user that they don't need to sign their comment since AddMe does this automatically. This can contain basic wikitext and HTML. Your signature will be automatically added to your comment.
placeholder-comment Placeholder text shown when the textarea is empty. Add your comment here
watch-page Text shown next to the checkbox that allows the user to watch the page the comment is saved on. Watch this page
submit Label for the submit button. Submit
cancel Label for the cancel button. Cancel
error-save Message shown when the comment failed to save. There was an error. Please try again.
error-fatal Message shown for unrecoverable errors. There was a fatal error with the AddMe gadget. Please report this issue at Meta talk:AddMe.
error-login Message shown to logged out users. Sorry, you must be logged in to endorse this project.
error-dup-comment Message shown when the user attempts to add a comment more than once. It looks like you've already added your endorsement! Would you like to add your comment anyway?

Deploying to other wikis

[edit]

If you are an interface administrator and would like to install AddMe as a gadget on your wiki, follow these steps:

  1. Create MediaWiki:Gadget-addMe.js with the following:
    mw.loader.load('https://meta.wikimedia.org/w/load.php?modules=ext.gadget.addMe');
    
  2. Add the following to MediaWiki:Gadgets-definition:
    addMe[ResourceLoader|default|dependencies=oojs-ui,mediawiki.api,mediawiki.util,mediawiki.jqueryMsg]|addMe.js
    
  3. Add a description for the gadget at MediaWiki:Gadget-addMe, preferably linking to this page ([[meta:Meta:AddMe]]).
  4. Use the above guide to add new projects. This involves creating the pages MediaWiki:Gadget-addMe-config.json and MediaWiki:Gadget-addMe-messages.
[edit]