Article feedback/Version 5/Technical Design

This page describes technical designs for the Article Feedback Tool Version 5 (AFT V5).

See also: feature requirements page, project overview page, useful links, as well as data and metrics plan.

Overview
The front end of the AFTv5 extension follows the ArticleFeedback extension: on article pages, a set of javascript modules attach a new div to the bottom of the page and fill it with a feedback form. On submission, the form is replaced by a CTA (call to action). Most of this code has been rewritten to allow for the selection of one of a set of possible forms, and one of a set of possible CTAs. Right now, form options 1, 2, and 3 are available, and the edit CTA is the primary choice (falling back to the learn more CTA if the current user cannot edit the article in question).

The back end is entirely new: rather than displaying aggregate data, the Special page shows a feed of the responses to the article passed in to the url. Right now the back end is not available in production; however, it is the first priority for the next phase. (For now, aggregate data from production is available via Dario's tools.)

Database schema


"More detailed information is available on the schema documentation page"

There are three types of tables that compose AFTv5: data type tables (describing the available fields and options by form), feedback tables (one for posts, and one for the answers that compose it), and aggregate tables (keeping easily-accessible counts for the special page).

When a feedback form is submitted, a record is created in  and also, depending on the feedback form, a number of rows may be added to   -- one row per answer.

Each answer is associated with a row in, which dictates the data type of the answer. Fields of type  have their answers stored in , for example.

In the same transaction, each row in the appropriate aggregate tables is updated -- by rating or boolean value for, or by select option for. For each filter the new feedback post matches (both for its article and for the central feedback page), the row in  is updated.

Later, when editors and monitors perform various actions on the feedback, the associated filter counts are updated -- for example, hiding a comment would increment the  filter and decrement the   filter.

Front End

 * TODO* Some code has been pushed to Gerrit that changes the description below: https://gerrit.wikimedia.org/r/#/c/8884/. The startup check is now located at ArticleFeedbackv5.hooks.php in the beforePageDisplay method. If this commit is approved and gets merged, update the docs accordingly.

After page load, the startup module (ext.articleFeedbackv5.startup.js) determines whether to display the form, and if so, loads the primary module (ext.articleFeedbackv5.startup.js). The primary module attaches a new div to the bottom of the page and invokes the jQuery plugin (jquery.articleFeedbackv5.js) on it, then adds a link in a prominent location -- if the user scrolls to the bottom of the page, they'll see the form there; if they click the link, they'll see it in a overlay window. The particular form the user sees, and the exact location of the link, are chosen via bucketing.

If the user hits the submit button, it runs an error check and, if there are no issues, invokes an AJAX request. Upon successful return, the form is replaced with a CTA (call to action).

Flow

 * 1) Startup phase
 * Determines whether to display the tool:
 * 1) * the user agent is supported
 * 2) * the page is an article
 * 3) * the category is whitelisted/blacklisted
 * If all is well, it loads the main module.
 * 1) Main phase
 * Creates a new div, inserts it at the bottom of the article, and invokes the jQuery plugin on it
 * Selects a trigger link option and adds it to the page (if any)
 * * NB: The click event calls the plugin's open-as-modal event
 * 1) Init phase (, method  )
 * Sets some state variables, chooses a display option, and binds the "appear" event to the holder div
 * 1) Load phase (, method  )
 * Sets up the bottom of the page and overlay containers, builds the selected form, and puts it in the appropriate container
 * 1) Submit phase (, method  )
 * Runs validation, locks the form, and sends off an ajax request
 * 1) Submit response phase (, method  )
 * On success, selects a CTA and loads it into the appropriate container, and removes the feedback link(s)
 * On error, sets an error state and unlocks the form
 * 1) CTA close (when displayed in modal)
 * If the user closes the CTA, it is entirely removed from the page and cannot be retrieved.

Query string options
You can choose a form and/or a trigger link option and avoid bucketing by passing the following in the url:

Form Bucketing Process


The decision of what form to display works like this:


 * 1) If the plugin is in the debug state, and a form has been requested in the url, and that form is known, select it.
 * 2) If there's a form-bucket cookie set, select it.
 * 3) Otherwise, call.

The decision of what link to display works like this:


 * 1) If the display bucket is   or , select   (nothing).
 * 2) If the bucketing object is missing from the config, select.
 * 3) If the plugin is in the debug state, and a link has been requested in the url, and that link is known, select it.
 * 4) Otherwise, call.

Note that the form selection doesn't check for a missing bucketing config object -- it should - TODO.

Submit AJAX call
This call is made when the user submits any of the feedback forms.

Call can be found at:

, method

Response can be found at:

Parameters:

Success response:

JSON object with one key,, containing this object:

Error response:

JSON object with one key,, containing the token for the appropriate error message

Abuse Filtering


AFT makes use of, SpamBlacklist, and AbuseFilter. You can turn abuse filtering on by setting  to true. If any of these three are available they will be used to filter out abusive feedback. See flowchart for details.

AFT makes use of AbuseFilter's "disallow" and "warn" actions, and it provides custom actions to automatically flag incoming feedback:

You can edit the available warnings by changing the page "MediaWiki:Abusefilter-warning-{somename}" -- e.g., on prototype: http://prototype.wikimedia.org/release-en/MediaWiki:Abusefilter-warning-feedback

Special Page
TODO


 * 1) Moderation tools - hide, promote (to talk page), or flag various pieces of feedback.
 * 2) Sorting and filtering options - good comments first (how that's defined is unclear), newest first, etc. Basically, tools are needed to manage or at least hide the inevitable flood of spam "feedback".
 * 3) A special page, on the level of the talk pages - add a link to this in the not-quite-top-level navigation on said talk page.
 * 4) Need to work out which bits of this page are must-have-now vs must-have-eventually.
 * 5) Phase 1 will have a limited version with:
 * 6) Filters: All, Visible only
 * 7) Moderation Tools: Hide this comment
 * 8) Sorting: By date only
 * 9) Pagination: Fixed at 50

Logging
Central activity log (https://en.wikipedia.org/w/index.php?title=Special%3ALog&type=articlefeedbackv5) calls upon class ArticleFeedbackv5LogFormatter to format the AFTv5 entries. This class extends from the default LogFormatter class and adds in some additional details to the entry (feedback text, page title & link, feedback n° & link)

The texts for all actions being logged are defined in ArticleFeedbackv5.php (as is the hook to the class that'll be formatting the log: ArticleFeedbackv5LogFormatter)

Note: _we_ don't want some of the activity to show up, which is why certain actions are prefixed with suppress/ (see *core*/includes/logging/LogFormatter.php; "case 'suppress'") rather than articlefeedbackv5/. This way, we still have logs of all these actions, though not immediately visible.

The logging of all activity happens through a function call to ApiArticleFeedbackv5Utils::logActivity (ApiArticleFeedbackv5Utils.php) which will both insert the log entry, and increment the activity count on an entry (joining with the logging table is complex and not desired on such huge dataset).

The "view activity" link in the feedback page toolbox (both on central feedback page & permalink) also fetches its data from this logging table.

Database
ApiArticleFeedbackv5Utils::logActivity is the wrapper method to call when inserting log entries. This method performs some additional checks and will build the final data to be inserted.

Platforms
We aim to support the following web browsers for phases 1.0 and 1.5:
 * Internet Explorer 7+
 * Firefox 3+
 * Safari 5+
 * Opera 10+
 * Chrome 5+

NB: Support for IE7 was pulled from phase 1.0.

We will focus our testing on these top browser versions for Wikipedia:
 * IE 8			(17%)
 * Chrome 14	       (16%)
 * Firefox 7		(11%)
 * IE 7			  (7%)
 * IE 9			  (6%)
 * Firefox 3		  (5%)
 * Firefox 6		  (2%)

These will be tested on these desktop platforms:
 * Windows	(78%)
 * Mac		 (8%)
 * Linux		 (3%)

We are not currently planning to support IE6 or mobile platforms for phases 1.0 and 1.5, and will not show the forms at all on these unsupported platforms. In future versions, we will aim for 'graceful degradation' in unsupported platforms, and are working on a good definition for testing that objective.