widgets/pages.js

  1. /*
  2.  * This file is part of AUX.
  3.  *
  4.  * AUX is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 3 of the License, or (at your option) any later version.
  8.  *
  9.  * AUX is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12.  * General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU General
  15.  * Public License along with this program; if not, write to the
  16.  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.  * Boston, MA  02110-1301  USA
  18.  */
  20. /**
  21.  * The <code>useraction</code> event is emitted when a widget gets modified by user interaction.
  22.  * The event is emitted for the option <code>show</code>.
  23.  *
  24.  * @event Pages#useraction
  25.  *
  26.  * @param {string} name - The name of the option which was changed due to the users action
  27.  * @param {mixed} value - The new value of the option
  28.  */
  29. import { addClass, toggleClass, isDomNode } from '../utils/dom.js';
  30. import { Container } from './container.js';
  31. import { ChildWidgets } from '../utils/child_widgets.js';
  32. import { defineRender } from '../renderer.js';
  34. function onPageSetActive(value) {
  35.   const pages = this.parent;
  37.   if (value) {
  38.     const index = pages.getPages().indexOf(this);
  39.     pages.showChild(this);
  40.     pages.update('show', index);
  41.     /**
  42.      * The page to show has changed.
  43.      *
  44.      * @param {Page} page - The {@link Page} instance of the newly selected page.
  45.      * @param {number} id - The ID of the page.
  46.      *
  47.      * @event Pages#changed
  48.      */
  49.     pages.emit('changed', this, index);
  50.   } else {
  51.     pages.hideChild(this);
  52.   }
  53. }
  55. function onPageAdded(page, position) {
  56.   const pages = this.widget;
  58.   page.addClass('aux-page');
  59.   page.on('set_active', onPageSetActive);
  61.   const current = pages.current();
  63.   if (page.get('active')) {
  64.     pages.set('show', position);
  65.   } else {
  66.     let show = pages.get('show');
  68.     // if the current active page has been moved, we have to update the
  69.     // show property
  70.     if (show >= position && show >= 0 && show < this.getList().length - 1) {
  71.       ++show;
  72.     }
  74.     // update all pages active option, possibly also that of the new page
  75.     pages.set('show', show);
  76.   }
  78.   // the new page is active
  79.   if (page.get('active')) {
  80.     // we don't want any animation
  81.     if (current && current !== page) pages.hideChild(current);
  83.     // we do not want to animate pages when they are being added
  84.     if (pages.isDrawn()) page.set('visible', true);
  85.     pages.showChild(page);
  86.   } else {
  87.     pages.hideChild(page);
  88.     page.forceHide();
  89.   }
  91.   /**
  92.    * A page was added to the Pages.
  93.    *
  94.    * @event Pages#added
  95.    *
  96.    * @param {Page} page - The {@link Page} which was added as a page.
  97.    */
  98.   pages.emit('added', page, position);
  99. }
  101. function onPageRemoved(page, position) {
  102.   const pages = this.widget;
  104.   page.removeClass('aux-page');
  105.   page.off('set_active', onPageSetActive);
  107.   const show = pages.get('show');
  108.   const length = this.getList().length;
  110.   if (position < show) {
  111.     pages.set('show', show - 1);
  112.   } else if (position === show) {
  113.     if (show < length) {
  114.       // show the next page
  115.       pages.set('show', show);
  116.     } else if (length) {
  117.       // show the previous page
  118.       pages.set('show', show - 1);
  119.     } else {
  120.       pages.set('show', -1);
  121.     }
  122.   }
  123.   /**
  124.    * A page was removed from the Pages
  125.    *
  126.    * @event Pages#removed
  127.    *
  128.    * @param {Page} page - The {@link Page} which was removed.
  129.    * @param {number} index - The index at which the container was.
  130.    */
  131.   pages.emit('removed', page, position);
  132. }
  134. /**
  135.  * Pages contains different pages ({@link Page}s) which can
  136.  * be swiched via option.
  137.  *
  138.  * @class Pages
  139.  *
  140.  * @param {Object} [options={ }] - An object containing initial options.
  141.  *
  142.  * @property {Array<Page|DOMNode|String>} [options.pages=[]] -
  143.  *   An array of either an instance of {@link Page} (or derivate),
  144.  *   a DOMNode or a string of HTML which gets wrapped in a new {@link Container}.
  145.  * @property {Integer} [options.show=-1] - The page to show. Set to -1 to hide all pages.
  146.  * @property {String} [options.animation="horizontal"] - The direction of the
  147.  *   flip animation, either `horizontal` or `vertical`.
  148.  *
  149.  * @extends Container
  150.  *
  151.  * @example
  152.  * var pages = new Pages({
  153.  *  pages: [
  154.  *   {
  155.  *    content: document.createElement("span"),
  156.  *   },
  157.  *   {
  158.  *    content: "<h1>Foobar</h1><p>Lorem ipsum dolor sit amet</p>",
  159.  *   }
  160.  *  ]
  161.  * });
  162.  */
  163. export class Pages extends Container {
  164.   static get _options() {
  165.     return {
  166.       direction: 'string',
  167.       pages: 'array',
  168.       show: 'int',
  169.       animation: 'string',
  170.     };
  171.   }
  173.   static get options() {
  174.     return {
  175.       direction: 'forward',
  176.       pages: [],
  177.       show: -1,
  178.       animation: 'horizontal',
  179.     };
  180.   }
  182.   static get static_events() {
  183.     return {
  184.       set_show: function (value) {
  185.         const list = this.pages.getList();
  187.         for (let i = 0; i < list.length; i++) {
  188.           const page = list[i];
  189.           page.update('active', i === value);
  190.         }
  191.       },
  192.     };
  193.   }
  195.   static get renderers() {
  196.     return [
  197.       defineRender('direction', function (direction) {
  198.         const element = this.element;
  199.         toggleClass(element, 'aux-forward', direction === 'forward');
  200.         toggleClass(element, 'aux-backward', direction === 'backward');
  201.       }),
  202.       defineRender('animation', function (animation) {
  203.         const element = this.element;
  204.         toggleClass(element, 'aux-vertical', animation === 'vertical');
  205.         toggleClass(element, 'aux-horizontal', animation === 'horizontal');
  206.       }),
  207.       defineRender('show', function (show) {
  208.         this.getPages().forEach((page, index) => {
  209.           if (index === show) {
  210.             page.addClass('aux-active');
  211.           } else {
  212.             page.removeClass('aux-active');
  213.           }
  214.         });
  215.       }),
  216.     ];
  217.   }
  219.   initialize(options) {
  220.     super.initialize(options);
  221.     /**
  222.      * The main DIV element. Has the class <code>.aux-pages</code>.
  223.      *
  224.      * @member Pages#element
  225.      */
  226.     this.pages = new ChildWidgets(this, {
  227.       filter: Page,
  228.     });
  229.     this.pages.on('child_added', onPageAdded);
  230.     this.pages.on('child_removed', onPageRemoved);
  231.   }
  233.   initialized() {
  234.     super.initialized();
  235.     this.addPages(this.options.pages);
  236.     this.set('show', this.options.show);
  237.   }
  239.   draw(O, element) {
  240.     addClass(element, 'aux-pages');
  242.     super.draw(O, element);
  243.   }
  245.   /**
  246.    * Adds an array of pages.
  247.    *
  248.    * @method Pages#addPages
  249.    *
  250.    * @property {Array<Page|DOMNode|String>} [options.pages=[]] -
  251.    *   An array of either an instance of {@link Page} (or derivate),
  252.    *   a DOMNode or a string which gets wrapped in a new {@link Page}.
  253.    *
  254.    * @example
  255.    * var p = new Pages();
  256.    * p.addPages(['foobar']);
  257.    *
  258.    */
  259.   addPages(pages) {
  260.     for (let i = 0; i < pages.length; i++) this.addPage(pages[i]);
  261.   }
  263.   createPage(content, options) {
  264.     if (typeof content === 'string' || content === void 0) {
  265.       if (!options) options = {};
  266.       const page = new Page(options);
  267.       page.element.innerHTML = content;
  268.       return page;
  269.     } else if (isDomNode(content)) {
  270.       if (content.tagName === 'TEMPLATE') {
  271.         content = content.content.cloneNode(true);
  272.       }
  274.       if (content.remove) content.remove();
  276.       if (!options) options = {};
  277.       const page = new Page(options);
  279.       page.element.appendChild(content);
  281.       return page;
  282.     } else if (content instanceof Page) {
  283.       return content;
  284.     } else {
  285.       throw new TypeError('Unexpected argument type.');
  286.     }
  287.   }
  289.   /**
  290.    * Adds a {@link Page} to the pages and a corresponding {@link Button}
  291.    *   to the pages {@link Navigation}.
  292.    *
  293.    * @method Pages#addPage
  294.    *
  295.    * @param {Page|DOMNode|String} content - The content of the page.
  296.    *   Either an instance of a {@link Page} (or derivate) widget,
  297.    *   a DOMNode or a string of HTML which gets wrapped in a new {@link Container}
  298.    *   with optional options from argument `options`.
  299.    * @param {integer|undefined} position - The position to add the new
  300.    *   page to. If undefined, the page is added at the end.
  301.    * @param {Object} [options={ }] - An object containing options for
  302.    *   the {@link Page} to be added as page if `content` is
  303.    *   either a string or a DOMNode.
  304.    * @emits Pages#added
  305.    */
  306.   addPage(content, position, options) {
  307.     const page = this.createPage(content, options);
  308.     const pages = this.getPages();
  309.     const element = this.element;
  310.     const length = pages.length;
  312.     if (position !== void 0 && typeof position !== 'number')
  313.       throw new TypeError('position: Argument must be a number.');
  315.     if (!(position >= 0 && position < length)) {
  316.       element.appendChild(page.element);
  317.     } else {
  318.       element.insertBefore(page.element, pages[position].element);
  319.     }
  321.     if (page.parent !== this) {
  322.       // if this page is a web component, the above appendChild would have
  323.       // already triggered a call to addChild
  324.       this.addChild(page);
  325.     }
  327.     return page;
  328.   }
  330.   /**
  331.    * Removes a page from the Pages.
  332.    *
  333.    * @method Pages#removePage
  334.    *
  335.    * @param {integer|Page} page - The container to remove. Either an
  336.    *   index or the {@link Page} widget generated by <code>addPage</code>.
  337.    * @param {Boolean} destroy - destroy the {@link Page} after removal.
  338.    *
  339.    * @emits Pages#removed
  340.    */
  341.   removePage(page, destroy) {
  342.     let position = -1;
  344.     if (page instanceof Page) {
  345.       position = this.pages.indexOf(page);
  346.     } else if (typeof page === 'number') {
  347.       position = page;
  348.       page = this.pages.at(position);
  349.     }
  351.     if (!page || position === -1) throw new Error('Unknown page.');
  353.     this.element.removeChild(page.element);
  355.     if (this.pages.at(position) === page) {
  356.       // NOTE: if we remove a child which is a web component,
  357.       // it will itself call removeChild
  358.       this.removeChild(page);
  359.     }
  361.     if (destroy) {
  362.       page.destroyAndRemove();
  363.     }
  364.   }
  366.   /**
  367.    * Removes all pages.
  368.    *
  369.    * @method Pages#empty
  370.    */
  371.   empty() {
  372.     while (this.getPages().length) this.removePage(0);
  373.   }
  375.   current() {
  376.     /**
  377.      * Returns the currently displayed page or null.
  378.      *
  379.      * @method Pages#current
  380.      */
  381.     return this.pages.at(this.options.show) || null;
  382.   }
  384.   /**
  385.    * Opens the first page of the pages. Returns <code>true</code> if a
  386.    * first page exists, <code>false</code> otherwise.
  387.    *
  388.    * @method Pages#first
  389.    *
  390.    * @returns {Boolean} True if successful, false otherwise.
  391.    */
  392.   first() {
  393.     if (this.getPages().length) {
  394.       this.set('show', 0);
  395.       return true;
  396.     }
  397.     return false;
  398.   }
  400.   /**
  401.    * Opens the last page of the pages. Returns <code>true</code> if a
  402.    * last page exists, <code>false</code> otherwise.
  403.    *
  404.    * @method Pages#last
  405.    *
  406.    * @returns {Boolean} True if successful, false otherwise.
  407.    */
  408.   last() {
  409.     const length = this.getPages().length;
  410.     if (length) {
  411.       this.set('show', length - 1);
  412.       return true;
  413.     }
  414.     return false;
  415.   }
  417.   /**
  418.    * Opens the next page of the pages. Returns <code>true</code> if a
  419.    * next page exists, <code>false</code> otherwise.
  420.    *
  421.    * @method Pages#next
  422.    *
  423.    * @returns {Boolean} True if successful, false otherwise.
  424.    */
  425.   next() {
  426.     const show = this.options.show;
  427.     const length = this.getPages().length;
  429.     if (show + 1 < length) {
  430.       this.set('show', show + 1);
  431.       return true;
  432.     }
  434.     return false;
  435.   }
  437.   /**
  438.    * Opens the previous page of the pages. Returns <code>true</code> if a
  439.    * previous page exists, <code>false</code> otherwise.
  440.    *
  441.    * @method Pages#prev
  442.    *
  443.    * @returns {Boolean} True if successful, false otherwise.
  444.    */
  445.   prev() {
  446.     const show = this.options.show;
  447.     const length = this.getPages().length;
  449.     if (show === 0) return false;
  451.     this.set('show', show - 1);
  453.     return show - 1 < length;
  454.   }
  456.   set(key, value) {
  457.     if (key === 'show') {
  458.       if (value !== this.options.show) {
  459.         if (value > this.options.show) {
  460.           this.set('direction', 'forward');
  461.         } else {
  462.           this.set('direction', 'backward');
  463.         }
  464.       }
  465.     } else if (key === 'pages') {
  466.       this.options.pages.forEach((page) => this.removePage(page, true));
  467.       value = this.addPages(value || []);
  468.     }
  469.     return super.set(key, value);
  470.   }
  472.   getPages() {
  473.     return this.pages.getList();
  474.   }
  476.   destroy() {
  477.     this.empty();
  478.     super.destroy();
  479.   }
  480. }
  482. /**
  483.  * Page is the child widget to be used in {@link Pages}.
  484.  *
  485.  * @class Page
  486.  *
  487.  * @param {Object} [options={ }] - An object containing initial options.
  488.  *
  489.  * @property {String} [options.label=""] - The label of the pages corresponding button
  490.  * @property {Number} [options.hiding_duration=-1] - Default to auto-determine hiding duration from style.
  491.  * @property {Number} [options.showing_duration=-1] - Default to auto-determine showing duration from style.
  492.  *
  493.  * @extends Container
  494.  */
  495. export class Page extends Container {
  496.   static get _options() {
  497.     return {
  498.       label: 'string',
  499.       icon: 'string',
  500.     };
  501.   }
  503.   static get options() {
  504.     return {
  505.       label: '',
  506.       icon: '',
  507.       hiding_duration: -1,
  508.       showing_duration: -1,
  509.       role: 'tabpanel',
  510.       active: false,
  511.     };
  512.   }
  513. }