d3plus-text

d3plus-text

A smart SVG text box with line wrapping and automatic font size scaling.

Installing

If you use NPM, npm install d3plus-text. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom bundle using Rollup or your preferred bundler. You can also load directly from d3plus.org:

<script src="https://d3plus.org/js/d3plus-text.v0.9.full.min.js"></script>

Getting Started

Without a doubt, the most commonly used aspect of this module is textBox, which is used for intelligently wrapping SVG text. At it's core, you can simply pass along data points with "text" values and the generator will add them to the page using a set of defaults. Here is a data array containing 3 different sentences to be wrapped:

var data = [
  {text: "Here is some sample text that has been wrapped using d3plus.textBox."},
  {text: "...and here is a second sentence!"},
  {text: "这是句3号。这也即使包装没有空格！"}
];

And finally, this is how that data array would be passed to the textBox generator.

new d3plus.TextBox()
  .data(data)
  .fontSize(16)
  .width(200)
  .x(function(d, i) { return i * 250; })
  .render();

While textBox comes with some handy defaults, this example shows how any of the methods can be overridden with static values or accessor functions. For more information on how the textSplit function splits strings, specifically in languages that don't use spaces, check out this blog post.

Please note the () at the end of the chain of commands. This is what tells the textBox to finally render to the page, and allows setting multiple properties of the textBox without it trying to render after each one is set.

Click here to view this example live on the web.

More Examples

• Automatic Font Resizing to Fit Container

API Reference

Functions

stringify(value)

Coerces value into a String.

TextBox()

Creates a wrapped text box for each point in an array of data. See this example for help getting started using the textBox function.

textSplit(sentence)

Splits a given sentence into an array of words.

textWidth(text, [style])

Given a text string, returns the predicted pixel width of the string when placed into DOM.

textWrap()

Based on the defined styles and dimensions, breaks a string into an array of strings for each line of text.

stringify(value)

Coerces value into a String.

Kind: global function

Param	Type
value	String

TextBox()

Creates a wrapped text box for each point in an array of data. See this example for help getting started using the textBox function.

Kind: global function

• TextBox()
  • .render([callback])
  • .data([data])
  • .delay([value])
  • .duration([value])
  • .ellipsis([value])
  • .fontColor([value])
  • .fontFamily([value])
  • .fontMax([value])
  • .fontMin([value])
  • .fontResize([value])
  • .fontSize([value])
  • .height([value])
  • .id([value])
  • .lineHeight([value])
  • .on([typenames], [listener])
  • .overflow([value])
  • .rotate([value])
  • .select([selector])
  • .split([value])
  • .text([value])
  • .textAnchor([value])
  • .verticalAlign([value])
  • .width([value])
  • .x([value])
  • .y([value])

TextBox.render([callback])

Renders the text boxes. If a callback is specified, it will be called once the shapes are done drawing.

Kind: static method of TextBox

Param	Type
[callback]	function

TextBox.data([data])

If data is specified, sets the data array to the specified array and returns this generator. If data is not specified, returns the current data array. A text box will be drawn for each object in the array.

Kind: static method of TextBox

Param	Type	Default
[data]	Array	[]

TextBox.delay([value])

If value is specified, sets the animation delay to the specified number and returns this generator. If value is not specified, returns the current animation delay.

Kind: static method of TextBox

Param	Type	Default
[value]	Number	0

TextBox.duration([value])

If value is specified, sets the animation duration to the specified number and returns this generator. If value is not specified, returns the current animation duration.

Kind: static method of TextBox

Param	Type	Default
[value]	Number	0

TextBox.ellipsis([value])

If value is specified, sets the ellipsis method to the specified function or string and returns this generator. If value is not specified, returns the current ellipsis method, which simply adds an ellipsis to the string by default.

Kind: static method of TextBox

Param	Type
[value]	function | String

Example (default accessor)

function(d) {
  return d + "...";
}

TextBox.fontColor([value])

If value is specified, sets the font color accessor to the specified function or string and returns this generator. If value is not specified, returns the current font color accessor, which is inferred from the container element by default.

Kind: static method of TextBox

Param	Type	Default
[value]	function | String	"black"

TextBox.fontFamily([value])

If value is specified, sets the font family accessor to the specified function or string and returns this generator. If value is not specified, returns the current font family accessor, which is inferred from the container element by default.

Kind: static method of TextBox

Param	Type	Default
[value]	function | String	"Verdana"

TextBox.fontMax([value])

If value is specified, sets the maximum font size accessor to the specified function or number and returns this generator. If value is not specified, returns the current maximum font size accessor. The maximum font size is used when resizing fonts dynamically.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Number	50

TextBox.fontMin([value])

If value is specified, sets the minimum font size accessor to the specified function or number and returns this generator. If value is not specified, returns the current minimum font size accessor. The minimum font size is used when resizing fonts dynamically.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Number	8

TextBox.fontResize([value])

If value is specified, sets the font resizing accessor to the specified function or boolean and returns this generator. If value is not specified, returns the current font resizing accessor.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Boolean	false

TextBox.fontSize([value])

If value is specified, sets the font size accessor to the specified function or number and returns this generator. If value is not specified, returns the current font size accessor, which is inferred from the container element by default.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Number	10

TextBox.height([value])

If value is specified, sets the height accessor to the specified function or number and returns this generator. If value is not specified, returns the current height accessor.

Kind: static method of TextBox

Param	Type
[value]	function | Number

Example (default accessor)

function(d) {
  return d.height || 200;
}

TextBox.id([value])

If value is specified, sets the id accessor to the specified function or number and returns this generator. If value is not specified, returns the current id accessor.

Kind: static method of TextBox

Param	Type
[value]	function | Number

Example (default accessor)

function(d, i) {
  return d.id || i + "";
}

TextBox.lineHeight([value])

If value is specified, sets the line height accessor to the specified function or number and returns this generator. If value is not specified, returns the current line height accessor, which is 1.1 times the font size by default.

Kind: static method of TextBox

Param	Type
[value]	function | Number

TextBox.on([typenames], [listener])

Adds or removes a listener to each box for the specified event typenames. If a listener is not specified, returns the currently-assigned listener for the specified event typename. Mirrors the core d3-selection behavior.

Kind: static method of TextBox

Param	Type
[typenames]	String
[listener]	function

TextBox.overflow([value])

If value is specified, sets the overflow accessor to the specified function or boolean and returns this generator. If value is not specified, returns the current overflow accessor.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Boolean	false

TextBox.rotate([value])

If value is specified, sets the rotate accessor to the specified function or string and returns this generator. If value is not specified, returns the current rotate accessor.

Kind: static method of TextBox

Param	Type	Default
[value]	function | Number	0

TextBox.select([selector])

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns this generator. If selector is not specified, returns the current SVG container element, which adds an SVG element to the page by default.

Kind: static method of TextBox

Param	Type
[selector]	String | HTMLElement

TextBox.split([value])

If value is specified, sets the word split function to the specified function and returns this generator. If value is not specified, returns the current word split function.

Kind: static method of TextBox

Param	Type	Description
[value]	function	A function that, when passed a string, is expected to return that string split into an array of words to wrap. The default split function splits strings on the following characters: -, /, ;, :, &

TextBox.text([value])

If value is specified, sets the text accessor to the specified function or string and returns this generator. If value is not specified, returns the current text accessor.

Kind: static method of TextBox

Param	Type
[value]	function | String

Example (default accessor)

function(d) {
  return d.text;
}

TextBox.textAnchor([value])

If value is specified, sets the horizontal text anchor accessor to the specified function or string and returns this generator. If value is not specified, returns the current horizontal text anchor accessor.

Kind: static method of TextBox

Param	Type	Default	Description
[value]	function | String	"start"	Analagous to the SVG text-anchor property.

TextBox.verticalAlign([value])

If value is specified, sets the vertical alignment accessor to the specified function or string and returns this generator. If value is not specified, returns the current vertical alignment accessor.

Kind: static method of TextBox

Param	Type	Default	Description
[value]	function | String	"top"	Accepts "top", "middle", and "bottom".

TextBox.width([value])

If value is specified, sets the width accessor to the specified function or number and returns this generator. If value is not specified, returns the current width accessor.

Kind: static method of TextBox

Param	Type
[value]	function | Number

Example (default accessor)

function(d) {
  return d.width || 200;
}

TextBox.x([value])

If value is specified, sets the x accessor to the specified function or number and returns this generator. If value is not specified, returns the current x accessor. The number returned should correspond to the left position of the textBox.

Kind: static method of TextBox

Param	Type
[value]	function | Number

Example (default accessor)

function(d) {
  return d.x || 0;
}

TextBox.y([value])

If value is specified, sets the y accessor to the specified function or number and returns this generator. If value is not specified, returns the current y accessor. The number returned should correspond to the top position of the textBox.

Kind: static method of TextBox

Param	Type
[value]	function | Number

Example (default accessor)

function(d) {
  return d.y || 0;
}

textSplit(sentence)

Splits a given sentence into an array of words.

Kind: global function

Param	Type
sentence	String

textWidth(text, [style])

Given a text string, returns the predicted pixel width of the string when placed into DOM.

Kind: global function

Param	Type	Description
text	String | Array	Can be either a single string or an array of strings to analyze.
[style]	Object	An object of CSS font styles to apply. Accepts any of the valid CSS font property values.

textWrap()

Based on the defined styles and dimensions, breaks a string into an array of strings for each line of text.

Kind: global function

• textWrap()
  • .fontFamily([value])
  • .fontSize([value])
  • .height([value])
  • .lineHeight([value])
  • .overflow([value])
  • .split([value])
  • .width([value])

textWrap.fontFamily([value])

If value is specified, sets the font family accessor to the specified function or string and returns this generator. If value is not specified, returns the current font family.

Kind: static method of textWrap

Param	Type
[value]	function | String

textWrap.fontSize([value])

If value is specified, sets the font size accessor to the specified function or number and returns this generator. If value is not specified, returns the current font size.

Kind: static method of textWrap

Param	Type
[value]	function | Number

textWrap.height([value])

If value is specified, sets height limit to the specified value and returns this generator. If value is not specified, returns the current value.

Kind: static method of textWrap

Param	Type	Default
[value]	Number	200

textWrap.lineHeight([value])

If value is specified, sets the line height accessor to the specified function or number and returns this generator. If value is not specified, returns the current line height accessor, which is 1.1 times the font size by default.

Kind: static method of textWrap

Param	Type
[value]	function | Number

textWrap.overflow([value])

If value is specified, sets the overflow to the specified boolean and returns this generator. If value is not specified, returns the current overflow value.

Kind: static method of textWrap

Param	Type	Default
[value]	Boolean	false

textWrap.split([value])

If value is specified, sets the word split function to the specified function and returns this generator. If value is not specified, returns the current word split function.

Kind: static method of textWrap

Param	Type	Description
[value]	function	A function that, when passed a string, is expected to return that string split into an array of words to textWrap. The default split function splits strings on the following characters: -, /, ;, :, &

textWrap.width([value])

If value is specified, sets width limit to the specified value and returns this generator. If value is not specified, returns the current value.

Kind: static method of textWrap

Param	Type	Default
[value]	Number	200

_{Documentation generated on Thu, 18 Aug 2016 19:47:53 GMT}