User talk:Ianezz/Catwatch2.js

About Catwatch2

What does it do?

Catwatch2.js creates a pop-up displaying the last change that occurred to the pages of a list of categories.

More specifically: given an initial list of categories, it recursively builds a list of pages and subcategories (up to the given depth), then considers the last edit done to each entry, and if it has been done less than the specified number of days ago, it displays a links to that page. Optionally, it can hide the pages last edited by a given user.

Important note

only the last edit to a page is taken in account (that's mainly because of the query API). This means that if a page was edited first by user Alice and then by user Bob (with Bob doing the last edit), and you decide to hide pages edited by user Bob, you won't see Alice's edit instead (i.e. all pages where Bob did the last edit won't be listed at all). It's either this, or a distinct query for each page (which is a bad idea, since it's quite easy to end with thousands of pages). It should be possbile to overcome this limitation in the future, by using a different approach in querying for data (currently working on that...) Querying first for category members, then for all the recent changes, and then merging the two lists may seem a good alternative approach, until one realizes that there are dozens of thousands of changes each day, and we can retrieve at most 500 per query (5000 if we were a bot). Another option could be retrieving the revision history of just the hidden pages, but again this results in a query for each hidden page.

How do I install it?

You have to be logged in to install it (but the script would otherwise work equally fine if there was a way to load it without being logged in).

Go to your preferences, select "Appearance", and then edit the "Custom JS" for the skin you are using. Then add one of the "importScriptURI" lines listed below, and optionally some code to fill in your favourite categories. For example, to install version 0.7 and pre-fill categories "MyCategory1", "MyCategory2" and "MyCategory3", you would add (as indicated later in this page):

   // Version 0.7
   importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=48080345&action=raw&ctype=text/javascript');
 
   // Pre-fill with MyCategory1, MyCategory2 and MyCategory3. Add as many as you wish
   hookEvent('load', function() {
       catwatch2.setCategories([
           "MyCategory1", 
           "MyCategory2", 
           "MyCategory3" 
       ]);
   });

If you want to live on the bleeding edge, you can omit the &oldid=xxx part of the URL and always get the latest (beta!) revision, but be warned that the script could be in a broken state.

Save and then clear your browser's cache (as indicated on that page). Then, you should notice a "catwatch2" link on the top right, just next to "My Watchlist". Just click it to display the user interface. That's it.

Oh, did I mention that it works exactly the same on Wikipedia as well (or any other MediaWiki installation, for what I know)?

How do I use it?

Click on the new "catwatch2" link on top right to display a form where you can enter, in order:

1. a list of category names to scan, one per line, with or without the "Category:" prefix; you can use the wildcard "*" in a name to select all the categories matching that pattern (example: "Media needing categories as of * 2010"), but you have to specify at least three characters before the first asterisk (i.e. "Castles in *" is ok, but "* in Italy" isn't, and neither is "xy*");
2. how many levels to descend (the depth of the scan): enter 0 to consider just the members of the given categories (i.e. just their children), 1 to consider also their sub-members (i.e. childrens and grandsons), and so on. Note that we have to perform a distinct query to the server for each category we have to descend, so going beyond 3 gets quite slow;
3. how many days to look in the past. This actually has little if no impact at all on the time needed to get the result, so you can specify it as large as you wish. In other words, this is just a filter that is applied after queries are performed (and queries are the slow part). You can change it, search again, and have a nearly-instant result;
4. optionally, the name of an user to ignore (without the "User:" prefix). Useful if you want to ignore changes you did yourself.
5. a set of radio buttons specifying how edits by bots, minor edits and new pages should be displayed ("Either" includes everything, "Yes" includes only pages with the specific flag, "No" excludes pages with the specifig flag).

Click the "Search" button and wait for results to be displayed. It may take minutes if the number of involved categories is large, and if it is the first time you scan that categories. After that, results are cached for a while (but keep in mind that this cache is destroyed if you reload the page).

You can hide the panel using the little "X" button on top right, and show it again (with the last results) clicking on "catwatch2" again.

Which browsers and skins are supported?

This script is being developed on Firefox 3.x (with javascript.options.strict set to true), but some care is taken to ensure it may work with other browsers as well. Both Safari and Google Chrome (webkit-based browsers) should be fine. Internet Explorer 6.5 works (perhaps with minor ahestetic bugs), IE8 too. Firefox 4.0b9 seems to be ok. Other browsers have not been tested as of now.

This script is being tested with the Vector and Monobook skins (it searches for the "bodyContent" and "pt-watchlist" elements in the DOM, falling back on the document body if "bodyContent" can't be found), but it should stay quite usable with other skins too.

Does it work on other wikis (i.e. on Wikipedia)?

Yes, it works unchanged on Wikipedia as well, and probably it works with any MediaWiki installation (provided you load the script from your user.js there). But categories on other wikis are not so important as they are on Wikimedia Commons, so that's not a top priority.

Who wrote this script?

This script was written by User:Ianezz, mainly to get his feet wet with EcmaScript. And to have an easy way to filter out his own changes from his "pet" category trees (which is something that neither Catscan nor Catscan2 currently does). Also, this script can work even with local (and private) MediaWiki installations, since (differently from Catscan) it runs in the users's browser.

Alternatives

Before using this script, you should seriously consider using the excellent Catscan and Catscan rewrite (or Catscan2). These tools are definitively more sophisticated

For developers

Logging

This script automatically uses log4javascript when it's available, otherwise it does without it just fine (by declaring stubs).

Local copy

To install itself, this script uses the function hookEvent(), which is normally available if the script is being downloaded from a MediaWiki installation. When that function is not available, the script assumes that:

1. it's being loaded from the local filesystem (or from another place);
2. the browser is Firefox (or any other Gecko-based browser);

thus it starts including hostnames in the URLs (Wikimedia Commons) and it asks for the special "BrowserUniversalRead" permission to "violate" the same-origin policy (since the query API is on a different server than the one where the HTML page loading the script is dowloaded from).

Queries

We do the following types of queries:

• action=query, generator=categorymembers, prop=revisions is the main query;
• action=query, meta=siteinfo, siprop=namespaces is the query for namespace prefixes;
• action=query, list=allusers, augroup=bot is the query for bots usernames.
• action=query, list=allcategories, acprefix=prefix is the query to expand category patterns.

Missing features

This is a list of features (in no particular order) that are currently missing, and that will be implemented at some point in the future.

• user feedback displaying query progress; done in version 0.4 (althought it doesn't work on IE6). From version 0.5 it works also on IE6;
• informative messages about wrong category names;
• mark minor edits done in version 0.3;
• filter out edits by bots or minor edits; done in version 0.6
• optionally use Magnus's Catscan rewrite as the backend (not so easy, because of the same-origin rule);
• provide a link to perform the same query on Magnus's Catscan rewrite;
• i18n support;
• a way for an user to save preferences, such as the default list of categories;
• asynchronous XmlHttpRequest. Now everything is synchronous, which means no parallel queries (and most of the time of a query is spent waiting for the server to answer) Asynchronous request were implemented in version 0.5, and speed up things a lot.
• include the given list of categories in the result (currently only their descendant are listed);
• query to display files newly added to a category; it's probably pointless, since a file must be edited to add it to a category. Perhaps that's not the case for categories added by templates (and the template is changed).
• limit queries somehow (by time and/or number of results?)
• include/exclude files by a substring in their name
• include/exclude files by their membership to another list of categories (i.e. query for members/descendant of category list 1 up to the specified depth, then query for members/descendant of category list 2 up to the specified depth, then show just the members of list 1 that also are in list 2, or the members of list 1 that are not in list 2)
• allow the "*" wildcard in the initial category list (i.e. "Media needing categories as of * 2009"), except in the first position. implemented in version 0.7

These are not really high on the priority list:

• filter out more than one user;
• small button next each username to quickly filter out that username
• small button next to each listed category to quickly add that category to the list of categories to search
• filter by namespace (Category, File, etc.);
• a way to specify to open all links in new windows;
• display changes to already watched files in bold, as on the watchlist.
• query to display all files currently not on the user's watchlist (so they can be copy-pasted to the user's watchlist)
• use a completely separate browser window, instead of displaying a div on top of everything else;

Releases

Current beta

No current beta.

Version 0.7

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=48080345&action=raw&ctype=text/javascript');

New features: patterns in categories.

Changes:

• Now it is possible to specify categories by pattern (example "Media needing categories as of * 2008"); the only limit is that you have to specify at least three characters before the first asterisk; you can both expand them before doing the search via the new "Expand" buttond, or go straight to the search;
• new method setCategories(), so it is possible to set the initial list of categories from user.js

Version 0.6

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47859254&action=raw&ctype=text/javascript');

Please upgrade to this version, as previous versions (0.5 and 0.4) could display only partial results.

Changes:

• now can filter bots, minor edits and new pages (same interface as Catscan2);
• display search totals on top of results;
• search depth can be choosen via radio buttons;

Bugfixes:

• (severe) Fixed race condition that becomes apparent when using results from the cache: only results related to the first category were displayed if the results were entirely loaded from the cache and either the category list or the category depth was changed.
• When linking back to the Catwatch2.js talk page, include the hostname in the URL so people using this script with other wikis (example: Wikipedia) land on the right page.

Other:

• improved documentation of the source;
• aestetical changes to the close button.

Version 0.5

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47766066&action=raw&ctype=text/javascript');

Changes:

• rewrote search code to use asynchronous requests. This means that queries are done in parallel, and searches complete sooner than before;
• changed the meaning of the depth parameter: now it matches the one found in Catscan/Catscan2, with 0 meaning just the immediate children of the categories, 1 meaning to include subcategories as well (thus including the grandsons), 2 to include sub-sub-categories, etc.

Version 0.4

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47713384&action=raw&ctype=text/javascript');

Mostly new features, and a bugfix

Bugfixes:

• fix a syntax error (a wrong method name) in doJSONQuery().

Changes:

• display some visual feedback (number of pages found so far) while performing the queries. Unfortunately, that donesn't seems to work on IE 6 (i.e. no errors, but no feedback is displayed).
• edits done by bots are detected and displayed as such (with a bold "m"). This is done by querying the server on what usernames are currently in the "bot" group, so an edit is considered done by a bot if the user that did is currently in the "bot" group , regardless of its membership at the time of the edit;
• cache partial query results, so previous query results can be reused. The cache lasts at most as long as the page displaying the pop-up, so if you need fresh results just reload the page and pop-up Catwatch2 again;
• query the server for the prefixes of the "Category:" namespace (so, in addition to the canonical prefix "Category", we can use the localized prefix as well: for example on the italian Wikipedia it is "Categoria").

Version 0.3

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47571481&action=raw&ctype=text/javascript');

Minor bugfixes and aestethic changes. No real changes in functionalities.

Bugfixes:

• Minor edits are now correctly detected and displayed as such (with a bold "m").
• New pages are now correctly detected and displayed as such (with a bold "N" and with a non-clickable "diff" link).

Changes:

• display the Catwatch2 version, both as a tooltip on the catwatch2 link, and in the popup title;
• the popup title now is a link to the Catwatch2 description page;
• the popup now covers just the wikipage content (id="bodyContent", which should be OK both for Monobook and Vector), or the whole page as before as a last resort;
• changed titlebar colors (it's still ugly...);

Version 0.2

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47493233&action=raw&ctype=text/javascript');

This is mainly a bugfix release.

Bugfixes:

• (severe) corrected handling of links to pages containing "'" in their name;
• the output list format now matches "My watchlist" (with links to diff, history, user contributions, etc.).
• dates are displayed as ISO dates ("YYYY-MM-DD") to avoid confusion;
• removed buggy cloneObject() function and changed code to do without it; it didn't affect the output, but that's a code snipped that really has no reason to exist;
• fixed toQuotedStringLiteral() (which erroneously called itself instead of calling toStringLiteral()). It didn't affect the output, since it wasn't used;

Version 0.1

 importScriptURI('http://commons.wikimedia.org/w/index.php?title=User:Ianezz/Catwatch2.js&oldid=47475349&action=raw&ctype=text/javascript');

First public release. Works on Firefox 3.x, IE 6.5, Google Chrome.

Feedback/Discussion

Please add here your feedback. If you are experiencing something that seems an error/bug, please remember to indicate what version of Catscan2 you are using (easy: just look at the popup top, the version is in parenthesis), and how to reproduce the problem.