/ember-line-clamp

An ember addon that provides a line-clamp solution with see more/see less capabilities

Primary LanguageJavaScriptMIT LicenseMIT

ember-line-clamp

Build Status npm version dependencies Status js-standard-style GitHub issues GitHub license

This Ember addon provides a component for truncating/clamping text.

  • Note: This component currently does not support block form.

Installation

  • npm install ember-line-clamp

Demo

Demo application here

Usage

To get started, place the <LineClamp /> component in one of your templates and provide a string to the @text attribute. The <LineClamp /> component supports other attributes, for more details you can always look at the source code.

text

The text attribute is not required but would be nice to truncate something.

Default: 

<LineClamp
  @text="A really long text to truncate"
/>

lines

This attribute allows you to set the number of lines to clamp the text.

Default: 3

<LineClamp
  @text="A really long text to truncate"
  @lines={{2}}
/>

stripText

This attribute allows user to prevent stripping text of <br> tags when clamping.

Default: true

<LineClamp
  @text="A really long text to truncate"
  @lines={{2}}
  @stripText={{false}}
/>

ellipsis

The characters/string to be used as the overflow element.

Default: ...

<LineClamp
  @text="A really long text to truncate"
  @lines={{2}}
  @ellipsis="..."
/>

interactive

Line clamp is not always interactive, in fact if you use -webkit-line-clamp there is not interaction enabled. This attribute allows you to enable see more/see less functionality and overpowers showMoreButton and showLessButton when false. In cases where you do not want any interaction -webkit-line-clamp is used in the background to save work.

Default: true

<LineClamp
  @text="A really long text to truncate"
  @interactive={{false}}
/>

truncate

Some users might not like our style for the component, and they would like to do some fancy stuff. You can use this attribute to control truncation from outside the component and have a button that controls the truncation.

Default: true

<LineClamp
  @text="A really long text to truncate"
  @interactive={{false}}
  @truncate={{truncate}}
/>
<button class="super-fancy-style" {{on 'click' this.toggleTruncate}}>{{buttonText}}</button>

showMoreButton

This attribute enables/disables 'See More' functionality

Default: true

<LineClamp
  @text="A really long text to truncate"
  @showMoreButton={{false}}
/>

showLessButton

This attribute enables/disables 'See Less' functionality

Default: true

<LineClamp
  @text="A really long text to truncate"
  @showLessButton={{false}}
/>

seeMoreText

This component should work in any language, hence this attribute allows you to set the text for the 'See More' button

Default: See More

<LineClamp
  @text="A really long text to truncate"
  @showLessButton={{false}}
  @seeMoreText="Ver Más"
/>

seeMoreA11yText

This component should have optional support for aria-label in the situation where text alone is not enough to convey context of button to users, hence this attribute allows you to set the aria-label for the 'See More' button. By default this attribute is not used.

Default: false

<LineClamp
  @text="A really long text to truncate"
  @showLessButton={{false}}
  @seeMoreText="See more"
  @seeMoreA11yText="A button which expands the content of this text"
/>

seeLessText

This component should work in any language, hence this attribute allows you to set the text for the 'See Less' button

Default: See Less

<LineClamp
  @text="A really long text to truncate"
  @showLessButton={{false}}
  @seeMoreText="Read More"
  @seeLessText="Read Less"
/>

seeLessA11yText

This component should have optional support for aria-label in the situation where text alone is not enough to convey context of button to users, hence this attribute allows you to set the aria-label for the 'See Less' button. By default this attribute is not used.

Default: false

<LineClamp
  @text="A really long text to truncate"
  @showLessButton={{false}}
  @seeMoreText="Read More"
  @seeLessText="Read Less"
  @seeLessA11yText="A button which unexpands the content of this text"
/>

onExpand

This attribute allows you to pass a closure to trigger when text is expanded

<LineClamp
  @text="A really long text to truncate"
  @onExpand={{this.doSomethingWhenTextIsExpanded}}
/>

onCollapse

This attribute allows you to pass a closure to trigger when text is collapsed

<LineClamp
  @text="A really long text to truncate"
  @onExpand={{this.doSomethingWhenTextIsExpanded}}
  @onCollapse={{this.doSomethingWhenTextIsCollapsed}}
/>

useJsOnly

This attribute allows you to ensure handleTruncate is called all the time. The caveat is the browser native CSS solutions will never be used. Note: When the browser native CSS solutions are used, handleTruncate is never called.

Default: false

<LineClamp
  @text="A really long text to truncate"
  @useJsOnly={{true}}
  @handleTruncate={{this.onHandleTruncate}}
/>

handleTruncate

This attribute allows you to pass a closure to trigger every time the text goes through the truncation process, receives a boolean to determine if the text was truncated. Not called when the browser native CSS solutions are used.

<LineClamp
  @text="A really long text to truncate"
  @handleTruncate={{this.onHandleTruncate}}
/>

Note: Will not execute when the native CSS line-clamp is used because there is no good way currently to tell whether the browser actually truncated the text or not. If you need handleTruncate to run all the time, please enable useJsOnly.

<LineClamp
  @text="A really long text to truncate"
  @useJsOnly={{true}}
  @handleTruncate={{this.onHandleTruncate}}
/>

Then create an action that gets notified after the text is truncated. When the text is truncated and ellipsis applied, didTruncate will be true. When the text isn't truncated, didTruncate will be false.

@action
onHandleTruncate(didTruncate) {
  if(didTruncate) {
    this.someProperty = true;
  }
}

Dev TODOs

  • tests
  • demo page
  • support block form

Thanks