User:PerfektesChaos/js/autoBackup

Gadget to save intermediate temporary backups from edited wikitext.

Ever lost your valuable contribution by browser crash? Your subtle text, refined over an hour has gone since your mobile computer ran out of power? Network connection interrupted, or server down? Does your cat unplug your PC sometimes?

With autoBackup the wikitext you are currently editing will be saved to your hard disk on regular occasions, ways to retrieve the text after unexpected incidents are provided.

Usage

• Include the following lines into your common.js or skin dependant like vector.js:

mw.loader.load("//en.wiki.x.io/w/index.php?title=User:PerfektesChaos/js/autoBackup/r.js&bcache=1&maxage=86400&action=raw&ctype=text/javascript",
               "text/javascript");

• The gadget works also with non-WMF sites using MediaWiki 1.18 or higher.

Customization

If you hit qouta limitations or have a special working style, you might adapt control parameters.

Insert the following statement into your standard user script like common.js (best before mw.loader.load, if any):

if ( typeof mw.libs.autoBackup !== "object" ) {
   mw.libs.autoBackup  =  {  opt: { }  };
}
mw.libs.autoBackup.opt.key1  =  value1;
mw.libs.autoBackup.opt.key2  =  value2;

Key	Default	Meaning
.opt.maxAge	72	number of full hours to remember at least 1 hour.
.opt.maxHist	5	number of history entries per revision to keep at least 1, but 2 or some more are recommended.
.opt.maxPages	10	number of pages to handle simultaneously at least 1 page required.
.opt.maxRev	3	number of revisions to keep at least 1, but 2 or some more are recommended.
.opt.mid	5	number of minutes for scheduled snapshots 0 or false switch off time triggering.
.opt.portlet	no	Create portlet link; any non-empty value
.folder()	(API)	List links to all page ids in storage
.fresh()	(API)	Trigger snapshot

Example:

if ( typeof mw.libs.autoBackup !== "object" ) {
   mw.libs.autoBackup  =  { };
}
mw.libs.autoBackup.mid  =  false;

Note: Customization may be ignored if not put into a standard user script, since other scripts are loaded later and autoBackup has no knowledge about, won’t wait for them.

Memorize: localStorage and sessionStorage

The localStorage facility (also known as “super cookie”) has been introduced a couple of years ago and should be available in most contemporary browsers. It is used to store the data. While its sibling sessionStorage is hold for one browser session only, localStorage is persistent.

The size of localStorage is limited. You should not expect more than 5 MB per domain or entry. Depending on the average size of pages or sections, kept revisions and multitasking edits you might hit the limit. By adaption of the numbers above to your working style it should be sufficient. Some browser offer customization of quota per domain; Firefox: dom.storage.default_quota – Opera: “Domain Quota For localStorage”.

Note that localStorage is intended as rescue in case of lost edits, not as regular way to store texts. The place where localStorage is located on your hard disk could be figured out, but these may be proprietary data bases not meant for periodical backup versions as separate files.

While a large localStorage is keeping content between browser sessions, a small sessionStorage is used as accelerator. Page identifiers of pages with pending snapshots are kept during one session and can give a quick response when opening any page whether a backup is in the queue. That one is redundant and discarded as soon as a session is terminated.

Some users disable free usage of localStorage for privacy and security reasons. However, there are whitelists for configuration which should permit your Wiki domain to utilize this feature.

Procedures

Every time a Wiki page is in any edit mode, snapshots will be taken and stored permanently. This can be triggered by:

• clicking the “Show preview” button, if caught
• clicking the “Show changes” button, if caught
• Summary field gets focus, if caught
• clicking the “Save page” button, if caught (the wikiserver may be down; network failure on the very last occasion)
• preview or diff page built
• periodical time schedule
• API call.

Subsequent snapshots with identical content won’t be stored again, trailing whitespace will be ignored.

No difference is made between single section edits and full page edit.

Retrieval

The easiest way is to visit a page with aborted edit after re-establishing the system. You will be informed and get a notification on top of page with a button.

If you click that * button you get a selection of stored snapshots for this page. There might be multiple revisions being caught. For each revision there are several snapshots expected in history. In case of crash you will choose the most recent one. However, an earlier one could be accessed as well. If you happened to delete an important unsaved piece of text from your edit that might serve as rollback function over unsaved page versions.

The snapshots are presented as non-editable textareas. You can inspect the content and select the text in common copy & paste manner. It is recommended to open the same page for editing again in a different browser window or tab, since that will influence the available localStorage structure.

If anybody else edited the referred page while you or your computer has been down, you will need to resolve the edit conflict carefully and merge your text into the existing version.

Do not rely on existence of a backup copy under all conditions.

Cleanup

Every time you join a page with pending snapshots the server is contacted whether it has been saved successfully. If you are recognized as the author of a later version of this page, the page is removed from snapshot history automatically. This ensures that in regular edit process after successful saving the snapshots are discarded. Edits by other users do not count.

You may delete superfluous revisions manually by clicking the X button of each revision if you join an active history.

Since floating the limited localStorage with many large intermediate versions will inhibit saving current texts, oldest and supernumerous revisions are removed by the algorithm. After three days it is expected that your contribution may be obsoleted; you should have managed to recover your system and connection meanwhile.

Pending

If there are recent shapshots for any reason and you visit that page in view mode, you will be informed near to the page haedline.

You mave have deliberately aborted an edit; this leads to the same situation like a system crash.

Manual inspection

If you want to get a survey over current snapshot collection, just open a page view of the same page in another tab while editing. Since there is a pending (unsaved) edit present, that page will notify you. You can inspect the intermediate versions and revisions (oldid), and also open some other pages with pending backups in other browser windows, identified by curid numbers.

Data structure

After some edits the following structure might result:

• curid=2007 Page A
  • Version oldid=100009
    1. snapshot-2
    2. snapshot-1
  • Version oldid=100003
    1. snapshot-26
    2. snapshot-25
    3. snapshot-24
    4. snapshot-23
    5. snapshot-22
• curid=3456 Page B
  • Version oldid=100001
    1. snapshot-8
    2. snapshot-7
    3. snapshot-6
    4. snapshot-5
    5. snapshot-4

The number of snapshots is limited to the 5 most recent ones.

Errors

If snapshot saving failed, you will be alerted on page. If localStorage is not permitted, you might change browser configuration. If running out of quota, manual cleanup should solve the problem. Perhaps yesterday you aborted an edit of a large page after various changes and previews.

Multiple users and projects

One localStorage entry is used per wiki project. If you are using multiple accounts within the same browser profile they are not distinguished.

It is assumed that you are the only person using this browser profile, therefore no privacy problems are expected. If you share a browser profile, many other information will be disclosed. Wikitext edits on a public wiki are supposed to become visible all over the world.

There is one localStorage quota for all applications within the domain and browser profile. If you are using other tools that utilize localStorage this might influence the available space.

Browser windows and tabs

If you close a browser window by accident, they are usually only hidden and still available with all volatile data as long as other windows or tabs are still alive. Modern browsers offer a way to re-open the recently closed windows so that you can continue directly.

Even earlier stages might be recovered cautiously; copy and paste your text into some external notepad first.

Pros and Cons

• Every script you load on page building might slow down your work process. Exchange of large text snapshots could need a moment.
• If you rely too much on automatic recovery you might become careless.
• My system never crashes, and wiki servers are always available and connected to me.
• If you make large scale edits, avoiding many entries in version history, your work of the recent hour could be lost by bad fate.

Compatibility

The script is harmonized with

• LivePreview
• WikEd

techniques.

Most current browsers support localStorage.

Code

Source code	Java Script – for load() human readable version
ResourceLoader	ext.gadget.autoBackup for mw:Extension:Gadgets Dependencies: user, mediawiki.api, mediawiki.user, mediawiki.util
Namespaces	any
mw.libs	autoBackup

Other languages

This gadget is prepared for multilingual support.

• If you like a version in your own language, please forward translations to me:
  • This documentation page.
  • The .cnf.text mapping on top of source code.
  • Further ISO 639 language codes your translation might support.

[ German page ]