Toolserver:Tool considerations

This page was moved from the Toolserver wiki.
Toolserver has been replaced by Toolforge. As such, the instructions here may no longer work, but may still be of historical interest.
Please help by updating examples, links, template links, etc. If a page is still relevant, move it to a normal title and leave a redirect.

There are a number of considerations that should be made when determining whether to or how to make a Toolserver tool. This page lists some of the most important considerations.

Necessity

The first thing that needs to be considered is whether a similar tool already exists. There is no authoritative directory of Toolserver tools, though there is Interiot's tstoc(expired). While writing your own tool can be a good learning experience, it isn't always the best use of resources, especially developer time.

Another consideration to make, especially if you're coding in PHP, is whether your tool or script is better suited as a MediaWiki extension.

Multi-maintainer tools

Multi-maintainer projects are available to Toolserver tools. Setting up a multi-maintainer tool has a number of benefits, but to end users the biggest benefit is a stable URL.

Abstraction

Code abstraction is one of the more important considerations when designing a Toolserver tool.

As an example, it's trivial to create a script that takes the contents of the speedy deletion category on a certain wiki and arranges the content by size. However, this tool won't work for any project that doesn't use the category name "Candidates for speedy deletion". Even if you programmed the tool with every translation and iteration of the speedy deletion categories, it wouldn't support other categories that users might want to query.

A much better solution is to create a tool that allows the user to select a specific wiki database and select a specific category. The flexibility to this approach reduces tool duplication and provides a better service for the end users.

When possible, tools should be designed to support every active wiki database, though it's fine to set a default database if a database is unspecified (this is especially important for historical URLs).

Never hard-code namespace names or site URLs. These should always be queried from the Toolserver database.

Security

Sanitize user input. Always! This is especially important if a tool is running SQL queries based on user input. Be sure that the input is sanitized so that it doesn't the script to unexpectedly error or allow end-users to run code that they should not be able to run.

Sanitize output. Your tools should escape special characters in HTML to avoid cross-site scripting vulnerabilities. In particular, the "<" and ">" characters must be escaped. Also, quote characters must be escaped, for example <attr title="%s"> is dangerous if " onload="alert(); is passed to it. You may have to escape single quotes as well if your use them in your HTML. Most modern programming languages contain pre-built functions to escape these dangerous characters for you. Escaping "&" is less crucial, though it's nice when tools output valid HTML.

Ensure that you don't crash any browsers by outputting too many results.

Place reasonable limits on your code if it involves resource-intensive processes. If a user sets the limit to 500000, it shouldn't cause any problems for the Toolserver servers or the user. Expect and account for user stupidity.

Passwords if collected (we recommend avoiding them) should be hashed with a salt. The Toolserver now has partial SSL support. You can also hash passwords with JavaScript. Per the rules you are not allowed to ask the wiki password of the user. All passwords should be sent with POST, not GET, to avoid having the password end up in the web server logs (which all toolserver users have access to!). There is also a shared authentication system (TUSC) that you may find useful.

Internationalization

When designing your tools, remember that not every user will speak the language that your interface is in. Using icons and colors in place of or next to key elements in your interface will allow non-native speakers to understand how to use your tool.

Services like translatewiki.net can be used to translate your tools, see Toolserver Intuition for a central initiative at the Toolserver that bridges with translatewiki.net (to avoid duplicate efforts).

Category:Documentation