gerrit/polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html

<!--
Copyright (C) 2017 The Android Open Source Project

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<script>
  (function(window) {
    'use strict';

    // Navigation parameters object format:
    //
    // Each object has a `view` property with a value from Gerrit.Nav.View. The
    // remaining properties depend on the value used for view.
    //
    //  - Gerrit.Nav.View.CHANGE:
    //    - `id`, required, String: the numeric ID of the change.
    //
    // - Gerrit.Nav.View.SEARCH:
    //    - `owner`, optional, String: the owner name.
    //    - `project`, optional, String: the project name.
    //    - `branch`, optional, String: the branch name.
    //    - `topic`, optional, String: the topic name.
    //    - `statuses`, optional, Array<String>: the list of change statuses to
    //        search for. If more than one is provided, the search will OR them
    //        together.
    //
    //  - Gerrit.Nav.View.DIFF:
    //    - `changeId`, required, String: the numeric ID of the change.
    //    - `path`, required, String: the filepath of the diff.
    //    - `patchNum`, required, Number, the patch for the right-hand-side of
    //        the diff.
    //    - `basePatchNum`, optional, Number, the patch for the left-hand-side
    //        of the diff. If `basePatchNum` is provided, then `patchNum` must
    //        also be provided.

    window.Gerrit = window.Gerrit || {};

    // Prevent redefinition.
    if (window.Gerrit.hasOwnProperty('Nav')) { return; }

    const uninitialized = () => {
      console.warn('Use of uninitialized routing');
    };

    window.Gerrit.Nav = {

      View: {
        CHANGE: 'change',
        SEARCH: 'search',
        DIFF: 'diff',
      },

      /** @type {Function} */
      _navigate: uninitialized,

      /** @type {Function} */
      _generateUrl: uninitialized,

      _checkPatchRange(patchNum, basePatchNum) {
        if (basePatchNum && !patchNum) {
          throw new Error('Cannot use base patch number without patch number.');
        }
      },

      /**
       * Setup router implementation.
       * @param {Function} handleNavigate
       * @param {Function} generateUrl
       */
      setup(navigate, generateUrl) {
        this._navigate = navigate;
        this._generateUrl = generateUrl;
      },

      destroy() {
        this._navigate = uninitialized;
        this._generateUrl = uninitialized;
      },

      /**
       * Generate a URL for the given route parameters.
       * @param {Object} params
       * @return {String}
       */
      _getUrlFor(params) {
        return this._generateUrl(params);
      },

      /**
       * @param {String} project The name of the project.
       * @return {String}
       */
      getUrlForProject(project) {
        return this._getUrlFor({
          view: Gerrit.Nav.View.SEARCH,
          project,
        });
      },

      /**
       * @param {String} branch The name of the branch.
       * @param {String} project The name of the project.
       * @param {String} status The status to search.
       * @return {String}
       */
      getUrlForBranch(branch, project, status) {
        return this._getUrlFor({
          view: Gerrit.Nav.View.SEARCH,
          branch,
          project,
          statuses: [status],
        });
      },

      /**
       * @param {String} topic The name of the topic.
       * @return {String}
       */
      getUrlForTopic(topic) {
        return this._getUrlFor({
          view: Gerrit.Nav.View.SEARCH,
          topic,
          statuses: ['open', 'merged'],
        });
      },

      /**
       * @param {!Object} change The change object.
       * @param {Number} opt_patchNum
       * @param {Number} opt_basePatchNum
       * @return {String}
       */
      getUrlForChange(change, opt_patchNum, opt_basePatchNum) {
        this._checkPatchRange(opt_patchNum, opt_basePatchNum);
        return this._getUrlFor({
          view: Gerrit.Nav.View.CHANGE,
          id: change._number,
          patchNum: opt_patchNum,
          basePatchNum: opt_basePatchNum,
        });
      },

      /**
       * @param {!Object} change The change object.
       * @param {Number} opt_patchNum
       * @param {Number} opt_basePatchNum
       * @return {String}
       */
      navigateToChange(change, opt_patchNum, opt_basePatchNum) {
        this._navigate(this.getUrlForChange(change, opt_patchNum,
            opt_basePatchNum));
      },

      /**
       * @param {!Object} change The change object.
       * @param {!String} path The file path.
       * @param {Number} opt_patchNum
       * @param {Number} opt_basePatchNum
       * @return {String}
       */
      getUrlForDiff(change, path, opt_patchNum, opt_basePatchNum) {
        this._checkPatchRange(opt_patchNum, opt_basePatchNum);
        return this._getUrlFor({
          view: Gerrit.Nav.View.DIFF,
          changeId: change._number,
          path,
          patchNum: opt_patchNum,
          basePatchNum: opt_basePatchNum,
        });
      },

      /**
       * @param {!Object} change The change object.
       * @param {!String} path The file path.
       * @param {Number} opt_patchNum
       * @param {Number} opt_basePatchNum
       */
      navigateToDiff(change, path, opt_patchNum, opt_basePatchNum) {
        this._navigate(this.getUrlForDiff(change, path, opt_patchNum,
            opt_basePatchNum));
      },

      /**
       * @param {String} owner The name of the owner.
       * @return {String}
       */
      getUrlForOwner(owner) {
        return this._getUrlFor({
          view: Gerrit.Nav.View.SEARCH,
          owner,
        });
      },
    };
  })(window);
</script>