contrib/smjs/README

   1 Methods
   2 -------
   3
   4 do_file(path)
   5
   6    Load and evaluate the file with the given path (string). For example:
   7
   8       do_file("/home/me/.elinks/hooks.js");
   9
  10    will reload your hooks file.
  11
  12
  13 elinks.alert(message)
  14
  15    Display the given message (string) in a message box. For example:
  16
  17       elinks.alert("Hello, world!");
  18
  19    will display a friendly greeting.
  20
  21
  22 elinks.execute(command)
  23
  24    Execute the given command (string) on the current terminal. For example:
  25
  26       var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'";
  27       elinks.execute("firefox " + quoted_uri);
  28
  29    will run Firefox with the URI of the current document.
  30
  31    Note: one must be very careful with elinks.execute, because depending
  32    on the OS, the command may be subject to interpretation by a command shell
  33    language. When constructing the command string, be sure to quote any
  34    dubious parts (such as the URI of the current document, as above).
  35
  36
  37 elinks.load_uri(uri, callback)
  38
  39    Load the given URI (string). When the URI completes loading, ELinks calls
  40    the given callback (function). The callback is passed the cache object
  41    that corresponds to the URI. For example:
  42
  43      elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes",
  44                      function (cached) { elinks.alert(cached.content); });
  45
  46    displays a fortune.
  47
  48
  49 Properties
  50 ----------
  51
  52 elinks.home (string)
  53
  54    ELinks's 'home' directory, where it stores its configuration files.
  55    Read-only. For example,
  56
  57       do_file(elinks.home + "hooks.js");
  58
  59    will reload your hooks file.
  60
  61
  62 elinks.location (string)
  63
  64    The URI of the currently open document. This can be read to get a string
  65    with the URI or set to load a different document. For example,
  66
  67       elinks.location = elinks.location + "/..";
  68
  69    will go up a directory (if the URI doesn't end in a file).
  70
  71
  72 elinks.bookmarks (hash)
  73
  74    This is a hash, the elements of which correspond to the bookmarks.
  75    One can delve into the bookmarks hierarchy in a reasonably nifty
  76    fashion, just by using standard ECMAScript syntax:
  77
  78       elinks.bookmarks.x.children.y.children.z.children.foo.title
  79
  80    gets the title of the bookmark titled 'foo' under the folder 'z',
  81    which is a subfolder of 'y', which is a subfolder of 'x'.
  82
  83    A bookmark object has these properties:
  84
  85    item.title (string)
  86
  87       This is the title of the bookmark. It can be read and set.
  88
  89    item.url (string)
  90
  91       This is the URI of the bookmark. It can be read and set.
  92
  93    item.children (hash)
  94
  95       This is a hash, the elements of which are the bookmarks that
  96       are children to the item. It is read-only.
  97
  98
  99 elinks.globhist (hash)
 100
 101    This is a hash, the elements of which correspond to entries in ELinks's
 102    global history. The hash is indexed by URI. For example,
 103
 104       elinks.globhist["file:///"]
 105
 106    will get you the history item for your root directory.
 107
 108    A history item has these properties:
 109
 110    item.title (string)
 111
 112       This is the title of the history item. It can be read and set.
 113
 114    item.url (string)
 115
 116       This is the URI of the history item. It can be read and set.
 117
 118    item.last_visit (number)
 119
 120       This is the UNIX time of the last visit time for the item. UNIX time
 121       is the number of seconds that have passed between the UNIX epoch (which
 122       is 1970-01-01 00:00:00 UTC) and the represented time. Note that this is
 123       _seconds_ since the epoch, whereas ECMAScript likes to use _milliseconds_
 124       since the epoch. This property can be set or read.
 125
 126
 127 elinks.keybinding (hash)
 128
 129    This is a hash, the elements of which correspond to ELinks's keymaps.
 130    Currently, there are three: elinks.keybinding.main, elinks.keybinding.edit,
 131    and elinks.keybinding.menu. These elements are also hashes, the elements of
 132    which correspond to bindings. For example, elinks.keymaps.main["q"] is
 133    the binding to the 'q' key in the main map. These bindings can be red,
 134    to get the name of the action to which the key is bound, or set, either
 135    to a string with the name of the ELinks action or to a function, which will
 136    thenceforth be called when the key is pressed. For example,
 137
 138       elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); }
 139
 140    binds the '!' key in the main map to a function that displays a friendly
 141    alert.
 142
 143       elinks.keymaps.main["/"] = "search-typeahead-text";
 144
 145    changes the '/' key to use the nice typeahead search function instead of
 146    opening that ugly old search dialogue box.
 147
 148
 149 Hooks
 150 -----
 151
 152 These are actually properties, but a special case: one assigns functions
 153 to them, which functions are called at certain events.
 154
 155 Note that the default hooks file assigns functions that provide a mechanism
 156 to register multiple functions to each hook. When these default hooks are
 157 called, they iterate over all functions that are registered to them, calling
 158 each one in serial.
 159
 160 If you want to register a preformat_html hook, for example,
 161 the preferred way to do so is not this:
 162
 163    elinks.preformat_html = foo;
 164
 165 but rather this:
 166
 167    elinks.preformat_html_hooks.push(foo);
 168
 169 which adds foo to an array of functions, over which the default
 170 elinks.preformat_html function will iterate.
 171
 172 If any function in that array returns false, the default hook
 173 will stop iteration, not calling any more handlers. This applies
 174 to all of the default hooks.
 175
 176
 177 elinks.preformat_html(cached, vs)
 178
 179    This function is called every time a document is loaded, before the document
 180    is actually rendered, to give scripts the opportunity to modify it. The
 181    first parameter is the cache object and the second is the view_state object
 182    (documented below). As explained above, it is preferred to add your hook
 183    to elinks.preformat_html_hooks rather than to assign it to
 184    elinks.preformat_html.
 185
 186
 187 elinks.goto_url_hook(url)
 188
 189    This function is called every time the user enters something
 190    in the Go to URL box. The url (string) can be modified or not,
 191    and the returned string is substituted for what the user entered.
 192    If the value false is returned, the URL is not changed and further hooks
 193    in ELinks are not run. As explained above, it is preferred to add your hook
 194    to elinks.goto_url_hooks rather than to assign it to elinks.goto_url_hook.
 195
 196
 197 elinks.follow_url_hook(url)
 198
 199    This function is called every time the user tries to load a document,
 200    whether by following a link, by entering a URI in the Go to URL box,
 201    by setting elinks.location, or whatever. It behaves the same as
 202    elinks.goto_url_hook above. As explained above, it is preferred to add your
 203    hook to elinks.follow_url_hooks rather than to assign it to
 204    elinks.follow_url_hook.
 205
 206 Other Objects
 207 -------------
 208
 209 cache
 210
 211   The cache object mentioned in the descriptions of elinks.load_uri and
 212   elinks.preformat_html is a wrapper for the internal ELinks cache object.
 213   Its properties are:
 214
 215   cached.content (string)
 216
 217      This is the content received from the server. It can be read and set.
 218
 219   cached.type (string)
 220
 221      This is the MIME type of the cache entry. It can be read and set.
 222
 223   cached.length (number)
 224
 225      This is the length of cached.content. It is read-only.
 226
 227   cached.head (string)
 228
 229      This is the header received from the server. It can be read and set.
 230
 231   cached.uri (string)
 232
 233      This is the URI of the cache entry. It is read-only.
 234
 235 view_state
 236
 237    The view_state object mentioned in the description of elinks.preformat_html
 238    is a wrapper for the internal ELinks view_state object. The view state holds
 239    information on how the current document is being displayed.
 240
 241    vs.plain (boolean)
 242
 243       Whether the current document is rendered as HTML or displayed
 244       as plaintext. This can be read and set.
 245
 246    vs.uri (string)
 247
 248       This is the URI of the current document. It is read-only.