From 44537de0c46c3bd738f9c0d3711a562c7cc5e1ae Mon Sep 17 00:00:00 2001 From: Miciah Dashiel Butler Masters Date: Tue, 14 Nov 2006 16:13:11 +0000 Subject: [PATCH] SMJS (user): Add documentation on the available interfaces Note that the interfaces may change at any time (which is the reason that I've put off committing this file for so long). --- contrib/smjs/README | 248 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 contrib/smjs/README diff --git a/contrib/smjs/README b/contrib/smjs/README new file mode 100644 index 00000000..16c1a00b --- /dev/null +++ b/contrib/smjs/README @@ -0,0 +1,248 @@ +Methods +------- + +do_file(path) + + Load and evaluate the file with the given path (string). For example: + + do_file("/home/me/.elinks/hooks.js"); + + will reload your hooks file. + + +elinks.alert(message) + + Display the given message (string) in a message box. For example: + + elinks.alert("Hello, world!"); + + will display a friendly greeting. + + +elinks.execute(command) + + Execute the given command (string) on the current terminal. For example: + + var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'"; + elinks.execute("firefox " + quoted_uri); + + will run Firefox with the URI of the current document. + + Note: one must be very careful with elinks.execute, because depending + on the OS, the command may be subject to interpretation by a command shell + language. When constructing the command string, be sure to quote any + dubious parts (such as the URI of the current document, as above). + + +elinks.load_uri(uri, callback) + + Load the given URI (string). When the URI completes loading, ELinks calls + the given callback (function). The callback is passed the cache object + that corresponds to the URI. For example: + + elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes", + function (cached) { elinks.alert(cached.content); }); + + displays a fortune. + + +Properties +---------- + +elinks.home (string) + + ELinks's 'home' directory, where it stores its configuration files. + Read-only. For example, + + do_file(elinks.home + "hooks.js"); + + will reload your hooks file. + + +elinks.location (string) + + The URI of the currently open document. This can be read to get a string + with the URI or set to load a different document. For example, + + elinks.location = elinks.location + "/.."; + + will go up a directory (if the URI doesn't end in a file). + + +elinks.bookmarks (hash) + + This is a hash, the elements of which correspond to the bookmarks. + One can delve into the bookmarks hierarchy in a reasonably nifty + fashion, just by using standard ECMAScript syntax: + + elinks.bookmarks.x.children.y.children.z.children.foo.title + + gets the title of the bookmark titled 'foo' under the folder 'z', + which is a subfolder of 'y', which is a subfolder of 'x'. + + A bookmark object has these properties: + + item.title (string) + + This is the title of the bookmark. It can be read and set. + + item.url (string) + + This is the URI of the bookmark. It can be read and set. + + item.children (hash) + + This is a hash, the elements of which are the bookmarks that + are children to the item. It is read-only. + + +elinks.globhist (hash) + + This is a hash, the elements of which correspond to entries in ELinks's + global history. The hash is indexed by URI. For example, + + elinks.globhist["file:///"] + + will get you the history item for your root directory. + + A history item has these properties: + + item.title (string) + + This is the title of the history item. It can be read and set. + + item.url (string) + + This is the URI of the history item. It can be read and set. + + item.last_visit (number) + + This is the UNIX time of the last visit time for the item. UNIX time + is the number of seconds that have passed between the UNIX epoch (which + is 1970-01-01 00:00:00 UTC) and the represented time. Note that this is + _seconds_ since the epoch, whereas ECMAScript likes to use _milliseconds_ + since the epoch. This property can be set or read. + + +elinks.keybinding (hash) + + This is a hash, the elements of which correspond to ELinks's keymaps. + Currently, there are three: elinks.keybinding.main, elinks.keybinding.edit, + and elinks.keybinding.menu. These elements are also hashes, the elements of + which correspond to bindings. For example, elinks.keymaps.main["q"] is + the binding to the 'q' key in the main map. These bindings can be red, + to get the name of the action to which the key is bound, or set, either + to a string with the name of the ELinks action or to a function, which will + thenceforth be called when the key is pressed. For example, + + elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); } + + binds the '!' key in the main map to a function that displays a friendly + alert. + + elinks.keymaps.main["/"] = "search-typeahead-text"; + + changes the '/' key to use the nice typeahead search function instead of + opening that ugly old search dialogue box. + + +Hooks +----- + +These are actually properties, but a special case: one assigns functions +to them, which functions are called at certain events. + +Note that the default hooks file assigns functions that provide a mechanism +to register multiple functions to each hook. When these default hooks are +called, they iterate over all functions that are registered to them, calling +each one in serial. + +If you want to register a preformat_html hook, for example, +the preferred way to do so is not this: + + elinks.preformat_html = foo; + +but rather this: + + elinks.preformat_html_hooks.push(foo); + +which adds foo to an array of functions, over which the default +elinks.preformat_html function will iterate. + +If any function in that array returns false, the default hook +will stop iteration, not calling any more handlers. This applies +to all of the default hooks. + + +elinks.preformat_html(cached, vs) + + This function is called every time a document is loaded, before the document + is actually rendered, to give scripts the opportunity to modify it. The + first parameter is the cache object and the second is the view_state object + (documented below). As explained above, it is preferred to add your hook + to elinks.preformat_html_hooks rather than to assign it to + elinks.preformat_html. + + +elinks.goto_url_hook(url) + + This function is called every time the user enters something + in the Go to URL box. The url (string) can be modified or not, + and the returned string is substituted for what the user entered. + If the value false is returned, the URL is not changed and further hooks + in ELinks are not run. As explained above, it is preferred to add your hook + to elinks.goto_url_hooks rather than to assign it to elinks.goto_url_hook. + + +elinks.follow_url_hook(url) + + This function is called every time the user tries to load a document, + whether by following a link, by entering a URI in the Go to URL box, + by setting elinks.location, or whatever. It behaves the same as + elinks.goto_url_hook above. As explained above, it is preferred to add your + hook to elinks.follow_url_hooks rather than to assign it to + elinks.follow_url_hook. + +Other Objects +------------- + +cache + + The cache object mentioned in the descriptions of elinks.load_uri and + elinks.preformat_html is a wrapper for the internal ELinks cache object. + Its properties are: + + cached.content (string) + + This is the content received from the server. It can be read and set. + + cached.type (string) + + This is the MIME type of the cache entry. It can be read and set. + + cached.length (number) + + This is the length of cached.content. It is read-only. + + cached.head (string) + + This is the header received from the server. It can be read and set. + + cached.uri (string) + + This is the URI of the cache entry. It is read-only. + +view_state + + The view_state object mentioned in the description of elinks.preformat_html + is a wrapper for the internal ELinks view_state object. The view state holds + information on how the current document is being displayed. + + vs.plain (boolean) + + Whether the current document is rendered as HTML or displayed + as plaintext. This can be read and set. + + vs.uri (string) + + This is the URI of the current document. It is read-only.