SemanSemantic-UItic-UI/server/documents/modules/popup.html.eco

---
layout      : 'default'
css         : 'popup'

title       : 'Popup'
description : 'A popup displays additional information on top of a page element'
type        : 'UI Module'
---
<script src="/javascript/popup.js"></script>

<%- @partial('header', { tabs: 'module' }) %>
<div class="main container">

  <div class="ui active tab" data-tab="definition">


    <div class="peek">
      <div class="ui vertical pointing secondary menu">
        <a class="active item">Types</a>
        <a class="item">Variations</a>
      </div>
    </div>

    <h2 class="ui dividing header">
      Types
    </h2>

    <div class="example">
      <h3 class="ui header">Popup</h3>
      <p>A standard popup</p>
      <i class="heart circular icon link" data-content="Hello, I am a pop-up."></i>
    </div>

    <div class="example">
      <h3 class="ui header">Title</h3>
      <p>A popup can be formatted with a title</p>
      <img src="/images/demo/photo.jpg" data-title="PonyDog22" data-content="Ponydog has been a member for 22 days" class="ui avatar image"> PonyDog22
    </div>

    <div class="example">
      <h3 class="ui header">HTML</h3>
      <p>A popup can be formatted with html</p>
      <i class="circular heart icon link" data-html="Average Rating: <div class='ui star rating'><i class='active icon'></i><i class='active icon'></i><i class='active icon'></i><i class='icon'></i><i class='icon'></i></div>"></i>
    </div>

    <h2 class="ui dividing header">Variations</h2>

    <div class="example">
      <h3 class="ui header">Size</h3>
      <p>A popup can be large or small</p>
      <i class="circular heart icon link" data-content="Hello. This is a small popup" data-variation="small"></i>
      <i class="circular heart icon link" data-content="Hello. This is a large popup" data-variation="large"></i>
    </div>

    <div class="example">
      <h3 class="ui header">Inverted</h3>
      <p>A popup can have its colors inverted</p>
      <i class="circular heart icon link" data-content="Hello. This is an inverted popup" data-variation="inverted"></i>
    </div>
  </div>

  <div class="ui tab" data-tab="usage">

    <h2 class="ui dividing header">Initializing</h2>

    <h3 class="ui header">Initializing an popup</h3>
    <div class="code">
    $('.ui.popup')
      .popup()
    ;
    </div>

    <div class="no example">
      <h3 class="ui header">Including content with HTML Metadata</h3>
      <p>Frequently used settings like, title, content, html, or offset or variation, can be included in html metadata<p>
      <div class="ui info icon ignored message">
        <i class="info icon"></i>
        <div class="content">
          <div class="header">Specifying Content</div>
          <p>Popups can specify content in three ways:<p>
          <ul class="list">
            <li>Using html <code>title</code> attribute</li>
            <li>Using <code>data-content</code> attribute</li>
            <li>Using <code>data-html</code> for specific html</li>
            <li>Using the content property in the initialization of the popup</li>
          </ul>
          <p>Popups can also specify some other frequently used settings using metadata<p>
          <ul class="list">
            <li><code>data-variation</code>: the popup variation to use </li>
            <li><code>data-offset</code>: a pixel offset correction for popup</li>
            <li><code>data-position</code>: the side to position popup on</li>
            <li><code>data-variation</code>: the popup variation to use </li>
          </ul>
        </div>
      </div>
      <h4 class="ui header">Initializing with metadata</h4>
      <div class="code" data-type="html">
        <i class="heart icon" title="Hello I am a popup"></i>
      </div>
      <div class="ui horizontal divider">Or</div>
      <h4 class="ui header">Initializing with javascript content</h4>
      <div class="code">
      $('.ui.popup')
        .popup({
          content: 'Hello I am a popup'
        })
      ;
      </div>
    </div>

    <h2 class="ui dividing header">Behavior</h2>

    <p>All the following <a href="/module.html#/behavior">behaviors</a> can be called using the syntax:</p>
    <div class="code">
    $('.your.element')
      .popup('behavior name', argumentOne, argumentTwo)
    ;
    </div>

    <table class="ui definition celled sortable table segment">
      <thead>
        <th>Behavior</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>show</td>
          <td>Shows popup</td>
        </tr>
        <tr>
          <td>hide</td>
          <td>Hides popup</td>
        </tr>
        <tr>
          <td>hide all</td>
          <td>Hides all visible pop ups on the page</td>
        </tr>
        <tr>
          <td>toggle</td>
          <td>Toggles visibility of popup</td>
        </tr>
        <tr>
          <td>is visible</td>
          <td>Returns whether popup is visible</td>
        </tr>
        <tr>
          <td>is hidden</td>
          <td>Returns whether popup is hidden</td>
        </tr>
        <tr>
          <td>exists</td>
          <td>Returns whether popup is created and inserted into the page</td>
        </tr>
        <tr>
          <td>set position(position)</td>
          <td>Repositions a popup</td>
        </tr>
        <tr>
          <td>remove</td>
          <td>Removes popup from the page</td>
        </tr>
      </tbody>
    </table>

  </div>


  <div class="ui tab" data-tab="examples">

    <div class="example">
      <h3 class="ui header">Specifying a trigger event</h3>
      <p>A popup trigger event can be specified</p>
      <div class="evaluated code">
    $('.example .teal.button')
      .popup({
        on: 'click'
      })
    ;
    $('.example input')
      .popup({
        on: 'focus'
      })
    ;
      </div>
      <div class="ui teal button" data-title="Using click events" data-content="Clicked popups will close if you click away, but not if you click inside the popup">Click Me</div>
      <div class="ui icon input">
        <input type="text" placeholder="Focus me..." data-content="You can use me to enter data">
        <i class="search icon"></i>
      </div>
    </div>

    <div class="example">
      <h3 class="ui header">Target Element</h3>
      <p>A popup can specify a different target element than itself to show a popup</p>
      <div class="evaluated code">
    $('.test.button')
      .popup({
        position : 'top right',
        target   : '.test.image',
        title    : 'My favorite dog',
        content  : 'My favorite dog would like other dogs as much as themselves'
      })
    ;
      </div>
      <div class="ui basic test button">Hover Me</div>
      <div class="ui divider"></div>
      <img class="medium ui test image" src="/images/demo/photo.jpg">

      <h3 class="ui header">Inline or relative to page</h3>
      <p>A popup can either be inserted directly after an element, or added as a child element to the page's <code>body</code>.</p>
      <div class="ui positive message">
        Using inline will allow your popups to go places other popups can't go, like inside <code>fixed</code> or <code>absolutely</code> positioned elements
      </div>
      <div class="ui info message">
        If you want to style each popup individually it makes sense to keep popup <code>inline: true</code>. If you are worried that your pop up might mistakingly inherit styles that it shouldn't, you should set <code>inline: false</code>.
      </div>
      <div class="code" data-type="css">
      /* this will only style the popup if inline is true */
      .example .popup {
        color: #FF0000;
      }
      </div>
      <div class="evaluated code">
    $('.inline.icon')
      .popup({
        inline: true
      })
    ;
      </div>
      <i class="heart circular icon link" data-content="This is a child element to the page's body and will not be styled" ></i>
      <i class="mail inline circular icon link" data-content="This popup was inserted inline and will be styled" ></i>

    </div>
    <div class="position example">
      <h3 class="ui header">Positioning</h3>
      <p>A popup can be positioned to any side of an element. If space is not available, it will automatically search for a similar alternative position to use.</p>
      <div class="ui segment">
        <i class="square inverted red heart icon link" data-content="Top Left" data-position="top left"></i>
        <i class="square inverted red heart icon link" data-content="Top Center" data-position="top center"></i>
        <i class="square inverted red heart icon link" data-content="Top Right" data-position="top right"></i>
        <i class="square inverted red heart icon link" data-content="Right Center" data-position="right center"></i>
        <i class="square inverted red heart icon link" data-content="Bottom Right" data-position="bottom right"></i>
        <i class="square inverted red heart icon link" data-content="Bottom Center" data-position="bottom center"></i>
        <i class="square inverted red heart icon link" data-content="Bottom Left" data-position="bottom left"></i>
        <i class="square inverted red heart icon link" data-content="Left Center" data-position="left center"></i>
      </div>
    </div>

    <div class="example">
      <h3 class="ui header">Specifying an offset</h3>
      <p>A popup position can be adjusted manually by specifying an offset property using <code>data-offset="value"</code></p>

      <i class="heart circular icon link" data-offset="50" data-content="As expected this popup is way off to the right"></i>
    </div>


    <div class="no example">
      <h3 class="ui header">Transitions</h3>
      <p>A popup can use any named ui transition.</p>
      <i class="large demo home circular link icon" data-title="Home" data-content="The place where you keep your dog"></i> Home

      <div class="ui divider"></div>

      <div class="ui selection dropdown">
        <input type="hidden" name="transition">
        <div class="default text">Choose a transition</div>
        <i class="dropdown icon"></i>
        <div class="menu">
          <div class="item">Horizontal Flip</div>
          <div class="item">Vertical Flip</div>
          <div class="item">Fade Up</div>
          <div class="item">Fade</div>
          <div class="item">Scale</div>
        </div>
      </div>
      <div class="ui clearing divider"></div>
      <div class="evaluated code">
    $('.selection')
      .dropdown({
        onChange: function(value) {
          $('.demo.icon')
            .popup({
              transition: value
            })
            .popup('toggle')
          ;
        }
      })
    ;
      </div>
    </div>
  </div>

  <div class="ui tab" data-tab="settings">

    <h3 class="ui header">
      Popup Settings
      <div class="sub header">Settings to configure popup behavior</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>context</td>
          <td>body</td>
          <td>Selector or jquery object specifying where the popup should be created</td>
        </tr>
        <tr>
          <td>position</td>
          <td>top center</td>
          <td>Position that the popup should appear</td>
        </tr>
        <tr>
          <td>inline</td>
          <td>false</td>
          <td>If a popup is inline it will be created next to current element, allowing for local css rules to apply. It will not be removed from the DOM after being hidden. Otherwise popups will appended to body and removed after being hidden.</td>
        </tr>
        <tr>
          <td>preserve</td>
          <td>false</td>
          <td>Whether popup contents should be preserved in the page after being hidden, allowing it to re-appear slightly faster on subsequent loads.</td>
        </tr>
        <tr>
          <td>on</td>
          <td>hover</td>
          <td>Event used to trigger popup. Can be either <b>focus, click or hover</b></td>
        </tr>
        <tr>
          <td>delay</td>
          <td>150</td>
          <td>Delay in milliseconds before showing a popup when using hover or focus events.</td>
        </tr>
        <tr>
          <td>transition</td>
          <td>
            slide down
          </td>
          <td>Named transition to use when animating menu in and out. Fade and slide down are available without including <a href="/modules/transition.html">ui transitions</a></td>
        </tr>
        <tr>
          <td>duration</td>
          <td>
            250
          </td>
          <td>Duration of animation events</td>
        </tr>
        <tr>
          <td>closable</td>
          <td>true</td>
          <td>When using <code>on: 'click'</code> specifies whether clicking the page should close the popup</td>
        </tr>
        <tr>
          <td>target</td>
          <td>false</td>
          <td>If a selector or jQuery object is specified this allows the popup to be positioned relative to that element.</td>
        </tr>
        <tr>
          <td>distanceAway</td>
          <td>0</td>
          <td>Offset for distance of popup from element</td>
        </tr>
        <tr>
          <td>offset</td>
          <td>0</td>
          <td>Offset in pixels from calculated position</td>
        </tr>
        <tr>
          <td>maxSearchDepth</td>
          <td>10</td>
          <td>Number of iterations before giving up search for popup position when a popup cannot fit on screen</td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      Content Settings
      <div class="sub header">Settings to specify popup contents</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>variation</td>
          <td>Popup variation to use, can use multiple variations with a space delimiter</td>
        </tr>
        <tr>
          <td>content</td>
          <td>Content to display</td>
        </tr>
        <tr>
          <td>title</td>
          <td>Title to display alongside content</td>
        </tr>
        <tr>
          <td>html</td>
          <td>HTML content to display instead of preformatted title and content</td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      DOM Settings
      <div class="sub header">DOM settings specify how this module should interface with the DOM</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="six wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>namespace</td>
          <td>popup</td>
          <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td>
        </tr>
        <tr>
          <td>selector</td>
          <td>
            <div class="code">
    selector    : {
      popup    : '.ui.popup'
    }
            </div>
          </td>
          <td>DOM Selectors used internally</td>
        </tr>
        <tr>
          <td>metadata</td>
          <td>
            <div class="code">
    metadata: {
      content   : 'content',
      html      : 'html',
      offset    : 'offset',
      position  : 'position',
      title     : 'title',
      variation : 'variation'
    }
            </div>
          </td>
          <td>HTML Data attributes used to store data</td>
        </tr>
        <tr>
          <td>className</td>
          <td>
            <div class="code">
    className   : {
      loading     : 'loading',
      popup       : 'ui popup',
      position    : 'top left center bottom right',
      visible     : 'visible'
    }
            </div>
          </td>
          <td>Class names used to attach style to state</td>
        </tr>
      </tbody>
    </table>

    <div class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      Debug Settings
      <div class="sub header">Debug settings controls debug output to the console</div>
    </h3>

    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>name</td>
          <td>Popup</td>
          <td>Name used in debug logs</td>
        </tr>
        <tr>
          <td>debug</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>performance</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>verbose</td>
          <td>True</td>
          <td>Provides ancillary debug output to console</td>
        </tr>
        <tr>
          <td>errors</td>
          <td colspan="2">
            <div class="code">
    error: {
      content   : 'Your popup has no content specified',
      method    : 'The method you called is not defined.',
      recursion : 'Popup attempted to reposition element to fit, but could not find an adequate position.'
    }
            </div>
          </td>
        </tr>
      </tbody>
    </table>

  </div>

</div>