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 (CSS) and .js (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:

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

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 .lnk doesn’t work.

The path in effect may be declared by various means:

Special:Gadgets with saving as personal user preference on wiki server.
- This gives the same assignment to localStorage 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
  - mw.libs.loadResourceFile.setFolder( path )
    (only if script library has been loaded previously)
  - localStorage.setItem( "loadResourceFile.path", 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.
- mw.libs.loadResourceFile.store=path;

After definition the path is shown within tooltip over tool link.

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 UTF-8 rather than ANSI format.
Typical identifiers are:
- (n/a) – UTF-8
- ISO-8859-1 – Western Europe (ANSI), alias latin1
- UTF-8

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):

if ( typeof mw.libs.loadResourceFile !== "object" ) {
   mw.libs.loadResourceFile  =  { };
}
mw.libs.loadResourceFile.key1 = value1;

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:

if ( ! mw.libs.loadResourceFile ) {
   mw.libs.loadResourceFile  =  { };
}

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.

Key	Value
"ARMADURA Z29 HELMET ARMOR Z29" by OSCAR CREATIVO Presettings		Meaning
`portlet`	boolean object	`true` – Show link in tool box (default) `false` – Do not show any link Object – Show link in modified shape; see mw.util.addPortletLink()
`portlet.scope`	"`p-tb`"	ID of container
`portlet.show`	"`Load CSS/JS file`"	Link title
`portlet.shortcut`		Keyboard code
`portlet.stick`	null	ID of container element to place ahead
`set`	"`UTF-8`"	Different default for encoding.
`store`		Default for base directory
API		The functions yield no return value.
`find(access)`		Start an interactive file selection including resource loading into document (using current encoding). `access` – optional string, with particular base directory
`folder(access)`		Set temporary default for base directory, and retrieve current path. `access` – string, with base directory n/a or `false` – retrieve current value `""` – empty string: reset to default Path – set temporary path
`loadFiles(apply,access,accept)`		Load one or more resource files. `apply` – string with file name, or Array with file names (each without path) `access` – optional string, with base directory `accept` – optional string, with encoding
`setCharset(accept)`		Set default for character encoding. `accept` – string, with encoding; or `false` for returning to standard

Example:

if ( typeof mw.libs.loadResourceFile !== "object" ) {
   mw.libs.loadResourceFile  =  { };
}
mw.libs.loadResourceFile.portlet = false;

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

Codes

Source code	JavaScript – for load() human readable version
ResourceLoader	`ext.gadget.loadResourceFile` for mw:Extension:Gadgets Dependencies: `user`, `user.options`, `mediawiki.user`, `mediawiki.util`
Namespaces	all
Cookies	`loadResourceFile.path` (localStorage)
`mw.libs`	`loadResourceFile`