Wikipedia:User scripts/Guide: Difference between revisions

Revision as of 18:31, 22 September 2008

Revision as of 22:25, 23 September 2008

Line 35:

Many scripts use this function simply to add some script interface, such as a link in a leftside portlet. Then the main part of the code is executed after user clicks on that link.

== Editing and loading the user script ==

=== Previewing in /monobook.js ===

You can edit your script directly on your [[Special:MyPage/monobook.js|/monobook.js]] page, then click [Show preview] and the new code is executed right away on the preview page.

=== Saving in /monobook.js ===

If required elements are missing on the preview page (for example, your script does something on history pages), you will have to save the script in order to test it.

However it's not convenient and creates unnecessary load on the WikiMedia servers. Also, it seems like these days Wikimedia servers are configured not to give out the saved .js version right away, so you have to wait some minute after saving and then [[Wikipedia:Bypass your cache|bypassing your browser cache]].

=== Local HTML file ===

* Save Wikipedia page to your local hard drive, including all corresponding .css and .js files. Specific details depend on your browser. <!--how-to might be nice-->

* Open saved page in your editor, insert your script code either between <code>&lt;script>&lt;/script></code> tags or as a separate local file with <code>&lt;script src="file://C://you_local_path/name.js"&lt;/script></code>.

* Open saved page in your browser and preview the result.

This is a very traffic-wise way to quickly develop a user script. However, it has the following disadvantages:

* browser will not let you test Ajax queries from a local file

* you have to save different pages depending on what exactly page (history, etc.) is needed for testing

* you have to periodically re-save all .js files to synchronize with MediaWiki changes

* if you want to "casually" test the script while you're browsing Wikipedia, you still have to use other testing methods

=== Load from a localhost web server ===

The best and most recommended way is to load a JavaScript file from your local web server. (See below for an easy to install web server.) Put this string in your [[Special:Mypage/monobook.js|/monobook.js]]:

<source lang="javascript">

importScriptURI( 'http://localhost/wikipediatest.js' );

</source>

Then run any [[web server]] on your computer and create the <tt>wikipediatest.js</tt> file in the appropriate folder. The code inside this file will be executed as if it was inside your <tt>/monobook.js</tt>.

You can edit your <tt>wikipediatest.js</tt> file with any text editor, perhaps with syntax highlighting and other convenient features, then save the file and simply reload any Wikipedia page to see the results. (You don't need to wait, and if your web server is nice or you set it right you don't even need to [[Wikipedia:Bypass your cache|bypass your browser cache]].)

For example you could use [http://www.ritlabs.com/en/products/tinyweb/ TinyWeb] which is less than 100kbyte on disk and doesn't require installation. Save and unzip <tt>tinyweb.zip</tt> for example into <tt>c:\Program Files\Tinyweb</tt>, then create a shortcut to <tt>tiny.exe</tt>, in shortcut properties add an argument — path to your folder with <tt>wikipediatest.js</tt> and any file <tt>index.html</tt> (required). Start TinyWeb with this shortcut; unload it with Task Manager.

Note that this method doesn't work in latest [[Opera (web browser)|Opera]] browser due to added security restriction, see [http://www.opera.com/docs/changelogs/windows/950/ Opera 9.50 for Windows changelog]: "Local servers can use remote resources, but not vice versa".

=== Browser-specific ===

Some browsers allow you to automatically execute your javascript code on specific web pages. This way you don't even have to be logged in.

The most famous solution is [[Greasemonkey]] for Firefox browsers. Some alternatives for other browsers are listed at [[Greasemonkey#Greasemonkey compatibility and equivalents for other browsers]].

However, making userscript work with one of these extensions might require some modifications to the script code.

Some notes for [[Opera (web browser)|Opera]]:

* placing your script in a corresponding folder as <code><name>.user.js</code> file should work for many userscripts

* older versions of Opera (probably below 9.50) did not support [[UTF-8]] local scripts, meaning you could only use latin characters

=== Pieces of code ===

You can run pieces of code on already loaded pages, for example directly in the browser address field: <code>javascript: var s = document.title; alert(s); void 0</code>

Or you can use [[bookmarklet]] «JavaScript Shell». It opens new browser window where you can paste or type your code and run it in the context of the current page.

* [http://www.squarefree.com/shell/ JavaScript Shell for FireFox and Opera]

* [http://blog.monstuff.com/archives/000287.html JavaScript Shell for IE]

However a full-blown Javascript debugger is much more convenient.

=== Publishing your user script ===

Once you have finished the user script code you either need to paste it into your <tt>/monobook.js</tt> if it is only for personal use. Or if it is for use by others then you should upload it to for instance [[Special:Mypage/yourscript.js|User:Yourname/yourscript.js]]. Then other users can import it by putting this line in their <tt>/monobook.js</tt>.

<source lang="javascript">

importScript( 'User:Yourname/yourscript.css' );

</source>

== CSS files ==

Some user scripts also use some CSS code, or even are built with CSS only. Then you need to code and test CSS code. That can be done in your <tt>/monobook.css</tt>, but that is slow and messy.

Instead you can load a CSS file from your local web server. (See previous section for an easy to install web server.) Put this line at the very top of your [[Special:Mypage/monobook.css|/monobook.css]]:

<source lang="css">

@import "http://localhost/wikipediatest.css";

</source>

'''Note!''' Such <code>@import</code> statements must come before any other declarations in your <tt>/monobook.css</tt>. But there can be <code>/* comments */</code> above them.

An alternative way is to put this line anywhere in your <tt>/monobook.js</tt> instead:

<source lang="javascript">

importStylesheetURI( 'http://localhost/wikipediatest.css' );

</source>

=== Publishing a CSS file ===

Once you have finished the CSS code you either need to paste it into your <tt>/monobook.css</tt> if it is only for personal use. Or if it is for use by others then you should upload it to for instance [[Special:Mypage/yourscript.css|User:Yourname/yourscript.css]]. Then other users can import it by putting this line in their <tt>/monobook.js</tt>. Note, that is in their ".js", not their ".css".

<source lang="javascript">

importStylesheet( 'User:Yourname/yourscript.css' );

</source>

If the CSS should be used together with a user script written in JavaScript then you can make it easy for the users. Simply put the line above in the JavaScript code for your user script, then the users only need to "install" your JavaScript.

For completeness, in case someone wonders. Users can import your <tt>User:Yourname/yourscript.css</tt> from their <tt>/monobook.css</tt> too. This of course has the advantage that it works even if the user has JavaScript disabled. Although it takes this slightly complex line of code:

<source lang="css">

@import "/w/index.php?title=User:Yourname/yourscript.css&action=raw&ctype=text/css";

</source>

== Software ==

Any text editor will do. If you plan to use non-ascii characters in string, your text editor should support [[UTF-8]].

[[Notepad++]] is recommended, since it can:

* highlight Javascript code

* quickly insert standart Javascript keywords and methods with Ctrl-Enter

* show the list of all functions and quickly jump to any function

* [[Code folding]]

For debugging in [[Firefox]] you can use Tools → Javascript Console which shows all Javascript and CSS errors. [http://getfirebug.com/ FireBug] is strongly recommended for convenient debugging.

For debugging in IE see [http://blogs.msdn.com/ie/archive/2004/10/26/247912.aspx IEBlog: Scripting Debugging in Internet Explorer]

== DHTML methods ==

Line 211 ⟶ 322:

There is no crucial difference between toolbar and edittools, you can insert your own custom links into both.

== Editing and loading the user script ==

=== Previewing in /monobook.js ===

You can edit your script directly on your [[Special:MyPage/monobook.js|/monobook.js]] page, then click [Show preview] and the new code is executed right away on the preview page.

=== Saving in /monobook.js ===

If required elements are missing on the preview page (for example, your script does something on history pages), you will have to save the script in order to test it.

However it's not convenient and creates unnecessary load on the WikiMedia servers. Also, it seems like these days Wikimedia servers are configured not to give out the saved .js version right away, so you have to wait some minute after saving and then [[Wikipedia:Bypass your cache|bypassing your browser cache]].

=== Local HTML file ===

* Save Wikipedia page to your local hard drive, including all corresponding .css and .js files. Specific details depend on your browser. <!--how-to might be nice-->

* Open saved page in your editor, insert your script code either between <code>&lt;script>&lt;/script></code> tags or as a separate local file with <code>&lt;script src="file://C://you_local_path/name.js"&lt;/script></code>.

* Open saved page in your browser and preview the result.

This is a very traffic-wise way to quickly develop a user script. However, it has the following disadvantages:

* browser will not let you test Ajax queries from a local file

* you have to save different pages depending on what exactly page (history, etc.) is needed for testing

* you have to periodically re-save all .js files to synchronize with MediaWiki changes

* if you want to "casually" test the script while you're browsing Wikipedia, you still have to use other testing methods

=== Load from a localhost web server ===

The best and most recommended way is to load a JavaScript file from your local web server. (See below for an easy to install web server.) Put this string in your [[Special:Mypage/monobook.js|/monobook.js]]:

<source lang="javascript">

importScriptURI( 'http://localhost/wikipediatest.js' );

</source>

Then run any [[web server]] on your computer and create the <tt>wikipediatest.js</tt> file in the appropriate folder. The code inside this file will be executed as if it was inside your <tt>/monobook.js</tt>.

You can edit your <tt>wikipediatest.js</tt> file with any text editor, perhaps with syntax highlighting and other convenient features, then save the file and simply reload any Wikipedia page to see the results. (You don't need to wait, and if your web server is nice or you set it right you don't even need to [[Wikipedia:Bypass your cache|bypass your browser cache]].)

For example you could use [http://www.ritlabs.com/en/products/tinyweb/ TinyWeb] which is less than 100kbyte on disk and doesn't require installation. Save and unzip <tt>tinyweb.zip</tt> for example into <tt>c:\Program Files\Tinyweb</tt>, then create a shortcut to <tt>tiny.exe</tt>, in shortcut properties add an argument — path to your folder with <tt>wikipediatest.js</tt> and any file <tt>index.html</tt> (required). Start TinyWeb with this shortcut; unload it with Task Manager.

Note that this method doesn't work in latest [[Opera (web browser)|Opera]] browser due to added security restriction, see [http://www.opera.com/docs/changelogs/windows/950/ Opera 9.50 for Windows changelog]: "Local servers can use remote resources, but not vice versa".

=== Browser-specific ===

Some browsers allow you to automatically execute your javascript code on specific web pages. This way you don't even have to be logged in.

The most famous solution is [[Greasemonkey]] for Firefox browsers. Some alternatives for other browsers are listed at [[Greasemonkey#Greasemonkey compatibility and equivalents for other browsers]].

However, making userscript work with one of these extensions might require some modifications to the script code.

Some notes for [[Opera (web browser)|Opera]]:

* placing your script in a corresponding folder as <code><name>.user.js</code> file should work for many userscripts

* older versions of Opera (probably below 9.50) did not support [[UTF-8]] local scripts, meaning you could only use latin characters

=== Pieces of code ===

You can run pieces of code on already loaded pages, for example directly in the browser address field: <code>javascript: var s = document.title; alert(s); void 0</code>

Or you can use [[bookmarklet]] «JavaScript Shell». It opens new browser window where you can paste or type your code and run it in the context of the current page.

* [http://www.squarefree.com/shell/ JavaScript Shell for FireFox and Opera]

* [http://blog.monstuff.com/archives/000287.html JavaScript Shell for IE]

However a full-blown Javascript debugger is much more convenient.

=== Publishing your user script ===

Once you have finished the user script code you either need to paste it into your <tt>/monobook.js</tt> if it is only for personal use. Or if it is for use by others then you should upload it to for instance [[Special:Mypage/yourscript.js|User:Yourname/yourscript.js]]. Then other users can import it by putting this line in their <tt>/monobook.js</tt>.

<source lang="javascript">

importScript( 'User:Yourname/yourscript.css' );

</source>

== CSS files ==

Some user scripts also use some CSS code, or even are built with CSS only. Then you need to code and test CSS code. That can be done in your <tt>/monobook.css</tt>, but that is slow and messy.

Instead you can load a CSS file from your local web server. (See previous section for an easy to install web server.) Put this line at the very top of your [[Special:Mypage/monobook.css|/monobook.css]]:

<source lang="css">

@import "http://localhost/wikipediatest.css";

</source>

'''Note!''' Such <code>@import</code> statements must come before any other declarations in your <tt>/monobook.css</tt>. But there can be <code>/* comments */</code> above them.

An alternative way is to put this line anywhere in your <tt>/monobook.js</tt> instead:

<source lang="javascript">

importStylesheetURI( 'http://localhost/wikipediatest.css' );

</source>

=== Publishing a CSS file ===

Once you have finished the CSS code you either need to paste it into your <tt>/monobook.css</tt> if it is only for personal use. Or if it is for use by others then you should upload it to for instance [[Special:Mypage/yourscript.css|User:Yourname/yourscript.css]]. Then other users can import it by putting this line in their <tt>/monobook.js</tt>. Note, that is in their ".js", not their ".css".

<source lang="javascript">

importStylesheet( 'User:Yourname/yourscript.css' );

</source>

If the CSS should be used together with a user script written in JavaScript then you can make it easy for the users. Simply put the line above in the JavaScript code for your user script, then the users only need to "install" your JavaScript.

For completeness, in case someone wonders. Users can import your <tt>User:Yourname/yourscript.css</tt> from their <tt>/monobook.css</tt> too. This of course has the advantage that it works even if the user has JavaScript disabled. Although it takes this slightly complex line of code:

<source lang="css">

@import "/w/index.php?title=User:Yourname/yourscript.css&action=raw&ctype=text/css";

</source>

== Software ==

Any text editor will do. If you plan to use non-ascii characters in string, your text editor should support [[UTF-8]].

[[Notepad++]] is recommended, since it can:

* highlight Javascript code

* quickly insert standart Javascript keywords and methods with Ctrl-Enter

* show the list of all functions and quickly jump to any function

* [[Code folding]]

For debugging in [[Firefox]] you can use Tools → Javascript Console which shows all Javascript and CSS errors. [http://getfirebug.com/ FireBug] is strongly recommended for convenient debugging.

For debugging in IE see [http://blogs.msdn.com/ie/archive/2004/10/26/247912.aspx IEBlog: Scripting Debugging in Internet Explorer]