<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-location">
  <refnamediv>
    <refname>cockpit.js: Page Location and Jumping</refname>
    <refpurpose>Page location and navigation between components</refpurpose>
  </refnamediv>

  <refsection id="cockpit-location-general">
    <title>Page location</title>

<programlisting>
location = cockpit.location
cockpit.location = "/path"
</programlisting>

    <para>Cockpit components often have different views, without changing the HTML file that is
      being viewed. These are known as pages. <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>window.location.hash</code>.</para>

    <para>The <code>cockpit.location</code> looks like a HTTP path with a possible query
      string:</para>

<programlisting>
/path/sub/page?option=value,option2
</programlisting>

    <para>The <link linkend="cockpit-location-path"><code>location.path</code></link> and
      <link linkend="cockpit-location-options"><code>location.options</code></link> 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>cockpit.location</code> or by calling the
      <link linkend="cockpit-location-go"><code>location.go()</code></link> function.</para>

    <para><code>cockpit.location</code> is designed similarly to <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
      <link linkend="cockpit-location-changed"><code>cockpit.onlocationchanged</code></link>
      event.</para>

    <para>Using the location object as a string will result in the
      <link linkend="cockpit-location-href"><code>location.href</code></link>.</para>

    <refsection id="cockpit-location-href">
      <title>location.href</title>
      <para>The string representation of this page location, including any options.</para>
    </refsection>

    <refsection id="cockpit-location-path">
      <title>location.path</title>
      <para>An array of path segments, parsed and decoded appropriately. An empty array denotes
        the root path.</para>
    </refsection>

    <refsection id="cockpit-location-options">
      <title>location.options</title>
      <para>A javascript object containing the various options present in the location.</para>
      <para>If an option appears more than once, its value will be an array.</para>
    </refsection>

    <refsection id="cockpit-location-go">
      <title>location.go()</title>
<programlisting>
location.go(path, [options])
</programlisting>
      <para>Changes the current location to the given <code>path</code> and <code>options</code>.
        If the <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>location.path</code>.
        If the <code>path</code> argument is an array of path segments, it will be treated as a
        full parsed absolute path.</para>

      <para>Any options found in a <code>path</code> will be added to those in the optional
        <code>options</code> argument, and used in the result.</para>

      <para>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>cockpit.location</code> object
        and doing a conditional navigation, by calling the saved <code>location.go()</code>
        method later. This will only navigate if the user or other code has not navigated in
        the meantime.</para>
    </refsection>

    <refsection id="cockpit-location-replace">
      <title>location.replace()</title>
<programlisting>
location.replace(path, [options])
</programlisting>
      <para>Similar to <link linkend="cockpit-location-go"><code>location.go()</code></link>
        except the location change will not result in a navigation change in the browser's
        history.</para>
    </refsection>

    <refsection id="cockpit-location-decode">
      <title>location.decode()</title>
<programlisting>
path = location.decode(href, [options])
</programlisting>
      <para>Decode a cockpit href into its <code>path</code> array. If the <code>options</code>
        argument is specified, then it will be populated with options found in the href.</para>

      <para>If href is a relative path it will be resolved relative to
        <code>location.href</code>.</para>
    </refsection>

    <refsection id="cockpit-location-encode">
      <title>location.encode()</title>
<programlisting>
href = location.encode(path, [options])
</programlisting>
      <para>Encode the given <code>path</code> and <code>options</code> into a cockpit href.
        The <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>location.href</code>.</para>
    </refsection>

    <refsection id="cockpit-location-changed">
      <title>cockpit.onlocationchanged</title>
<programlisting>
cockpit.addEventListener("locationchanged", function() { ... })
</programlisting>
      <para>An event emitted when over the <code>cockpit.location</code> changes. Typically a
        component reacts to this event by updating its interface to reflect the new
        <link linkend="cockpit-location-path"><code>cockpit.location.path</code></link> and
        <link linkend="cockpit-location-options"><code>cockpit.location.options</code></link>.</para>

      <para>This event is not triggered immediately during a <code>location.go()</code> or
        similar call. It will be triggered asynchronously at a later time.</para>
    </refsection>
  </refsection>

  <refsection id="cockpit-jump">
    <title>Jumping between components</title>

<programlisting>
cockpit.jump("/system/log")
</programlisting>

    <para>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>cockpit.jump()</code> function. Stable component paths are documented. Don't assume
      you can navigate into paths that are not stable API.</para>

    <refsection id="cockpit-jump-jump">
      <title>cockpit.jump()</title>
<programlisting>
cockpit.jump(path, [ host ])
</programlisting>
      <para>Ask Cockpit to jump to another component. The location of the current component will
        not be affected. The <code>path</code> argument can be a string path, starting with <code>/</code>
        or an array containing the parts of a path that will be joined to create a path. If <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.</para>
      <para>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.</para>
    </refsection>

    <refsection id="cockpit-jump-hidden">
      <title>cockpit.hidden</title>

      <para>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
        <link linkend="cockpit-jump-visibilitychange"><code>cockpit.onvisibilitychange</code></link>
        event to decide whether or not to perform expensive tasks to update the interface.</para>

      <para>This property is analogous to the <code>document.hidden</code> page visibility API, but
        works with the document and frame implementation of Cockpit.</para>
    </refsection>

    <refsection id="cockpit-jump-visibilitychange">
      <title>cockpit.onvisibilitychange</title>

<programlisting>
cockpit.onvisibilitychange = function() { ... }
</programlisting>

      <para>This event is emitted when the
        <link linkend="cockpit-jump-hidden"><code>cockpit.hidden</code></link> property changes.
        This event is similar to the <code>document.onvisibilitychange</code> API, but works with
        the document and frame implementation of Cockpit.</para>

    </refsection>

  </refsection>
</refentry>
