# Component
The Component object represents a single node of our template structure, so when you update its properties the changes are immediately reflected on the canvas and in the code to export (indeed, when you ask to export the code we just go through all the tree of nodes). An example on how to update properties:
component.set({
tagName: 'span',
attributes: { ... },
removable: false,
});
component.get('tagName');
// -> 'span'
# Properties
type
String (opens new window)? Component type, eg.text
,image
,video
, etc.tagName
String (opens new window)? HTML tag of the component, eg.span
. Default:div
attributes
Object (opens new window)? Key-value object of the component's attributes, eg.{ title: 'Hello' }
Default:{}
name
String (opens new window)? Name of the component. Will be used, for example, in Layers and badgesremovable
Boolean (opens new window)? Whentrue
the component is removable from the canvas, default:true
draggable
(Boolean (opens new window) | String (opens new window))? Indicates if it's possible to drag the component inside others. You can also specify a query string to indentify elements, eg.'.some-class[title=Hello], [data-gjs-type=column]'
means you can drag the component only inside elements containingsome-class
class andHello
title, andcolumn
components. Default:true
droppable
(Boolean (opens new window) | String (opens new window))? Indicates if it's possible to drop other components inside. You can use a query string as withdraggable
. Default:true
badgable
Boolean (opens new window)? Set to false if you don't want to see the badge (with the name) over the component. Default:true
stylable
(Boolean (opens new window) | Array (opens new window)<String (opens new window)>)? True if it's possible to style the component. You can also indicate an array of CSS properties which is possible to style, eg.['color', 'width']
, all other properties will be hidden from the style manager. Default:true
stylable-require
Array (opens new window)<String (opens new window)>? Indicate an array of style properties to show up which has been marked astoRequire
. Default:[]
unstylable
Array (opens new window)<String (opens new window)>? Indicate an array of style properties which should be hidden from the style manager. Default:[]
style-signature
Array (opens new window)<String (opens new window)>? This option comes handy when you need to remove or export strictly component-specific rules. Be default, if this option is not empty, the editor will remove rules when there are no components, of that type, in the canvas. Eg. '['.navbar', '[navbar-']'. Default:''
highlightable
Boolean (opens new window)? It can be highlighted with 'dotted' borders if true. Default:true
copyable
Boolean (opens new window)? True if it's possible to clone the component. Default:true
resizable
Boolean (opens new window)? Indicates if it's possible to resize the component. It's also possible to pass an object as options for the Resizer (opens new window). Default:false
editable
Boolean (opens new window)? Allow to edit the content of the component (used on Text components). Default:false
layerable
Boolean (opens new window)? Set tofalse
if you need to hide the component inside Layers. Default:true
selectable
Boolean (opens new window)? Allow component to be selected when clicked. Default:true
hoverable
Boolean (opens new window)? Shows a highlight outline when hovering on the element iftrue
. Default:true
void
Boolean (opens new window)? This property is used by the HTML exporter as void elements don't have closing tags, eg.<br/>
,<hr/>
, etc. Default:false
content
String (opens new window)? Content of the component (not escaped) which will be appended before children rendering. Default:''
icon
String (opens new window)? Component's icon, this string will be inserted before the name (in Layers and badge), eg. it can be an HTML string ''. Default:''
script
(String (opens new window) | Function (opens new window))? Component's javascript. More about it here. Default:''
script-export
(String (opens new window) | Function (opens new window))? You can specify javascript available only in export functions (eg. when you get the HTML). If this property is defined it will overwrite thescript
one (in export functions). Default:''
traits
Array (opens new window)<(Object (opens new window) | String (opens new window))>? Component's traits. More about it here. Default:['id', 'title']
propagate
Array (opens new window)<String (opens new window)>? Indicates an array of properties which will be inhereted by all NEW appended children. For example if you create a component likes this:{ removable: false, draggable: false, propagate: ['removable', 'draggable'] }
and append some new component inside, the new added component will get the exact same properties indicated in thepropagate
array (and thepropagate
property itself). Default:[]
toolbar
Array (opens new window)<Object (opens new window)>? Set an array of items to show up inside the toolbar when the component is selected (move, clone, delete). Eg.toolbar: [ { attributes: {class: 'fa fa-arrows'}, command: 'tlb-move' }, ... ]
. By default, whentoolbar
property is falsy the editor will add automatically commands likemove
,delete
, etc. based on its properties.components
Collection<Component>? Children components. Default:null
# init
Hook method, called once the model is created
# updated
Hook method, called when the model has been updated (eg. updated some model's property)
# Parameters
property
String (opens new window) Property name, if triggered after some property updatevalue
any Property value, if triggered after some property updateprevious
any Property previous value, if triggered after some property update
# removed
Hook method, called once the model has been removed
# is
Check component's type
# Parameters
type
string (opens new window) Component type
# Examples
component.is('image')
// -> false
Returns Boolean (opens new window)
# props
Return all the propeties
Returns Object (opens new window)
# index
Get the index of the component in the parent collection.
Returns Number (opens new window)
# setDragMode
Change the drag mode of the component. To get more about this feature read: https://github.com/artf/grapesjs/issues/1936 (opens new window)
# Parameters
value
String (opens new window) Drag mode, options: 'absolute' | 'translate'
Returns this
# find
Find inner components by query string. ATTENTION: this method works only with already rendered component
# Parameters
query
String (opens new window) Query string
# Examples
component.find('div > .class');
// -> [Component, Component, ...]
Returns Array (opens new window) Array of components
# findType
Find all inner components by component type.
The advantage of this method over find
is that you can use it
also before rendering the component
# Parameters
type
String (opens new window) Component type
# Examples
const allImages = component.findType('image');
console.log(allImages[0]) // prints the first found component
Returns Array (opens new window)<Component>
# closest
Find the closest parent component by query string. ATTENTION: this method works only with already rendered component
# Parameters
query
string (opens new window) Query string
# Examples
component.closest('div.some-class');
// -> Component
Returns Component
# closestType
Find the closest parent component by its type.
The advantage of this method over closest
is that you can use it
also before rendering the component
# Parameters
type
String (opens new window) Component type
# Examples
const Section = component.closestType('section');
console.log(Section);
Returns Component Found component, otherwise undefined
# contains
The method returns a Boolean value indicating whether the passed component is a descendant of a given component
# Parameters
component
Component Component to check
Returns Boolean (opens new window)
# replaceWith
Replace a component with another one
# Parameters
el
(String (opens new window) | Component) Component or HTML string
# Examples
component.replaceWith('<div>Some new content</div>');
// -> Component
Returns (Component | Array (opens new window)<Component>) New added component/s
# setAttributes
Update attributes of the component
# Parameters
attrs
Object (opens new window) Key value attributesopts
(optional, default{}
)options
Object (opens new window) Options for the model update
# Examples
component.setAttributes({ id: 'test', 'data-key': 'value' });
Returns this
# addAttributes
Add attributes to the component
# Parameters
attrs
Object (opens new window) Key value attributesopts
(optional, default{}
)options
Object (opens new window) Options for the model update
# Examples
component.addAttributes({ 'data-key': 'value' });
Returns this
# getStyle
Get the style of the component
Returns Object (opens new window)
# setStyle
Set the style on the component
# Parameters
prop
Object (opens new window) Key value style object (optional, default{}
)opts
(optional, default{}
)
# Examples
component.setStyle({ color: 'red' });
Returns Object (opens new window)
# getAttributes
Return all component's attributes
Returns Object (opens new window)
# addClass
Add classes
# Parameters
classes
(Array (opens new window)<String (opens new window)> | String (opens new window)) Array or string of classes
# Examples
model.addClass('class1');
model.addClass('class1 class2');
model.addClass(['class1', 'class2']);
// -> [SelectorObject, ...]
Returns Array (opens new window) Array of added selectors
# setClass
Set classes (resets current collection)
# Parameters
classes
(Array (opens new window)<String (opens new window)> | String (opens new window)) Array or string of classes
# Examples
model.setClass('class1');
model.setClass('class1 class2');
model.setClass(['class1', 'class2']);
// -> [SelectorObject, ...]
Returns Array (opens new window) Array of added selectors
# removeClass
Remove classes
# Parameters
classes
(Array (opens new window)<String (opens new window)> | String (opens new window)) Array or string of classes
# Examples
model.removeClass('class1');
model.removeClass('class1 class2');
model.removeClass(['class1', 'class2']);
// -> [SelectorObject, ...]
Returns Array (opens new window) Array of removed selectors
# getClasses
Returns component's classes as an array of strings
Returns Array (opens new window)
# append
Add new component children
# Parameters
components
(Component | String (opens new window)) Component to addopts
Object (opens new window) Options, same as inmodel.add()
(from backbone) (optional, default{}
)
# Examples
someComponent.get('components').length // -> 0
const videoComponent = someComponent.append('<video></video><div></div>')[0];
// This will add 2 components (`video` and `div`) to your `someComponent`
someComponent.get('components').length // -> 2
// You can pass components directly
otherComponent.append(otherComponent2);
otherComponent.append([otherComponent3, otherComponent4]);
Returns Array (opens new window) Array of appended components
# components
Set new collection if components
are provided, otherwise the
current collection is returned
# Parameters
components
(Component | String (opens new window))? Components to set
# Examples
// Set new collection
component.components('<span></span><div></div>');
// Get current collection
const collection = component.components();
console.log(collection.length);
// -> 2
Returns (Collection | Array (opens new window)<Component>)
# empty
Remove all inner components
- @return {this}
# Parameters
opts
(optional, default{}
)
# parent
Get the parent component, if exists
# Parameters
opts
(optional, default{}
)
# Examples
component.parent();
// -> Component
Returns Component
# getTrait
Get the trait by id/name
# Parameters
id
String (opens new window) Theid
orname
of the trait
# Examples
const traitTitle = component.getTrait('title');
traitTitle && traitTitle.set('label', 'New label');
Returns Trait Trait model
# updateTrait
Update a trait
# Parameters
id
String (opens new window) Theid
orname
of the traitprops
Object (opens new window) Object with the props to update
# Examples
component.updateTrait('title', {
type: 'select',
options: [ 'Option 1', 'Option 2' ],
});
Returns this
# getTraitIndex
Get the trait position index by id/name. Useful in case you want to replace some trait, at runtime, with something else.
# Parameters
id
String (opens new window) Theid
orname
of the trait
# Examples
const traitTitle = component.getTraitIndex('title');
console.log(traitTitle); // 1
Returns Number (opens new window) Index position of the current trait
# removeTrait
Remove trait/s by id/s.
# Parameters
id
(String (opens new window) | Array (opens new window)<String (opens new window)>) Theid
/name
of the trait (or an array)
# Examples
component.removeTrait('title');
component.removeTrait(['title', 'id']);
Returns Array (opens new window) Array of removed traits
# addTrait
Add trait/s by id/s.
# Parameters
trait
(String (opens new window) | Object (opens new window) | Array (opens new window)<(String (opens new window) | Object (opens new window))>) Trait to add (or an array of traits)opts
Options Options for the add (optional, default{}
)
# Examples
component.addTrait('title', { at: 1 }); // Add title trait (`at` option is the position index)
component.addTrait({
type: 'checkbox',
name: 'disabled',
});
component.addTrait(['title', {...}, ...]);
Returns Array (opens new window) Array of added traits
# getName
Get the name of the component
Returns String (opens new window)
# getIcon
Get the icon string
Returns String (opens new window)
# toHTML
Return HTML string of the component
# Parameters
opts
Object (opens new window) Options (optional, default{}
)opts.tag
String (opens new window)? Custom tagNameopts.attributes
(Object (opens new window) | Function (opens new window)) You can pass an object of custom attributes to replace with the current one or you can even pass a function to generate attributes dynamically (optional, defaultnull
)
# Examples
// Simple HTML return
component.set({ tagName: 'span' });
component.setAttributes({ title: 'Hello' });
component.toHTML();
// -> <span title="Hello"></span>
// Custom attributes
component.toHTML({ attributes: { 'data-test': 'Hello' } });
// -> <span data-test="Hello"></span>
// Custom dynamic attributes
component.toHTML({
attributes(component, attributes) {
if (component.get('tagName') == 'span') {
attributes.title = 'Custom attribute';
}
return attributes;
},
});
// -> <span title="Custom attribute"></span>
Returns String (opens new window) HTML string
# getChangedProps
Return an object containing only changed props
# Parameters
res
# getId
Return the component id
Returns String (opens new window)
# setId
Set new id on the component
# Parameters
id
String (opens new window)opts
Returns this
# getEl
Get the DOM element of the component. This works only if the component is already rendered
# Parameters
frame
Frame Specific frame from which taking the element
Returns HTMLElement (opens new window)
# getView
Get the View of the component. This works only if the component is already rendered
# Parameters
frame
Frame Get View of a specific frame
Returns ComponentView
# onAll
Execute callback function on itself and all inner components
# Parameters
clb
Function (opens new window) Callback function, the model is passed as an argument
# Examples
component.onAll(component => {
// do something with component
})
Returns this
# remove
Remove the component
# Parameters
opts
(optional, default{}
)
Returns this
# move
Move the component to another destination component
# Parameters
component
Component Destination component (so the current one will be appended as a child)opts
Object (opens new window) Options for the append action (optional, default{}
)
# Examples
// Move the selected component on top of the wrapper
const dest = editor.getWrapper();
editor.getSelected().move(dest, { at: 0 });
Returns this
# getList
The list of components is taken from the Components module. Initially, the list, was set statically on the Component object but it was not ok, as it was shared between multiple editor instances
# Parameters
model
# checkId
This method checks, for each parsed component and style object (are not Components/CSSRules yet), for duplicated id and fixes them This method is used in Components.js just after the parsing
# Parameters
components
styles
(optional, default[]
)list
(optional, default{}
)opts
(optional, default{}
)
← DOM Components Panels →