/usr/share/doc/cockpit/guide/cockpit-location.html is in cockpit-doc 164-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>cockpit.js: Page Location and Jumping</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="api-base1.html" title="API: base1">
<link rel="prev" href="cockpit-channels.html" title="cockpit.js: Raw Channels">
<link rel="next" href="cockpit-locale.html" title="cockpit.js: Localization">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="cockpit-channels.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="api-base1.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="cockpit-locale.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="cockpit-location"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>cockpit.js: Page Location and Jumping</h2>
<p>cockpit.js: Page Location and Jumping — Page location and navigation between components</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsection">
<a name="cockpit-location-general"></a><h2>Page location</h2>
<pre class="programlisting">
location = cockpit.location
cockpit.location = "/path"
</pre>
<p>Cockpit components often have different views, without changing the HTML file that is
being viewed. These are known as pages. <code class="code">cockpit.location</code> is an object that can
be used to read the current page and to navigate to a different page location. It works by
updating <code class="code">window.location.hash</code>.</p>
<p>The <code class="code">cockpit.location</code> looks like a HTTP path with a possible query
string:</p>
<pre class="programlisting">
/path/sub/page?option=value,option2
</pre>
<p>The <a class="link" href="cockpit-location.html#cockpit-location-path" title="location.path"><code class="code">location.path</code></a> and
<a class="link" href="cockpit-location.html#cockpit-location-options" title="location.options"><code class="code">location.options</code></a> contain a parsed
form of the location. While the location cannot be modified in place, a new one can be
created by assigning a string to <code class="code">cockpit.location</code> or by calling the
<a class="link" href="cockpit-location.html#cockpit-location-go" title="location.go()"><code class="code">location.go()</code></a> function.</p>
<p><code class="code">cockpit.location</code> is designed similarly to <code class="code">window.location</code>
in that the location object is preplaced whenever the current page location changes. To be
aware of when the page location changes listen for the
<a class="link" href="cockpit-location.html#cockpit-location-changed" title="cockpit.onlocationchanged"><code class="code">cockpit.onlocationchanged</code></a>
event.</p>
<p>Using the location object as a string will result in the
<a class="link" href="cockpit-location.html#cockpit-location-href" title="location.href"><code class="code">location.href</code></a>.</p>
<div class="refsection">
<a name="cockpit-location-href"></a><h3>location.href</h3>
<p>The string representation of this page location, including any options.</p>
</div>
<div class="refsection">
<a name="cockpit-location-path"></a><h3>location.path</h3>
<p>An array of path segments, parsed and decoded appropriately. An empty array denotes
the root path.</p>
</div>
<div class="refsection">
<a name="cockpit-location-options"></a><h3>location.options</h3>
<p>A javascript object containing the various options present in the location.</p>
<p>If an option appears more than once, its value will be an array.</p>
</div>
<div class="refsection">
<a name="cockpit-location-go"></a><h3>location.go()</h3>
<pre class="programlisting">
location.go(path, [options])
</pre>
<p>Changes the current location to the given <code class="code">path</code> and <code class="code">options</code>.
If the <code class="code">path</code> argument is a string, it will be parsed into a path. If it is
a relative path, then the result will be relative to the current <code class="code">location.path</code>.
If the <code class="code">path</code> argument is an array of path segments, it will be treated as a
full parsed absolute path.</p>
<p>Any options found in a <code class="code">path</code> will be added to those in the optional
<code class="code">options</code> argument, and used in the result.</p>
<p>The location change will only take effect if the location has not changed in the
meantime. This can be to good effect by saving a <code class="code">cockpit.location</code> object
and doing a conditional navigation, by calling the saved <code class="code">location.go()</code>
method later. This will only navigate if the user or other code has not navigated in
the meantime.</p>
</div>
<div class="refsection">
<a name="cockpit-location-replace"></a><h3>location.replace()</h3>
<pre class="programlisting">
location.replace(path, [options])
</pre>
<p>Similar to <a class="link" href="cockpit-location.html#cockpit-location-go" title="location.go()"><code class="code">location.go()</code></a>
except the location change will not result in a navigation change in the browser's
history.</p>
</div>
<div class="refsection">
<a name="cockpit-location-decode"></a><h3>location.decode()</h3>
<pre class="programlisting">
path = location.decode(href, [options])
</pre>
<p>Decode a cockpit href into its <code class="code">path</code> array. If the <code class="code">options</code>
argument is specified, then it will be populated with options found in the href.</p>
<p>If href is a relative path it will be resolved relative to
<code class="code">location.href</code>.</p>
</div>
<div class="refsection">
<a name="cockpit-location-encode"></a><h3>location.encode()</h3>
<pre class="programlisting">
href = location.encode(path, [options])
</pre>
<p>Encode the given <code class="code">path</code> and <code class="code">options</code> into a cockpit href.
The <code class="code">path</code> argument may be an array of path segments, or a string path. If
a relative path is passed, it will be resolved relative to <code class="code">location.href</code>.</p>
</div>
<div class="refsection">
<a name="cockpit-location-changed"></a><h3>cockpit.onlocationchanged</h3>
<pre class="programlisting">
cockpit.addEventListener("locationchanged", function() { ... })
</pre>
<p>An event emitted when over the <code class="code">cockpit.location</code> changes. Typically a
component reacts to this event by updating its interface to reflect the new
<a class="link" href="cockpit-location.html#cockpit-location-path" title="location.path"><code class="code">cockpit.location.path</code></a> and
<a class="link" href="cockpit-location.html#cockpit-location-options" title="location.options"><code class="code">cockpit.location.options</code></a>.</p>
<p>This event is not triggered immediately during a <code class="code">location.go()</code> or
similar call. It will be triggered asynchronously at a later time.</p>
</div>
</div>
<div class="refsection">
<a name="cockpit-jump"></a><h2>Jumping between components</h2>
<pre class="programlisting">
cockpit.jump("/system/log")
</pre>
<p>In Cockpit in there multiple components shown. In order to tell Cockpit to jump to and show
another component and a certain location within that component, use the
<code class="code">cockpit.jump()</code> function. Stable component paths are documented. Don't assume
you can navigate into paths that are not stable API.</p>
<div class="refsection">
<a name="cockpit-jump-jump"></a><h3>cockpit.jump()</h3>
<pre class="programlisting">
cockpit.jump(path, [ host ])
</pre>
<p>Ask Cockpit to jump to another component. The location of the current component will
not be affected. The <code class="code">path</code> argument can be a string path, starting with <code class="code">/</code>
or an array containing the parts of a path that will be joined to create a path. If <code class="code">host</code>
is not specified, then the component on the same host as the caller will be displayed. If
host is null, then the host portion of the path will be removed, displaying the component on
the host that cockpit is connected directly to. This is mostly useful for displaying a
dashboard or other multi-machine components.</p>
<p>If the calling component is not running within Cockpit, or the calling component is not
currently displayed, then the jump will not happen, and this function has no effect.</p>
</div>
<div class="refsection">
<a name="cockpit-jump-hidden"></a><h3>cockpit.hidden</h3>
<p>A boolean property that indicates if the current component page is visible or hidden.
When the code or user jumps to another component, the prior one remains loaded and initialized
but is hidden. Use this property together with the
<a class="link" href="cockpit-location.html#cockpit-jump-visibilitychange" title="cockpit.onvisibilitychange"><code class="code">cockpit.onvisibilitychange</code></a>
event to decide whether or not to perform expensive tasks to update the interface.</p>
<p>This property is analogous to the <code class="code">document.hidden</code> page visibility API, but
works with the document and frame implementation of Cockpit.</p>
</div>
<div class="refsection">
<a name="cockpit-jump-visibilitychange"></a><h3>cockpit.onvisibilitychange</h3>
<pre class="programlisting">
cockpit.onvisibilitychange = function() { ... }
</pre>
<p>This event is emitted when the
<a class="link" href="cockpit-location.html#cockpit-jump-hidden" title="cockpit.hidden"><code class="code">cockpit.hidden</code></a> property changes.
This event is similar to the <code class="code">document.onvisibilitychange</code> API, but works with
the document and frame implementation of Cockpit.</p>
</div>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>
|