Placard placard.js

Adds a pop-up element to inputs/textareas on focus with additional options for explicit accept/cancel actions.

Cancel

Usage

Via JavaScript

Call the placard control via JavaScript:

$('#myPlacard').placard();

Via data-attributes

The placard will automatically instantiate any placard with data-initialize="placard". If you add the control markup after page load with data-initialize="placard", the control will initialize on focus.

Markup

Use the following markup for a simple input OR textarea OR contenteditable div placard:


<div class="placard" id="myPlacard" data-initialize="placard">
  <div class="placard-popup"></div>
  <input class="form-control placard-field" type="text"/>
</div>


<div class="placard" id="myPlacard2" data-initialize="placard">
  <div class="placard-popup"></div>
  <textarea class="form-control placard-field"></textarea>
</div>


<div class="placard" id="myPlacard3" data-initialize="placard">
  <div class="placard-popup"></div>
  <div class="form-control placard-field" contenteditable="true"></div>
</div>

For header and footer content, use the following input OR textarea OR contenteditable div placards:


<div class="placard" id="myPlacard4" data-initialize="placard">
  <div class="placard-popup"></div>
  <div class="placard-header"><h5>Header</h5></div>
  <input class="form-control placard-field" type="text"/>
  <div class="placard-footer">
    <a class="placard-cancel" href="#">Cancel</a>
    <button class="btn btn-primary btn-xs placard-accept" type="button">Save</button>
  </div>
</div>


<div class="placard" id="myPlacard5" data-initialize="placard">
  <div class="placard-popup"></div>
  <div class="placard-header"><h5>Header</h5></div>
  <textarea class="form-control placard-field"></textarea>
  <div class="placard-footer">
    <a class="placard-cancel" href="#">Cancel</a>
    <button class="btn btn-primary btn-xs placard-accept" type="button">Save</button>
  </div>
</div>


<div class="placard" id="myPlacard6" data-initialize="placard">
  <div class="placard-popup"></div>
  <div class="placard-header"><h5>Header</h5></div>
  <div class="form-control placard-field" contenteditable="true"></div>
  <div class="placard-footer">
    <a class="placard-cancel" href="#">Cancel</a>
    <button class="btn btn-primary btn-xs placard-accept" type="button">Save</button>
  </div>
</div>

Optional data-attributes

  • Add data-ellipsis="true" to the placard element to enable ellipsis on the placard-field. Inputs and regular contenteditable divs use CSS. JavaScript is used to enable ellipsis for textareas and contenteditable divs with data-textarea="true". Use the .('getValue'); and .('setValue'); methods to retrieve or set values for placards with ellipsis enabled to avoid incorrect values. Be warned: performance drops with large fields for the JavaScript solution when ellipsis is enabled.
  • Add data-textarea="true" to the .placard-field element if using a contenteditable div to make that element look and behave more like a textarea.

Glass styling

Add the glass class to the input, textarea, or contenteditable div with class placard-field for a field with minimalistic chrome unless hovered upon or clicked.

Options

You can pass options via JavaScript upon initialization.

Name type default description
explicit boolean false Requires the user explicitly select 'accept' or 'cancel' before the placard is dismissed.
externalClickAction string cancel Specifies what action occurs on an external click (click outside the placard element).
externalClickExceptions array [ ] Array of jQuery selector strings. Anything that matches the selector (searched globally) will not count as an external click. Allows other items to be clicked without dismissing the placard.
onAccept function undefined Call this function when the user indicates they want to 'accept' changes. Passes a helpers object containing previousValue and current value as an argument. The default accept behaviors will not occur, so you can determine what happens next. Useful for validation purposes.
onCancel function undefined Call this function when the user indicates they want to 'cancel' changes. Passes a helpers object containing previousValue and current value as an argument. The default cancel behaviors will not occur, so you can determine what happens next. Useful for validation purposes.
revertOnCancel boolean OR number -1 Dictates whether the placard reverts the entered value when a 'cancel' action occurs. -1 checks for a '.placard-accept' element on initialization, setting this value to true if present. Also accepts true or false values.

Methods

.placard('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup
.placard('disable')
Ensures the placard is disabled, preventing users from manipulating the placard value.
.placard('enable')
Ensures the placard is enabled, allowing users to manipulate the placard value.
.placard('getValue');
Gets the current actual placard value
.placard('hide');
Hides the placard pop-up
.placard('setValue');
Sets the current actual placard value 
$('#myPlacard').placard('setValue', 'foxen');
Parameter description
value Required. String or number used to set the placard value.
.placard('show');
Shows the placard pop-up.

Events

Event Type Description
accepted.fu.placard Fires when the user indicates the desire to 'accept' changes. This event fires after the onAccept function, if defined.
canceled.fu.placard Fires when the user indicates the desire to 'cancel' changes. This event fires after the onCancel function, if defined.
hidden.fu.placard Fires when you dismiss the placard and the popup disappears.
shown.fu.placard Fires when the placard obtains focus and the popup appears.

All placard events are fired on the .placard classed element.


$('#myPlacard').on('accepted.fu.placard', function () {
  // do something…
});

Examples

Adds a pop-up element to inputs/textareas/contenteditable-divs on focus with additional options for explicit accept/cancel actions.

On an input
With .placard-header and .placard-footer option.
Field label
Cancel
With the .glass option on .placard-field
Field label
Cancel
Sample Methods