d3plus-text
A smart SVG text box with line wrapping and automatic font size scaling.
Installing
If you use NPM, run npm install d3plus-text --save
. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. 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
API Reference
Functions
- fontExists - Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or
false
if none are installed on the user's machine. - stringify - Coerces value into a String.
- strip - Removes all non ASCII characters from 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 - Splits a given sentence into an array of words.
- textWidth - 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.
- titleCase - Capitalizes the first letter of each word in a phrase/sentence.
d3plus.fontExists(font) <>
Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or false
if none are installed on the user's machine.
This is a global function.
Returns: String
| Boolean
- Either the name of the first font that can be rendered, or false
if none are installed on the user's machine.
d3plus.stringify(value) <>
Coerces value into a String.
This is a global function.
d3plus.strip(value) <>
Removes all non ASCII characters from a string.
This is a global function.
d3plus.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.
This is a global function, and extends all of the methods and functionality of BaseClass
.
# d3plus..render([callback]) <>
Renders the text boxes. If a callback is specified, it will be called once the shapes are done drawing.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d + "...";
}
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..fontWeight([value]) <>
If value is specified, sets the font weight accessor to the specified function or number and returns this generator. If value is not specified, returns the current font weight accessor, which is inferred from the container element by default.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d.height || 200;
}
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d, i) {
return d.id || i + "";
}
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..pointerEvents([value]) <>
If value is specified, sets the pointer-events accessor to the specified function or string and returns this generator. If value is not specified, returns the current pointer-events accessor.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d.text;
}
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d.width || 200;
}
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d.x || 0;
}
# d3plus..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.
This is a static method of TextBox
.
default accessor
function(d) {
return d.y || 0;
}
d3plus.textSplit(sentence) <>
Splits a given sentence into an array of words.
This is a global function.
d3plus.textWidth(text, [style]) <>
Given a text string, returns the predicted pixel width of the string when placed into DOM.
This is a 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. |
d3plus.textWrap() <>
Based on the defined styles and dimensions, breaks a string into an array of strings for each line of text.
This is a global function.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..fontWeight([value]) <>
If value is specified, sets the font weight accessor to the specified function or number and returns this generator. If value is not specified, returns the current font weight.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
# d3plus..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.
This is a static method of textWrap
.
d3plus.titleCase(str, [opts]) <>
Capitalizes the first letter of each word in a phrase/sentence.
This is a global function.
Param | Type | Description |
---|
str | String | The string to apply the title case logic. |
[opts] | Object | Optional parameters to apply. |
[opts.lng] | String | The locale to use when looking up all lowercase or uppecase words. |
Documentation generated on Fri, 26 May 2017 19:59:36 GMT