{ "file": "addon/services/fountainhead.js", "content": "
import Ember from 'ember';\nimport Service from 'ember-service';\nimport $ from 'jquery';\nconst { ActionHandler } = Ember;\n\n/**\n * This is the primary service backing Fountianhead and handles configurations,\n * addon methods and storage of the generated documentation meta data. Important\n * members include:\n * - {{c-l 'apiNamespace'}}: Configures fetch service namespace\n * - {{c-l 'meta'}}: Generated documentation metadata\n * - {{c-l 'fetchMeta'}}: Public method called in the `beforeModel` of either the\n *   `api` or `guides` route and fetches documentation meta data\n * - {{c-l 'checkScrollToSection'}}: Action called when checking for auto scroll\n *   target\n * @class Fountainhead\n * @constructor\n * @extends Ember.Service\n */\nexport default Service.extend(ActionHandler, {\n\n  // Properties\n  // ---------------------------------------------------------------------------\n  /**\n   * All Fountainhead API requests are prefixed with this namespace. If you\n   * export your docs JSON files to a non-default location, or your application\n   * is served under a url namespace, you can overwrite this property to match your\n   * endpoint's root url namespace.\n   * @property apiNamespace\n   * @type {string}\n   * @public\n   * @default '/docs'\n   */\n  apiNamespace: '/docs',\n  /**\n   * When using the History Location type, this will match the hash fragment that is\n   * used for linking to specific documentation headers/properties. Ember Router\n   * doesn't seem to notice these changes? so we track them and pass them down to the\n   * page components where they trigger page scrolls when the back button is used.\n   * @property fragmentId\n   * @protected\n   * @type {string}\n   * @default ''\n   */\n  fragmentId: '',\n  /**\n   * Documentation meta fetched from `/meta.json`. Contains high level map\n   * of modules, classes and guides available in documentation. Is generated in\n   * {{c-l module='Lib'}}.\n   *\n   * ```javascript\n   * // meta.json Object Shape:\n   * {\n   *   classes: [],\n   *   description: '',\n   *   guides: [],\n   *   hashRouting: boolean\n   *   modules: [],\n   *   name: '',\n   *   parser: '',\n   *   repository: '',\n   *   version: ''\n   * }\n   * ```\n   *\n   * ## `hashRouting` and Page Load Scrolling With Fragment Ids\n   * Fountainhead has automatic scrolling on page load for links with a target id in\n   * them. For consuming applications using history location we use fragments ids for\n   * the target:\n   * `https://yourdocs.com/guides/your-guide#scroll-target`\n   *\n   * For consuming applications using hash location, the meta response will have\n   * property `hashRouting` set to true. This flags Fountainhead to use a query\n   * parameter for the scroll target:\n   * `https://yourdocs.com/#/guides/your-guide?id=scroll-target`\n   *\n   * Although this requires generating different link text and handling scrolling\n   * targets two different ways, it allows us to have clean urls with fragments for\n   * apps that have updated to history location while still supporting apps\n   * with hash location routing.\n   *\n   * This property is used throughout Fountainhead when checking which routing the\n   * consuming app is using.\n   * @property meta\n   * @type {?Object}\n   * @default null\n   */\n  meta: null,\n  /**\n   * Set to true if the call for documentation meta data fails. Almost always this\n   * means the user has not generated documentation yet, so the {{c-l class='Route.API'}}\n   * route uses this to show getting started instructions when there is an error.\n   * @property metaError\n   * @type {Boolean}\n   * @public\n   * @default false\n   */\n  metaError: false,\n\n  // Methods\n  // ---------------------------------------------------------------------------\n  /**\n   * Fires request for documentation meta data and returns the promise. This\n   * method is called in the `beforeModel` of either the `docs` or `guides`\n   * route, whichever is entered first.\n   *\n   * {{#fountainhead-alert brand='info' dismiss=false}}\n   *   {{fountainhead-svg svgId='info'}} If the request fails {{cross-link item='metaError'}} will be set to `true`.\n   * {{/fountainhead-alert}}\n   * @method fetchMeta\n   * @public\n   * @return {Promise}\n   */\n  fetchMeta() {\n    return $.get(`${this.get('apiNamespace')}/meta.json`).then(\n      meta => this.set('meta', meta),\n      error => this.set('metaError', true)\n    );\n  },\n\n  // Actions\n  // ---------------------------------------------------------------------------\n  actions: {\n    /**\n     * Reset the tracked fragment. Should be called when leaving routes b/c a hash\n     * change event will not fire fire for the new clicked\n     * @method setFragmentId\n     */\n    setFragmentId(id='') {\n      this.set('fragmentId', id);\n    },\n    /**\n     * Begins tracking the `location.hash` to pass down to page components. See\n     * {{c-l 'fragmentId'}} for details.\n     * @method trackHash\n     * @public\n     * @action\n     */\n    trackHash() {\n      // event only fires on change, synchronize current hash with service fragmentId\n      this.set('fragmentId', location.hash.slice(1) || '');\n\n      // With same type and function, `addEventListener` should discard duplicated\n      // listener calls\n      const hashChange = () => {\n        this.set('fragmentId', location.hash.slice(1));\n      };\n      window.addEventListener('hashchange', hashChange, false);\n    }\n  }\n});\n
" }