Properties
data :String (Needs to be set at runtime)
String containing words that will be used to generate word cloud
Example
"Of course that’s your contention. You’re a first year grad student. You just got finished readin’ some Marxian historian, Pete Garrison probably. You’re gonna be convinced of that ’til next month when you get to James Lemon and then you’re gonna be talkin’ about how the economies of Virginia and Pennsylvania were entrepreneurial and capitalist way back in 1740. That’s gonna last until next year. You’re gonna be in here regurgitating Gordon Wood, talkin’ about, you know, the Pre-Revolutionary utopia and the capital-forming effects of military mobilization… ‘Wood drastically underestimates the impact of social distinctions predicated upon wealth, especially inherited wealth.’ You got that from Vickers, Work in Essex County, page 98, right? Yeah, I read that, too. Were you gonna plagiarize the whole thing for us? Do you have any thoughts of your own on this matter? Or do you, is that your thing? You come into a bar. You read some obscure passage and then pretend, you pawn it off as your own, as your own idea just to impress some girls and embarrass my friend? See, the sad thing about a guy like you is in 50 years, you’re gonna start doin’ some thinkin’ on your own and you’re gonna come up with the fact that there are two certainties in life. One: don’t do that. And two: you dropped a hundred and fifty grand on a fuckin’ education you coulda got for a dollar fifty in late charges at the public library.";
duration :Number (500)
Duration (in milliseconds) of any component transitions.
fontSizeMax :function (function () { return Math.min(size.width, size.height)/10 })
Function that returns maximum font size to use.
fontSizeMin :function (function () { return Math.min(size.width, size.height)/40 })
Function that returns minimum font size to use.
height :Number/String (600)
Height of component in either pixels (Number) or percentage of parent container (XX%)
Example
viz.height(600) or viz.height('100%');
hideWords :String ("i,me,my,myself,we,us,our,ours,ourselves,you,your,yours,yourself,yourselves,he,him,his,himself,she,her,hers,herself,it,its,itself,they,them,their,theirs,themselves,what,which,who,whom,whose,this,that,these,those,am,is,are,was,were,be,been,being,have,has,had,having,do,does,did,doing,will,would,should,can,could,ought,i'm,you're,he's,she's,it's,we're,they're,i've,you've,we've,they've,i'd,you'd,he'd,she'd,we'd,they'd,i'll,you'll,he'll,she'll,we'll,they'll,isn't,aren't,wasn't,weren't,hasn't,haven't,hadn't,doesn't,don't,didn't,won't,wouldn't,shan't,shouldn't,can't,cannot,couldn't,mustn't,let's,that's,who's,what's,here's,there's,when's,where's,why's,how's,a,an,the,and,but,if,or,because,as,until,while,of,at,by,for,with,about,against,between,into,through,during,before,after,above,below,to,from,up,upon,down,in,out,on,off,over,under,again,further,then,once,here,there,when,where,why,how,all,any,both,each,few,more,most,other,some,such,no,nor,not,only,own,same,so,than,too,very,say,says,said,shall")
Words that won't be displayed in word cloud. Passed in as a comma-delimited string.
margin :Object ({top:'5%', bottom:'5%', left:'8%', right:'10%'})
Margins between component render area and border of container. This can either be a fixed pixels (Number) or a percentage (%) of height/width.
showNumerals :Boolean (false)
Determines whether to show any numerals within the word cloud
width :Number/String (600)
Width of component in either pixels (Number) or percentage of parent container (XX%)
Example
viz.width(600) or viz.width('100%');
Methods
applyCallbacks()
Used to set listeners to multiple events at once.
This method is usually called internally from a vizuly2.core.component to set listeners for style specific methods.
Example
var stylesCallbacks = [
{on: 'updated.styles', callback: applyStyles},
{on: 'mouseover.styles', callback: styles_onMouseOver},
{on: 'mouseout.styles', callback: styles_onMouseOut}
];
viz.applyCallbacks(stylesCallbacks);
applyStyles(styles)
Used to apply a collection of styles at one time
Parameters:
Name | Type | Description |
---|---|---|
styles |
String |
A style collection object |
Example
var blueStyles =
{
'background-color-top': '#021F51',
'background-color-bottom': '#039FDB',
'value-label-color': '#FFF',
'x-axis-label-color': '#FFF',
'y-axis-label-color': '#FFF',
'bar-fill': '#02C3FF',
'axis-stroke': '#FFF',
'bar-radius': 0
}
viz.applyStyles(blueStyles);
clearStyles()
Used to clear all runtime styles and set all styles back to components default style settings.
destroy()
Removes the component from the DOM and removes all event listeners. Typically this is called when a page programmer is removing the component from memory and wants to free the component up for garbage collection by the browser.
getStyle(style, args)
Used by the component at runtime to get the current value for a given style. This can be either the default style or runtime applied styles.
The value returned could be either a static value, or a result of a dynamic function that calculates the style at runtime.
Parameters:
Name | Type | Description |
---|---|---|
style |
String |
Name of the style |
args |
Array |
Any arguments that need to be passed to the style functor |
Example
// This sets all '.vz-bar' elements with a fill matching the 'bar-fill-color' style
selection
.selectAll('.vz-bar')
.style('fill', function (d,i) { return viz.getStyle('bar-fill-color',arguments); });
id()
Returns a unique identifier that has been auto generated at instantiation. This ensures that multiple components of the same type will have a unique DOM id
Example
// Returns the viz parent DIV element
document.getElementById(viz.id());
// Alternatively you can also use
viz.selection();
on(event, listener)
Used to set listeners to component events. Passing a null listener value will clear the event listener
Note: You can use event namespaces (D3.dispatch) to set multiple listeners for a single event
Parameters:
Name | Type | Description |
---|---|---|
event |
String |
of event to be listened for |
listener |
function |
function used to capture emited event |
Example
// Sets a listener to the update event
viz.on('update', myListenerFunction);
// Sets two namespace specific listener to a mouseover event
viz.on('mouseover.module_1', myModule1ListenerFunction);
viz.on('mouseover.module_2', myModule2ListenerFunction);
// Clears the event listener for the update event
viz.on('update', null);
onChange(Property, Listener)
Used to capture any component property change events.
Parameters:
Name | Type | Description |
---|---|---|
Property |
String |
name of change event to be listened for |
Listener |
function |
function used to capture emited event |
parent()
Returns the parent DOM element the component appended to.
removeDataTip()
Used by internally components to remove a data tip. This is usually called on a mouseout
event.
selection()
Returns a d3.selection of the component's DIV container that was created at component instantiation.
showDataTip(e, d, i, j)
Used internally by components to display a data tip. This is usually called on a mouseover
event.
Parameters:
Name | Type | Description |
---|---|---|
e |
DOMElement |
The target element that triggered the call |
d |
Object |
The datum associated with the triggering event |
i |
Number |
The index associated with the datum |
j |
Number |
Optional - The series (if one exists) asscoiated with the datum |
size()
Returns a size object based on the components internal measure function with absolute pixel values. This is helpful for applying styles/decorations after the component has rendered and you want to know specific measurements of the component.
style(style, value)
Used to set, retrieve and clear runtime styles
Parameters:
Name | Type | Description |
---|---|---|
style |
String |
Name of the style |
value |
function |
Value of the style |
Example
// Retrieves a current style value (either runtime style of default style)
viz.style('myStyleName');
// Sets a new style value
viz.style('myStyleName', myStyleValue);
// Clears a runtime style (default styles will still be active)
viz.style('myStyleName', null);
(static) update()
Triggers the render pipeline process to refresh the component on the screen.
updateOnResize(resize, delay)
This function can be used to dynamically update a component when the window is resized.
Typically this is used when the viz.size()
or viz.width()
is set to a percentage.
A default delay of 50 milliseconds is used to buffer resize events and prevent the component from repeatedly updating
while the user is resizing the window. This delay can be modified as seen in the delay
parameter below.
Parameters:
Name | Type | Description |
---|---|---|
resize |
Boolean |
A |
delay |
Number |
Optional. The time in milliseconds to wait between resize events before calling |
Example
// Sets the width of the component to 100% and uses the resizeOnUpdate with a 100ms delay buffer.
viz.width('100%').updateOnResize(true, 100);
validate()
Validates that all public properties (passed in props param) have non null values.
This method is usually called internally from a vizuly2.core.component measure function.
Events
In addition to component specific events, all components natively support these events produced by the vizuly2.core.component
factory:
All Events can be accessed via the viz.on('eventName', myEventListener)
format.
// Sets a listener to the update event
viz.on('updated', myListenerFunction);
// Sets two namespace specific listener to a mouseover event
viz.on('mouseover.module_1', myModule1ListenerFunction);
viz.on('mouseover.module_2', myModule2ListenerFunction);
// Clears the event listener for the update event
viz.on('updated', null);
click :VizulyEvent
Fires when user clicks a word.
Parameters:
Name | Type | Description |
---|---|---|
e |
DOM element that fired event |
|
d |
Datum associated with DOM element |
|
i |
Index of datum in display series |
|
this |
Vizuly Component that emitted event |
initialized :VizulyEvent
Fires after component initialize()
method has been called.
Parameters:
Type | Description |
---|---|
VizulyComponent |
viz - The viz that emited the event |
measured :VizulyEvent
Fires after component measure()
method has been called
Parameters:
Type | Description |
---|---|
VizulyComponent |
viz - The viz that emited the event |
mouseout :VizulyEvent
Fires when user moves the mouse off a word.
Parameters:
Name | Type | Description |
---|---|---|
e |
DOM element that fired event |
|
d |
Datum associated with DOM element |
|
i |
Index of datum in display series |
|
this |
Vizuly Component that emitted event |
mouseover :VizulyEvent
Fires when user moves the mouse over a word.
Parameters:
Name | Type | Description |
---|---|---|
e |
DOM element that fired event |
|
d |
Datum associated with DOM element |
|
i |
Index of datum in display series |
|
this |
Vizuly Component that emitted event |
styled :VizulyEvent
Fires after component applyStyles()
method has been called.
Parameters:
Type | Description |
---|---|
VizulyComponent |
viz - The viz that emited the event |
updated :VizulyEvent
Fires after component update()
method has been called.
Parameters:
Type | Description |
---|---|
VizulyComponent |
viz - The viz that emited the event |
validated :VizulyEvent
Fires after component validate()
method has been called.
Parameters:
Type | Description |
---|---|
VizulyComponent |
viz - The viz that emited the event |