update method

void update({ RouteInformation? configuration, BeamParameters? beamParameters, Object? data, bool buildBeamLocation = true, bool rebuild = true, bool updateParent = true, bool updateRouteInformation = true, bool replaceRouteInformation = false, bool takePriority = true, })

Main method to update the configuration of this delegate and its currentBeamLocation.

This "top-level" update is generally used for navigation between BeamLocations and not within a specific BeamLocation. For latter purpose, see BeamLocation.update. Nevertheless, update will work for navigation within BeamLocation.

Calling update will run the locationBuilder.

Beamer.of(context).update(
  state: BeamState.fromUriString('/xx'),
);

all of the beaming functions call update to really do the update.

beamParameters hold various parameters such as transitionDelegate and other that will be used for this update and stored in history.

data can be used to hold arbitrary Object throughout navigation. See BeamLocation.data for more information.

buildBeamLocation determines whether a BeamLocation should be created from configuration, using the locationBuilder. For example, when using beamTo and passing an already created BeamLocation, this can be false.

rebuild determines whether to call notifyListeners. This can be false if we already have built the UI and just want to notify the platform, e.g. browser, of the new RouteInformation.

updateParent is used in nested navigation to call update on parent.

updateRouteInformation determines whether to update the browser's URL. This is usually done through notifyListeners, but in specific cases, e.g. when rebuild is false, browser would not be updated. This is mainly used to not update the route information from parent, when it has already been done by this delegate.

Implementation

void update({
  RouteInformation? configuration,
  BeamParameters? beamParameters,
  Object? data,
  bool buildBeamLocation = true,
  bool rebuild = true,
  bool updateParent = true,
  bool updateRouteInformation = true,
  bool replaceRouteInformation = false,
  bool takePriority = true,
}) {
  if (takePriority) {
    this.takePriority();
  }

  if (_buildInProgress) {
    rebuild = false;
  }

  replaceRouteInformation
      ? SystemNavigator.selectSingleEntryHistory()
      : SystemNavigator.selectMultiEntryHistory();

  this.configuration = configuration != null
      ? Utils.createNewConfiguration(this.configuration, configuration)
      : currentBeamLocation.state.routeInformation.copyWith();

  // update beam parameters
  _currentBeamParameters = beamParameters ?? _currentBeamParameters;

  if (buildBeamLocation) {
    // build a BeamLocation from configuration
    _beamLocationCandidate = locationBuilder(
      this.configuration.copyWith(),
      _currentBeamParameters,
    );
  }

  // run guards on _beamLocationCandidate
  final context = _context;
  if (context != null) {
    final didApply = _runGuards(context, _beamLocationCandidate);
    _didRunGuards = true;
    if (didApply) {
      return;
    } else {
      // TODO revert configuration if guard just blocked navigation
    }
  }

  // adds the candidate to history
  // it will become currentBeamLocation after this step
  _updateBeamingHistory(_beamLocationCandidate);
  if (data != null) {
    currentBeamLocation.data = data;
  }

  routeListener?.call(this.configuration, this);

  // update parent if necessary
  if (this.updateParent && updateParent) {
    _parent?.update(
      configuration: this.configuration.copyWith(),
      rebuild: false,
      updateRouteInformation: false,
    );
  }

  // update browser history
  // if this is from nested Beamer
  // or
  // if rebuild was false (browser will not be notified implicitly)
  if (updateRouteInformation && active && (_parent != null || !rebuild)) {
    this.updateRouteInformation(this.configuration);
  }

  // initiate build
  if (rebuild) {
    notifyListeners();
  }
}