<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ELinks Object</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="The ELinks Manual"><link rel="up" href="ch15.html" title="Chapter 15. Scripting ELinks with ECMAScript"><link rel="prev" href="ch15.html" title="Chapter 15. Scripting ELinks with ECMAScript"><link rel="next" href="ch15s03.html" title="Cache Object"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ELinks Object</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch15.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Scripting ELinks with ECMAScript</th><td width="20%" align="right"> <a accesskey="n" href="ch15s03.html">Next</a></td></tr></table><hr></div><div class="section" title="ELinks Object"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="smjs-elinks-object"></a>ELinks Object</h2></div></div></div><p>The global <a class="link" href="ch15.html#smjs-global.elinks"><span class="emphasis"><em>elinks</em></span></a> property refers to this object.</p><div class="section" title="ELinks Object Methods"><div class="titlepage"><div><div><h3 class="title"><a name="smjs-elinks-methods"></a>ELinks Object Methods</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"> <a name="smjs-elinks.alert"></a> elinks.alert(message) </span></dt><dd><p class="simpara"> Display the given message (string) in a message box. For example: </p><pre class="screen">elinks.alert("Hello, world!");</pre><p class="simpara">will display a friendly greeting.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p></dd><dt><span class="term"> <a name="smjs-elinks.execute"></a> elinks.execute(command) </span></dt><dd><p class="simpara"> Execute the given command (string) on the current terminal. For example: </p><pre class="screen">var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'"; elinks.execute("firefox " + quoted_uri);</pre><p class="simpara">will run Firefox with the URI of the current document.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.12pre1</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>One must be very careful with <span class="emphasis"><em>elinks.execute</em></span>, 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).</p></div></dd><dt><span class="term"> <a name="smjs-elinks.load_uri"></a> elinks.load_uri(uri, callback) </span></dt><dd><p class="simpara"> Load the given URI (string). When the URI completes loading, ELinks calls the given callback (function). The callback is passed the <a class="link" href="ch15s03.html" title="Cache Object">cache object</a> that corresponds to the URI. For example: </p><pre class="screen">elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes", function (cached) { elinks.alert(cached.content); });</pre><p class="simpara">displays a fortune.</p><p class="simpara">The <a class="link" href="ch15s03.html" title="Cache Object">cache object</a> will not expire until after the callback returns.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.12pre1</p></dd></dl></div></div><div class="section" title="ELinks Object Properties"><div class="titlepage"><div><div><h3 class="title"><a name="smjs-elinks-properties"></a>ELinks Object Properties</h3></div></div></div><div class="variablelist"><dl><dt><span class="term"> <a name="smjs-elinks.home"></a> elinks.home (string) </span></dt><dd><p class="simpara"> ELinks's “home” directory, where it stores its configuration files. Read-only. For example, </p><pre class="screen">do_file(elinks.home + "hooks.js");</pre><p class="simpara">will reload your hooks file.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p></dd><dt><span class="term"> <a name="smjs-elinks.location"></a> elinks.location (string) </span></dt><dd><p class="simpara"> 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, </p><pre class="screen">elinks.location = elinks.location + "/..";</pre><p class="simpara">will go up a directory (if the URI doesn't end in a file).</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p></dd><dt><span class="term"> <a name="smjs-elinks.bookmarks"></a> elinks.bookmarks (hash) </span></dt><dd><p class="simpara"> 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: </p><pre class="screen">elinks.bookmarks.x.children.y.children.z.children.foo.title</pre><p class="simpara">gets the title of the bookmark titled “foo” under the folder “z”, which is a subfolder of “y”, which is a subfolder of “x”.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p><p class="simpara"><a name="smjs-bookmark-properties"></a>A bookmark object has these properties:</p><div class="variablelist"><dl><dt><span class="term"> <a name="smjs-bookmark.title"></a> item.title (string) </span></dt><dd> This is the title of the bookmark. It can be read and set. </dd><dt><span class="term"> <a name="smjs-bookmark.url"></a> item.url (string) </span></dt><dd> This is the URI of the bookmark. It can be read and set. </dd><dt><span class="term"> <a name="smjs-bookmark.children"></a> item.children (hash) </span></dt><dd> This is a hash, the elements of which are the bookmarks that are children to the item. It is read-only. </dd></dl></div></dd><dt><span class="term"> <a name="smjs-elinks.globhist"></a> elinks.globhist (hash) </span></dt><dd><p class="simpara"> This is a hash, the elements of which correspond to entries in ELinks's global history. The hash is indexed by URI. For example, </p><pre class="screen">elinks.globhist["file:///"]</pre><p class="simpara">will get you the history item for your root directory.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.12pre1</p><p class="simpara"><a name="smjs-global_history_item-properties"></a>A history item has these properties:</p><div class="variablelist"><dl><dt><span class="term"> <a name="smjs-global_history_item.title"></a> item.title (string) </span></dt><dd> This is the title of the history item. It can be read and set. </dd><dt><span class="term"> <a name="smjs-global_history_item.url"></a> item.url (string) </span></dt><dd> This is the URI of the history item. It can be read and set. </dd><dt><span class="term"> <a name="smjs-global_history_item.last_visit"></a> item.last_visit (number) </span></dt><dd> 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 <span class="emphasis"><em>seconds</em></span> since the epoch, whereas ECMAScript likes to use <span class="emphasis"><em>milliseconds</em></span> since the epoch. This property can be set or read. </dd></dl></div></dd><dt><span class="term"> <a name="smjs-elinks.action"></a> elinks.action (hash) </span></dt><dd><p class="simpara"> This hash lets you call the built-in actions of ELinks. For example, you can call <code class="literal">elinks.action.auth_manager()</code> to open the authentication manager. The names of the actions are the same as in elinks.conf or in the keybinding manager, except they have underscores instead of dashes in order to make them valid ECMAScript identifiers. </p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.12pre1</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>When you read an action function from this hash, ELinks binds it to the current tab; any later calls to the function throw errors if that tab no longer has the focus (in its terminal). This may be changed in a future version. It is safest to call the function right away, rather than save it in a variable and call it later.</p></div></dd><dt><span class="term"> <a name="smjs-elinks.keymaps"></a> elinks.keymaps (hash) </span></dt><dd><p class="simpara"> This is a hash, the elements of which correspond to ELinks's keymaps. Currently, there are three: <span class="emphasis"><em>elinks.keymaps.main</em></span>, <span class="emphasis"><em>elinks.keymaps.edit</em></span>, and <span class="emphasis"><em>elinks.keymaps.menu</em></span>. These elements are also hashes, the elements of which correspond to bindings. For example, <code class="literal">elinks.keymaps.main["q"]</code> is the binding to the “q” key in the main map. These bindings can be read, to get the name of the action to which the key is bound, or set to one of: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> A string with the name of the ELinks action. </li><li class="listitem"> A function, which will thenceforth be called when the key is pressed. </li><li class="listitem"> The string <code class="literal">"none"</code>, to unbind the key. You can also use the <code class="literal">null</code> value for this purpose, but that crashes ELinks 0.11.4 and 0.12pre1 (<a class="ulink" href="http://bugzilla.elinks.cz/show_bug.cgi?id=1027" target="_top">bug 1027</a>), so it may be best to use the string for now. </li></ul></div><p class="simpara">For example,</p><pre class="screen">elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); }</pre><p class="simpara">binds the “!” key in the main map to a function that displays a friendly alert.</p><pre class="screen">elinks.keymaps.main["/"] = "search-typeahead-text";</pre><p class="simpara">changes the “/” key to use the nice typeahead search function instead of opening that ugly old search dialogue box.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0, unless you use <code class="literal">null</code>.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Do not read a function from <a class="link" href="ch15s02.html#smjs-elinks.action"><span class="emphasis"><em>elinks.action</em></span></a>, e.g. <code class="literal">elinks.action.search_typeahead_text</code>, and place it in a keymap. ELinks binds such functions to the current tab when the script reads them from <span class="emphasis"><em>elinks.action</em></span>, so they will not work right in other tabs. Use the name of the action instead.</p></div></dd><dt><span class="term"> <a name="smjs-elinks.vs"></a> elinks.vs (view_state) </span></dt><dd><p class="simpara"> This property refers to the <a class="link" href="ch15s04.html" title="View-state Object">view-state object</a> for the current document, if any. </p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.12pre1</p></dd></dl></div></div><div class="section" title="ELinks Object Hooks"><div class="titlepage"><div><div><h3 class="title"><a name="smjs-elinks-hooks"></a>ELinks Object Hooks</h3></div></div></div><p>These are actually properties, but a special case: one assigns functions to them, which functions are called at certain events.</p><p>In the ELinks source tree, <code class="literal">contrib/smjs/hooks.js</code> provides a mechanism with which multiple scripts can add their functions to the same hooks. Please see <code class="literal">contrib/smjs/README</code> for details.</p><div class="variablelist"><dl><dt><span class="term"> <a name="smjs-elinks.preformat_html"></a> elinks.preformat_html(cached, vs) </span></dt><dd><p class="simpara"> 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 <a class="link" href="ch15s03.html" title="Cache Object">cache object</a> and the second is the <a class="link" href="ch15s04.html" title="View-state Object">view-state object</a>. </p><p class="simpara">The <a class="link" href="ch15s03.html" title="Cache Object">cache object</a> will not expire until after this function returns.</p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.1 as described. ELinks 0.11.0 did not provide the <span class="emphasis"><em>vs</em></span> argument.</p></dd><dt><span class="term"> <a name="smjs-elinks.goto_url_hook"></a> elinks.goto_url_hook(url) </span></dt><dd><p class="simpara"> This function is called every time the user enters something in the <span class="emphasis"><em>Go to URL</em></span> box. The url (string) can be modified or not, and the returned string is substituted for what the user entered. If the value <code class="literal">false</code> is returned, the URL is not changed and further hooks in ELinks are not run. </p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p></dd><dt><span class="term"> <a name="smjs-elinks.follow_url_hook"></a> elinks.follow_url_hook(url) </span></dt><dd><p class="simpara"> 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 <a class="link" href="ch15s02.html#smjs-elinks.location"><span class="emphasis"><em>elinks.location</em></span></a>, or whatever. It behaves the same as <a class="link" href="ch15s02.html#smjs-elinks.goto_url_hook"><span class="emphasis"><em>elinks.goto_url_hook</em></span></a> above. </p><p class="simpara"><span class="strong"><strong>Compatibility:</strong></span> ELinks 0.11.0</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch15.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch15.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch15s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. Scripting ELinks with ECMAScript </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Cache Object</td></tr></table></div></body></html>