User:PerfektesChaos/js/localEdit

Combined tool to enable editing of local files (on hard disk) in a particular Wiki project environment.

A wiki text which shall not be visible in the early development stage is to be produced, disclosed after terminating the edit process.

• The text will be refined for your eyes only.
  • Initial versions are to be stored on hard disk (or similar) only, not as wiki user page.
  • This goes also for major revisons of existing texts.
• The preview shall provide the same functionality as if it would be a regular web page in Wiki: Templates and images are to be displayed correctly, and links could be followed or might be redlinks if target not yet existing.
• The edit interface should be identical to the normal environment. If the user is familiar with any edit tool for wiki syntax or other gadgets this has to be available.
• The files are to be managed by the regular file system of the local machine, e. g. Unicode files as plain .TXT, and may be copied or edited externally by other tools.

Basically this is possible with sandbox and a lot of c&p, but that is error-prone. This is not a recommended working style and takes the risk of text losses. It might be done once for one text, but not for subsequent text creation.

Security issues

Any activity which enables contact between the wiki web page and the local file system is opening a possible security leak.

• Usage is on your own risk.
• The combination of wiki side script and browser add-on does as much as possible to minimize the vulnerability.

Security concept

The software is split into

1. a regular user script, which is embedded into the HTML page of the Wiki, without any access outside the browser frame and on the PC,
2. a browser-specific extension (“add-on”), which has similar capabilities like other programs, at least with access to the local file system.

An effective separation is needed between these two components. The web page in the Wiki world must not be able to control the browser extension by other means than explicitly permitted.

This is achieved by the following provisions:

• The internet page has no access to the add-on at all.
• The wiki page can only inform about events (“a button has been pressed”) and broadcast the events blindly, no clue whether anybody and who is listening for such messages.
• The JavaScript information (“global objects”) have no contact at all. There are no functions called from the other side, and no data will be read.
• On information transfer some plain text strings are submitted, but never executed. They contain some keywords for activity properties.
• The browser extension, which is “privileged”, writes only text strings into Wiki document, and is occasionally broadcasting some events.
• For any event which is caught by the browser extension it is checked first, whether the URL of the sending page matches the expectations. Only if this is a special user page and that has been registered, the event will be treated and local files may be released.

That is also recommended by developer.mozilla.org.

• Only files in a directory enabled for this purpose or sub-directories may be read (or written) without interaction by user. File and path names are not accepted from the web site; they are to be selected interactively by the user. Such information is not stored on the web.

Installation

• The following lines need to be inserted into the personal common.js:

mw.loader.load("//en.wikipedia.org/w/index.php?title=User:PerfektesChaos/js/localEdit/r.js&action=raw&bcache=1&maxage=604800&ctype=text/javascript",
               "text/javascript");

This provides the web side script. It fits to all browsers.

Next, the extension for the browser is to be installed.

• Firefox (gecko)
• No other browser/engine is known to give access to local files.
  • Google Chrome does not deal with the local file system yet.

Configuration

visible

In the common.js the following adaptations (world wide visible) are possible, if ever required:

• .opt.scan
  Selection pattern for text files
  • Standard: *.txt; *.text; *.wiki
• .opt.suffix
  Extension for file name completion, if not provided for new files.
  • Standard: txt

Before mw.loader.load the following lines may be written and the desired options take effect, like e.g.:

if ( typeof mw.libs.localEdit !== "object" ) {
   mw.libs.localEdit  =  {  opt: { }  };
}
mw.libs.autoBackup.opt.scan    =  "*.txt; *.wikitex";
mw.libs.autoBackup.opt.suffix  =  "wikitex";

Add-On

In the configuration dialog after installation there are three settings possible. The first one is necessary.

1. URL of the own user page
   • By copy&paste the entire URL is to be taken from the address field of the browser. Special characters are encoded differently and displayed prettier than really present in URL.
   • Also the protocol (https or http) is required. If both shall be used, there are both URL to be registered. It is recommended to work only with secure server from now.
   • Any number of URL might be provided.
   • Out of the specific pages derived from these user pages the access to local files will be denied.
2. The add-on might be activated when the browser is started.
   • That is the default after installation to make the first steps easier. Later, after learning how it works, and when the gadget is not used permanently, this option should be turned off. The local file mode shall be started explicitly and only if really needed.
3. The base directory for all files may be selected now.
   • That could be done at a later stage on every occasion.

Usage

For text production open your user sub-page /LocalEdit.

• This page does not need to exist. Even better, this page should never be created.
• The page may contain arbitrary text; that will be ignored.

When the page /LocalEdit is displayed with activated script, it shows a table with current state information.

• It is shown, whether the current browser is applicable; if yes, whether the add-on has been switched on.

If the add-on was not activated before, this may be done now. Reload the page then.

With activated add-on a base directory for text files may be chosen.

• Additionally a sub directory specific to the current Wiki project (and user account) can be defined.
  The sub directory is designed to work simultaneously in multiple languages and project types while structuring the activities. In the same way there might be a different sub directory for every user account, if you have a multiple personality or several authors use the same PC.

The visible parameters for file selection are reflected.

Below there is a link to edit mode.

Edit mode

In edit mode a normal text area with all gadgets and options is available. However, from the accustomed buttons only Show preview is present. Since the page is not located on the server, it cannot be compared, nor is the page supposed to be stored.

Instead, there are the usual buttons as expected within an editor:

• Open file
• Save file
• Save file as

and an option “ANSI” for open; see character sets.

• With Open file an existing file can be selected; a name for a file which is not existing yet may be chosen as well.
• However, text for a not yet existing file may be typed into text area right now, applying a file name when saving later.
• If a file name was defined, it is possible to save this file.
  The current value is displayed below the page headline.
• With Save file as a new name may be determined. This is used for the next save until change.
• In the further process Open file is possible only if the content of the text area has been saved or emptied.

Sequence

The work flow of add-on activation and page loading should be straight forward. By the “back” button of the browser, bookmarking etc. some parameters might left unset. This won’t cause data losses, but leads to blocked buttons or wrong file names. By reloading pages this can be overcome and and made good for initialization.

If not needed

If you do not need local editing any longer, you may switch off the add-on by simply clicking on the icon button in browser toolbar. Immediately the add-on will not listen to any event nor performing any other action than wake-up call by another click.

If you won’t need the add-on for a longer period you may deactivate it temporarily in browser settings.

Character sets

By default files are always read and written in UTF-8. That is the encoding which is used on the wiki servers and expected in text area in all text browsers. It allows arbitrary characters and compact saving.

If an existing file which has been coded in (western) 8 bit code (ANSI) shall be introduced you have the opportunity to check exceptionally the box near Open file button. Otherwise your text might be terminated at the first occurrence of “ä”. If your text is plain English (ASCII) it will work anyway. That file is written in UTF-8 when saved.

Intermediate external editing

If the text shall be manipulated out of the browser, the file might need code conversion by appropriate import (and export).

• Microsoft Windows notepad can do so at “Save as”.
• With Linux/Unix there is an innumerable variety of conversion tools.
• Emacs might convert automatically; especially when for the period of development the following comment is placed at the end of text:

<-- Local Variables:
    coding: mule-utf-8-unix
    End:
    -->

Compatibility

The script is respecting the techniques of:

• LivePreview
• WikEd

Codes

Source code	Java Script – for load() human readable version
ResourceLoader	user:PerfektesChaos/localEdit for mw:Extension:Gadgets Dependencies: none on inclusion
Namespaces	2
mw.libs	localEdit

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 .lang.texts mapping on top of source code.
  • Further ISO 639 language codes your translation might support.

[ German page ]

---

This page has been developed locally using the described tool.