## Blocks
You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1]
```js
const editor = grapesjs.init({
blockManager: {
// options
}
})
```
Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.
```js
// Listen to events
editor.on('block:add', (block) => { ... });
// Use the API
const blockManager = editor.Blocks;
blockManager.add(...);
```
## Available Events
* `block:add` - Block added. The [Block] is passed as an argument to the callback.
* `block:remove` - Block removed. The [Block] is passed as an argument to the callback.
* `block:update` - Block updated. The [Block] and the object containing changes are passed as arguments to the callback.
* `block:drag:start` - Started dragging block, the [Block] is passed as an argument.
* `block:drag` - Dragging block, the [Block] is passed as an argument.
* `block:drag:stop` - Dragging of the block is stopped. The dropped [Component] (if dropped successfully) and the [Block] are passed as arguments.
* `block` - Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback.
## Methods
* [add][2]
* [get][3]
* [getAll][4]
* [getAllVisible][5]
* [remove][6]
* [getConfig][7]
* [getCategories][8]
* [getContainer][9]
* [render][10]
[Block]: block.html
[Component]: component.html
## getConfig
Get configuration object
Returns **[Object][11]**
## add
Add new block.
### Parameters
* `id` **[String][12]** Block ID
* `props` **[Block]** Block properties
* `opts` (optional, default `{}`)
### Examples
```javascript
blockManager.add('h1-block', {
label: 'Heading',
content: 'Put your title here
',
category: 'Basic',
attributes: {
title: 'Insert h1 block'
}
});
```
Returns **[Block]** Added block
## get
Get the block by id.
### Parameters
* `id` **[String][12]** Block id
### Examples
```javascript
const block = blockManager.get('h1-block');
console.log(JSON.stringify(block));
// {label: 'Heading', content: 'Put your ...', ...}
```
Returns **[Block]**
## getAll
Return all blocks.
### Examples
```javascript
const blocks = blockManager.getAll();
console.log(JSON.stringify(blocks));
// [{label: 'Heading', content: 'Put your ...'}, ...]
```
Returns **Collection<[Block]>**
## getAllVisible
Return the visible collection, which containes blocks actually rendered
Returns **Collection<[Block]>**
## remove
Remove block.
### Parameters
* `block` **([String][12] | [Block])** Block or block ID
* `opts` (optional, default `{}`)
### Examples
```javascript
const removed = blockManager.remove('BLOCK_ID');
// or by passing the Block
const block = blockManager.get('BLOCK_ID');
blockManager.remove(block);
```
Returns **[Block]** Removed block
## getCategories
Get all available categories.
It's possible to add categories only within blocks via 'add()' method
Returns **([Array][13] | Collection)**
## getContainer
Return the Blocks container element
Returns **[HTMLElement][14]**
## render
Render blocks
### Parameters
* `blocks` **[Array][13]** Blocks to render, without the argument will render all global blocks
* `opts` **[Object][11]** Options (optional, default `{}`)
* `opts.external` **[Boolean][15]?** Render blocks in a new container (HTMLElement will be returned)
* `opts.ignoreCategories` **[Boolean][15]?** Render blocks without categories
### Examples
```javascript
// Render all blocks (inside the global collection)
blockManager.render();
// Render new set of blocks
const blocks = blockManager.getAll();
const filtered = blocks.filter(block => block.get('category') == 'sections')
blockManager.render(filtered);
// Or a new set from an array
blockManager.render([
{label: 'Label text', content: '
Content
'}
]);
// Back to blocks from the global collection
blockManager.render();
// You can also render your blocks outside of the main block container
const newBlocksEl = blockManager.render(filtered, { external: true });
document.getElementById('some-id').appendChild(newBlocksEl);
```
Returns **[HTMLElement][14]** Rendered element
[1]: https://github.com/artf/grapesjs/blob/master/src/block_manager/config/config.js
[2]: #add
[3]: #get
[4]: #getall
[5]: #getallvisible
[6]: #remove
[7]: #getconfig
[8]: #getcategories
[9]: #getcontainer
[10]: #render
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[14]: https://developer.mozilla.org/docs/Web/HTML/Element
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean