User:PerfektesChaos/js/loadResourceFile

JavaScript gadget – load local files into wiki page interactively, like CSS or JavaScript resources.

This avoids to load too many scripts always into every wiki page. If really needed, a particular tool can be used once in a while on particular pages.

Local resource files have some more advantages against user pages on wiki:
 * They might be modified on the fly, without saving new page revisions first.
 * This keeps version history slim, especially when developing new tools.
 * Spontaneous minor adjustments to current needs are possible, e.g. for debugging.
 * They might contain information which should not be visible to other users, even not world wide.

Functionality
A link within tool box of wiki page is offered. Furthermore there are different calls to base functions available (API).

The tool link gives access to interactive selection of one or more resource files within a pre-selected path, which will be appplied to the current wiki page.

The file name extensions  (CSS) and   (JavaScript) may be used (in capital letters, too).

It must be allowed to use local files from a web based document.
 * Some browsers could block this for security reasons.
 * NoScript has such a preference.
 * Enable: [Options] → [Advanced] → [permit links on local files].

It is necessary to declare the path externally.
 * The structure of the path segments tells about private details: user name in local network, operating system, local network, data organisation.
 * An HTML document should never know the full path of any local file.
 * For every single wiki project a path is to be defined. Different paths may be used, or alwas the same directory.

Usage
Insert these lines into personal common.js: This makes all functions available, including a link within tool box.

Base directory
It is assumed that all script files and CSS styles assigned for use within wiki pages are concentrated within one directory.

They need to exist within this folder.
 * On ux file systems, symlinks should work; this gives access to files on other locations.
 * With Windows a link file  doesn’t work.

The path in effect may be declared by various means: After definition the path is shown within tooltip over tool link.
 * Special:Gadgets with saving as personal user preference on wiki server.
 * This gives the same assignment to  as follows.
 * The script library must have been loaded first, as shown in Usage section.
 * By execution of JavaScript code (might be in effect until page reloading only, if a different path has been declared also)
 * in a context assigned to this project
 * via browser console utility belonging to the current wiki project
 * by showing the preview of the own common.js without saving
 * using a bookmarklet
 * of one of the following two statements
 * path
 * (only if script library has been loaded previously)
 * path
 * (can be used independently but needs wiki project context)
 * By application object; might be within greasemonkey etc., hiding from other users and www public.
 * path

A slash after base folder is possible but not required. The kind of slash (\) does not matter.

The starting point of interactive file selection menu cannot be influenced.

Character encoding
It is recommended to store all resource files in UTF-8 encoding.
 * Many resource files will contain ASCII characters only; those cause no problems.
 * On Windows the notepad editor permits a file to be saved as  rather than   format.
 * Typical identifiers are:
 * (n/a) –
 * – Western Europe (ANSI), alias

There are facilities offered to use all resource files or all subsequent files for this page or just the current file in deviating encoding.

User configuration
The initial environment and the behaviour can be equipped by each user individually.

Quick interactive costumization
Base directory and default character encoding can be set interactively on Special:Gadgets as soon as the script library has been loaded.

The portlet link can be switched on and off only.

When reloading a page the preferences declared here come into effect. This dynamic assignment overrides the static setting by application object.

These user preferences are not visible to other users.

Configuration by JavaScript
Insert the following lines into common.js etc. (best before mw.loader.load): See API for more information.

Application object and API
Before script loading an application object may be declared as follows, e.g. within personal common.js page: Subsequently assignments can be made according to the following table. Static assignments of values are to be made before script library was called. Later the functions are to be used for changing the current setting.

After loading the API functions may be used always, whether the application object has been declared by user or not.

Example:

Future
The current implementation may be used with any browser during recent 15 years.

Modern browsers permit a “blob” access. There file names are not disclosed, but file content only, which would enable navigation into arbitrary folders.

However, it is supposed that in a tidy household all files for working on wiki are collected in one directory. So, there is no reason for another approach now, executing file content actively.

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

Codes
de:User:PerfektesChaos/js/loadResourceFile