cockpit.js: Page Location and Jumpingcockpit.js: Page Location and Jumping — Page location and navigation between components |
Page location
location = cockpit.location cockpit.location = "/path"
Cockpit components often have different views, without changing the HTML file that is
being viewed. These are known as pages. cockpit.location is an object that can
be used to read the current page and to navigate to a different page location. It works by
updating window.location.hash.
The cockpit.location looks like a HTTP path with a possible query
string:
/path/sub/page?option=value,option2
The location.path and
location.options 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 cockpit.location or by calling the
location.go() function.
cockpit.location is designed similarly to window.location
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
cockpit.onlocationchanged
event.
Using the location object as a string will result in the
location.href.
location.path
An array of path segments, parsed and decoded appropriately. An empty array denotes the root path.
location.options
A javascript object containing the various options present in the location.
If an option appears more than once, its value will be an array.
location.go()
location.go(path, [options])
Changes the current location to the given path and options.
If the path 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 location.path.
If the path argument is an array of path segments, it will be treated as a
full parsed absolute path.
Any options found in a path will be added to those in the optional
options argument, and used in the result.
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 cockpit.location object
and doing a conditional navigation, by calling the saved location.go()
method later. This will only navigate if the user or other code has not navigated in
the meantime.
location.replace()
location.replace(path, [options])
Similar to location.go()
except the location change will not result in a navigation change in the browser's
history.
location.decode()
path = location.decode(href, [options])
Decode a cockpit href into its path array. If the options
argument is specified, then it will be populated with options found in the href.
If href is a relative path it will be resolved relative to
location.href.
location.encode()
href = location.encode(path, [options])
Encode the given path and options into a cockpit href.
The path argument may be an array of path segments, or a string path. If
a relative path is passed, it will be resolved relative to location.href.
cockpit.onlocationchanged
cockpit.addEventListener("locationchanged", function() { ... })
An event emitted when over the cockpit.location changes. Typically a
component reacts to this event by updating its interface to reflect the new
cockpit.location.path and
cockpit.location.options.
This event is not triggered immediately during a location.go() or
similar call. It will be triggered asynchronously at a later time.
Jumping between components
cockpit.jump("/system/log")
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
cockpit.jump() function. Stable component paths are documented. Don't assume
you can navigate into paths that are not stable API.
cockpit.jump()
cockpit.jump(path, [ host ])
Ask Cockpit to jump to another component. The location of the current component will
not be affected. The path argument can be a string path, starting with /
or an array containing the parts of a path that will be joined to create a path. If host
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.
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.
cockpit.hidden
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
cockpit.onvisibilitychange
event to decide whether or not to perform expensive tasks to update the interface.
This property is analogous to the document.hidden page visibility API, but
works with the document and frame implementation of Cockpit.
cockpit.onvisibilitychange
cockpit.onvisibilitychange = function() { ... }
This event is emitted when the
cockpit.hidden property changes.
This event is similar to the document.onvisibilitychange API, but works with
the document and frame implementation of Cockpit.