doc/smjs-scripting.txt

   1 [[smjs-scripting]]
   2 Scripting ELinks with ECMAScript
   3 --------------------------------
   4
   5 As a user of ELinks, you can control its behaviour by writing scripts
   6 in ECMAScript.  Unlike <<ecmascript,scripts in SCRIPT elements of
   7 HTML>>, these user scripts run with all the permissions of your user
   8 account, the same as with <<lua-scripting,Lua>>.  The object model is
   9 very different too.
  10
  11 Support for ECMAScript user scripts was first added in ELinks 0.11.0.
  12 The `configure` script enables it by default if the required SpiderMonkey
  13 library has been installed, but you can disable it with `configure
  14 \--disable-sm-scripting` or by <<CONFIG-SCRIPTING-SPIDERMONKEY,editing
  15 features.conf>>.
  16
  17 WARNING: ECMAScript scripting is still a bit experimental: there seem to be
  18 ways to crash ELinks with it, and the object model may change.  However, if
  19 you don't have a `hooks.js` file, there is not much risk in enabling the
  20 feature at compile time.
  21
  22 When ELinks starts up, it evaluates the ECMAScript file `hooks.js` in
  23 your ELinks configuration directory (thus normally `~/.elinks/hooks.js`
  24 on Unix-like systems), or if the file does not exist there, then in
  25 the system-wide ELinks configuration directory (the location depends
  26 on how ELinks was built, but `/etc/elinks/hooks.js` is typical).
  27
  28 In the ELinks source tree, the `contrib/smjs` directory contains some
  29 examples about scripting ELinks with ECMAScript.  Please see the
  30 `README` file in that directory for details.
  31
  32
  33 [[smjs-global-object]]
  34 Global Object
  35 ~~~~~~~~~~~~~
  36
  37 The global object provided to ECMAScript user scripts contains the standard
  38 ECMAScript classes, as well as the following:
  39
  40
  41 [[smjs-global-methods]]
  42 Global Object Methods
  43 ^^^^^^^^^^^^^^^^^^^^^
  44
  45 [[smjs-global.do_file]] do_file(path)::
  46         Load and evaluate the file with the given path (string). For example:
  47 +
  48 --
  49 ----------------------------------------------------------------------
  50 do_file("/home/me/.elinks/hooks.js");
  51 ----------------------------------------------------------------------
  52
  53 will reload your hooks file.
  54
  55 *Compatibility:* ELinks 0.11.0
  56 --
  57
  58
  59 [[smjs-global-properties]]
  60 Global Object Properties
  61 ^^^^^^^^^^^^^^^^^^^^^^^^
  62
  63 [[smjs-global.elinks]] elinks (elinks)::
  64         A reference to the <<smjs-elinks-object,ELinks object>>.
  65 +
  66 *Compatibility:* ELinks 0.11.0
  67
  68
  69 [[smjs-elinks-object]]
  70 ELinks Object
  71 ~~~~~~~~~~~~~
  72
  73 The global <<smjs-global.elinks,'elinks'>> property refers to this object.
  74
  75
  76 [[smjs-elinks-methods]]
  77 ELinks Object Methods
  78 ^^^^^^^^^^^^^^^^^^^^^
  79
  80 [[smjs-elinks.alert]] elinks.alert(message)::
  81         Display the given message (string) in a message box. For example:
  82 +
  83 --
  84 ----------------------------------------------------------------------
  85 elinks.alert("Hello, world!");
  86 ----------------------------------------------------------------------
  87
  88 will display a friendly greeting.
  89
  90 *Compatibility:* ELinks 0.11.0
  91 --
  92
  93 [[smjs-elinks.execute]] elinks.execute(command)::
  94         Execute the given command (string) on the current terminal.
  95         For example:
  96 +
  97 --
  98 ----------------------------------------------------------------------
  99 var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'";
 100 elinks.execute("firefox " + quoted_uri);
 101 ----------------------------------------------------------------------
 102
 103 will run Firefox with the URI of the current document.
 104
 105 *Compatibility:* ELinks 0.12pre1
 106
 107 WARNING: One must be very careful with 'elinks.execute', because depending
 108 on the OS, the command may be subject to interpretation by a command
 109 shell language. When constructing the command string, be sure to quote
 110 any dubious parts (such as the URI of the current document, as above).
 111 --
 112
 113 [[smjs-elinks.load_uri]] elinks.load_uri(uri, callback)::
 114         Load the given URI (string). When the URI completes loading, ELinks
 115         calls the given callback (function). The callback is passed the
 116         <<smjs-cache_entry-object,cache object>> that corresponds to the URI.
 117         For example:
 118 +
 119 --
 120 ----------------------------------------------------------------------
 121 elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes",
 122                 function (cached) { elinks.alert(cached.content); });
 123 ----------------------------------------------------------------------
 124
 125 displays a fortune.
 126
 127 The <<smjs-cache_entry-object,cache object>> will not expire until after the
 128 callback returns.
 129
 130 *Compatibility:* ELinks 0.12pre1
 131 --
 132
 133
 134 [[smjs-elinks-properties]]
 135 ELinks Object Properties
 136 ^^^^^^^^^^^^^^^^^^^^^^^^
 137
 138 [[smjs-elinks.home]] elinks.home (string)::
 139         ELinks's ``home'' directory, where it stores its configuration files.
 140         Read-only. For example,
 141 +
 142 --
 143 ----------------------------------------------------------------------
 144 do_file(elinks.home + "hooks.js");
 145 ----------------------------------------------------------------------
 146
 147 will reload your hooks file.
 148
 149 *Compatibility:* ELinks 0.11.0
 150 --
 151
 152 [[smjs-elinks.location]] elinks.location (string)::
 153         The URI of the currently open document. This can be read to get a
 154         string with the URI or set to load a different document.
 155         For example,
 156 +
 157 --
 158 ----------------------------------------------------------------------
 159 elinks.location = elinks.location + "/..";
 160 ----------------------------------------------------------------------
 161
 162 will go up a directory (if the URI doesn't end in a file).
 163
 164 *Compatibility:* ELinks 0.11.0
 165 --
 166
 167 [[smjs-elinks.bookmarks]] elinks.bookmarks (hash)::
 168         This is a hash, the elements of which correspond to the bookmarks.
 169         One can delve into the bookmarks hierarchy in a reasonably nifty
 170         fashion, just by using standard ECMAScript syntax:
 171 +
 172 --
 173 ----------------------------------------------------------------------
 174 elinks.bookmarks.x.children.y.children.z.children.foo.title
 175 ----------------------------------------------------------------------
 176
 177 gets the title of the bookmark titled ``foo'' under the folder ``z'',
 178 which is a subfolder of ``y'', which is a subfolder of ``x''.
 179
 180 *Compatibility:* ELinks 0.11.0
 181
 182 [[smjs-bookmark-properties]]
 183 A bookmark object has these properties:
 184
 185 [[smjs-bookmark.title]] item.title (string)::
 186         This is the title of the bookmark. It can be read and set.
 187
 188 [[smjs-bookmark.url]] item.url (string)::
 189         This is the URI of the bookmark. It can be read and set.
 190
 191 [[smjs-bookmark.children]] item.children (hash)::
 192         This is a hash, the elements of which are the bookmarks that
 193         are children to the item. It is read-only.
 194 --
 195
 196 [[smjs-elinks.globhist]] elinks.globhist (hash)::
 197         This is a hash, the elements of which correspond to entries in ELinks's
 198         global history. The hash is indexed by URI. For example,
 199 +
 200 --
 201 ----------------------------------------------------------------------
 202 elinks.globhist["file:///"]
 203 ----------------------------------------------------------------------
 204
 205 will get you the history item for your root directory.
 206
 207 *Compatibility:* ELinks 0.12pre1
 208
 209 [[smjs-global_history_item-properties]]
 210 A history item has these properties:
 211
 212 [[smjs-global_history_item.title]] item.title (string)::
 213         This is the title of the history item. It can be read and set.
 214
 215 [[smjs-global_history_item.url]] item.url (string)::
 216         This is the URI of the history item. It can be read and set.
 217
 218 [[smjs-global_history_item.last_visit]] item.last_visit (number)::
 219         This is the UNIX time of the last visit time for the item. UNIX time
 220         is the number of seconds that have passed between the UNIX epoch
 221         (which is 1970-01-01 00:00:00 UTC) and the represented time. Note that
 222         this is 'seconds' since the epoch, whereas ECMAScript likes to use
 223         'milliseconds' since the epoch. This property can be set or read.
 224 --
 225
 226 [[smjs-elinks.action]] elinks.action (hash)::
 227         This hash lets you call the built-in actions of ELinks.  For example,
 228         you can call `elinks.action.auth_manager()` to open the authentication
 229         manager.  The names of the actions are the same as in elinks.conf or
 230         in the keybinding manager, except they have underscores instead of
 231         dashes in order to make them valid ECMAScript identifiers.
 232 +
 233 --
 234 *Compatibility:* ELinks 0.12pre1
 235
 236 NOTE: When you read an action function from this hash, ELinks binds it to the
 237 current tab; any later calls to the function throw errors if that tab no
 238 longer has the focus (in its terminal).  This may be changed in a future
 239 version.  It is safest to call the function right away, rather than save it
 240 in a variable and call it later.
 241 --
 242
 243 [[smjs-elinks.keymaps]] elinks.keymaps (hash)::
 244         This is a hash, the elements of which correspond to ELinks's keymaps.
 245         Currently, there are three: 'elinks.keymaps.main', 'elinks.keymaps.edit',
 246         and 'elinks.keymaps.menu'. These elements are also hashes, the elements of
 247         which correspond to bindings. For example, `elinks.keymaps.main["q"]` is
 248         the binding to the ``q'' key in the main map. These bindings can be read,
 249         to get the name of the action to which the key is bound, or set to one of:
 250 +
 251 --
 252 - A string with the name of the ELinks action.
 253 - A function, which will thenceforth be called when the key is pressed.
 254 - The string `"none"`, to unbind the key.  You can also use the `null`
 255   value for this purpose, but that crashes ELinks 0.11.4 and 0.12pre1
 256   (http://bugzilla.elinks.cz/show_bug.cgi?id=1027[bug 1027]),
 257   so it may be best to use the string for now.
 258 --
 259 +
 260 --
 261 For example,
 262
 263 ----------------------------------------------------------------------
 264 elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); }
 265 ----------------------------------------------------------------------
 266
 267 binds the ``!'' key in the main map to a function that displays a friendly
 268 alert.
 269
 270 ----------------------------------------------------------------------
 271 elinks.keymaps.main["/"] = "search-typeahead-text";
 272 ----------------------------------------------------------------------
 273
 274 changes the ``/'' key to use the nice typeahead search function instead of
 275 opening that ugly old search dialogue box.
 276
 277 *Compatibility:* ELinks 0.11.0, unless you use `null`.
 278
 279 NOTE: Do not read a function from <<smjs-elinks.action,'elinks.action'>>,
 280 e.g. `elinks.action.search_typeahead_text`, and place it in a keymap.
 281 ELinks binds such functions to the current tab when the script reads
 282 them from 'elinks.action', so they will not work right in other tabs.
 283 Use the name of the action instead.
 284 --
 285
 286 [[smjs-elinks.vs]] elinks.vs (view_state)::
 287         This property refers to the <<smjs-view_state-object,view-state
 288         object>> for the current document, if any.
 289 +
 290 *Compatibility:* ELinks 0.12pre1
 291
 292
 293 [[smjs-elinks-hooks]]
 294 ELinks Object Hooks
 295 ^^^^^^^^^^^^^^^^^^^
 296
 297 These are actually properties, but a special case: one assigns functions
 298 to them, which functions are called at certain events.
 299
 300 In the ELinks source tree, `contrib/smjs/hooks.js` provides a mechanism
 301 with which multiple scripts can add their functions to the same hooks.
 302 Please see `contrib/smjs/README` for details.
 303
 304 [[smjs-elinks.preformat_html]] elinks.preformat_html(cached, vs)::
 305         This function is called every time a document is loaded, before the
 306         document is actually rendered, to give scripts the opportunity to
 307         modify it. The first parameter is the <<smjs-cache_entry-object,cache
 308         object>> and the second is the <<smjs-view_state-object,view-state
 309         object>>.
 310 +
 311 --
 312 The <<smjs-cache_entry-object,cache object>> will not expire until after this
 313 function returns.
 314
 315 *Compatibility:* ELinks 0.11.1 as described.  ELinks 0.11.0 did not provide
 316 the 'vs' argument.
 317 --
 318
 319 [[smjs-elinks.goto_url_hook]] elinks.goto_url_hook(url)::
 320         This function is called every time the user enters something in the
 321         'Go to URL' box. The url (string) can be modified or not, and the
 322         returned string is substituted for what the user entered.  If the
 323         value `false` is returned, the URL is not changed and further hooks
 324         in ELinks are not run.
 325 +
 326 *Compatibility:* ELinks 0.11.0
 327
 328 [[smjs-elinks.follow_url_hook]] elinks.follow_url_hook(url)::
 329         This function is called every time the user tries to load a document,
 330         whether by following a link, by entering a URI in the Go to URL box,
 331         by setting <<smjs-elinks.location,'elinks.location'>>, or whatever.
 332         It behaves the same as <<smjs-elinks.goto_url_hook,'elinks.goto_url_hook'>>
 333         above.
 334 +
 335 *Compatibility:* ELinks 0.11.0
 336
 337
 338 [[smjs-cache_entry-object]]
 339 Cache Object
 340 ~~~~~~~~~~~~
 341
 342 The cache object mentioned in the descriptions of
 343 <<smjs-elinks.load_uri,'elinks.load_uri'>> and
 344 <<smjs-elinks.preformat_html,'elinks.preformat_html'>> is a wrapper for the
 345 internal ELinks cache object.  ELinks passes the ECMAScript cache object as an
 346 argument to your ECMAScript function, and keeps the corresponding document in
 347 the cache until the function returns.  After that, ELinks may remove the
 348 document from the cache, even if the function has saved the cache object to
 349 some global variable.  Such an expired cache object does not work but it does
 350 not crash ELinks either.
 351
 352 *Compatibility:* ELinks 0.11.0
 353
 354
 355 [[smjs-cache_entry-properties]]
 356 Cache Object Properties
 357 ^^^^^^^^^^^^^^^^^^^^^^^
 358
 359 [[smjs-cache_entry.content]] cached.content (string)::
 360         This is the content received from the server. It can be read and set.
 361
 362 [[smjs-cache_entry.type]] cached.type (string)::
 363         This is the MIME type of the cache entry. It can be read and set.
 364
 365 [[smjs-cache_entry.length]] cached.length (number)::
 366         This is the length of cached.content. It is read-only.
 367
 368 [[smjs-cache_entry.head]] cached.head (string)::
 369         This is the header received from the server. It can be read and set.
 370
 371 [[smjs-cache_entry.uri]] cached.uri (string)::
 372         This is the URI of the cache entry. It is read-only.
 373
 374
 375 [[smjs-view_state-object]]
 376 View-state Object
 377 ~~~~~~~~~~~~~~~~~
 378
 379 The view-state object mentioned in the descriptions of
 380 <<smjs-elinks.preformat_html,'elinks.preformat_html'>> and
 381 <<smjs-elinks.vs,'elinks.vs'>> is a wrapper for the internal ELinks view_state
 382 object.  The view state holds information on how the current document is being
 383 displayed.
 384
 385 *Compatibility:* ELinks 0.11.1
 386
 387
 388 [[smjs-view_state-properties]]
 389 View-state Object Properties
 390 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 391
 392 [[smjs.view_state.plain]] vs.plain (boolean)::
 393         Whether the current document is rendered as HTML or displayed
 394         as plaintext. This can be read and set.
 395
 396 [[smjs.view_state.uri]] vs.uri (string)::
 397         This is the URI of the current document. It is read-only.