third_party/polymer/components/core-layout-trbl/core-layout-trbl.html

   1 <!--
   2 Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
   3 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   6 Code distributed by Google as part of the polymer project is also
   7 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   8 -->
   9
  10 <!--
  11 `<core-layout-trbl>` arranges nodes horizontally via absolute positioning.
  12 Set the `vertical` attribute (boolean) to arrange vertically instead.
  13
  14 `<core-layout-trbl>` arranges it's <b>sibling elements</b>, not
  15 it's children.
  16
  17 One arranged node may be marked as elastic by giving it a `flex`
  18 attribute (boolean).
  19
  20 You may remove a node from layout by giving it a `nolayout`
  21 attribute (boolean).
  22
  23 CSS Notes:
  24
  25 `padding` is ignored on the parent node.
  26 `margin` is ignored on arranged nodes.
  27 `min-width` is ignored on arranged nodes, use `min-width` on the parent node
  28 instead.
  29
  30 Example:
  31
  32 Arrange three `div` into columns. `flex` attribute on Column Two makes that
  33 column elastic.
  34
  35      <core-layout-trbl></core-layout-trbl>
  36      <div>Column One</div>
  37      <div flex>Column Two</div>
  38      <div>Column Three</div>
  39
  40 Remember that `<core-layout-trbl>` arranges it's sibling elements, not it's children.
  41
  42 If body has width 52 device pixels (in this case, ascii characters), call that 52px.
  43 Column One has it's natural width of 12px (including border), Column Three has it's
  44 natural width of 14px, body border uses 2px, and Column Two automatically uses the
  45 remaining space: 24px.
  46
  47      |-                    52px                        -|
  48      ----------------------------------------------------
  49      ||Column One||      Column Two      ||Column Three||
  50      ----------------------------------------------------
  51       |-  12px  -||-     (24px)         -||    14px   -|
  52
  53 As the parent node resizes, the elastic column reacts via CSS to adjust it's size.
  54 No javascript is used during parent resizing, for best performance.
  55
  56 Changes in content or sibling size are not handled automatically.
  57
  58      ----------------------------------------------------------------
  59      ||Column One|             Column Two             |Column Three||
  60      ----------------------------------------------------------------
  61
  62      --------------------------------------
  63      ||Column One|Column Two|Column Three||
  64      --------------------------------------
  65
  66 Arrange in rows by adding the `vertical` attribute.
  67
  68 Example:
  69
  70      <core-layout-trbl vertical></core-layout-trbl>
  71      <div>Row One</div>
  72      <div flex>Row Two</div>
  73      <div>Row Three</div>
  74
  75 This setup will cause Row Two to stretch to fill the container.
  76
  77      -----------             -----------
  78      |---------|             |---------|
  79      |         |             |         |
  80      |Row One  |             |Row One  |
  81      |         |             |         |
  82      |---------|             |---------|
  83      |         |             |         |
  84      |Row Two  |             |Row Two  |
  85      |         |             |         |
  86      |---------|             |         |
  87      |         |             |         |
  88      |Row Three|             |         |
  89      |         |             |---------|
  90      |---------|             |         |
  91      -----------             |Row Three|
  92                              |         |
  93                              |---------|
  94                              |---------|
  95
  96 Layouts can be nested arbitrarily.
  97
  98      <core-layout-trbl></core-layout-trbl>
  99      <div>Menu</div>
 100      <div flex>
 101         <core-layout-trbl vertical></core-layout-trbl>
 102         <div>Title</div>
 103         <div>Toolbar</div>
 104         <div flex>Main</div>
 105         <div>Footer</div>
 106      </div>
 107
 108 Renders something like this
 109
 110      --------------------------------
 111      ||Menu     ||Title            ||
 112      ||         ||-----------------||
 113      ||         ||Toolbar          ||
 114      ||         ||-----------------||
 115      ||         ||Main             ||
 116      ||         ||                 ||
 117      ||         ||-----------------||
 118      ||         ||Footer           ||
 119      --------------------------------
 120
 121 @group Polymer Core Elements
 122 @element core-layout-trbl
 123 -->
 124 <link rel="import" href="../polymer/polymer.html">
 125
 126 <polymer-element name="core-layout-trbl" attributes="vertical">
 127
 128   <template>
 129
 130     <style>
 131       :host {
 132         display: none;
 133       }
 134     </style>
 135
 136   </template>
 137
 138   <script>
 139
 140     Polymer('core-layout-trbl', {
 141
 142       vertical: false,
 143
 144       ready: function() {
 145         this.setAttribute('nolayout', '');
 146       },
 147
 148       attached: function() {
 149         this.asyncMethod(function() {
 150           this.prepare();
 151           this.layout();
 152         });
 153       },
 154
 155       prepare: function() {
 156         var parent = this.parentNode.host || this.parentNode;
 157         // explicit position harmful on <body>
 158         if (parent.localName !== 'body') {
 159         // may recalc
 160           var cs = window.getComputedStyle(parent);
 161           if (cs.position === 'static') {
 162             parent.style.position = 'relative';
 163           }
 164           //parent.style.overflow = 'hidden';
 165         }
 166         // changes will cause another recalc at next validation step
 167         var stylize = this.stylize, vertical;
 168         this.parentNode.childNodes.array().forEach(function(c, i) {
 169           if (c.nodeType === Node.ELEMENT_NODE && !c.hasAttribute('nolayout')) {
 170             stylize(c, {
 171               position: 'absolute',
 172               boxSizing: 'border-box',
 173               MozBoxSizing: 'border-box',
 174             });
 175             // test for auto-vertical
 176             if (vertical === undefined) {
 177               vertical = (c.offsetWidth == 0 && c.offsetHeight !== 0);
 178             }
 179           }
 180         });
 181         this.vertical = this.vertical || vertical;
 182       },
 183
 184       /**
 185        * Arrange sibling nodes end-to-end in one dimension.
 186        *
 187        * Arrangement is horizontal unless the `vertical`
 188        * attribute is applied on this node.
 189        *
 190        * @method layout
 191        */
 192       layout: function() {
 193         var parent = this.parentNode.host || this.parentNode;
 194         var vertical = this.vertical;
 195         var ww = 0, hh = 0, pre = [], fit, post = [];
 196         var list = pre;
 197         // gather element information (at most one recalc)
 198         this.parentNode.childNodes.array().forEach(function(c, i) {
 199           if (c.nodeType===Node.ELEMENT_NODE && !c.hasAttribute('nolayout')) {
 200             var info = {
 201               element: c,
 202               w: c.offsetWidth,
 203               h: c.offsetHeight
 204             };
 205             if (!c.hasAttribute('fit') && !c.hasAttribute('flex')) {
 206               ww += c.offsetWidth;
 207               hh += c.offsetHeight;
 208               list.push(info);
 209             } else {
 210               fit = c;
 211               list = post;
 212               ww = hh = 0;
 213             }
 214           }
 215         });
 216         // update layout styles (invalidate, no recalc)
 217         var v = 0;
 218         var mxp = 0, myp = 0;
 219         var stylize = this.stylize;
 220         pre.forEach(function(info) {
 221           if (vertical) {
 222             stylize(info.element, {
 223               top: v + 'px', right: mxp, height: info.h + 'px', left: mxp
 224             });
 225           } else {
 226             stylize(info.element, {
 227               top: myp, width: info.w + 'px', bottom: myp, left: v + 'px'
 228             });
 229           }
 230           v += vertical ? info.h : info.w;
 231         });
 232         if (fit) {
 233           if (vertical) {
 234             stylize(fit, {
 235               top: v + 'px', right: mxp, bottom: hh + 'px', left: mxp
 236             });
 237           } else {
 238             stylize(fit, {
 239               top: myp, right: ww + 'px', bottom: myp, left: v + 'px'
 240             });
 241           }
 242           v = vertical ? hh : ww;
 243           post.forEach(function(info) {
 244             v -= vertical ? info.h : info.w;
 245             if (vertical) {
 246               stylize(info.element, {
 247                 height: info.h + 'px', right: mxp, bottom: v + 'px', left: mxp
 248               });
 249             } else {
 250               stylize(info.element, {
 251                 top: myp, right: v + 'px', bottom: myp, width: info.w + 'px'
 252               });
 253             }
 254           });
 255         }
 256       },
 257
 258       stylize: function(element, styles) {
 259         var style = element.style;
 260         Object.keys(styles).forEach(function(k){
 261           style[k] = styles[k];
 262         });
 263       }
 264
 265   });
 266
 267   </script>
 268
 269 </polymer-element>