= cockpit.js: Page Location and JumpingPage location and navigation between components[[cockpit-location-general]]== Page location....location = cockpit.locationcockpit.location = "/path"....Cockpit components often have different views, without changing the HTMLfile that is being viewed. These are known as pages.`+cockpit.location+` is an object that can be used to read the currentpage 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 querystring:..../path/sub/page?option=value,option2....The link:#cockpit-location-path[`+location.path+`] andlink:#cockpit-location-options[`+location.options+`] contain a parsedform of the location. While the location cannot be modified in place, anew one can be created by assigning a string to `+cockpit.location+` orby calling the link:#cockpit-location-go[`+location.go()+`] function.`+cockpit.location+` is designed similarly to `+window.location+` inthat the location object is preplaced whenever the current page locationchanges. To be aware of when the page location changes listen for thelink:#cockpit-location-changed[`+cockpit.onlocationchanged+`] event.Using the location object as a string will result in thelink:#cockpit-location-href[`+location.href+`].[[cockpit-location-href]]=== location.hrefThe string representation of this page location, including any options.[[cockpit-location-path]]=== location.pathAn array of path segments, parsed and decoded appropriately. An emptyarray denotes the root path.[[cockpit-location-options]]=== location.optionsA javascript object containing the various options present in thelocation.If an option appears more than once, its value will be an array.[[cockpit-location-go]]=== location.go()....location.go(path, [options])....Changes the current location to the given `+path+` and `+options+`. Ifthe `+path+` argument is a string, it will be parsed into a path. If itis a relative path, then the result will be relative to the current`+location.path+`. If the `+path+` argument is an array of pathsegments, 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 notchanged in the meantime. This can be to good effect by saving a`+cockpit.location+` object and doing a conditional navigation, bycalling the saved `+location.go()+` method later. This will onlynavigate if the user or other code has not navigated in the meantime.[[cockpit-location-replace]]=== location.replace()....location.replace(path, [options])....Similar to link:#cockpit-location-go[`+location.go()+`] except thelocation change will not result in a navigation change in the browser'shistory.[[cockpit-location-decode]]=== 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 inthe href.If href is a relative path it will be resolved relative to`+location.href+`.[[cockpit-location-encode]]=== 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. Ifa relative path is passed, it will be resolved relative to`+location.href+`.[[cockpit-location-changed]]=== cockpit.onlocationchanged....cockpit.addEventListener("locationchanged", function() { ... })....An event emitted when over the `+cockpit.location+` changes. Typically acomponent reacts to this event by updating its interface to reflect thenew link:#cockpit-location-path[`+cockpit.location.path+`] andlink:#cockpit-location-options[`+cockpit.location.options+`].This event is not triggered immediately during a `+location.go()+` orsimilar call. It will be triggered asynchronously at a later time.[[cockpit-jump]]== Jumping between components....cockpit.jump("/system/log")....In Cockpit in there multiple components shown. In order to tell Cockpitto jump to and show another component and a certain location within thatcomponent, use the `+cockpit.jump()+` function. Stable component pathsare documented. Don't assume you can navigate into paths that are notstable API.[[cockpit-jump-jump]]=== cockpit.jump()....cockpit.jump(path, [ host ])....Ask Cockpit to jump to another component. The location of the currentcomponent will not be affected. The `+path+` argument can be a stringpath, starting with `+/+` or an array containing the parts of a paththat will be joined to create a path. If `+host+` is not specified, thenthe component on the same host as the caller will be displayed. If hostis null, then the host portion of the path will be removed, displayingthe component on the host that cockpit is connected directly to.If the calling component is not running within Cockpit, or the callingcomponent is not currently displayed, then the jump will not happen, andthis function has no effect.[[cockpit-jump-hidden]]=== cockpit.hiddenA boolean property that indicates if the current component page isvisible or hidden. When the code or user jumps to another component, theprior one remains loaded and initialized but is hidden. Use thisproperty together with thelink:#cockpit-jump-visibilitychange[`+cockpit.onvisibilitychange+`]event to decide whether or not to perform expensive tasks to update theinterface.This property is analogous to the `+document.hidden+` page visibilityAPI, but works with the document and frame implementation of Cockpit.[[cockpit-jump-visibilitychange]]=== cockpit.onvisibilitychange....cockpit.onvisibilitychange = function() { ... }....This event is emitted when thelink:#cockpit-jump-hidden[`+cockpit.hidden+`] property changes. Thisevent is similar to the `+document.onvisibilitychange+` API, but workswith the document and frame implementation of Cockpit.