Navigation

This guide describes the navigation events, and shows how to load URLs and files, filter navigation requests, work with navigation history, etc.

Loading the application

To load the application’s main page, execute this code:

browser->loadUrl(app->baseUrl());

Loading URL

To navigate to a URL you can use one of the following methods:

• Browser::loadUrl(const std::string& url). This is an alias for the method below.
• Navigation::loadUrl(const std::string& url)
• Navigation::loadUrl(const std::string& url, const LoadUrlOptions& options)

The following example shows how to navigate to https://www.google.com:

browser->navigation()->loadUrl("https://www.google.com");

The code above requests navigation to the given resource and exits immediately. It does not wait until the resource is loaded completely.

If you need to block the current thread execution until the resource is loaded completely, use this code:

// Will automatically unblock after `kDefaultNavigationTimeoutInSeconds`.
browser->navigation()->loadUrlAndWait("https://www.google.com");

// Will block for no longer than 10 seconds.
browser->navigation()->loadUrlAndWait("https://www.google.com", 10);

Check out the API reference for more details.

Loading a local file

You can use the same methods to load HTML files from the local file system. You just need to provide an absolute path to the HTML file instead of a URL.

navigation->loadUrl("C:\\www\\index.html");

Reloading

There are several options to reload the currently loaded web page:

Reload using HTTP cache:

navigation->reload();

Reload ignoring HTTP cache:

navigation->reloadIgnoringCache();

Reload using HTTP cache and check for repost:

navigation->reloadAndCheckForRepost();

Reload ignoring HTTP cache and check for repost:

navigation->reloadIgnoringCacheAndCheckForRepost();

Stopping

Use the Navigation::stop() method to cancel any pending navigation or download operation, and stop any dynamic page elements, such as background sounds and animations:

navigation->stop();

Back & forward

Molybden allows working with the navigation back-forward history list.

When you create a browser instance it navigates to the about:blank web page by default, so there is always one entry in the navigation back-forward list.

To load the previous location in the back-forward list use the following approach:

if (navigation->canGoBack()) {
  navigation->goBack();
}

To load the next location in the back-forward list use:

if (navigation->canGoForward()) {
  navigation->goForward();
}

To navigate to the entry at a specific index in the back-forward list use:

if (index >= 0 && index < navigation->entryCount()) {
  navigation->goToIndex(index);
}

You can go through the back-forward list and get the details about every navigation entry:

for (uint32_t index = 0; index < navigation->entryCount(); index++) {
  NavigationEntry entry = navigation->entryAtIndex(index);
  std::cout << entry.url << std::endl;
  std::cout << entry.title << std::endl;
}

You can modify the back-forward list by removing the entries:

// Returns the number of entries in the back/forward list.
uint32_t entryCount = navigation->entryCount();
for (uint32_t i = entryCount - 2; i >= 0; i--) {
  navigation->removeEntryAtIndex(i);
}

Filtering URLs

You can decide whether navigation request to a specific URL should be ignored or not.

The following code demonstrates how to ignore navigation requests to all URLs that start with https://www.google:

navigation->onStartNavigation = [](const StartNavigationArgs& args,
                                   StartNavigationAction action) {
  action.ignore();
};

Filtering resources

Using the Network::onBeforeUrlRequest delegate you can decide whether the resources such as HTML, image, JavaScript or CSS file, favicon, etc. should be loaded. By default, all resources are loaded.

The following example demonstrates how to suppress all images:

auto network = profile->network();
network->onBeforeUrlRequest = [](const BeforeUrlRequestArgs& args,
                                 BeforeUrlRequestAction action) {
  if (args.request.resource_type == ResourceType::kImage) {
    action.cancel();
  } else {
    action.proceed();
  }
};

Navigation events

Loading a web page is a complex process during which different navigation events are fired. The following diagram shows the order in which the navigation events might be fired when loading a web page:

Load started

To get notifications when content loading has started use the LoadStarted event:

navigation->onLoadStarted += [](const LoadStarted& event) {};

This event corresponds to the moment when the spinner of the tab starts spinning.

Load finished

To get notifications when content loading has finished use the LoadFinished event. For example:

navigation->onLoadFinished += [](const LoadFinished& event) {};

This event corresponds to the moment when the spinner of the tab stops spinning.

Navigation started

To get notifications when navigation has started use the NavigationStarted event. For example:

navigation->onNavigationStarted += [](const NavigationStarted& event) {
  std::cout << event.url << std::endl;
  std::cout << event.is_same_document << std::endl;
};

Navigation stopped

To get notifications when navigation has stopped use the NavigationStopped event:

navigation->onNavigationStopped += [](const NavigationStopped& event) {};

This event is fired when navigation is stopped via the Navigation::stop() method.

Navigation redirected

To get notifications when navigation has been redirected to a new URL use the NavigationRedirected event:

navigation->onNavigationRedirected += [](const NavigationRedirected& event) {};

Navigation finished

To get notifications when navigation has finished use the NavigationFinished event:

navigation->onNavigationFinished += [](const NavigationFinished& event) {};

This event is fired when navigation is committed, aborted, or replaced by a new one. To know if the navigation has committed, use NavigationFinished::has_committed. Use NavigationFinished::is_error_page to know if the navigation resulted in an error page.

If the event is called because the navigation committed, the document load will still be ongoing.

The event is fired by same-document (in the scope of the same document) navigations, such as fragment navigations or window.history.pushState()/window.history.replaceState(), which will not result in a document change. Use NavigationFinished::is_same_document to check if it is a same-document navigation.

Frame load finished

To get notifications when content loading in the frame has finished use the FrameLoadFinished

event:

navigation->onFrameLoadFinished += [](const FrameLoadFinished& event) {};

This event corresponds to the moment when the content in the has been loaded completely.

Frame load failed

To get notifications when content loading in the frame has failed for some reason, use the FrameLoadFailed event:

navigation->onFrameLoadFailed += [](const FrameLoadFailed& event) {};

Frame document load finished

To get notifications when the document loading in the Frame has finished use the FrameDocumentLoadFinished event:

navigation->onFrameDocumentLoadFinished += [](const FrameDocumentLoadFinished& event) {};

At this point, deferred scripts were executed, and the content scripts marked “document_end” get injected into the frame.