Help:Wikipedia: The Missing Manual/Customizing Wikipedia/Easier editing with JavaScript

From Wikipedia, the free encyclopedia
Jump to: navigation, search
Wikipedia: The Missing Manual (Discuss)

You can customize Wikipedia in ways that make your editing easier with user scripts, which are written in JavaScript code. As you've seen in Power Users' Clinic boxes[clarification needed] in this book, user scripts let you do things like color code your User contributions page, or remove pages from your watchlist by just clicking a box on your watchlist report, or adding additional links on the left side of the screen. As you explore Wikipedia, you'll find many more user scripts that editors have created to make editing work easier.

Here's how it works: When the Wikipedia server builds a page to send to your browser, it includes any JavaScript code stored in your personal JavaScript page at Wikipedia. Your browser follows the JavaScript instructions when it shows you the page, controlling how the Wikipedia page looks and works.

Best of all, you don't have to understand JavaScript to use it. You just need to know the process for cutting and pasting chunks of code to your personal JavaScript file. This chapter shows you how.

Setting up your browser[edit]

User scripts don't work if JavaScript isn't turned on. JavaScript is automatically turned on in almost every Web browser, so you don't have to change the standard settings. If user scripts aren't working for you (you're just seeing the regular Wikipedia screen after you implement some JavaScript), this section shows you how to check your settings.

How you check the settings depends on your browser:

  • Internet Explorer. As of September 2014, JavaScript has JavaScript has been disabled for IE6 and IE7 due to security issues. The setting is called "Active scripting". Go to Tools→Internet Options→Security tab. Select Internet for the zone, and then click the Custom level button. Scroll down to the Scripting section, and then, in the Active scripting subsection, make sure that Enable is already selected. If not, click to turn it on, and then click the Okay button. When the Change settings dialog box appears, click Yes. (In Internet Explorer 6, this dialog box is labeled Warning.)
  • Firefox. In Windows, go to Tools→Options; on a Mac, go to Firefox→Preferences; on Linux, go to Edit→Preferences . At the top of the Options box, click Content (if it's not already highlighted), and make sure the "Enable JavaScript" checkbox is turned on. If not, click to turn it on, and then click OK.
Tip:
If you have security concerns about globally turning on JavaScript for all Web sites, the Firefox add-on NoScript lets you turn on JavaScript on a site-by-site basis.
  • Opera. Go to Tools→Preferences→Advanced tab. On the left, select Content, and make sure the Enable JavaScript checkbox is turned on. If not, turn it on, and then click OK.
  • Safari. Go to Safari Preferences→Security, and, under Web Content, make sure the Enable JavaScript checkbox is turned on. Close the Preferences window when you're done.

Adding and deleting scripts[edit]

To use user scripts, you create a personal JavaScript page, which only you and Wikipedia administrators can edit. On this page, you put the user scripts that you want to use, or pointers to other pages where JavaScript code is stored (which Wikipedia uses to add code to your page).

When you want to stop using a script, you edit that personal page, deleting the JavaScript code or pointer, or marking it as non-executable information. That's called commenting it out, and it just means you're telling the Wikipedia software not to follow those instructions.

Note:
In late 2007, Wikipedia added a new feature that lets you implement user scripts with just a couple of clicks. On the My Preferences page, check the Gadgets tab to see if the script you want to add is listed on that tab. If so, you can save time by turning it on that tab, rather than following the instructions in this section. (For details, see the section about xx.)

Your personal JavaScript page[edit]

Creating your JavaScript page is as easy as creating a subpage in your own user space, as described in Chapter 3: Setting up your account and personal workspace. See the section about xx if you need a refresher on subpages. In this chapter, you will name your personal page common.js, which is a special name for personal JavaScript used while you are logged in to Wikipedia.

Note:
It is also possible to name your JavaScript page as the name of your preferred skin (see the section about xx) followed by .js, e.g. vector.js or monobook.js. JavaScript in such pages is only used while you are using that skin; should you change your skin, you would need to move the JavaScript page to the name of your new skin. You might want to use such a name for your JavaScript page if you know your scripts only work with certain skins.

When you're ready to do the JavaScript jive, go to your user page, and follow these steps:

1. On your user page, click "edit this page". In the edit box, type either *[[User:YourUsernameGoesHere/common.js]] or simply *[[/common.js]]. Then add an edit summary like Creating link to new common.js page, do a preview, and then save your edit.

You've just added a link to your soon-to-be-created JavaScript page. The link to the new page is red, since it doesn't yet exist.

2. Click the red link to the common.js page, and, at the top of the edit box, add the following: // User scripts.(In JavaScript code, anything that begins with double slashes is a comment. You'll see the "User scripts" comment, as shown in Figure 21-1.) Add an edit summary (like Creating initial page), preview the page (to reinforce the habit), and then save the page.

By saving the page with only a comment, initially, you're creating a version of the page that you can revert to if something goes wrong. That's extremely unlikely, but it doesn't hurt to have the option.
Figure 21-1. All common.js pages have the same warning at the top – don't copy a script just because someone else leaves a note on your user talk page about what a neato-cool tool they've created. (Leaving uninvited, non-personal postings on user talk pages is considered spam, and fortunately it doesn't happen very often.) If you use JavaScript code someone else wrote, make sure it's someone you trust.

Adding a script[edit]

As discussed in Chapter 7 (the section about xx), when you're evaluating a user account to determine whether it's a vandalism-only account, it's helpful to look at more than the user talk page of the editor. You'll often want to look at individual edits (the User contributions page) and the block log, for instance. This tutorial will show you how to implement some JavaScript that add tabs, making that research easier.

1. Go to the page Wikipedia:WikiProject User scripts/Scripts/User tabs (Figure 21-2), and copy all the text within the dotted box.

This page has no "edit this page" tab, meaning it's protected. Don't copy JavaScript or any other code from an unprotected page, since someone may have tampered with it.
Figure 21-2. The script at the page Wikipedia:WikiProject User scripts/Scripts/User tabs has three full lines of comment (two at the top, one at the bottom); these have two slashes at the beginning. The actual code that will be executed is the middle fifteen lines. The blanks spaces at the beginning of any line are optional—they're there to make the script easier for humans to read. Computers don't care one way or another. (The blank spaces at the beginnings of lines are why the text goes off-screen on the right; that's normal for Wikipedia wikitext.)

2. Open your own common.js page, and then, in the edit box, paste the text that you copied in step 1.

If you haven't created a common.js page yet, instructions are on the section about xx.

3. Change [[User:Where/usertabs]] to [[Wikipedia:WikiProject User scripts/Scripts/User tabs]], to show where you got the script.

Your edit box should look like Figure 21-3.
Figure 21-3. In editing mode, common.js pages look different from regular pages. There's no edit toolbar, because there's no need for buttons for inserting a signature, or a table, or other text. There's also a message about using the "Show preview" button to test the added JavaScript before saving the page.

4. Add an edit summary (Adding JavaScript for user tabs, for example) and then click the "Show preview" button.

The preview should look like Figure 21-4. If everything looks as you expect (as is the case here, there's no visible change), save the page. If something looks wrong, recheck the code that you added to the page.
Figure 21-4. The nice thing about previewing a change to your personal JavaScript page is that the JavaScript is implemented immediately. If it should change the common.js page, you see that. In this case, the new tabs will only show on a user page, so the preview doesn't tell you how you're doing.

5. After you save the change, you should bypass your cache so that Wikipedia isn't using an old version of your common.js (see the section about xx). Then go to a page where you expect the change to appear—for example, click on the "my talk" link on the upper right, and check if the change has happened.

As shown in Figure 21-5, it indeed has.

If you still can't see what you expect after bypassing your cache, then ask for assistance at the Help desk (shortcut: WP:HD).

Figure 21-5. Now a number of additional tabs appear whenever you go to a user or user talk page. If you decide you don't want one or more of these, all you need to do is comment out the corresponding line on your common.js page (put two slashes at the very beginning), and that tab won't appear any more.

Preventing code overload[edit]

It's good practice to put anything other than a very short script into a separate page, with a name ending in .js, so that only you—and administrators—can edit it. That way, you don't end up with a very long, difficult-to-understand and difficult-to-edit common.js page.

Suppose, for example, you put the "User tabs" JavaScript from the previous steps, into a new page called User:Your username goes here/UserTabs.js. That keeps it out of your common.js page, but it also means that Wikipedia doesn't recognize it as JavaScript you actually want to use. In fact, when you go into edit mode at a new page, to paste in the code, you see a warning message (Figure 21-7) that tells you that Wikipedia can't match the file name against one of the skins you can choose (see the section about xx), and therefore won't automatically execute the script when you're logged on.

Figure 21-6. When you create a page whose name ends with .js or .css, Wikipedia checks to see if that's the name of a skin (see the section about xx). If not, it gives you this warning. In this case, you can ignore the warning. But if you typed (for example) COMMON.js rather than common.js, earlier in the chapter, the misspelling would be critical and the warning would be relevant.

To actually use the JavaScript at your new User:Your username goes here/UserTabs.js page, you have to tell Wikipedia to import into your common.js page. When the Wikipedia software reads your common.js page, it reads the import script, and learns where to go to get the actual JavaScript. Figure 21-7 shows a bunch of import scripts on an editor's common.js page.

Figure 21-7. The page User:Ais523/monobook.js has a number of JavaScript functions (user scripts) added via the importScript command, rather than pasting all the JavaScript into the page. One advantage of importScript is that you get a neat list of all your user scripts, rather than a mass of code. Separating functions by putting them on separate pages also makes it easier to share scripts with other editors.
Note:
In Figure 21-7, the line second from the bottom has two slash marks in front, making the line into a comment. In geekspeak, the line is commented out, so the script won't run. To reverse that in the future, making it functional again, just delete the slashes.

Importing multi-function scripts of other editors[edit]

Several Wikipedia editors have created big, fabulously useful, multi-function scripts. You absolutely don't want to cut and paste these scripts, even to a separate page of your own, because you need the editor who created it to maintain it. You want to get enhancements to the code as they occur. By using the import function, you get the benefit of those updates (as do the hundreds of other editors using the same script).

Warning:
As always, don't trust any page that isn't protected from editing by regular editors. Don't ever import from an unprotected page.

Removing scripts[edit]

As you can see from reading this chapter, editing your common.js page is no big deal. It's no harder than cutting and pasting text to any Wikipedia article. You can remove a function by deleting it, or by commenting it out (putting a pair of slashes at the beginning of each line). Commenting out works best for cases where you're importing a function (see Figure 21-7) and there's just one line to comment out. If you have 10 or 15 lines of code that you copied to your common.js page that you don't want any more, the page will be a lot neater if you delete it all, perhaps leaving a single comment line about where you found the code, in case you want to copy it back in at some later point.

If You Don't Use the Vector Skin

As discussed in the previous chapter (the section about xx), in your My Preferences page, on the Skin tab, you have an option of selecting one of seven skins, which rearrange the elements and formatting on each Wikipedia page that you view. The tab has buttons to click to see a preview of each skin, so you can get a clear sense of what a change of skins can do.

You have no guarantee that a user script that works in Vector—which is what almost all editors use, and the norm for testing user scripts—will also work if you use another skin. But if you want to try using a different skin, understand that each skin looks for a specific, and different, personal file when it implements your personal JavaScript (e.g. Vector looks for vector.js). To avoid needing to create a new personal JavaScript page to try out a different skin, place your JavaScript into common.js, which is used by all skins.

The files used by the other seven skins are:

  • Cologne Blue: cologneblue.js
  • Monobook: monobook.js
  • Modern: modern.js

Fixing problems[edit]

If you run into a problem with JavaScript, use this tried-and-true procedure to deal with it. Perform the fixes in the following order, so you're starting with the simplest fix, and working your way up to the most complex:

  • If you're not sure whether JavaScript is turned on in the browser you're using, follow the procedures on the section about xx to make sure that it is.
  • You may need to bypass your browser's cache (the copy of pages that it keeps, to speed up the process of showing you what you want to see):
  • Internet Explorer. Press Ctrl+F5.
  • Mozilla Firefox. Press the Shift key while clicking the Reload button (or press Ctrl+Shift+R).
  • Opera/Konqueror. Press F5.
  • Safari. Press ⌘-Option-E.
  • Sometimes bypassing the cache doesn't work, but purging it does. As discussed at the Wikipedia:Purge, page, follow this procedure: Click the "edit this page" tab. In your browser's address bar, at the end of the URL, where you see &action=edit, replace edit with purge, so it reads &action=purge. Then press Enter to tell your browser to go to that revised URL.
  • Finally, if you're using Firefox 2 as your browser, you can use its browser console to track down errors one by one. Go to Tools→Error Console. You'll probably see a lot of warnings, but you want to see errors, so click the red stop sign icon, the one with Errors next to it.
The next page lists any scripts with problems. Clicking an entry in the list takes you to the page with the code on it, with the error highlighted. Now recheck the source of the code (that's why you put comments in the code about where you got it). If you didn't make a mistake in copying, then you probably want to comment out the script (by placing double slash marks at the beginning of each line) if it's interfering with other scripts. Then either post a talk page note for whoever created the script, or a note at the Village Pump technical page (WP:VPT). (The second choice is better if you think the script is a popular one.)
Note:
The Opera browser has a similar feature: Go to Tools→Advanced→Error console.
  • One error in a JavaScript file is enough to disable all scripts. The error won't damage anything; it just has the effect of commenting out the entire common.js page, making it inactive. And of course it's irritating. If you can't identify the problem script via the browser error console, revert to the last version of the page that worked (see the section about xx for more on reverting). Then add back, one by one, whatever scripts were lost by reverting, being extra careful as you copy or import, to see at what point the problem occurs.

Resources[edit]

You'll find technical information about JavaScript (user scripts) here:

User scripts are scattered throughout Wikipedia. You may find one just because someone mentioned it, or because you came across it in the index (shortcut: WP:EIW). The largest collection of scripts (or links to scripts) is at Wikipedia:WikiProject User scripts/Scripts (shortcut: WP:JS). Other places to check are: