ember-cli-bootstrap3-tooltip

This addon allows you to quickly and conveniently create a Bootstrap3 Tooltip.

Tested Against

Demo

The demonstration web application can be found here: http://ember-cli-bootstrap3-tooltip.cybertooth.io/.

What Does This Addon Do?

This addon supplied the following components:

• twbs-abbr - an <abbr> element whose title attribute is rendered as a Bootstrap tooltip.
• twbs-cite - a <cite> element whose title attribute is rendered as a Bootstrap tooltip.
• twbs-span - a <span> element whose title attribute is rendered as a Bootstrap tooltip. This is very convenient when you want to embed a tooltip into <a>nchor or <button> elements.

...and the following mixins:

• Tooltip - imported as import Tooltip as 'ember-cli-bootstrap3-tooltip/mixins/tooltip' and can be added to new or existing components.

Further information about these items can be found in the Usage section below.

Requirements

• Ember >= 1.13.0
• Ember CLI
• You must have Bootstrap 3.x installed in your Ember application. Feel free to use the ember-cli-bootstrap3-sass addon to setup Bootstrap if you haven't already done so.
• Tooltips require the tooltip plugin to be included in your version of Bootstrap.

Installation

The following will install this addon:

ember install ember-cli-bootstrap3-tooltip

As mentioned, you must install Bootstrap3 along with the tooltip plugin. See the requirements section above.

Upgrading

When working through the Ember upgrade process, I recommend invoking the ember install ember-cli-bootstrap3-tooltip command once you are done to get the latest version of the addon.

Usage

Components

{{twbs-abbr title="Some tooltip value"}}

Create an <abbr> element whose title property will be used to generate a tooltip.

Arguments

• title - the tooltip String.
• classNames - any additional CSS classes (e.g. initialism)
• Also see the Tooltip mixin description below

Examples

{{#twbs-abbr title="Best Friends, Forever"}}BFF{{/twbs-abbr}}
{{#twbs-abbr annimation?=false title="Best Friends, Forever"}}BFF{{/twbs-abbr}}
{{#twbs-abbr delay=500 title="Best Friends, Forever"}}BFF{{/twbs-abbr}}
{{#twbs-abbr html?=true title="Best Friends, <strong>Forever</strong>"}}BFF{{/twbs-abbr}}
{{#twbs-abbr placement="right" title="Best Friends, Forever"}}BFF{{/twbs-abbr}}

{{twbs-cite title="Some tooltip value"}}

Create a <cite> element whose title property will be used to generate a tooltip.

Arguments

• title - the tooltip String.
• classNames - any additional CSS classes.
• Also see the Tooltip mixin description below.

Examples

<blockquote>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p>
  <footer>Someone famous in {{#twbs-cite title="Source Title"}}Source Title{{/twbs-cite}}</footer>
</blockquote>

{{twbs-span title="Some tooltip value"}}

Create an <span> element whose title property will be used to generate a tooltip.

Arguments

• title - the tooltip String.
• classNames - any additional CSS classes.
• Also see the Tooltip mixin description below.

Examples

{{#twbs-span title="Some sort of tooltip in a span"}}Hover Over This{{/twbs-span}}
{{#twbs-span annimation?=false title="Some sort of tooltip in a span"}}Hover Over This{{/twbs-span}}
{{#twbs-span delay=500 title="Some sort of tooltip in a span"}}Hover Over This{{/twbs-span}}
{{#twbs-span html?=true title="Some sort of tooltip in a span"}}Hover Over This{{/twbs-span}}
{{#twbs-span placement="right" title="Some sort of tooltip in a span"}}Hover Over This{{/twbs-span}}

Mixins

Tooltip

Check out the Bootstrap Tooltip Options documentation as all have been exposed in this mixin, with the following cavaets:

• The boolean options have been renamed to include a question mark; e.g. animation is animation? and html is html?.
• For simplicity sake, the delay option has been turned into two arguments: delayHide and delayShow.
• title is changed to defaultTitle because title is already used for the actual tooltip.
• container and trigger is also renamed to tooltipContainer and tooltipTrigger respectively to avoid a naming conflict with Ember.

Properties

• animation - Alias to animation?.
• animation? - Apply a CSS fade transition to the tooltip (boolean defaults to true)
• defaultTitle - Default title value if title attribute isn't present. If a function is given, it will be called with its this reference set to the element that the tooltip is attached to. (String defaults to ''; or a function)
• delayHide - Delay hiding the tooltip (ms) - does not apply to manual trigger type (number defaults to 0)
• delayShow - Delay showing the tooltip (ms) - does not apply to manual trigger type (number defaults to 0)
• html - Alias to html?.
• html? - Insert HTML into the tooltip. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks. (boolean defaults to false)
• placement - How to position the tooltip: top | bottom | left | right | auto. When auto is specified, it will dynamically reorient the tooltip. For example, if placement is auto left, the tooltip will display to the left when possible, otherwise it will display right. When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the tooltip instance. (String defaulting to top; or a function)
• selector - If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have tooltips added. See this and an informative example. (String defaults to false)
• template - Base HTML to use when creating the tooltip. The tooltip's title will be injected into the .tooltip-inner. .tooltip-arrow will become the tooltip's arrow. The outermost wrapper element should have the .tooltip class. (String defaults to <div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>)
• tooltipContainer - Appends the tooltip to a specific element. Example: container: 'body'. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize. (String defaults to false)
• tooltipTrigger - How tooltip is triggered: click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger. (String defaults to 'hover focus')
• viewport - Keeps the tooltip within the bounds of this element. Example: viewport: '#viewport' or { "selector": "#viewport", "padding": 0 }. If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the tooltip instance. (String or Object or function; defaulting to { selector: 'body', padding: 0 })

Troubleshooting And Tips

1. If you have a title that is dynamic, maybe it includes the current time, you will want to bind a function to the mixin's defaultTitle property and NOT specify a title argument.
2. Bootstrap3 CSS and the tooltip Javascript plugin must be installed.

Ember Addon Building And Testing

Setup

Checkout

$ git clone git@github.com:cybertoothca/ember-cli-bootstrap3-tooltip.git

With NPM

npm install

With Yarn

yarn

Running The Dummy Application

• ember server
• Visit your app at http://localhost:4200.

Running Addon Tests

• npm test (Runs ember try:testall to test your addon against multiple Ember versions)
• ember test
• ember test --server

Building The Addon

• ember build

For more information on using ember-cli, visit http://ember-cli.com/.

Linking This Addon For Local Testing

Linking

1. From the command line at the root of this project run the npm link command to link this addon within your local node repository.
2. From the other Ember project that you wish to test this addon in, execute the following command: npm link ember-cli-bootstrap3-tooltip.
3. Now in that same other Ember project, you should go into the package.json and add the ember addon with the version *. It will look something like this: "ember-cli-bootstrap3-tooltip": "*". Now when/if you execute npm install on this other project it will know to look for the linked addon rather than fetch it from the central repository.

Unlinking

1. Remove the addon from your local node repository with the following command (that can be run anywhere): npm uninstall -g ember-cli-bootstrap3-tooltip
2. Remove the reference to the ember-cli-bootstrap3-tooltip in your other project's package.json.
3. Run an npm prune and bower prune from the root of your other project's command line.

Deploying The Dummy Application

Make sure your ~/.aws/credentials file has a profile named cybertooth with a valid key and secret,

[cybertooth]
aws_access_key_id = <KEY>
aws_secret_access_key = <SECRET>

Deploy by invoking the following command: ember deploy production

Confirm your changes are showing up in our S3 container: http://ember-cli-bootstrap3-tooltip.cybertooth.io/

Releasing & Publishing To NPM

npm version x.y.z-sub.#
git push
git push --tags
npm publish