core-dropdown.html

<!--
Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<!--

`core-dropdown` is an element that is initially hidden and is positioned relatively to another
element, usually the element that triggers the dropdown. The dropdown and the triggering element
should be children of the same offsetParent, e.g. the same `<div>` with `position: relative`.
It can be used to implement dropdown menus, menu buttons, etc..

Example:

    <template is="auto-binding">
      <div relative>
        <core-icon-button id="trigger" icon="menu"></core-icon-button>
        <core-dropdown relatedTarget="{{$.trigger}}">
          <core-menu>
            <core-item>Cut</core-item>
            <core-item>Copy</core-item>
            <core-item>Paste</core-item>
          </core-menu>
        </core-dropdown>
      </div>
    </template>

Positioning
-----------

By default, the dropdown is absolutely positioned on top of the `relatedTarget` with the top and
left edges aligned. The `halign` and `valign` properties controls the various alignments. The size
of the dropdown is automatically restrained such that it is entirely visible on the screen. Use the
`margin`

If you need more control over the dropdown's position, use CSS. The `halign` and `valign` properties are
ignored if the dropdown is positioned with CSS.

Example:

    <style>
      /* manually position the dropdown below the trigger */
      core-dropdown {
        position: absolute;
        top: 38px;
        left: 0;
      }
    </style>

    <template is="auto-binding">
      <div relative>
        <core-icon-button id="trigger" icon="menu"></core-icon-button>
        <core-dropdown relatedTarget="{{$.trigger}}">
          <core-menu>
            <core-item>Cut</core-item>
            <core-item>Copy</core-item>
            <core-item>Paste</core-item>
          </core-menu>
        </core-dropdown>
      </div>
    </template>

@group Polymer Core Elements
@element core-dropdown
@homepage github.io
-->
<link href="../polymer/polymer.html" rel="import">

<link href="core-dropdown-overlay.html" rel="import">

<polymer-element name="core-dropdown">
<template>

  <link href="core-dropdown.css" rel="stylesheet">

  <core-dropdown-overlay id="overlay" target="{{}}" relatedTarget="{{relatedTarget}}" opened="{{opened}}" halign="{{halign}}" valign="{{valign}}" margin="{{margin}}" transition="{{transition}}"></core-dropdown-overlay>

  <content></content>

</template>
<script>

  Polymer({

    publish: {

      /**
       * The element associated with this dropdown, usually the element that triggers
       * the menu.
       *
       * @attribute relatedTarget
       * @type Node
       */
      relatedTarget: null,

      /**
       * If true, the menu is currently visible.
       *
       * @attribute opened
       * @type boolean
       * @default false
       */
      opened: false,

      /**
       * The horizontal alignment of the popup relative to `relatedTarget`. `left`
       * means the left edges are aligned together. `right` means the right edges
       * are aligned together.
       *
       * @attribute halign
       * @type 'left' | 'right'
       * @default 'left'
       */
      halign: 'left',

      /**
       * The vertical alignment of the popup relative to `relatedTarget`. `top` means
       * the top edges are aligned together. `bottom` means the bottom edges are
       * aligned together.
       *
       * @attribute valign
       * @type 'top' | 'bottom'
       * @default 'top'
       */
      valign: 'top',

      /**
       * A pixel amount around the dropdown that will be reserved. It's useful for
       * ensuring that, for example, a shadow displayed outside the dropdown will
       * always be visible.
       *
       * @attribute margin
       * @type number
       * @default 0
       */
      margin: 0,

      /**
       * The transition property specifies a string which identifies a 
       * <a href="../core-transition/">`core-transition`</a> element that 
       * will be used to help the overlay open and close. The default
       * `core-transition-fade` will cause the overlay to fade in and out.
       *
       * @attribute transition
       * @type string
       * @default null
       */
      transition: null

    }

  });

</script>
</polymer-element>