Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
179 lines (121 sloc) 7.13 KB

Browser API

import Browser from "@hickory/browser";

const history = Browser();

Options

  • query - An object with two required properties: parse and stringify.

    • parse - A function that will convert a search string to a query value. This function should return a default value when it is called with no arguments.

    • stringify - A function that will convert a query value into a search string. This function should return an empty string when it is called with no arguments.

  • decode - Whether or not to automatically decode the pathname when creating a location. This should almost always be true, but if you have a reason to use invalid URIs, then you can set this to false (possibly to your own peril). (default: true)

  • raw - A function that will be used to set the rawPathname property of location objects. When creating a location from a string, this function will be passed the pathname section parsed from the string. When creating a location from an object, this function will be passed the pathname section of that object. The default value of this option is a function that will return the encoded version of the pathname (but will not double-encode an already encoded pathname).

  • baseSegment - This is a string that begins with a forward slash and ends with a non-foward slash character. It should be provided if your application is not being served from the root of your server.

Properties

location

The current location object.

action

The action used to get to the current location object.

Methods

navigate()

history.navigate("/the-producers");
history.navigate({
  pathname: "/oklahoma",
  state: { musical: true }
});

The navigate function is used to navigate to a new location.

There are three ways that it can do this: PUSH, REPLACE, and ANCHOR.

  1. PUSH navigation pushes the new location onto the session history after the current location. Any existing locations after the current location are dropped.
history.navigate("/lion-king", "PUSH");
history.navigate(
  {
    pathname: "/wicked",
    state: { musical: true }
  },
  "PUSH"
);
  1. REPLACE navigation replaces the current location with the new location. Any existing locations after the current location are unaffected.
history.navigate("/cats", "REPLACE");
history.navigate(
  {
    pathname: "/rent",
    state: { musical: true }
  },
  "REPLACE"
);
  1. ANCHOR mimics the behavior of clicking on an <a> element. When the new location's URL is exactly the same as the current location's, it will act like REPLACE; when they are different, it will act like PUSH.
history.navigate("/hairspray", "ANCHOR");
history.navigate(
  {
    pathname: "/hamilton",
    state: { musical: true }
  },
  "ANCHOR"
);

arguments

to - This can either be a string or an object. If it is a string, it will be parsed to create a location object. If it is an object, then its properties will be used to create a new location object. If the provided object is missing any location properties, then those will be given default values on the new location object.

navType - ANCHOR, PUSH, or REPLACE. If none are provided, this will default to ANCHOR.

go()

history.go(-1);
history.go();
history.go(2);

The go function is used to jump forward and backward to already visited locations. If you call it with a negative number, it goes backward. With a positive number, it goes forward. If you call it with no value (or 0), it will reload the current location.

arguments

num - The number of steps forward or backward to go.

toHref()

history.toHref({ pathname: "/spamalot" });
// /spamalot

The toHref function generates the string representation of the location object. This string will be prepended with the baseSegment (if you provided one).

arguments

location - The location to create a path for.

respondWith()

history.respondWith(pendingNavigation => {
  console.log(pendingNavigation.action, pendingNavigation.location);
  pendingNavigation.finish();
});

The respondWith function is used to pass a response handler to the history instance. The function passed will be called every time that a location change occurs. Any route matching/data loading that you need to perform should be triggered by this function.

The response handler function will be passed a "pending navigation" object. This object has four properties: location, action, finish, and cancel.

  • location - This is the location object that is being navigated to.
  • action - This is the string (POP, PUSH, or REPLACE) for the navigation type.
  • finish - Once all matching/loading has finished, then you need to call the finish method to finalize the navigation. If you do not call this, the navigation will not actually occur.
  • cancel - This method allows you to cancel a navigation. It should be called if another location change occurs while the current pending navigation is still pending. Calling cancel gives your history instance the opportunity to roll back to its previous state. This is only really necessary for POP navigation since the browser has already changed the location before Hickory knows about the location change. This method takes one argument, an action string; the action string may be used to alter the cancel behavior.

arguments

fn - The function to be called when the location changes.

confirmWith()

history.confirmWith((info, confirm, prevent) => {
  const result = window.confirm("Are you sure you want to navigate?");
  if (result) {
    confirm();
  } else {
    prevent();
  }
});

The confirmWith function allows you to register a function that will be called when navigation happens. This allows you to prevent navigation, which can be useful if you have a form whose data will be lost after navigation. If there is no registered confirmation function, then navigation will happen automatically.

Only one confirmation function can be registered at a time, so if you call confirmWith when there is already a confirmation function, the existing one will be removed.

arguments

fn - The function to be called to confirm the navigation. This will receive three arguments. The first one is an object with three properties: to is the locatin that you are navigating to, from is the location that you are navigating from, and action is the type of navigation. The second is a confirm function, which you should call when you want the navigation to happen. The third is a prevent function, which you should call when you want to stop the navigation.

removeConfirmation()

history.removeConfirmation();

The removeConfirmation function will remove the current confirmation function (if one exists). After calling removeConfirmation, navigation will happen automatically (until another confirmation function is added).

destroy()

history.destroy();

The destroy function allows you to remove all event listeners. Generally speaking, you will not need to call this. However, if for some reason you want to create a new history object, you should call this one on the existing history object .