mirror of https://github.com/artf/grapesjs.git
MuTaToR08
7 years ago
committed by
GitHub
GitHub
428 changed files with 105635 additions and 66879 deletions
@ -0,0 +1,3 @@ |
|||
# Shows a funding button via Open Collective |
|||
|
|||
open_collective: grapesjs |
|||
@ -0,0 +1,26 @@ |
|||
## WARNING |
|||
READ and FOLLOW next 5 steps, then REMOVE them before posting the issue |
|||
|
|||
1. Follow CONTRIBUTING Guidelines https://github.com/artf/grapesjs/blob/master/CONTRIBUTING.md |
|||
2. Use the GitHub Issues EXCLUSIVELY for BUGS, FEATURE REQUESTS or QUESTIONS. Prefix the title of the issue with its context, eg. `[Bug]: ....` |
|||
3. Do a quick SEARCH first, to see if someone else didn't open the same issue |
|||
4. DON'T ASK to create examples/code for you, read DOCS and APIs first, then you can post what you have tried (we'd like to see your code) and what you're unable to achieve |
|||
5. All relative statements/questions have to be filled/answered, otherwise, the issue might be CLOSED |
|||
|
|||
## You're submitting a BUG |
|||
1. Are you using the latest release (older versions are NOT supported)? |
|||
1. If you're not sure, type `grapesjs.version` in console and press ENTER |
|||
1. Are you facing the bug with your local copy of GrapesJS or with the current demo? |
|||
1. If a local copy |
|||
1. Indicate all informations about your OS, browser and GrapesJS version. |
|||
1. Are you able to reproduce the bug from the demo? |
|||
1. What is the expected behavior? |
|||
1. What happens instead? |
|||
1. If you're able to reproduce the bug indicate all the necessary steps |
|||
1. Attach screenshots (using KAP/LICEcap), screencasts or live demo |
|||
1. JSFiddle Starter template https://jsfiddle.net/szLp8h4n |
|||
1. CodeSandbox Starter template https://codesandbox.io/s/1r0w2pk1vl |
|||
|
|||
## You're submitting a FEATURE REQUEST |
|||
1. Be sure to work on the latest version, as the feature might be already there |
|||
1. Keep in mind that the feature should be considered valid to use for everyone, not only for your case |
|||
@ -0,0 +1,38 @@ |
|||
# Configuration for Lock Threads - https://github.com/dessant/lock-threads |
|||
|
|||
# Number of days of inactivity before a closed issue or pull request is locked |
|||
daysUntilLock: 365 |
|||
|
|||
# Skip issues and pull requests created before a given timestamp. Timestamp must |
|||
# follow ISO 8601 (`YYYY-MM-DD`). Set to `false` to disable |
|||
skipCreatedBefore: false |
|||
|
|||
# Issues and pull requests with these labels will be ignored. Set to `[]` to disable |
|||
exemptLabels: [] |
|||
|
|||
# Label to add before locking, such as `outdated`. Set to `false` to disable |
|||
lockLabel: outdated |
|||
|
|||
# Comment to post before locking. Set to `false` to disable |
|||
lockComment: > |
|||
This thread has been automatically locked since there has not been |
|||
any recent activity after it was closed. Please open a new issue for |
|||
related bugs. |
|||
|
|||
# Assign `resolved` as the reason for locking. Set to `false` to disable |
|||
setLockReason: true |
|||
|
|||
# Limit to only `issues` or `pulls` |
|||
# only: issues |
|||
|
|||
# Optionally, specify configuration settings just for `issues` or `pulls` |
|||
# issues: |
|||
# exemptLabels: |
|||
# - help-wanted |
|||
# lockLabel: outdated |
|||
|
|||
# pulls: |
|||
# daysUntilLock: 30 |
|||
|
|||
# Repository to extend settings from |
|||
# _extends: repo |
|||
@ -0,0 +1,13 @@ |
|||
# Configuration for probot-no-response - https://github.com/probot/no-response |
|||
|
|||
# Number of days of inactivity before an Issue is closed for lack of response |
|||
daysUntilClose: 10 |
|||
# Label requiring a response |
|||
responseRequiredLabel: more-information-needed |
|||
# Comment to post when closing an Issue for lack of response. Set to `false` to disable |
|||
closeComment: > |
|||
This issue has been automatically closed because there has been no response |
|||
to our request for more information from the original author. With only the |
|||
information that is currently in the issue, we don't have enough information |
|||
to take action. Please reach out if you have or find the answers we need so |
|||
that we can investigate further. |
|||
@ -1,3 +1,4 @@ |
|||
language: node_js |
|||
node_js: |
|||
- "7.6" |
|||
- "8" |
|||
- "10" |
|||
|
|||
@ -0,0 +1,46 @@ |
|||
# Contributor Covenant Code of Conduct |
|||
|
|||
## Our Pledge |
|||
|
|||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. |
|||
|
|||
## Our Standards |
|||
|
|||
Examples of behavior that contributes to creating a positive environment include: |
|||
|
|||
* Using welcoming and inclusive language |
|||
* Being respectful of differing viewpoints and experiences |
|||
* Gracefully accepting constructive criticism |
|||
* Focusing on what is best for the community |
|||
* Showing empathy towards other community members |
|||
|
|||
Examples of unacceptable behavior by participants include: |
|||
|
|||
* The use of sexualized language or imagery and unwelcome sexual attention or advances |
|||
* Trolling, insulting/derogatory comments, and personal or political attacks |
|||
* Public or private harassment |
|||
* Publishing others' private information, such as a physical or electronic address, without explicit permission |
|||
* Other conduct which could reasonably be considered inappropriate in a professional setting |
|||
|
|||
## Our Responsibilities |
|||
|
|||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. |
|||
|
|||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. |
|||
|
|||
## Scope |
|||
|
|||
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. |
|||
|
|||
## Enforcement |
|||
|
|||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at artur.catch@hotmail.it. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. |
|||
|
|||
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. |
|||
|
|||
## Attribution |
|||
|
|||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] |
|||
|
|||
[homepage]: http://contributor-covenant.org |
|||
[version]: http://contributor-covenant.org/version/1/4/ |
|||
@ -0,0 +1,52 @@ |
|||
# Contribute |
|||
|
|||
## Introduction |
|||
|
|||
First of all, thank you for considering contributing to GrapesJS! |
|||
|
|||
We welcome any type of contribution, not only code. Like for example: |
|||
- **QA**: file bug reports, the more details you can give the better (e.g. screenshots with the console open) |
|||
- **Marketing**: writing blog posts, howto's, tutorials, etc. |
|||
- **Community**: presenting the project at meetups, organizing a dedicated meetup for the local community, etc. |
|||
- **Money**: We welcome financial contributions in full transparency on our [Open Collective]. |
|||
|
|||
|
|||
## Your First Contribution |
|||
|
|||
Working on your first Pull Request? You can learn how from this **free** series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). |
|||
|
|||
|
|||
## Submitting code |
|||
|
|||
Any code change should be submitted as a pull request. Before start working on something make always a search in opened issues and pull requests, this might help you to avoid waisting time. |
|||
|
|||
A pull request could be a bug fix, new feature and much more, but in all cases, **open a new issue** and talk about what you want to do. Often happens to work on something already fixed (ready to release) or in progress. |
|||
|
|||
The title should be brief but comprehensive, the description contains a link to the opened issue and the proposed solution. The pull request should contain tests whenever possible. Keep in mind that the bigger is the pull request, the longer it will take to review and merge. Try to break down large pull requests in smaller chunks that are easier to review and merge. |
|||
|
|||
|
|||
## Styleguide |
|||
|
|||
The code is auto formatted with [prettier](https://github.com/prettier/prettier) on any commit, therefore you can write in any style you prefer |
|||
|
|||
|
|||
## Expenses |
|||
|
|||
Anyone can file an expense (code, marketing, etc.) via our [Open Collective]. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed. |
|||
|
|||
Before submitting an expense contact core contributors via the current active chat room ([Discord](https://discord.gg/QAbgGXq)) and explain your intents |
|||
|
|||
|
|||
## Questions |
|||
|
|||
If you have any questions, create an [issue](https://github.com/artf/grapesjs/issues) (protip: do a quick search first to see if someone else didn't ask the same question before!). |
|||
|
|||
|
|||
|
|||
## Credits |
|||
|
|||
Thank you to all the people who have already contributed to GrapesJS! |
|||
<a href="/artf/grapesjs/graphs/contributors"><img src="https://opencollective.com/grapesjs/contributors.svg?width=890" /></a> |
|||
|
|||
|
|||
[Open Collective]: <https://opencollective.com/grapesjs> |
|||
File diff suppressed because one or more lines are too long
Binary file not shown.
Binary file not shown.
|
Before Width: | Height: | Size: 357 KiB After Width: | Height: | Size: 434 KiB |
Binary file not shown.
Binary file not shown.
Binary file not shown.
File diff suppressed because it is too large
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -0,0 +1,14 @@ |
|||
<template> |
|||
<div class="demo-container"> |
|||
<slot/> |
|||
</div> |
|||
</template> |
|||
|
|||
<style scoped> |
|||
.demo-container { |
|||
min-height: 20px; |
|||
border: 1px solid #eee; |
|||
border-radius: 2px; |
|||
padding: 25px 35px; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,29 @@ |
|||
<template> |
|||
<div> |
|||
<div class="gjs" id="gjs2"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
<div id="blocks2"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
window.editor2 = grapesjs.init(utils.gjsConfigBlocks); |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style> |
|||
.gjs { |
|||
border: 3px solid #444; |
|||
} |
|||
.gjs-block { |
|||
width: auto; |
|||
height: auto; |
|||
min-height: auto; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,15 @@ |
|||
<template src="./demos/DemoCanvasOnly.html"> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor = grapesjs.init(utils.gjsConfigStart); |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style src="./demos/DemoCanvasOnly.css"> |
|||
</style> |
|||
@ -0,0 +1,48 @@ |
|||
<template> |
|||
<div> |
|||
<div class="panel__top" id="panel__top3"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions3"></div> |
|||
</div> |
|||
<div class="gjs" id="gjs3"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
<div id="blocks3"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor3 = grapesjs.init(utils.gjsConfigPanels); |
|||
editor3.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top3' |
|||
})); |
|||
editor3.Panels.addPanel(Object.assign({}, utils.panelBasicActions, { |
|||
el: '#panel__basic-actions3' |
|||
})); |
|||
window.editor3 = editor3; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style> |
|||
.panel__top { |
|||
padding: 0; |
|||
width: 100%; |
|||
display: flex; |
|||
position: initial; |
|||
justify-content: center; |
|||
justify-content: space-between; |
|||
} |
|||
.panel__basic-actions { |
|||
position: initial; |
|||
} |
|||
.content pre { |
|||
padding-top: 0; |
|||
padding-bottom: 0; |
|||
margin-top: 0; |
|||
margin-bottom: 0; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,56 @@ |
|||
<template> |
|||
<div> |
|||
<div class="panel__top" id="panel__top7"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions7"></div> |
|||
<div class="panel__devices" id="panel__devices7"></div> |
|||
<div class="panel__switcher" id="panel__switcher7"></div> |
|||
</div> |
|||
|
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div class="gjs" id="gjs7"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
</div> |
|||
<div class="panel__right" id="panel__right7"> |
|||
<div class="layers-container" id="layers-container7"></div> |
|||
<div class="styles-container" id="styles-container7"></div> |
|||
<div class="traits-container" id="traits-container7"></div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div id="blocks7"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor7 = grapesjs.init(utils.gjsConfigDevices); |
|||
editor7.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top7' |
|||
})); |
|||
editor7.Panels.addPanel(Object.assign({}, utils.panelBasicActions, { |
|||
el: '#panel__basic-actions7' |
|||
})); |
|||
editor7.Panels.addPanel(Object.assign({}, utils.panelSidebar, { |
|||
el: '#panel__right7' |
|||
})); |
|||
editor7.Panels.addPanel(Object.assign({}, utils.panelSwitcherTraits, { |
|||
el: '#panel__switcher7' |
|||
})); |
|||
editor7.Panels.addPanel(Object.assign({}, utils.panelDevices, { |
|||
el: '#panel__devices7' |
|||
})); |
|||
window.editor7 = editor7; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style> |
|||
.panel__devices { |
|||
position: initial; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,40 @@ |
|||
<template> |
|||
<div> |
|||
<div class="panel__top" id="panel__top4"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions4"></div> |
|||
</div> |
|||
|
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div class="gjs" id="gjs4"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
</div> |
|||
<div class="panel__right" id="panel__right4"> |
|||
<div id="layers-container"></div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div id="blocks4"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor4 = grapesjs.init(utils.gjsConfigLayers); |
|||
editor4.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top4' |
|||
})); |
|||
editor4.Panels.addPanel(Object.assign({}, utils.panelBasicActions, { |
|||
el: '#panel__basic-actions4' |
|||
})); |
|||
window.editor4 = editor4; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style src="./demos/DemoLayers.css"> |
|||
</style> |
|||
@ -0,0 +1,51 @@ |
|||
<template> |
|||
<div> |
|||
<div class="panel__top" id="panel__top5"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions5"></div> |
|||
<div class="panel__switcher" id="panel__switcher5"></div> |
|||
</div> |
|||
|
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div class="gjs" id="gjs5"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
</div> |
|||
<div class="panel__right" id="panel__right5"> |
|||
<div class="layers-container" id="layers-container5"></div> |
|||
<div class="styles-container" id="styles-container5"></div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div id="blocks5"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor5 = grapesjs.init(utils.gjsConfigStyle); |
|||
editor5.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top5' |
|||
})); |
|||
editor5.Panels.addPanel(Object.assign({}, utils.panelBasicActions, { |
|||
el: '#panel__basic-actions5' |
|||
})); |
|||
editor5.Panels.addPanel(Object.assign({}, utils.panelSidebar, { |
|||
el: '#panel__right5' |
|||
})); |
|||
editor5.Panels.addPanel(Object.assign({}, utils.panelSwitcher, { |
|||
el: '#panel__switcher5' |
|||
})); |
|||
window.editor5 = editor5; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style> |
|||
.panel__switcher { |
|||
position: initial; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,80 @@ |
|||
<template> |
|||
<div class="gjs__themed"> |
|||
<div class="panel__top" id="panel__top8"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions8"></div> |
|||
<div class="panel__devices" id="panel__devices8"></div> |
|||
<div class="panel__switcher" id="panel__switcher8"></div> |
|||
</div> |
|||
|
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div class="gjs" id="gjs8"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
</div> |
|||
<div class="panel__right" id="panel__right8"> |
|||
<div class="layers-container" id="layers-container8"></div> |
|||
<div class="styles-container" id="styles-container8"></div> |
|||
<div class="traits-container" id="traits-container8"></div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div id="blocks8"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor8 = grapesjs.init(utils.gjsConfigTheme); |
|||
editor8.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top8' |
|||
})); |
|||
editor8.Panels.addPanel(Object.assign({}, utils.panelBasicActionsIcons, { |
|||
el: '#panel__basic-actions8' |
|||
})); |
|||
editor8.Panels.addPanel(Object.assign({}, utils.panelSidebar, { |
|||
el: '#panel__right8' |
|||
})); |
|||
editor8.Panels.addPanel(Object.assign({}, utils.panelSwitcherTraitsIcons, { |
|||
el: '#panel__switcher8' |
|||
})); |
|||
editor8.Panels.addPanel(Object.assign({}, utils.panelDevicesIcons, { |
|||
el: '#panel__devices8' |
|||
})); |
|||
window.editor8 = editor8; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style lang="stylus"> |
|||
.gjs__themed { |
|||
/* Primary color for the background */ |
|||
.gjs-one-bg { |
|||
background-color: #78366a; |
|||
} |
|||
|
|||
/* Secondary color for the text color */ |
|||
.gjs-two-color { |
|||
color: rgba(255, 255, 255, 0.7); |
|||
} |
|||
|
|||
/* Tertiary color for the background */ |
|||
.gjs-three-bg { |
|||
background-color: #ec5896; |
|||
color: white; |
|||
} |
|||
|
|||
/* Quaternary color for the text color */ |
|||
.gjs-four-color, |
|||
.gjs-four-color-h:hover { |
|||
color: #ec5896; |
|||
} |
|||
|
|||
.gjs { |
|||
border: none; |
|||
} |
|||
} |
|||
</style> |
|||
@ -0,0 +1,52 @@ |
|||
<template> |
|||
<div> |
|||
<div class="panel__top" id="panel__top6"> |
|||
<div class="panel__basic-actions" id="panel__basic-actions6"></div> |
|||
<div class="panel__switcher" id="panel__switcher6"></div> |
|||
</div> |
|||
|
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div class="gjs" id="gjs6"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
</div> |
|||
<div class="panel__right" id="panel__right6"> |
|||
<div class="layers-container" id="layers-container6"></div> |
|||
<div class="styles-container" id="styles-container6"></div> |
|||
<div class="traits-container" id="traits-container6"></div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div id="blocks6"></div> |
|||
</div> |
|||
</template> |
|||
|
|||
<script> |
|||
import utils from './demos/utils.js'; |
|||
|
|||
export default { |
|||
mounted() { |
|||
const editor6 = grapesjs.init(utils.gjsConfigTraits); |
|||
editor6.Panels.addPanel(Object.assign({}, utils.panelTop, { |
|||
el: '#panel__top6' |
|||
})); |
|||
editor6.Panels.addPanel(Object.assign({}, utils.panelBasicActions, { |
|||
el: '#panel__basic-actions6' |
|||
})); |
|||
editor6.Panels.addPanel(Object.assign({}, utils.panelSidebar, { |
|||
el: '#panel__right6' |
|||
})); |
|||
editor6.Panels.addPanel(Object.assign({}, utils.panelSwitcherTraits, { |
|||
el: '#panel__switcher6' |
|||
})); |
|||
window.editor6 = editor6; |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style> |
|||
.panel__switcher { |
|||
position: initial; |
|||
} |
|||
</style> |
|||
@ -0,0 +1,33 @@ |
|||
<template> |
|||
<iframe :width="width" :height="height" :src="src" allowfullscreen="allowfullscreen" frameborder="0"/> |
|||
</template> |
|||
|
|||
<script> |
|||
export default { |
|||
name: 'DemoViewer', |
|||
props: { |
|||
value: { |
|||
type: String, |
|||
default: '', |
|||
}, |
|||
user: { |
|||
type: String, |
|||
default: 'artur_arseniev', |
|||
}, |
|||
width: { |
|||
type: String, |
|||
default: '100%', |
|||
}, |
|||
height: { |
|||
type: String, |
|||
default: '300', |
|||
}, |
|||
}, |
|||
computed: { |
|||
src() { |
|||
const { value, user } = this; |
|||
return `//jsfiddle.net/${user}/${value}/embedded/js,html,css,result`; |
|||
} |
|||
} |
|||
} |
|||
</script> |
|||
@ -0,0 +1,11 @@ |
|||
/* Let's highlight canvas boundaries */ |
|||
#gjs { |
|||
border: 3px solid #444; |
|||
} |
|||
|
|||
/* Reset some default styling */ |
|||
.gjs-cv-canvas { |
|||
top: 0; |
|||
width: 100%; |
|||
height: 100%; |
|||
} |
|||
@ -0,0 +1,3 @@ |
|||
<div id="gjs"> |
|||
<h1>Hello World Component!</h1> |
|||
</div> |
|||
@ -0,0 +1,14 @@ |
|||
const editor = grapesjs.init({ |
|||
// Indicate where to init the editor. You can also pass an HTMLElement
|
|||
container: '#gjs', |
|||
// Get the content for the canvas directly from the element
|
|||
// As an alternative we could use: `components: '<h1>Hello World Component!</h1>'`,
|
|||
fromElement: true, |
|||
// Size of the editor
|
|||
height: '300px', |
|||
width: 'auto', |
|||
// Disable the storage manager for the moment
|
|||
storageManager: false, |
|||
// Avoid any default panel
|
|||
panels: { defaults: [] }, |
|||
}); |
|||
@ -0,0 +1,17 @@ |
|||
.editor-row { |
|||
display: flex; |
|||
justify-content: flex-start; |
|||
align-items: stretch; |
|||
flex-wrap: nowrap; |
|||
height: 300px; |
|||
} |
|||
|
|||
.editor-canvas { |
|||
flex-grow: 1; |
|||
} |
|||
|
|||
.panel__right { |
|||
flex-basis: 230px; |
|||
position: relative; |
|||
overflow-y: auto; |
|||
} |
|||
@ -0,0 +1,392 @@ |
|||
export const loadScript = url => new Promise((resolve, reject) => { |
|||
const script = document.createElement('script'); |
|||
script.onload = resolve; |
|||
script.onerror = reject; |
|||
script.src = url; |
|||
document.head.appendChild(script); |
|||
}); |
|||
|
|||
export const loadStyle = url => new Promise((resolve) => { |
|||
const link = document.createElement('link'); |
|||
link.rel = 'stylesheet'; |
|||
link.type = 'text/css'; |
|||
link.href = url; |
|||
document.head.appendChild(link); |
|||
resolve(); |
|||
}); |
|||
|
|||
|
|||
// Don't know yet why but can't use ES6
|
|||
|
|||
var blockManager = { |
|||
appendTo: '#blocks2', |
|||
blocks: [ |
|||
{ |
|||
id: 'section', // id is mandatory
|
|||
label: '<b>Section</b>', |
|||
attributes: { class:'gjs-block-section' }, |
|||
content: `<section>
|
|||
<h1>This is a simple title</h1> |
|||
<div>This is just a Lorem text: Lorem ipsum dolor sit amet, consectetur adipiscing elit</div> |
|||
</section>`, |
|||
}, { |
|||
id: 'text', |
|||
label: 'Text', |
|||
content: '<div data-gjs-type="text">Insert your text here</div>', |
|||
}, { |
|||
id: 'image', |
|||
label: 'Image', |
|||
// Select the component once dropped in canavas
|
|||
select: true, |
|||
// You can pass components as a JSON instead of a simple HTML string,
|
|||
// in this case we also use a defined component type `image`
|
|||
content: { type: 'image' }, |
|||
// This triggers `active` on dropped components
|
|||
activate: true, |
|||
} |
|||
] |
|||
}; |
|||
|
|||
var blockManagerIcons = Object.assign({}, blockManager, { |
|||
blocks: [ |
|||
Object.assign({}, blockManager.blocks[0], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 3H5c-1.11 0-2 .89-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5a2 2 0 0 0-2-2m0 2v14H5V5h14z"></path></svg>', |
|||
}), |
|||
Object.assign({}, blockManager.blocks[1], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.5 4l1.16 4.35-.96.26c-.45-.87-.91-1.74-1.44-2.18C16.73 6 16.11 6 15.5 6H13v10.5c0 .5 0 1 .33 1.25.34.25 1 .25 1.67.25v1H9v-1c.67 0 1.33 0 1.67-.25.33-.25.33-.75.33-1.25V6H8.5c-.61 0-1.23 0-1.76.43-.53.44-.99 1.31-1.44 2.18l-.96-.26L5.5 4h13z"></path></svg>', |
|||
}), |
|||
Object.assign({}, blockManager.blocks[2], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 5c1.1 0 2 .9 2 2v10c0 1.1-.9 2-2 2H4a2 2 0 0 1-2-2V7c0-1.11.89-2 2-2h16M5 16h14l-4.5-6-3.5 4.5-2.5-3L5 16z"></path></svg>', |
|||
}), |
|||
] |
|||
}); |
|||
|
|||
var styleManager = { |
|||
sectors: [{ |
|||
name: 'Dimension', |
|||
open: false, |
|||
// Use built-in properties
|
|||
buildProps: ['width', 'min-height', 'padding'], |
|||
// Use `properties` to define/override single property
|
|||
properties: [ |
|||
{ |
|||
// Type of the input,
|
|||
// options: integer | radio | select | color | slider | file | composite | stack
|
|||
type: 'integer', |
|||
name: 'The width', // Label for the property
|
|||
property: 'width', // CSS property (if buildProps contains it will be extended)
|
|||
units: ['px', '%'], // Units, available only for 'integer' types
|
|||
defaults: 'auto', // Default value
|
|||
min: 0, // Min value, available only for 'integer' types
|
|||
} |
|||
] |
|||
},{ |
|||
name: 'Extra', |
|||
open: false, |
|||
buildProps: ['background-color', 'box-shadow', 'custom-prop'], |
|||
properties: [ |
|||
{ |
|||
id: 'custom-prop', |
|||
name: 'Custom Label', |
|||
property: 'font-size', |
|||
type: 'select', |
|||
defaults: '32px', |
|||
// List of options, available only for 'select' and 'radio' types
|
|||
options: [ |
|||
{ value: '12px', name: 'Tiny' }, |
|||
{ value: '18px', name: 'Medium' }, |
|||
{ value: '32px', name: 'Big' }, |
|||
], |
|||
} |
|||
] |
|||
}] |
|||
}; |
|||
|
|||
var layerManager = { scrollLayers: 0 }; |
|||
var selectorManager = {}; |
|||
var traitManager = {}; |
|||
var deviceManager = { |
|||
devices: [{ |
|||
name: 'Desktop', |
|||
width: '', // default size
|
|||
}, { |
|||
name: 'Mobile', |
|||
width: '320px', // this value will be used on canvas width
|
|||
widthMedia: '480px', // this value will be used in CSS @media
|
|||
}] |
|||
}; |
|||
|
|||
var panelTop = { id: 'panel-top' }; |
|||
var panelBasicActions = { |
|||
id: 'panel-basic', |
|||
buttons: [ |
|||
{ |
|||
id: 'visibility', |
|||
// active by default
|
|||
active: true, |
|||
className: 'btn-toggle-borders', |
|||
label: '<u>B</u>', |
|||
// Built-in command
|
|||
command: 'sw-visibility', |
|||
}, { |
|||
id: 'export', |
|||
className: 'btn-open-export', |
|||
label: 'Exp', |
|||
command: 'export-template', |
|||
// For grouping context of buttons in the same panel
|
|||
context: 'export-template', |
|||
}, { |
|||
id: 'show-json', |
|||
className: 'btn-show-json', |
|||
label: 'JSON', |
|||
context: 'show-json', |
|||
command(editor) { |
|||
editor.Modal.setTitle('Components JSON') |
|||
.setContent(`<textarea style="width:100%; height: 250px;">
|
|||
${JSON.stringify(editor.getComponents())} |
|||
</textarea>`) |
|||
.open(); |
|||
}, |
|||
} |
|||
], |
|||
}; |
|||
var panelBasicActionsIcons = Object.assign({}, panelBasicActions, { |
|||
buttons: [ |
|||
Object.assign({}, panelBasicActions.buttons[0], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15 5h2V3h-2m0 18h2v-2h-2M11 5h2V3h-2m8 2h2V3h-2m0 6h2V7h-2m0 14h2v-2h-2m0-6h2v-2h-2m0 6h2v-2h-2M3 5h2V3H3m0 6h2V7H3m0 6h2v-2H3m0 6h2v-2H3m0 6h2v-2H3m8 2h2v-2h-2m-4 2h2v-2H7M7 5h2V3H7v2z"></path></svg>', |
|||
}), |
|||
Object.assign({}, panelBasicActions.buttons[1], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M5 20h14v-2H5m14-9h-4V3H9v6H5l7 7 7-7z"></path></svg>', |
|||
}), |
|||
Object.assign({}, panelBasicActions.buttons[2], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8 3c-1.1 0-2 .9-2 2v4c0 1.1-.9 2-2 2H3v2h1c1.1 0 2 .9 2 2v4c0 1.1.9 2 2 2h2v-2H8v-5c0-1.1-.9-2-2-2 1.1 0 2-.9 2-2V5h2V3m6 0c1.1 0 2 .9 2 2v4c0 1.1.9 2 2 2h1v2h-1c-1.1 0-2 .9-2 2v4c0 1.1-.9 2-2 2h-2v-2h2v-5c0-1.1.9-2 2-2-1.1 0-2-.9-2-2V5h-2V3h2z"></path></svg>', |
|||
}), |
|||
] |
|||
}); |
|||
var panelSidebar = { |
|||
el: '#panel__right4', |
|||
id: 'layers', |
|||
// Make the panel resizable
|
|||
resizable: { |
|||
maxDim: 350, |
|||
minDim: 200, |
|||
tc: 0, // Top handler
|
|||
cl: 1, // Left handler
|
|||
cr: 0, // Right handler
|
|||
bc: 0, // Bottom handler
|
|||
// Being a flex child we need to change `flex-basis` property
|
|||
// instead of the `width` (default)
|
|||
keyWidth: 'flex-basis', |
|||
}, |
|||
}; |
|||
|
|||
var buttonShowLayers = { |
|||
id: 'show-layers', |
|||
active: true, |
|||
togglable: false, |
|||
label: 'Layers', |
|||
command: { |
|||
getRowEl(editor) { return editor.getContainer().parentNode.parentNode; }, |
|||
getLayersEl(row) { return row.querySelector('.layers-container') }, |
|||
getStyleEl(row) { return row.querySelector('.styles-container') }, |
|||
|
|||
run(editor, sender) { |
|||
const row = this.getRowEl(editor); |
|||
const lmEl = this.getLayersEl(row); |
|||
lmEl.style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
const row = this.getRowEl(editor); |
|||
const lmEl = this.getLayersEl(row); |
|||
lmEl.style.display = 'none'; |
|||
}, |
|||
}, |
|||
}; |
|||
var buttonShowStyle = { |
|||
id: 'show-style', |
|||
label: 'Styles', |
|||
togglable: false, |
|||
active: true, |
|||
command: { |
|||
getRowEl(editor) { return editor.getContainer().parentNode.parentNode; }, |
|||
getLayersEl(row) { return row.querySelector('.layers-container') }, |
|||
getStyleEl(row) { return row.querySelector('.styles-container') }, |
|||
|
|||
run(editor, sender) { |
|||
const row = this.getRowEl(editor); |
|||
const smEl = this.getStyleEl(row); |
|||
smEl.style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
const row = this.getRowEl(editor); |
|||
const smEl = this.getStyleEl(row); |
|||
smEl.style.display = 'none'; |
|||
}, |
|||
}, |
|||
}; |
|||
var buttonShowTraits = { |
|||
id: 'show-traits', |
|||
label: 'Traits', |
|||
togglable: false, |
|||
active: true, |
|||
command: { |
|||
getTraitsEl(editor) { |
|||
const row = editor.getContainer().closest('.editor-row'); |
|||
return row.querySelector('.traits-container'); |
|||
}, |
|||
run(editor, sender) { |
|||
this.getTraitsEl(editor).style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
this.getTraitsEl(editor).style.display = 'none'; |
|||
}, |
|||
}, |
|||
}; |
|||
|
|||
var panelSwitcher = { |
|||
id: 'panel-switcher', |
|||
buttons: [ |
|||
buttonShowLayers, |
|||
buttonShowStyle, |
|||
], |
|||
}; |
|||
|
|||
var panelSwitcherTraits = { |
|||
id: 'panel-switcher', |
|||
buttons: [ |
|||
buttonShowLayers, |
|||
buttonShowStyle, |
|||
buttonShowTraits, |
|||
], |
|||
}; |
|||
|
|||
var panelSwitcherTraitsIcons = { |
|||
id: 'panel-switcher', |
|||
buttons: [ |
|||
Object.assign({}, buttonShowLayers, { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 16l7.36-5.73L21 9l-9-7-9 7 1.63 1.27M12 18.54l-7.38-5.73L3 14.07l9 7 9-7-1.63-1.27L12 18.54z"></path></svg>', |
|||
}), |
|||
Object.assign({}, buttonShowStyle, { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.5 12c-.83 0-1.5-.67-1.5-1.5S16.67 9 17.5 9s1.5.67 1.5 1.5-.67 1.5-1.5 1.5m-3-4c-.83 0-1.5-.67-1.5-1.5S13.67 5 14.5 5s1.5.67 1.5 1.5S15.33 8 14.5 8m-5 0C8.67 8 8 7.33 8 6.5S8.67 5 9.5 5s1.5.67 1.5 1.5S10.33 8 9.5 8m-3 4c-.83 0-1.5-.67-1.5-1.5S5.67 9 6.5 9 8 9.67 8 10.5 7.33 12 6.5 12M12 3a9 9 0 0 0 0 18c.83 0 1.5-.67 1.5-1.5 0-.39-.15-.74-.39-1-.23-.27-.38-.62-.38-1 0-.83.67-1.5 1.5-1.5H16c2.76 0 5-2.24 5-5 0-4.42-4.03-8-9-8z"></path></svg>', |
|||
}), |
|||
Object.assign({}, buttonShowTraits, { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 15.5c-1.93 0-3.5-1.57-3.5-3.5s1.57-3.5 3.5-3.5 3.5 1.57 3.5 3.5-1.57 3.5-3.5 3.5m7.43-2.53c.04-.32.07-.64.07-.97 0-.33-.03-.66-.07-1l2.11-1.63c.19-.15.24-.42.12-.64l-2-3.46c-.12-.22-.39-.31-.61-.22l-2.49 1c-.52-.39-1.06-.73-1.69-.98l-.37-2.65A.506.506 0 0 0 14 2h-4c-.25 0-.46.18-.5.42l-.37 2.65c-.63.25-1.17.59-1.69.98l-2.49-1c-.22-.09-.49 0-.61.22l-2 3.46c-.13.22-.07.49.12.64L4.57 11c-.04.34-.07.67-.07 1 0 .33.03.65.07.97l-2.11 1.66c-.19.15-.25.42-.12.64l2 3.46c.12.22.39.3.61.22l2.49-1.01c.52.4 1.06.74 1.69.99l.37 2.65c.04.24.25.42.5.42h4c.25 0 .46-.18.5-.42l.37-2.65c.63-.26 1.17-.59 1.69-.99l2.49 1.01c.22.08.49 0 .61-.22l2-3.46c.12-.22.07-.49-.12-.64l-2.11-1.66z"></path></svg>', |
|||
}), |
|||
], |
|||
}; |
|||
|
|||
var panelDevices = { |
|||
id: 'panel-devices', |
|||
buttons: [{ |
|||
id: 'device-desktop', |
|||
label: 'D', |
|||
command: { run: editor => editor.setDevice('Desktop') }, |
|||
active: true, |
|||
togglable: false, |
|||
}, { |
|||
id: 'device-mobile', |
|||
label: 'M', |
|||
command: { run: editor => editor.setDevice('Mobile') }, |
|||
togglable: false, |
|||
}], |
|||
}; |
|||
|
|||
var panelDevicesIcons = Object.assign({}, panelDevices, { |
|||
buttons: [ |
|||
Object.assign({}, panelDevices.buttons[0], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 14H3V4h18m0-2H3c-1.11 0-2 .89-2 2v12c0 1.1.9 2 2 2h7l-2 3v1h8v-1l-2-3h7c1.1 0 2-.9 2-2V4a2 2 0 0 0-2-2z"></path></svg>', |
|||
}), |
|||
Object.assign({}, panelDevices.buttons[1], { |
|||
label: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16 18H7V4h9m-4.5 18c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5m4-21h-8A2.5 2.5 0 0 0 5 3.5v17A2.5 2.5 0 0 0 7.5 23h8a2.5 2.5 0 0 0 2.5-2.5v-17A2.5 2.5 0 0 0 15.5 1z"></path></svg>', |
|||
}), |
|||
] |
|||
}); |
|||
|
|||
var gjsConfigStart = { |
|||
// Indicate where to init the editor. It's also possible to pass an HTMLElement
|
|||
container: '#gjs', |
|||
// Get the content for the canvas direectly from the element
|
|||
// As an alternative we could use: `components: '<h1>Hello World Component!</h1>'`,
|
|||
fromElement: true, |
|||
// Size of the editor
|
|||
height: '300px', |
|||
width: 'auto', |
|||
// Disable the storage manager for the moment
|
|||
storageManager: { type: null }, |
|||
// Avoid any default panel
|
|||
panels: { defaults: [] }, |
|||
}; |
|||
|
|||
var gjsConfigBlocks = Object.assign({}, gjsConfigStart, { |
|||
container: '#gjs2', |
|||
blockManager, |
|||
}); |
|||
|
|||
var gjsConfigPanels = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs3', |
|||
blockManager: Object.assign({}, blockManager, { appendTo: '#blocks3' }), |
|||
}); |
|||
|
|||
var gjsConfigLayers = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs4', |
|||
blockManager: Object.assign({}, blockManager, { appendTo: '#blocks4' }), |
|||
layerManager: { appendTo: '#layers-container', scrollLayers: 0 }, |
|||
panels: { defaults: [panelSidebar] } |
|||
}); |
|||
|
|||
var gjsConfigStyle = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs5', |
|||
blockManager: Object.assign({}, blockManager, { appendTo: '#blocks5' }), |
|||
layerManager: { appendTo: '#layers-container5', scrollLayers: 0 }, |
|||
styleManager: Object.assign({}, styleManager, { appendTo: '#styles-container5' }), |
|||
selectorManager: Object.assign({}, selectorManager, { appendTo: '#styles-container5' }), |
|||
}); |
|||
|
|||
var gjsConfigTraits = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs6', |
|||
blockManager: Object.assign({}, blockManager, { appendTo: '#blocks6' }), |
|||
layerManager: Object.assign({}, layerManager, { appendTo: '#layers-container6' }), |
|||
styleManager: Object.assign({}, styleManager, { appendTo: '#styles-container6' }), |
|||
traitManager: Object.assign({}, traitManager, { appendTo: '#traits-container6' }), |
|||
selectorManager: Object.assign({}, selectorManager, { appendTo: '#styles-container6' }), |
|||
}); |
|||
|
|||
var gjsConfigDevices = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs7', |
|||
blockManager: Object.assign({}, blockManager, { appendTo: '#blocks7' }), |
|||
layerManager: Object.assign({}, layerManager, { appendTo: '#layers-container7' }), |
|||
styleManager: Object.assign({}, styleManager, { appendTo: '#styles-container7' }), |
|||
traitManager: Object.assign({}, traitManager, { appendTo: '#traits-container7' }), |
|||
selectorManager: Object.assign({}, selectorManager, { appendTo: '#styles-container7' }), |
|||
deviceManager, |
|||
}); |
|||
|
|||
var gjsConfigTheme = Object.assign({}, gjsConfigBlocks, { |
|||
container: '#gjs8', |
|||
blockManager: Object.assign({}, blockManagerIcons, { appendTo: '#blocks8' }), |
|||
layerManager: Object.assign({}, layerManager, { appendTo: '#layers-container8' }), |
|||
styleManager: Object.assign({}, styleManager, { appendTo: '#styles-container8' }), |
|||
traitManager: Object.assign({}, traitManager, { appendTo: '#traits-container8' }), |
|||
selectorManager: Object.assign({}, selectorManager, { appendTo: '#styles-container8' }), |
|||
deviceManager, |
|||
}); |
|||
|
|||
export default { |
|||
gjsConfigStart, |
|||
gjsConfigBlocks, |
|||
gjsConfigPanels, |
|||
gjsConfigLayers, |
|||
gjsConfigStyle, |
|||
gjsConfigTraits, |
|||
gjsConfigDevices, |
|||
gjsConfigTheme, |
|||
panelTop, |
|||
panelBasicActions, |
|||
panelBasicActionsIcons, |
|||
panelSidebar, |
|||
panelSwitcher, |
|||
panelSwitcherTraits, |
|||
panelSwitcherTraitsIcons, |
|||
panelDevices, |
|||
panelDevicesIcons, |
|||
}; |
|||
@ -0,0 +1,107 @@ |
|||
const version = require('./../../package.json').version; |
|||
const isDev = process.argv[2] === 'dev'; |
|||
const devPath = 'http://localhost:8080/dist'; |
|||
|
|||
module.exports = { |
|||
title: 'GrapesJS', |
|||
description: 'GrapesJS documentation', |
|||
base: '/docs/', |
|||
ga: 'UA-74284223-1', |
|||
serviceWorker: false, // Enable Service Worker for offline usage
|
|||
head: [ |
|||
['link', { rel: 'icon', href: '/logo-icon.png' }], |
|||
['link', { rel: 'stylesheet', href: isDev ? `${devPath}/css/grapes.min.css` : `../stylesheets/grapes.min.css?v${version}` }], |
|||
['script', { src: isDev ? `${devPath}/grapes.min.js` : `../js/grapes.min.js?v${version}` }], |
|||
], |
|||
localesSKIP: { |
|||
'/': { |
|||
lang: 'en-US', |
|||
}, |
|||
'/it/': { |
|||
lang: 'it-IT', |
|||
description: 'GrapesJS documentazione', |
|||
} |
|||
}, |
|||
themeConfig: { |
|||
editLinks: true, |
|||
docsDir: 'docs', |
|||
docsBranch: 'dev', |
|||
repo: 'artf/grapesjs', |
|||
editLinkText: 'Edit this page on GitHub', |
|||
|
|||
logo: '/logo.png', |
|||
lastUpdated: 'Last Updated', |
|||
locales: { |
|||
'/': { |
|||
selectText: 'EN', |
|||
label: 'English', |
|||
}, |
|||
'/it/': { |
|||
selectText: 'IT', |
|||
label: 'Italiano', |
|||
nav: [ |
|||
{ text: 'Supportaci', link: 'https://opencollective.com/grapesjs' }, |
|||
], |
|||
sidebar: [ |
|||
'/', |
|||
['/getting-started', 'Getting Started'], |
|||
] |
|||
} |
|||
}, |
|||
nav: [ |
|||
{ text: 'Docs', link: '/' }, |
|||
{ text: 'API Reference', link: '/api/' }, |
|||
{ text: 'Support Us', link: 'https://opencollective.com/grapesjs' }, |
|||
{ text: 'Twitter', link: 'https://twitter.com/grapesjs' }, |
|||
], |
|||
sidebar: { |
|||
'/api/': [ |
|||
'', |
|||
['/api/editor', 'Editor'], |
|||
['/api/canvas', 'Canvas'], |
|||
['/api/assets', 'Asset Manager'], |
|||
['/api/block_manager', 'Block Manager'], |
|||
['/api/commands', 'Commands'], |
|||
['/api/components', 'DOM Components'], |
|||
['/api/component', ' - Component'], |
|||
['/api/panels', 'Panels'], |
|||
['/api/style_manager', 'Style Manager'], |
|||
['/api/storage_manager', 'Storage Manager'], |
|||
['/api/device_manager', 'Device Manager'], |
|||
['/api/selector_manager', 'Selector Manager'], |
|||
['/api/css_composer', 'CSS Composer'], |
|||
['/api/modal_dialog', 'Modal'], |
|||
['/api/rich_text_editor', 'Rich Text Editor'], |
|||
['/api/keymaps', 'Keymaps'], |
|||
['/api/undo_manager', 'Undo Manager'], |
|||
], |
|||
'/': [ |
|||
'', |
|||
['/getting-started', 'Getting Started'], |
|||
// ['/faq', 'FAQ'],
|
|||
{ |
|||
title: 'Modules', |
|||
collapsable: false, |
|||
children: [ |
|||
['/modules/Assets', 'Assets'], |
|||
['/modules/Blocks', 'Blocks'], |
|||
['/modules/Commands', 'Commands'], |
|||
['/modules/Components', 'Components'], |
|||
['/modules/Components-js', 'Components & JS'], |
|||
['/modules/Traits', 'Traits'], |
|||
['/modules/Style-manager', 'Style Manager'], |
|||
['/modules/Storage', 'Storage Manager'], |
|||
['/modules/Plugins', 'Plugins'], |
|||
] |
|||
}, { |
|||
title: 'Guides', |
|||
collapsable: false, |
|||
children: [ |
|||
['/guides/Replace-Rich-Text-Editor', 'Replace Rich Text Editor'], |
|||
['/guides/Custom-CSS-parser', 'Use Custom CSS Parser'], |
|||
] |
|||
} |
|||
], |
|||
} |
|||
}, |
|||
} |
|||
@ -0,0 +1,9 @@ |
|||
// We can use this hook to install additional Vue plugins, register global components, or add additional router hooks
|
|||
module.exports = ({ |
|||
Vue, // the version of Vue being used in the VuePress app
|
|||
options, // the options for the root Vue instance
|
|||
router, // the router instance for the app
|
|||
siteData // site metadata
|
|||
}) => { |
|||
// ...apply enhancements to the app
|
|||
} |
|||
@ -0,0 +1,77 @@ |
|||
$accentColor = #e2627f |
|||
$accentColor = #e67891 |
|||
$navBarColor = white |
|||
$scrollBarSize = 8px |
|||
$pageWidth = 900px |
|||
|
|||
.img-ctr { |
|||
margin: 0 auto; |
|||
display: block; |
|||
} |
|||
|
|||
.navbar { |
|||
background-color: rgb(111, 41, 67); |
|||
background-image: linear-gradient(120deg, rgb(217, 131, 166), rgb(77, 17, 79)); |
|||
color: $navBarColor; |
|||
border: none; |
|||
|
|||
.logo { |
|||
min-width: auto; |
|||
} |
|||
|
|||
.site-name { |
|||
color: $navBarColor; |
|||
} |
|||
} |
|||
|
|||
.token.string { |
|||
color: $accentColor; |
|||
} |
|||
|
|||
@media (min-width: 719px) { |
|||
.nav-links a:hover, |
|||
.nav-links a.router-link-active { |
|||
color: #ffeff2; |
|||
} |
|||
} |
|||
|
|||
.search-box input { |
|||
border: 1px solid transparent; |
|||
transition: border 0.25s; |
|||
} |
|||
|
|||
.page-nav, |
|||
.page-edit, |
|||
.content:not(.custom) { |
|||
max-width: $pageWidth; |
|||
} |
|||
|
|||
.page__getting-started { |
|||
.language-js .language-js { |
|||
max-height: 300px; |
|||
} |
|||
} |
|||
|
|||
|
|||
// Scrollbars |
|||
* { |
|||
::-webkit-scrollbar-track {} |
|||
|
|||
::-webkit-scrollbar-thumb { |
|||
background-color: alpha(black, 0.1); |
|||
} |
|||
|
|||
::-webkit-scrollbar { |
|||
width: $scrollBarSize; |
|||
} |
|||
} |
|||
|
|||
.language-js { |
|||
::-webkit-scrollbar { |
|||
height: $scrollBarSize; |
|||
} |
|||
|
|||
::-webkit-scrollbar-thumb { |
|||
background-color: alpha(white, 0.3); |
|||
} |
|||
} |
|||
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 8.7 KiB |
|
After Width: | Height: | Size: 201 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 8.5 KiB |
|
After Width: | Height: | Size: 7.8 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
After Width: | Height: | Size: 174 KiB |
|
After Width: | Height: | Size: 93 KiB |
|
After Width: | Height: | Size: 3.9 KiB |
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 205 KiB |
|
After Width: | Height: | Size: 25 KiB |
|
After Width: | Height: | Size: 7.1 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 69 KiB |
|
After Width: | Height: | Size: 5.5 KiB |
|
After Width: | Height: | Size: 8.7 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 11 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 1.7 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 43 KiB |
@ -0,0 +1,80 @@ |
|||
<script> |
|||
export default { |
|||
render (h) { |
|||
return h('div', { class: 'carbon-ads', attrs: { id: 'native-carbon' }}) |
|||
}, |
|||
mounted () { |
|||
window.BSANativeCallback = (a) => { |
|||
const total = a.ads.length; |
|||
|
|||
if (!total) { |
|||
const src = document.createElement('script'); |
|||
src.src = `//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=grapesjscom`; |
|||
src.setAttribute('id', '_carbonads_js'); |
|||
const adCont = document.getElementById('native-carbon'); |
|||
adCont && adCont.appendChild(src); |
|||
} |
|||
}; |
|||
this.load(); |
|||
}, |
|||
watch: { |
|||
'$route' (to, from) { |
|||
if ( |
|||
to.path !== from.path && |
|||
this.$el.querySelector('#carbonads') |
|||
) { |
|||
this.$el.innerHTML = ''; |
|||
this.load(); |
|||
} |
|||
} |
|||
}, |
|||
methods: { |
|||
initCarbon() { |
|||
const { _bsa } = window; |
|||
if(typeof _bsa !== 'undefined' && _bsa) { |
|||
_bsa.init('default', 'CK7I62QJ', 'placement:grapesjscomdocs', { |
|||
target: '#native-carbon', |
|||
}); |
|||
} |
|||
}, |
|||
load () { |
|||
const s = document.createElement('script'); |
|||
// s.id = '_carbonads_js'; |
|||
// s.src = `//cdn.carbonads.com/carbon.js?serve=CKYI5KJU&placement=grapesjscom`; |
|||
s.src = `//m.servedby-buysellads.com/monetization.js`; |
|||
s.onload = () => this.initCarbon(); |
|||
this.$el.appendChild(s); |
|||
} |
|||
} |
|||
} |
|||
</script> |
|||
|
|||
<style lang="stylus"> |
|||
@import "~@default-theme/styles/config.styl" |
|||
|
|||
.carbon-ads |
|||
min-height 102px |
|||
padding 1.5rem 1.5rem 0 |
|||
margin-bottom -0.5rem |
|||
font-size 0.75rem |
|||
a |
|||
color #444 |
|||
font-weight normal |
|||
display inline |
|||
.carbon-img |
|||
float left |
|||
margin-right 1rem |
|||
border 1px solid $borderColor |
|||
img |
|||
display block |
|||
.carbon-poweredby |
|||
color #999 |
|||
display block |
|||
margin-top 0.5em |
|||
|
|||
@media (max-width: $MQMobile) |
|||
.carbon-ads |
|||
.carbon-img img |
|||
width 100px |
|||
height 77px |
|||
</style> |
|||
@ -0,0 +1,17 @@ |
|||
<template> |
|||
<Layout> |
|||
<CarbonAds slot="sidebar-top"/> |
|||
</Layout> |
|||
</template> |
|||
|
|||
<script> |
|||
var Layout = require('@default-theme/Layout.vue').default; |
|||
var CarbonAds = require('./CarbonAds.vue').default; |
|||
|
|||
export default { |
|||
components: { |
|||
Layout, |
|||
CarbonAds, |
|||
} |
|||
} |
|||
</script> |
|||
@ -0,0 +1,458 @@ |
|||
# Getting started |
|||
|
|||
This page will introduce you to the main options of GrapesJS and how it works, in the way to be able to create your custom editor. |
|||
|
|||
The pretty minimalistic way to instantiate the editor could be like this: |
|||
|
|||
```html |
|||
<link rel="stylesheet" href="path/to/grapes.min.css"> |
|||
<script src="path/to/grapes.min.js"></script> |
|||
|
|||
<div id="gjs"></div> |
|||
|
|||
<script type="text/javascript"> |
|||
var editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
components: '<div class="txt-red">Hello world!</div>', |
|||
style: '.txt-red{color: red}', |
|||
}); |
|||
</script> |
|||
``` |
|||
In just few lines, with the default configurations, you're already able to see something with which play around. |
|||
|
|||
[[img/default-gjs.jpg]] |
|||
|
|||
You'll see components commands on top left position that come handy to create and manage your blocks, below there are options which need to highlight and export them. When you select components ('mouse pointer' icon), on the right side, you should see pop up Class Manager and Style Manager options which allow to customize the style of the components. There is also a Layer Manager/Navigator ('hamburger' icon) which helps to manage easily the structure. |
|||
|
|||
Of course all those stuff (panels, buttons, commands, etc.) are set just as default so you can overwrite them and add more other. Before you start to create things you should know that GrapesJS UI is composed basically by a canvas (where you will 'draw') and panels (which will contain buttons) |
|||
|
|||
[[img/canvas-panels.jpg]] |
|||
|
|||
|
|||
If you'd like to extend the already instantiated editor you have to check [API Reference]. Check also [how to create plugins](./Creating-plugins) using the same API. |
|||
In this guide we'll focus on how to initialize the editor with all custom UI from scratch. |
|||
|
|||
Let's start the editor with some basic toolbar panel |
|||
|
|||
```js |
|||
... |
|||
var editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
height: '100%', |
|||
|
|||
panels: { |
|||
defaults: [{ |
|||
id: 'commands', |
|||
}], |
|||
} |
|||
}); |
|||
... |
|||
``` |
|||
In this example we set a panel with 'commands' as an id and after the render we'll see nothing more than an empty div added to our panels. The new panel is already styled as the id 'commands' is one of the default but you can use whatever you like and place it wherever you want with CSS. With refresh we might see something like shown in the image below, with the new panel on the left: |
|||
|
|||
[[img/new-panel.png]] |
|||
|
|||
> Check [Editor API Reference] for more details about editor configurations |
|||
|
|||
Now let's put some button inside |
|||
|
|||
```js |
|||
... |
|||
panels: { |
|||
defaults : [{ |
|||
id : 'commands', |
|||
buttons : [{ |
|||
id : 'smile', |
|||
className : 'fa fa-smile-o', |
|||
attributes : { title: 'Smile' } |
|||
}], |
|||
}], |
|||
} |
|||
... |
|||
``` |
|||
|
|||
On refresh the page might present some changes ('fa fa-smile-o' are from FontAwesome set, so be sure to have placed correctly the font directory) |
|||
|
|||
[[img/new-btn.png]] |
|||
|
|||
Yeah, the button is pretty nice and happy, but useless without any command assigned, if you click on it nothing gonna happen. |
|||
|
|||
> Check [Panels API Reference] for more details about Panels and Buttons |
|||
|
|||
|
|||
Assigning commands is pretty easy, but before you should define one or use one of defaults ([Built-in commands](./Built-in-commands)). So in this case we gonna create a new one. |
|||
|
|||
```js |
|||
... |
|||
panels: { |
|||
defaults : [{ |
|||
id : 'commands', |
|||
buttons : [{ |
|||
id : 'smile', |
|||
className : 'fa fa-smile-o', |
|||
attributes : { title: 'Smile' }, |
|||
command : 'helloWorld', |
|||
}], |
|||
}], |
|||
}, |
|||
commands: { |
|||
defaults: [{ |
|||
id: 'helloWorld', |
|||
|
|||
run: function(editor, senderBtn){ |
|||
alert('Hello world!'); |
|||
// Deactivate button |
|||
senderBtn.set('active', false); |
|||
}, |
|||
|
|||
stop: function(editor, senderBtn){ |
|||
}, |
|||
}] |
|||
} |
|||
... |
|||
``` |
|||
As you see we added a new command `helloWorld` and used its `id` as an identifier inside `button.command`. In addition to this we've also implemented two required methods, `run` and `stop`, to make button execute commands. |
|||
|
|||
[[img/btn-clicked.png]] |
|||
|
|||
|
|||
> Check [Commands API Reference] |
|||
|
|||
|
|||
Check the [demo](http://grapesjs.com/demo.html) for more complete usage of panels, buttons and built-in commands. |
|||
|
|||
|
|||
## Components |
|||
|
|||
Components are elements inside the canvas, which can be drawn by commands or injected directly via configurations. In simple terms components represent the structure of our HTML document. You can init the editor with passing components as an HTML string |
|||
|
|||
```js |
|||
... |
|||
// Disable default local storage in case you've already used GrapesJS |
|||
storageManager: {type: 'none'}, |
|||
|
|||
components: '<div style="width:300px; min-height:100px; margin: 0 auto"></div>' + |
|||
'<div style="width:400px; min-height:100px; margin: 0 auto"></div>' + |
|||
'<div style="width:500px; min-height:100px; margin: 0 auto"></div>', |
|||
... |
|||
``` |
|||
We added 3 simple components with some basic style. If you refresh probably you'll see the same empty page but are actually there, you only need to highlight them. |
|||
For this purpose already exists a command, so add it to your panel in this way |
|||
|
|||
```js |
|||
... |
|||
panels: { |
|||
defaults : [{ |
|||
id : 'commands', |
|||
buttons : [ |
|||
{ |
|||
id: 'smile', |
|||
... |
|||
}, |
|||
{ |
|||
id : 'vis', |
|||
className : 'fa fa-eye', |
|||
command : 'sw-visibility', |
|||
context : 'some-random-context', // For grouping context of buttons in the same panel |
|||
active : true, |
|||
}, |
|||
], |
|||
}], |
|||
}, |
|||
... |
|||
``` |
|||
Worth noting the use of `context` option (try to click 'smile' command without it) and `active` to enable it after the render. |
|||
Now you should be able to see blocks inside canvas. |
|||
|
|||
[[img/blocks3.jpg]] |
|||
|
|||
You could add other commands to enable interactions with blocks. Check [Built-in commands](./Built-in-commands) to get more information |
|||
|
|||
> Check [Components API Reference] |
|||
|
|||
|
|||
## Style Manager |
|||
|
|||
Any HTML structure requires, at some point, a proper style, so to meet this need the Style Manager was added as a built-in feature in GrapesJS. Style manager is composed by sectors, which group inside different types of CSS properties. So you can add, for instance, a `Dimension` sector for `width` and `height`, and another one as `Typography` for `font-size` and `color`. So it's up to you decide how organize sectors. |
|||
|
|||
To enable this module we rely on a built-in command `open-sm`, which shows up the Style Manager, which we gonna bind to another button in a separate panel |
|||
|
|||
```js |
|||
... |
|||
panels: { |
|||
defaults : [ |
|||
{ |
|||
id : 'commands', |
|||
... |
|||
},{ |
|||
// If you use this id the default CSS will place this panel on top right corner for you |
|||
id : 'views', |
|||
buttons : [{ |
|||
id : 'open-style-manager', |
|||
className : 'fa fa-paint-brush', |
|||
command : 'open-sm', |
|||
active : true, |
|||
}] |
|||
} |
|||
], |
|||
}, |
|||
... |
|||
``` |
|||
|
|||
After this you'll be able to see something like in the image below |
|||
|
|||
[[img/enabled-sm.jpg]] |
|||
|
|||
As you can see Style Manager is enabled but before using it you have to select an element in the canvas, for this purpose we can add another button with a built-in command `select-comp` in this way |
|||
|
|||
```js |
|||
... |
|||
panels: { |
|||
defaults : [{ |
|||
id : 'commands', |
|||
buttons : [ |
|||
{ |
|||
id: 'smile', |
|||
... |
|||
},{ |
|||
id : 'select', |
|||
className : 'fa fa-mouse-pointer', |
|||
command : 'select-comp', |
|||
} |
|||
], |
|||
}], |
|||
}, |
|||
... |
|||
``` |
|||
|
|||
Selecting one of the component will show up the Style Manager with default sectors, properties and an input where you can manage classes. The default class you see (cXX) was generated by extracting style from the component |
|||
|
|||
[[img/default-sm.jpg]] |
|||
|
|||
As we exploring different configurations inside GrapesJS we gonna overwrite all the default sectors to create some custom one |
|||
|
|||
Let's put a few sectors with use of `buildProps` which helps us building common properties |
|||
|
|||
```js |
|||
... |
|||
styleManager : { |
|||
sectors: [{ |
|||
name: 'Dimension', |
|||
buildProps: ['width', 'min-height'] |
|||
},{ |
|||
name: 'Extra', |
|||
buildProps: ['background-color', 'box-shadow'] |
|||
}] |
|||
} |
|||
... |
|||
``` |
|||
|
|||
Now you should be able to style components |
|||
|
|||
[[img/style-comp.jpg]] |
|||
|
|||
You can check the list of usable properties inside `buildProps` here: [Built-in properties](./Built-in-properties) |
|||
otherwise is possible to build them on your own, let's see how we'd have done the previous configuration without the `buildProps` helper |
|||
|
|||
```js |
|||
... |
|||
styleManager : { |
|||
sectors: [ |
|||
{ |
|||
name: 'Dimension', |
|||
properties:[ |
|||
{ |
|||
// Just the name |
|||
name : 'Width', |
|||
// CSS property |
|||
property : 'width', |
|||
// Type of the input, options: integer | radio | select | color | file | composite | stack |
|||
type : 'integer', |
|||
// Units, available only for 'integer' types |
|||
units : ['px', '%'], |
|||
// Default value |
|||
defaults : 'auto', |
|||
// Min value, available only for 'integer' types |
|||
min : 0, |
|||
},{ |
|||
// Here I'm going to be more original |
|||
name : 'Minimum height', |
|||
property : 'min-height', |
|||
type : 'select', |
|||
defaults : '100px', |
|||
// List of options, available only for 'select' and 'radio' types |
|||
list : [{ |
|||
value : '100px', |
|||
name : '100', |
|||
},{ |
|||
value : '200px', |
|||
name : '200', |
|||
},{ |
|||
value : '300px', |
|||
name : '300', |
|||
}], |
|||
} |
|||
] |
|||
},{ |
|||
name: 'Extra', |
|||
// Sectors are expanded by default so put this one closed |
|||
open: false, |
|||
properties:[ |
|||
{ |
|||
name : 'Background', |
|||
property : 'background-color', |
|||
type : 'color', |
|||
defaults: 'none' |
|||
},{ |
|||
name : 'Box shadow', |
|||
property : 'box-shadow', |
|||
type : 'stack', |
|||
preview : true, |
|||
// List of nested properties, available only for 'stack' and 'composite' types |
|||
properties : [{ |
|||
name: 'Shadow type', |
|||
// Nested properties with stack/composite type don't require proper 'property' name |
|||
// as all of them will be merged to parent property, eg. box-shadow: X Y ...; |
|||
property: 'shadow-type', |
|||
type: 'select', |
|||
defaults: '', |
|||
list: [ { value : '', name : 'Outside', }, |
|||
{ value : 'inset', name : 'Inside', }], |
|||
},{ |
|||
name: 'X position', |
|||
property: 'shadow-x', |
|||
type: 'integer', |
|||
units: ['px','%'], |
|||
defaults : 0, |
|||
},{ |
|||
name: 'Y position', |
|||
property: 'shadow-y', |
|||
type: 'integer', |
|||
units: ['px','%'], |
|||
defaults : 0, |
|||
},{ |
|||
name: 'Blur', |
|||
property: 'shadow-blur', |
|||
type: 'integer', |
|||
units: ['px'], |
|||
defaults : 0, |
|||
min: 0, |
|||
},{ |
|||
name: 'Spread', |
|||
property: 'shadow-spread', |
|||
type: 'integer', |
|||
units: ['px'], |
|||
defaults : 0, |
|||
},{ |
|||
name: 'Color', |
|||
property: 'shadow-color', |
|||
type: 'color', |
|||
defaults: 'black', |
|||
},], |
|||
} |
|||
] |
|||
} |
|||
] |
|||
} |
|||
... |
|||
``` |
|||
|
|||
As you can see using `buildProps` actually will save you a lot of work. You could also mix this techniques to obtain custom properties in less time. For example, let's see how can we setup the same width but with a different value of `min`: |
|||
|
|||
```js |
|||
... |
|||
styleManager : { |
|||
sectors: [{ |
|||
name: 'Dimension', |
|||
buildProps: ['width', 'min-height'], |
|||
properties:[{ |
|||
property: 'width', // Use 'property' as id |
|||
min: 30 |
|||
}] |
|||
}, |
|||
... |
|||
} |
|||
... |
|||
``` |
|||
|
|||
> Check [Style Manager API Reference] |
|||
|
|||
|
|||
## Store/load data |
|||
|
|||
In this last part we're gonna see how to store and load template data inside GrapesJS. You may already noticed that even if you refresh the page after changes on canvas your data are not lost and this because GrapesJS comes with some built-in storage implementation. |
|||
The default one is the localStorage which is pretty simple and all the data are stored locally on your computer. Let's see the options available for this storage |
|||
|
|||
```js |
|||
... |
|||
var editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
... |
|||
// Default configuration |
|||
storageManager: { |
|||
id: 'gjs-', // Prefix identifier that will be used inside storing and loading |
|||
type: 'local', // Type of the storage |
|||
autosave: true, // Store data automatically |
|||
autoload: true, // Autoload stored data on init |
|||
stepsBeforeSave: 1, // If autosave enabled, indicates how many changes are necessary before store method is triggered |
|||
storeComponents: false, // Enable/Disable storing of components in JSON format |
|||
storeStyles: false, // Enable/Disable storing of rules/style in JSON format |
|||
storeHtml: true, // Enable/Disable storing of components as HTML string |
|||
storeCss: true, // Enable/Disable storing of rules/style as CSS string |
|||
} |
|||
}); |
|||
... |
|||
``` |
|||
|
|||
Worth noting the defaut `id` parameter which adds a prefix for all keys to store. If you check the localStorage inside your DOM panel you'll see something like `{ 'gjs-components': '<div>....' ...}` in this way it prevents the risk of collisions, quite common with localStorage use in large applications. |
|||
|
|||
Storing data locally it's easy and fast but useless in some common cases. In the next example we'll see how to setup a remote storage, which is not far from the previous one |
|||
|
|||
```js |
|||
... |
|||
var editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
... |
|||
storageManager: { |
|||
type: 'remote', |
|||
stepsBeforeSave: 10, |
|||
urlStore: 'http://store/endpoint', |
|||
urlLoad: 'http://load/endpoint', |
|||
params: {}, // For custom values on requests |
|||
} |
|||
}); |
|||
... |
|||
``` |
|||
|
|||
As you can see we've left some default option unchanged, increased changes necessary for autosave triggering and passed remote endpoints. |
|||
|
|||
If you prefer you could also disable autosaving and do it by yourself using some custom command in this way: |
|||
|
|||
```js |
|||
... |
|||
storageManager: { |
|||
type: 'remote', |
|||
autosave: false, |
|||
}, |
|||
... |
|||
commands: { |
|||
defaults: [{ |
|||
id: 'storeData', |
|||
run: function(editor, senderBtn){ |
|||
editor.store(); |
|||
}, |
|||
}] |
|||
} |
|||
... |
|||
``` |
|||
|
|||
> Check [Storage Manager API Reference] |
|||
|
|||
|
|||
[API Reference]: <API-Reference> |
|||
[Panels API Reference]: <API-Panels> |
|||
[Commands API Reference]: <API-Commands> |
|||
[Components API Reference]: <API-Components> |
|||
[Style Manager API Reference]: <API-Style-Manager> |
|||
[Editor API Reference]: <API-Editor> |
|||
[Storage Manager API Reference]: <API-Storage-Manager> |
|||
@ -0,0 +1,57 @@ |
|||
# Introduction |
|||
|
|||
[[toc]] |
|||
|
|||
## What is GrapesJS? |
|||
At first glance might think this is just another page/HTML builder, but it's something more. GrapesJS is a multi-purpose, Web Builder Framework, which means it allows you to easily create a drag & drop enabled builder of "things". By "things" we mean anything with HTML-like structure, which entails much more than web pages. We use HTML-like structure basically everywhere: Newsletters (eg. [MJML](https://mjml.io/)), Native Mobile Applications (eg. [React Native](https://github.com/facebook/react-native)), Native Desktop Applications (eg. [Vuido](https://vuido.mimec.org)), PDFs (eg. [React PDF](https://github.com/diegomura/react-pdf)), etc. So, for everything you can imagine as a set of elements like `<tag some="attribute">... other nested elements ...</tag>` you can create easily a GrapesJS builder around it and then use it independently your applications. |
|||
GrapesJS ships with features and tools that enable you to craft easy to use builders. Which allows your users to create complex HTML-like templates without any knowledge of coding. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Why GrapesJS? |
|||
GrapesJS was designed primarily to for use inside Content Management Systems to speed up the creation of dynamic templates and replace common WYSIWYG editors. Which are good for content editing, but inappropriate for creating HTML structures. Instead of creating an application we decided to create an extensible framework that could be used by anyone for any purpose. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Quick Start |
|||
To showcase the power of GrapesJS we have created some presets. |
|||
|
|||
* [grapesjs-preset-webpage](https://github.com/artf/grapesjs-preset-webpage) - [Webpage Builder](http://artf.github.io/grapesjs/demo.html) |
|||
* [grapesjs-preset-newsletter](https://github.com/artf/grapesjs-preset-newsletter) - [Newsletter Builder](http://artf.github.io/grapesjs/demo-newsletter-editor.html) |
|||
* [grapesjs-mjml](https://github.com/artf/grapesjs-mjml) - [Newsletter Builder with MJML](http://artf.github.io/grapesjs/demo-mjml.html) |
|||
|
|||
You can actually use them as a starting point for your editors, so, just follow the instructions on their repositories to get a quick start for your builder. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Download |
|||
|
|||
Latest version: [](https://www.npmjs.com/package/grapesjs) |
|||
|
|||
You can download GrapesJS from one of these sources |
|||
|
|||
* CDNs |
|||
* unpkg |
|||
* `https://unpkg.com/grapesjs` |
|||
* `https://unpkg.com/grapesjs/dist/css/grapes.min.css` |
|||
* cdnjs |
|||
* `https://cdnjs.cloudflare.com/ajax/libs/grapesjs/0.12.17/grapes.min.js` |
|||
* `https://cdnjs.cloudflare.com/ajax/libs/grapesjs/0.12.17/css/grapes.min.css` |
|||
* npm |
|||
* `npm i grapesjs` |
|||
* git |
|||
* `git clone https://github.com/artf/grapesjs.git` |
|||
|
|||
|
|||
|
|||
|
|||
## Changelog |
|||
|
|||
To track changes made in the library we rely on [Github Releases](https://github.com/artf/grapesjs/releases) |
|||
|
|||
@ -0,0 +1,41 @@ |
|||
// This script uses documentation to generate API Reference files
|
|||
const path = require('path'); |
|||
const exec = require('child_process').exec; |
|||
const docRoot = __dirname; |
|||
const srcRoot = path.join(docRoot, '../src/'); |
|||
const binRoot = path.join(docRoot, '../node_modules/.bin/'); |
|||
const cmds = [ |
|||
['editor/index.js', 'editor.md'], |
|||
['asset_manager/index.js', 'assets.md'], |
|||
['block_manager/index.js', 'block_manager.md'], |
|||
['commands/index.js', 'commands.md'], |
|||
['dom_components/index.js', 'components.md'], |
|||
['dom_components/model/Component.js', 'component.md'], |
|||
['panels/index.js', 'panels.md'], |
|||
['style_manager/index.js', 'style_manager.md'], |
|||
['storage_manager/index.js', 'storage_manager.md'], |
|||
['device_manager/index.js', 'device_manager.md'], |
|||
['selector_manager/index.js', 'selector_manager.md'], |
|||
['css_composer/index.js', 'css_composer.md'], |
|||
['modal_dialog/index.js', 'modal_dialog.md'], |
|||
['rich_text_editor/index.js', 'rich_text_editor.md'], |
|||
['keymaps/index.js', 'keymaps.md'], |
|||
['undo_manager/index.js', 'undo_manager.md'], |
|||
['canvas/index.js', 'canvas.md'], |
|||
].map(entry => |
|||
`${binRoot}documentation build ${srcRoot}/${entry[0]} -o ${docRoot}/api/${entry[1]} -f md --shallow --markdown-toc false`) |
|||
.join(' && '); |
|||
|
|||
console.log('Start API Reference generation...'); |
|||
exec(cmds, (error, stdout, stderr) => { |
|||
if (error) { |
|||
console.error( 'Failed to update API Reference: ', error); |
|||
return; |
|||
} |
|||
|
|||
stdout.trim().split('\n').forEach(function (line) { |
|||
console.info(line); |
|||
}); |
|||
|
|||
console.log('API Reference generation done!'); |
|||
}); |
|||
@ -0,0 +1,7 @@ |
|||
--- |
|||
pageClass: page__apis |
|||
--- |
|||
|
|||
# API Reference |
|||
|
|||
Here you can find the documentation about GrapesJS' APIs. Mainly, you would use them for your editor to extend the basic functionality of the framework or you could also [create a plugin](/modules/Plugins.html) and make those extensions reusable and available to others. |
|||
@ -0,0 +1,255 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## AssetManager |
|||
|
|||
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({ |
|||
assetManager: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const assetManager = editor.AssetManager; |
|||
``` |
|||
|
|||
- [add][2] |
|||
- [get][3] |
|||
- [getAll][4] |
|||
- [getAllVisible][5] |
|||
- [remove][6] |
|||
- [store][7] |
|||
- [load][8] |
|||
- [getContainer][9] |
|||
- [getAssetsEl][10] |
|||
- [addType][11] |
|||
- [getType][12] |
|||
- [getTypes][13] |
|||
|
|||
## add |
|||
|
|||
Add new asset/s to the collection. URLs are supposed to be unique |
|||
|
|||
### Parameters |
|||
|
|||
- `asset` **([string][14] \| [Object][15] \| [Array][16]<[string][14]> | [Array][16]<[Object][15]>)** URL strings or an objects representing the resource. |
|||
- `opts` **[Object][15]?** Options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// In case of strings, would be interpreted as images |
|||
assetManager.add('http://img.jpg'); |
|||
assetManager.add(['http://img.jpg', './path/to/img.png']); |
|||
|
|||
// Using objects you could indicate the type and other meta informations |
|||
assetManager.add({ |
|||
src: 'http://img.jpg', |
|||
//type: 'image', //image is default |
|||
height: 300, |
|||
width: 200, |
|||
}); |
|||
assetManager.add([{ |
|||
src: 'http://img.jpg', |
|||
},{ |
|||
src: './path/to/img.png', |
|||
}]); |
|||
``` |
|||
|
|||
Returns **Model** |
|||
|
|||
## get |
|||
|
|||
Returns the asset by URL |
|||
|
|||
### Parameters |
|||
|
|||
- `src` **[string][14]** URL of the asset |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var asset = assetManager.get('http://img.jpg'); |
|||
``` |
|||
|
|||
Returns **[Object][15]** Object representing the asset |
|||
|
|||
## getAll |
|||
|
|||
Return the global collection, containing all the assets |
|||
|
|||
Returns **Collection** |
|||
|
|||
## getAllVisible |
|||
|
|||
Return the visible collection, which containes assets actually rendered |
|||
|
|||
Returns **Collection** |
|||
|
|||
## remove |
|||
|
|||
Remove the asset by its URL |
|||
|
|||
### Parameters |
|||
|
|||
- `src` **[string][14]** URL of the asset |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
assetManager.remove('http://img.jpg'); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## store |
|||
|
|||
Store assets data to the selected storage |
|||
|
|||
### Parameters |
|||
|
|||
- `noStore` **[Boolean][17]** If true, won't store |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var assets = assetManager.store(); |
|||
``` |
|||
|
|||
Returns **[Object][15]** Data to store |
|||
|
|||
## load |
|||
|
|||
Load data from the passed object. |
|||
The fetched data will be added to the collection. |
|||
|
|||
### Parameters |
|||
|
|||
- `data` **[Object][15]** Object of data to load (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var assets = assetManager.load({ |
|||
assets: [...] |
|||
}) |
|||
``` |
|||
|
|||
Returns **[Object][15]** Loaded assets |
|||
|
|||
## getContainer |
|||
|
|||
Return the Asset Manager Container |
|||
|
|||
Returns **[HTMLElement][18]** |
|||
|
|||
## getAssetsEl |
|||
|
|||
Get assets element container |
|||
|
|||
Returns **[HTMLElement][18]** |
|||
|
|||
## render |
|||
|
|||
Render assets |
|||
|
|||
### Parameters |
|||
|
|||
- `assets` **[array][16]** Assets to render, without the argument will render |
|||
all global assets |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Render all assets |
|||
assetManager.render(); |
|||
|
|||
// Render some of the assets |
|||
const assets = assetManager.getAll(); |
|||
assetManager.render(assets.filter( |
|||
asset => asset.get('category') == 'cats' |
|||
)); |
|||
``` |
|||
|
|||
Returns **[HTMLElement][18]** |
|||
|
|||
## addType |
|||
|
|||
Add new type. If you want to get more about type definition we suggest to read the [module's page][19] |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][14]** Type ID |
|||
- `definition` **[Object][15]** Definition of the type. Each definition contains |
|||
`model` (business logic), `view` (presentation logic) |
|||
and `isType` function which recognize the type of the |
|||
passed entity |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
assetManager.addType('my-type', { |
|||
model: {}, |
|||
view: {}, |
|||
isType: (value) => {}, |
|||
}) |
|||
``` |
|||
|
|||
## getType |
|||
|
|||
Get type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][14]** Type ID |
|||
|
|||
Returns **[Object][15]** Type definition |
|||
|
|||
## getTypes |
|||
|
|||
Get types |
|||
|
|||
Returns **[Array][16]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/asset_manager/config/config.js |
|||
|
|||
[2]: #add |
|||
|
|||
[3]: #get |
|||
|
|||
[4]: #getall |
|||
|
|||
[5]: #getallvisible |
|||
|
|||
[6]: #remove |
|||
|
|||
[7]: #store |
|||
|
|||
[8]: #load |
|||
|
|||
[9]: #getcontainer |
|||
|
|||
[10]: #getassetsel |
|||
|
|||
[11]: #addtype |
|||
|
|||
[12]: #gettype |
|||
|
|||
[13]: #gettypes |
|||
|
|||
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[18]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
|
|||
[19]: /modules/Assets.html |
|||
@ -0,0 +1,197 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## BlockManager |
|||
|
|||
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. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const blockManager = editor.BlockManager; |
|||
``` |
|||
|
|||
- [add][2] |
|||
- [get][3] |
|||
- [getAll][4] |
|||
- [getAllVisible][5] |
|||
- [remove][6] |
|||
- [getConfig][7] |
|||
- [getCategories][8] |
|||
- [getContainer][9] |
|||
- [render][10] |
|||
|
|||
## getConfig |
|||
|
|||
Get configuration object |
|||
|
|||
Returns **[Object][11]** |
|||
|
|||
## onLoad |
|||
|
|||
Load default blocks if the collection is empty |
|||
|
|||
## add |
|||
|
|||
Add new block to the collection. |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][12]** Block id |
|||
- `opts` **[Object][11]** Options |
|||
- `opts.label` **[string][12]** Name of the block |
|||
- `opts.content` **[string][12]** HTML content |
|||
- `opts.category` **([string][12] \| [Object][11])** Group the block inside a catgegory. |
|||
You should pass objects with id property, eg: |
|||
{id: 'some-uid', label: 'My category'} |
|||
The string will be converted in: |
|||
'someid' => {id: 'someid', label: 'someid'} |
|||
- `opts.attributes` **[Object][11]** Block attributes (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
blockManager.add('h1-block', { |
|||
label: 'Heading', |
|||
content: '<h1>Put your title here</h1>', |
|||
category: 'Basic', |
|||
attributes: { |
|||
title: 'Insert h1 block' |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
Returns **Block** Added block |
|||
|
|||
## get |
|||
|
|||
Return 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: '<h1>Put your ...', ...} |
|||
``` |
|||
|
|||
## getAll |
|||
|
|||
Return all blocks |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const blocks = blockManager.getAll(); |
|||
console.log(JSON.stringify(blocks)); |
|||
// [{label: 'Heading', content: '<h1>Put your ...'}, ...] |
|||
``` |
|||
|
|||
Returns **Collection** |
|||
|
|||
## getAllVisible |
|||
|
|||
Return the visible collection, which containes blocks actually rendered |
|||
|
|||
Returns **Collection** |
|||
|
|||
## remove |
|||
|
|||
Remove a block by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][12]** Block id |
|||
|
|||
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: '<div>Content</div>'} |
|||
]); |
|||
|
|||
// 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 |
|||
@ -0,0 +1,183 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Canvas |
|||
|
|||
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({ |
|||
canvas: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const canvas = editor.Canvas; |
|||
``` |
|||
|
|||
- [getConfig][2] |
|||
- [getElement][3] |
|||
- [getFrameEl][4] |
|||
- [getWindow][5] |
|||
- [getDocument][6] |
|||
- [getBody][7] |
|||
- [getWrapperEl][8] |
|||
- [setCustomBadgeLabel][9] |
|||
- [hasFocus][10] |
|||
- [scrollTo][11] |
|||
- [setZoom][12] |
|||
- [getZoom][13] |
|||
|
|||
## getConfig |
|||
|
|||
Get the configuration object |
|||
|
|||
Returns **[Object][14]** |
|||
|
|||
## getElement |
|||
|
|||
Get the canvas element |
|||
|
|||
Returns **[HTMLElement][15]** |
|||
|
|||
## getFrameEl |
|||
|
|||
Get the iframe element of the canvas |
|||
|
|||
Returns **[HTMLIFrameElement][16]** |
|||
|
|||
## getWindow |
|||
|
|||
Get the window instance of the iframe element |
|||
|
|||
Returns **[Window][17]** |
|||
|
|||
## getDocument |
|||
|
|||
Get the document of the iframe element |
|||
|
|||
Returns **HTMLDocument** |
|||
|
|||
## getBody |
|||
|
|||
Get the body of the iframe element |
|||
|
|||
Returns **[HTMLBodyElement][18]** |
|||
|
|||
## getWrapperEl |
|||
|
|||
Get the wrapper element containing all the components |
|||
|
|||
Returns **[HTMLElement][15]** |
|||
|
|||
## setCustomBadgeLabel |
|||
|
|||
Set custom badge naming strategy |
|||
|
|||
### Parameters |
|||
|
|||
- `f` **[Function][19]** |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
canvas.setCustomBadgeLabel(function(component){ |
|||
return component.getName(); |
|||
}); |
|||
``` |
|||
|
|||
## getRect |
|||
|
|||
Get canvas rectangular data |
|||
|
|||
Returns **[Object][14]** |
|||
|
|||
## hasFocus |
|||
|
|||
Check if the canvas is focused |
|||
|
|||
Returns **[Boolean][20]** |
|||
|
|||
## scrollTo |
|||
|
|||
Scroll canvas to the element if it's not visible. The scrolling is |
|||
executed via `scrollIntoView` API and options of this method are |
|||
passed to it. For instance, you can scroll smoothly by using |
|||
`{ behavior: 'smooth' }`. |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **([HTMLElement][15] | Component)** |
|||
- `opts` **[Object][14]** Options, same as options for `scrollIntoView` (optional, default `{}`) |
|||
- `opts.force` **[Boolean][20]** Force the scroll, even if the element is already visible (optional, default `false`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const selected = editor.getSelected(); |
|||
// Scroll smoothly (this behavior can be polyfilled) |
|||
canvas.scrollTo(selected, { behavior: 'smooth' }); |
|||
// Force the scroll, even if the element is alredy visible |
|||
canvas.scrollTo(selected, { force: true }); |
|||
``` |
|||
|
|||
## setZoom |
|||
|
|||
Set zoom value |
|||
|
|||
### Parameters |
|||
|
|||
- `value` **[Number][21]** The zoom value, from 0 to 100 |
|||
|
|||
Returns **this** |
|||
|
|||
## getZoom |
|||
|
|||
Get zoom value |
|||
|
|||
Returns **[Number][21]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/canvas/config/config.js |
|||
|
|||
[2]: #getconfig |
|||
|
|||
[3]: #getelement |
|||
|
|||
[4]: #getframeel |
|||
|
|||
[5]: #getwindow |
|||
|
|||
[6]: #getdocument |
|||
|
|||
[7]: #getbody |
|||
|
|||
[8]: #getwrapperel |
|||
|
|||
[9]: #setcustombadgelabel |
|||
|
|||
[10]: #hasfocus |
|||
|
|||
[11]: #scrollto |
|||
|
|||
[12]: #setzoom |
|||
|
|||
[13]: #getzoom |
|||
|
|||
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement |
|||
|
|||
[17]: https://developer.mozilla.org/docs/Web/API/Window |
|||
|
|||
[18]: https://developer.mozilla.org/docs/Web/HTML/Element/body |
|||
|
|||
[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
|||
@ -0,0 +1,210 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Commands |
|||
|
|||
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({ |
|||
commands: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const commands = editor.Commands; |
|||
``` |
|||
|
|||
- [add][2] |
|||
- [get][3] |
|||
- [getAll][4] |
|||
- [extend][5] |
|||
- [has][6] |
|||
- [run][7] |
|||
- [stop][8] |
|||
- [isActive][9] |
|||
- [getActive][10] |
|||
|
|||
## add |
|||
|
|||
Add new command to the collection |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][11]** Command's ID |
|||
- `command` **([Object][12] \| [Function][13])** Object representing your command, |
|||
By passing just a function it's intended as a stateless command |
|||
(just like passing an object with only `run` method). |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
commands.add('myCommand', { |
|||
run(editor, sender) { |
|||
alert('Hello world!'); |
|||
}, |
|||
stop(editor, sender) { |
|||
}, |
|||
}); |
|||
// As a function |
|||
commands.add('myCommand2', editor => { ... }); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## get |
|||
|
|||
Get command by ID |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][11]** Command's ID |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var myCommand = commands.get('myCommand'); |
|||
myCommand.run(); |
|||
``` |
|||
|
|||
Returns **[Object][12]** Object representing the command |
|||
|
|||
## extend |
|||
|
|||
Extend the command. The command to extend should be defined as an object |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][11]** Command's ID |
|||
- `cmd` (optional, default `{}`) |
|||
- `Object` **[Object][12]** with the new command functions |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
commands.extend('old-command', { |
|||
someInnerFunction() { |
|||
// ... |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## has |
|||
|
|||
Check if command exists |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][11]** Command's ID |
|||
|
|||
Returns **[Boolean][14]** |
|||
|
|||
## getAll |
|||
|
|||
Get an object containing all the commands |
|||
|
|||
Returns **[Object][12]** |
|||
|
|||
## run |
|||
|
|||
Execute the command |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][11]** Command ID |
|||
- `options` **[Object][12]** Options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
commands.run('myCommand', { someOption: 1 }); |
|||
``` |
|||
|
|||
Returns **any** The return is defined by the command |
|||
|
|||
## stop |
|||
|
|||
Stop the command |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][11]** Command ID |
|||
- `options` **[Object][12]** Options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
commands.stop('myCommand', { someOption: 1 }); |
|||
``` |
|||
|
|||
Returns **any** The return is defined by the command |
|||
|
|||
## isActive |
|||
|
|||
Check if the command is active. You activate commands with `run` |
|||
and disable them with `stop`. If the command was created without `stop` |
|||
method it can't be registered as active |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][11]** Command id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const cId = 'some-command'; |
|||
commands.run(cId); |
|||
commands.isActive(cId); |
|||
// -> true |
|||
commands.stop(cId); |
|||
commands.isActive(cId); |
|||
// -> false |
|||
``` |
|||
|
|||
Returns **[Boolean][14]** |
|||
|
|||
## getActive |
|||
|
|||
Get all active commands |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
console.log(commands.getActive()); |
|||
// -> { someCommand: itsLastReturn, anotherOne: ... }; |
|||
``` |
|||
|
|||
Returns **[Object][12]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/commands/config/config.js |
|||
|
|||
[2]: #add |
|||
|
|||
[3]: #get |
|||
|
|||
[4]: #getall |
|||
|
|||
[5]: #extend |
|||
|
|||
[6]: #has |
|||
|
|||
[7]: #run |
|||
|
|||
[8]: #stop |
|||
|
|||
[9]: #isactive |
|||
|
|||
[10]: #getactive |
|||
|
|||
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
@ -0,0 +1,616 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## 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: |
|||
|
|||
```js |
|||
component.set({ |
|||
tagName: 'span', |
|||
attributes: { ... }, |
|||
removable: false, |
|||
}); |
|||
component.get('tagName'); |
|||
// -> 'span' |
|||
``` |
|||
|
|||
### Properties |
|||
|
|||
- `type` **[String][1]?** Component type, eg. `text`, `image`, `video`, etc. |
|||
- `tagName` **[String][1]?** HTML tag of the component, eg. `span`. Default: `div` |
|||
- `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}` |
|||
- `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges |
|||
- `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true` |
|||
- `draggable` **([Boolean][3] \| [String][1])?** 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 |
|||
containing `some-class` class and `Hello` title, and `column` components. Default: `true` |
|||
- `droppable` **([Boolean][3] \| [String][1])?** Indicates if it's possible to drop other components inside. You can use |
|||
a query string as with `draggable`. Default: `true` |
|||
- `badgable` **[Boolean][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true` |
|||
- `stylable` **([Boolean][3] \| [Array][4]<[String][1]>)?** 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][4]<[String][1]>?** Indicate an array of style properties to show up which has been marked as `toRequire`. Default: `[]` |
|||
- `unstylable` **[Array][4]<[String][1]>?** Indicate an array of style properties which should be hidden from the style manager. Default: `[]` |
|||
- `style-signature` **[Array][4]<[String][1]>?** 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][3]?** It can be highlighted with 'dotted' borders if true. Default: `true` |
|||
- `copyable` **[Boolean][3]?** True if it's possible to clone the component. Default: `true` |
|||
- `resizable` **[Boolean][3]?** Indicates if it's possible to resize the component. It's also possible to pass an object as [options for the Resizer][5]. Default: `false` |
|||
- `editable` **[Boolean][3]?** Allow to edit the content of the component (used on Text components). Default: `false` |
|||
- `layerable` **[Boolean][3]?** Set to `false` if you need to hide the component inside Layers. Default: `true` |
|||
- `selectable` **[Boolean][3]?** Allow component to be selected when clicked. Default: `true` |
|||
- `hoverable` **[Boolean][3]?** Shows a highlight outline when hovering on the element if `true`. Default: `true` |
|||
- `void` **[Boolean][3]?** This property is used by the HTML exporter as void elements don't have closing tags, eg. `<br/>`, `<hr/>`, etc. Default: `false` |
|||
- `content` **[String][1]?** Content of the component (not escaped) which will be appended before children rendering. Default: `''` |
|||
- `icon` **[String][1]?** Component's icon, this string will be inserted before the name (in Layers and badge), eg. it can be an HTML string '<i class="fa fa-square-o"></i>'. Default: `''` |
|||
- `script` **([String][1] \| [Function][6])?** Component's javascript. More about it [here][7]. Default: `''` |
|||
- `script-export` **([String][1] \| [Function][6])?** You can specify javascript available only in export functions (eg. when you get the HTML). |
|||
If this property is defined it will overwrite the `script` one (in export functions). Default: `''` |
|||
- `traits` **[Array][4]<([Object][2] \| [String][1])>?** Component's traits. More about it [here][8]. Default: `['id', 'title']` |
|||
- `propagate` **[Array][4]<[String][1]>?** 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 the `propagate` array (and the `propagate` property itself). Default: `[]` |
|||
- `toolbar` **[Array][4]<[Object][2]>?** 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, when `toolbar` property is falsy the editor will add automatically commands like `move`, `delete`, etc. based on its properties. |
|||
- `components` **Collection<[Component][9]>?** 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][1]** Property name, if triggered after some property update |
|||
- `value` **any** Property value, if triggered after some property update |
|||
- `previous` **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][1]** Component type |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.is('image') |
|||
// -> false |
|||
``` |
|||
|
|||
Returns **[Boolean][3]** |
|||
|
|||
## props |
|||
|
|||
Return all the propeties |
|||
|
|||
Returns **[Object][2]** |
|||
|
|||
## index |
|||
|
|||
Get the index of the component in the parent collection. |
|||
|
|||
Returns **[Number][10]** |
|||
|
|||
## setDragMode |
|||
|
|||
Change the drag mode of the component. |
|||
To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][11] |
|||
|
|||
### Parameters |
|||
|
|||
- `value` **[String][1]** 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][1]** Query string |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.find('div > .class'); |
|||
// -> [Component, Component, ...] |
|||
``` |
|||
|
|||
Returns **[Array][4]** Array of components |
|||
|
|||
## findType |
|||
|
|||
Find all inner components by component id. |
|||
The advantage of this method over `find` is that you can use it |
|||
also before rendering the component |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][1]** Component id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const allImages = component.findType('image'); |
|||
console.log(allImages[0]) // prints the first found component |
|||
``` |
|||
|
|||
Returns **[Array][4]<[Component][9]>** |
|||
|
|||
## closest |
|||
|
|||
Find the closest parent component by query string. |
|||
**ATTENTION**: this method works only with already rendered component |
|||
|
|||
### Parameters |
|||
|
|||
- `query` **[string][1]** Query string |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.closest('div.some-class'); |
|||
// -> Component |
|||
``` |
|||
|
|||
Returns **[Component][9]** |
|||
|
|||
## replaceWith |
|||
|
|||
Replace a component with another one |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **([String][1] \| [Component][9])** Component or HTML string |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.replaceWith('<div>Some new content</div>'); |
|||
// -> Component |
|||
``` |
|||
|
|||
Returns **([Component][9] \| [Array][4]<[Component][9]>)** New added component/s |
|||
|
|||
## setAttributes |
|||
|
|||
Update attributes of the component |
|||
|
|||
### Parameters |
|||
|
|||
- `attrs` **[Object][2]** Key value attributes |
|||
- `opts` (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.setAttributes({ id: 'test', 'data-key': 'value' }); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## addAttributes |
|||
|
|||
Add attributes to the component |
|||
|
|||
### Parameters |
|||
|
|||
- `attrs` **[Object][2]** Key value attributes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.addAttributes({ 'data-key': 'value' }); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## getStyle |
|||
|
|||
Get the style of the component |
|||
|
|||
Returns **[Object][2]** |
|||
|
|||
## setStyle |
|||
|
|||
Set the style on the component |
|||
|
|||
### Parameters |
|||
|
|||
- `prop` **[Object][2]** Key value style object (optional, default `{}`) |
|||
- `opts` (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.setStyle({ color: 'red' }); |
|||
``` |
|||
|
|||
Returns **[Object][2]** |
|||
|
|||
## getAttributes |
|||
|
|||
Return all component's attributes |
|||
|
|||
Returns **[Object][2]** |
|||
|
|||
## addClass |
|||
|
|||
Add classes |
|||
|
|||
### Parameters |
|||
|
|||
- `classes` **([Array][4]<[String][1]> | [String][1])** Array or string of classes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
model.addClass('class1'); |
|||
model.addClass('class1 class2'); |
|||
model.addClass(['class1', 'class2']); |
|||
// -> [SelectorObject, ...] |
|||
``` |
|||
|
|||
Returns **[Array][4]** Array of added selectors |
|||
|
|||
## setClass |
|||
|
|||
Set classes (resets current collection) |
|||
|
|||
### Parameters |
|||
|
|||
- `classes` **([Array][4]<[String][1]> | [String][1])** Array or string of classes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
model.setClass('class1'); |
|||
model.setClass('class1 class2'); |
|||
model.setClass(['class1', 'class2']); |
|||
// -> [SelectorObject, ...] |
|||
``` |
|||
|
|||
Returns **[Array][4]** Array of added selectors |
|||
|
|||
## removeClass |
|||
|
|||
Remove classes |
|||
|
|||
### Parameters |
|||
|
|||
- `classes` **([Array][4]<[String][1]> | [String][1])** Array or string of classes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
model.removeClass('class1'); |
|||
model.removeClass('class1 class2'); |
|||
model.removeClass(['class1', 'class2']); |
|||
// -> [SelectorObject, ...] |
|||
``` |
|||
|
|||
Returns **[Array][4]** Array of removed selectors |
|||
|
|||
## getClasses |
|||
|
|||
Returns component's classes as an array of strings |
|||
|
|||
Returns **[Array][4]** |
|||
|
|||
## append |
|||
|
|||
Add new component children |
|||
|
|||
### Parameters |
|||
|
|||
- `components` **([Component][9] \| [String][1])** Component to add |
|||
- `opts` **[Object][2]** Options, same as in `model.add()`(from backbone) (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
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][4]** Array of appended components |
|||
|
|||
## components |
|||
|
|||
Set new collection if `components` are provided, otherwise the |
|||
current collection is returned |
|||
|
|||
### Parameters |
|||
|
|||
- `components` **([Component][9] \| [String][1])?** Components to set |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Set new collection |
|||
component.components('<span></span><div></div>'); |
|||
// Get current collection |
|||
const collection = component.components(); |
|||
console.log(collection.length); |
|||
// -> 2 |
|||
``` |
|||
|
|||
Returns **(Collection | [Array][4]<[Component][9]>)** |
|||
|
|||
## parent |
|||
|
|||
Get the parent component, if exists |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.parent(); |
|||
// -> Component |
|||
``` |
|||
|
|||
Returns **[Component][9]** |
|||
|
|||
## getTrait |
|||
|
|||
Get the trait by id/name |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][1]** The `id` or `name` of the trait |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const traitTitle = component.getTrait('title'); |
|||
traitTitle && traitTitle.set('label', 'New label'); |
|||
``` |
|||
|
|||
Returns **Trait** Trait model |
|||
|
|||
## updateTrait |
|||
|
|||
Update a trait |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][1]** The `id` or `name` of the trait |
|||
- `props` **[Object][2]** Object with the props to update |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
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][1]** The `id` or `name` of the trait |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const traitTitle = component.getTraitIndex('title'); |
|||
console.log(traitTitle); // 1 |
|||
``` |
|||
|
|||
Returns **[Number][10]** Index position of the current trait |
|||
|
|||
## removeTrait |
|||
|
|||
Remove trait/s by id/s. |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **([String][1] \| [Array][4]<[String][1]>)** The `id`/`name` of the trait (or an array) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.removeTrait('title'); |
|||
component.removeTrait(['title', 'id']); |
|||
``` |
|||
|
|||
Returns **[Array][4]** Array of removed traits |
|||
|
|||
## addTrait |
|||
|
|||
Add trait/s by id/s. |
|||
|
|||
### Parameters |
|||
|
|||
- `trait` **([String][1] \| [Object][2] \| [Array][4]<([String][1] \| [Object][2])>)** Trait to add (or an array of traits) |
|||
- `opts` **Options** Options for the add (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
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][4]** Array of added traits |
|||
|
|||
## getName |
|||
|
|||
Get the name of the component |
|||
|
|||
Returns **[String][1]** |
|||
|
|||
## getIcon |
|||
|
|||
Get the icon string |
|||
|
|||
Returns **[String][1]** |
|||
|
|||
## toHTML |
|||
|
|||
Return HTML string of the component |
|||
|
|||
### Parameters |
|||
|
|||
- `opts` **[Object][2]** Options (optional, default `{}`) |
|||
- `opts.attributes` **([Object][2] \| [Function][6])** 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, default `null`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// 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][1]** HTML string |
|||
|
|||
## getId |
|||
|
|||
Return the component id |
|||
|
|||
Returns **[String][1]** |
|||
|
|||
## setId |
|||
|
|||
Set new id on the component |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[String][1]** |
|||
|
|||
Returns **this** |
|||
|
|||
## getEl |
|||
|
|||
Get the DOM element of the component. |
|||
This works only if the component is already rendered |
|||
|
|||
Returns **[HTMLElement][12]** |
|||
|
|||
## getView |
|||
|
|||
Get the View of the component. |
|||
This works only if the component is already rendered |
|||
|
|||
Returns **ComponentView** |
|||
|
|||
## onAll |
|||
|
|||
Execute callback function on itself and all inner components |
|||
|
|||
### Parameters |
|||
|
|||
- `clb` **[Function][6]** Callback function, the model is passed as an argument |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
component.onAll(component => { |
|||
// do something with component |
|||
}) |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## remove |
|||
|
|||
Remove the component |
|||
|
|||
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 `{}`) |
|||
|
|||
[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[5]: https://github.com/artf/grapesjs/blob/master/src/utils/Resizer.js |
|||
|
|||
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[7]: /modules/Components-js.html |
|||
|
|||
[8]: /modules/Traits.html |
|||
|
|||
[9]: #component |
|||
|
|||
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
|||
|
|||
[11]: https://github.com/artf/grapesjs/issues/1936 |
|||
|
|||
[12]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
@ -0,0 +1,229 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## DomComponents |
|||
|
|||
With this module is possible to manage components inside the canvas. 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({ |
|||
domComponents: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const domComponents = editor.DomComponents; |
|||
``` |
|||
|
|||
- [getWrapper][2] |
|||
- [getComponents][3] |
|||
- [addComponent][4] |
|||
- [clear][5] |
|||
- [load][6] |
|||
- [store][7] |
|||
- [addType][8] |
|||
- [getType][9] |
|||
- [getTypes][10] |
|||
- [render][11] |
|||
|
|||
## load |
|||
|
|||
Load components from the passed object, if the object is empty will try to fetch them |
|||
autonomously from the selected storage |
|||
The fetched data will be added to the collection |
|||
|
|||
### Parameters |
|||
|
|||
- `data` **[Object][12]** Object of data to load (optional, default `''`) |
|||
|
|||
Returns **[Object][12]** Loaded data |
|||
|
|||
## store |
|||
|
|||
Store components on the selected storage |
|||
|
|||
### Parameters |
|||
|
|||
- `noStore` **[Boolean][13]** If true, won't store |
|||
|
|||
Returns **[Object][12]** Data to store |
|||
|
|||
## getWrapper |
|||
|
|||
Returns root component inside the canvas. Something like `<body>` inside HTML page |
|||
The wrapper doesn't differ from the original Component Model |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Change background of the wrapper and set some attribute |
|||
var wrapper = domComponents.getWrapper(); |
|||
wrapper.set('style', {'background-color': 'red'}); |
|||
wrapper.set('attributes', {'title': 'Hello!'}); |
|||
``` |
|||
|
|||
Returns **Component** Root Component |
|||
|
|||
## getComponents |
|||
|
|||
Returns wrapper's children collection. Once you have the collection you can |
|||
add other Components(Models) inside. Each component can have several nested |
|||
components inside and you can nest them as more as you wish. |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Let's add some component |
|||
var wrapperChildren = domComponents.getComponents(); |
|||
var comp1 = wrapperChildren.add({ |
|||
style: { 'background-color': 'red'} |
|||
}); |
|||
var comp2 = wrapperChildren.add({ |
|||
tagName: 'span', |
|||
attributes: { title: 'Hello!'} |
|||
}); |
|||
// Now let's add an other one inside first component |
|||
// First we have to get the collection inside. Each |
|||
// component has 'components' property |
|||
var comp1Children = comp1.get('components'); |
|||
// Procede as before. You could also add multiple objects |
|||
comp1Children.add([ |
|||
{ style: { 'background-color': 'blue'}}, |
|||
{ style: { height: '100px', width: '100px'}} |
|||
]); |
|||
// Remove comp2 |
|||
wrapperChildren.remove(comp2); |
|||
``` |
|||
|
|||
Returns **Components** Collection of components |
|||
|
|||
## addComponent |
|||
|
|||
Add new components to the wrapper's children. It's the same |
|||
as 'domComponents.getComponents().add(...)' |
|||
|
|||
### Parameters |
|||
|
|||
- `component` **([Object][12] | Component | [Array][14]<[Object][12]>)** Component/s to add |
|||
- `component.tagName` **[string][15]** Tag name (optional, default `'div'`) |
|||
- `component.type` **[string][15]** Type of the component. Available: ''(default), 'text', 'image' (optional, default `''`) |
|||
- `component.removable` **[boolean][13]** If component is removable (optional, default `true`) |
|||
- `component.draggable` **[boolean][13]** If is possible to move the component around the structure (optional, default `true`) |
|||
- `component.droppable` **[boolean][13]** If is possible to drop inside other components (optional, default `true`) |
|||
- `component.badgable` **[boolean][13]** If the badge is visible when the component is selected (optional, default `true`) |
|||
- `component.stylable` **[boolean][13]** If is possible to style component (optional, default `true`) |
|||
- `component.copyable` **[boolean][13]** If is possible to copy&paste the component (optional, default `true`) |
|||
- `component.content` **[string][15]** String inside component (optional, default `''`) |
|||
- `component.style` **[Object][12]** Style object (optional, default `{}`) |
|||
- `component.attributes` **[Object][12]** Attribute object (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Example of a new component with some extra property |
|||
var comp1 = domComponents.addComponent({ |
|||
tagName: 'div', |
|||
removable: true, // Can't remove it |
|||
draggable: true, // Can't move it |
|||
copyable: true, // Disable copy/past |
|||
content: 'Content text', // Text inside component |
|||
style: { color: 'red'}, |
|||
attributes: { title: 'here' } |
|||
}); |
|||
``` |
|||
|
|||
Returns **(Component | [Array][14]<Component>)** Component/s added |
|||
|
|||
## render |
|||
|
|||
Render and returns wrapper element with all components inside. |
|||
Once the wrapper is rendered, and it's what happens when you init the editor, |
|||
the all new components will be added automatically and property changes are all |
|||
updated immediately |
|||
|
|||
Returns **[HTMLElement][16]** |
|||
|
|||
## clear |
|||
|
|||
Remove all components |
|||
|
|||
Returns **this** |
|||
|
|||
## addType |
|||
|
|||
Add new component type. |
|||
Read more about this in [Define New Component][17] |
|||
|
|||
### Parameters |
|||
|
|||
- `type` **[string][15]** Component ID |
|||
- `methods` **[Object][12]** Component methods |
|||
|
|||
Returns **this** |
|||
|
|||
## getType |
|||
|
|||
Get component type. |
|||
Read more about this in [Define New Component][17] |
|||
|
|||
### Parameters |
|||
|
|||
- `type` **[string][15]** Component ID |
|||
|
|||
Returns **[Object][12]** Component type defintion, eg. `{ model: ..., view: ... }` |
|||
|
|||
## removeType |
|||
|
|||
Remove component type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` |
|||
- `type` **[string][15]** Component ID |
|||
|
|||
Returns **([Object][12] \| [undefined][18])** Removed component type, undefined otherwise |
|||
|
|||
## getTypes |
|||
|
|||
Return the array of all types |
|||
|
|||
Returns **[Array][14]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/dom_components/config/config.js |
|||
|
|||
[2]: #getwrapper |
|||
|
|||
[3]: #getcomponents |
|||
|
|||
[4]: #addcomponent |
|||
|
|||
[5]: #clear |
|||
|
|||
[6]: #load |
|||
|
|||
[7]: #store |
|||
|
|||
[8]: #addtype |
|||
|
|||
[9]: #gettype |
|||
|
|||
[10]: #gettypes |
|||
|
|||
[11]: #render |
|||
|
|||
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
|
|||
[17]: https://grapesjs.com/docs/modules/Components.html#define-new-component |
|||
|
|||
[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined |
|||
@ -0,0 +1,195 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## CssComposer |
|||
|
|||
This module contains and manage CSS rules for the template inside the canvas. |
|||
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({ |
|||
cssComposer: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const cssComposer = editor.CssComposer; |
|||
``` |
|||
|
|||
- [load][2] |
|||
- [store][3] |
|||
- [add][4] |
|||
- [get][5] |
|||
- [getAll][6] |
|||
- [clear][7] |
|||
- [setRule][8] |
|||
- [getRule][9] |
|||
|
|||
## load |
|||
|
|||
Load data from the passed object, if the object is empty will try to fetch them |
|||
autonomously from the storage manager. |
|||
The fetched data will be added to the collection |
|||
|
|||
### Parameters |
|||
|
|||
- `data` **[Object][10]** Object of data to load |
|||
|
|||
Returns **[Object][10]** Loaded rules |
|||
|
|||
## store |
|||
|
|||
Store data to the selected storage |
|||
|
|||
### Parameters |
|||
|
|||
- `noStore` **[Boolean][11]** If true, won't store |
|||
|
|||
Returns **[Object][10]** Data to store |
|||
|
|||
## add |
|||
|
|||
Add new rule to the collection, if not yet exists with the same selectors |
|||
|
|||
### Parameters |
|||
|
|||
- `selectors` **[Array][12]<Selector>** Array of selectors |
|||
- `state` **[String][13]** Css rule state |
|||
- `width` **[String][13]** For which device this style is oriented |
|||
- `opts` **[Object][10]** Other options for the rule (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var sm = editor.SelectorManager; |
|||
var sel1 = sm.add('myClass1'); |
|||
var sel2 = sm.add('myClass2'); |
|||
var rule = cssComposer.add([sel1, sel2], 'hover'); |
|||
rule.set('style', { |
|||
width: '100px', |
|||
color: '#fff', |
|||
}); |
|||
``` |
|||
|
|||
Returns **Model** |
|||
|
|||
## get |
|||
|
|||
Get the rule |
|||
|
|||
### Parameters |
|||
|
|||
- `selectors` **[Array][12]<Selector>** Array of selectors |
|||
- `state` **[String][13]** Css rule state |
|||
- `width` **[String][13]** For which device this style is oriented |
|||
- `ruleProps` **[Object][10]** Other rule props |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var sm = editor.SelectorManager; |
|||
var sel1 = sm.add('myClass1'); |
|||
var sel2 = sm.add('myClass2'); |
|||
var rule = cssComposer.get([sel1, sel2], 'hover'); |
|||
// Update the style |
|||
rule.set('style', { |
|||
width: '300px', |
|||
color: '#000', |
|||
}); |
|||
``` |
|||
|
|||
Returns **(Model | null)** |
|||
|
|||
## getAll |
|||
|
|||
Get the collection of rules |
|||
|
|||
Returns **Collection** |
|||
|
|||
## clear |
|||
|
|||
Remove all rules |
|||
|
|||
Returns **this** |
|||
|
|||
## setRule |
|||
|
|||
Add/update the CSS rule with a generic selector |
|||
|
|||
### Parameters |
|||
|
|||
- `selectors` **[string][13]** Selector, eg. '.myclass' |
|||
- `style` **[Object][10]** Style properties and values |
|||
- `opts` **[Object][10]** Additional properties (optional, default `{}`) |
|||
- `opts.atRuleType` **[String][13]** At-rule type, eg. 'media' (optional, default `''`) |
|||
- `opts.atRuleParams` **[String][13]** At-rule parameters, eg. '(min-width: 500px)' (optional, default `''`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Simple class-based rule |
|||
const rule = cc.setRule('.class1.class2', { color: 'red' }); |
|||
console.log(rule.toCSS()) // output: .class1.class2 { color: red } |
|||
// With state and other mixed selector |
|||
const rule = cc.setRule('.class1.class2:hover, div#myid', { color: 'red' }); |
|||
// output: .class1.class2:hover, div#myid { color: red } |
|||
// With media |
|||
const rule = cc.setRule('.class1:hover', { color: 'red' }, { |
|||
atRuleType: 'media', |
|||
atRuleParams: '(min-width: 500px)', |
|||
}); |
|||
// output: @media (min-width: 500px) { .class1:hover { color: red } } |
|||
``` |
|||
|
|||
Returns **CssRule** The new/updated rule |
|||
|
|||
## getRule |
|||
|
|||
Get the CSS rule by a generic selector |
|||
|
|||
### Parameters |
|||
|
|||
- `selectors` **[string][13]** Selector, eg. '.myclass:hover' |
|||
- `opts` (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const rule = cc.getRule('.myclass1:hover'); |
|||
const rule2 = cc.getRule('.myclass1:hover, div#myid'); |
|||
const rule3 = cc.getRule('.myclass1', { |
|||
atRuleType: 'media', |
|||
atRuleParams: '(min-width: 500px)', |
|||
}); |
|||
``` |
|||
|
|||
Returns **CssRule** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/css_composer/config/config.js |
|||
|
|||
[2]: #load |
|||
|
|||
[3]: #store |
|||
|
|||
[4]: #add |
|||
|
|||
[5]: #get |
|||
|
|||
[6]: #getall |
|||
|
|||
[7]: #clear |
|||
|
|||
[8]: #setrule |
|||
|
|||
[9]: #getrule |
|||
|
|||
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
@ -0,0 +1,87 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## DeviceManager |
|||
|
|||
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({ |
|||
deviceManager: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const deviceManager = editor.DeviceManager; |
|||
``` |
|||
|
|||
- [add][2] |
|||
- [get][3] |
|||
- [getAll][4] |
|||
|
|||
## add |
|||
|
|||
Add new device to the collection. URLs are supposed to be unique |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][5]** Device name |
|||
- `width` **[string][5]** Width of the device |
|||
- `opts` **[Object][6]** Custom options |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
deviceManager.add('Tablet', '900px'); |
|||
deviceManager.add('Tablet2', '900px', { |
|||
height: '300px', |
|||
widthMedia: '810px', // the width that will be used for the CSS media |
|||
}); |
|||
``` |
|||
|
|||
Returns **Device** Added device |
|||
|
|||
## get |
|||
|
|||
Return device by name |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][5]** Name of the device |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var device = deviceManager.get('Tablet'); |
|||
console.log(JSON.stringify(device)); |
|||
// {name: 'Tablet', width: '900px'} |
|||
``` |
|||
|
|||
## getAll |
|||
|
|||
Return all devices |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var devices = deviceManager.getAll(); |
|||
console.log(JSON.stringify(devices)); |
|||
// [{name: 'Desktop', width: ''}, ...] |
|||
``` |
|||
|
|||
Returns **Collection** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/device_manager/config/config.js |
|||
|
|||
[2]: #add |
|||
|
|||
[3]: #get |
|||
|
|||
[4]: #getAll |
|||
|
|||
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
@ -0,0 +1,609 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Editor |
|||
|
|||
Editor contains the top level API which you'll probably use to customize the editor or extend it with plugins. |
|||
You get the Editor instance on init method and you can pass options via its [Configuration Object][1] |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// options |
|||
}); |
|||
``` |
|||
|
|||
## Available Events |
|||
|
|||
You can make use of available events in this way |
|||
|
|||
```js |
|||
editor.on('EVENT-NAME', (some, argument) => { |
|||
// do something |
|||
}) |
|||
``` |
|||
|
|||
### Components |
|||
|
|||
- `component:create` - Component is created (only the model, is not yet mounted in the canvas), called after the init() method |
|||
- `component:mount` - Component is mounted to an element and rendered in canvas |
|||
- `component:add` - Triggered when a new component is added to the editor, the model is passed as an argument to the callback |
|||
- `component:remove` - Triggered when a component is removed, the model is passed as an argument to the callback |
|||
- `component:clone` - Triggered when a component is cloned, the new model is passed as an argument to the callback |
|||
- `component:update` - Triggered when a component is updated (moved, styled, etc.), the model is passed as an argument to the callback |
|||
- `component:update:{propertyName}` - Listen any property change, the model is passed as an argument to the callback |
|||
- `component:styleUpdate` - Triggered when the style of the component is updated, the model is passed as an argument to the callback |
|||
- `component:styleUpdate:{propertyName}` - Listen for a specific style property change, the model is passed as an argument to the callback |
|||
- `component:selected` - New component selected, the selected model is passed as an argument to the callback |
|||
- `component:deselected` - Component deselected, the deselected model is passed as an argument to the callback |
|||
- `component:toggled` - Component selection changed, toggled model is passed as an argument to the callback |
|||
- `component:type:add` - New component type added, the new type is passed as an argument to the callback |
|||
- `component:type:update` - Component type updated, the updated type is passed as an argument to the callback |
|||
|
|||
### Blocks |
|||
|
|||
- `block:add` - New block added |
|||
- `block:remove` - Block removed |
|||
- `block:drag:start` - Started dragging block, model of the block is passed as an argument |
|||
- `block:drag` - Dragging block, the block's model and the drag event are passed as arguments |
|||
- `block:drag:stop` - Dragging of the block is stopped. As agruments for the callback you get, the dropped component model (if dropped successfully) and the model of the block |
|||
|
|||
### Assets |
|||
|
|||
- `asset:add` - New asset added |
|||
- `asset:remove` - Asset removed |
|||
- `asset:upload:start` - Before the upload is started |
|||
- `asset:upload:end` - After the upload is ended |
|||
- `asset:upload:error` - On any error in upload, passes the error as an argument |
|||
- `asset:upload:response` - On upload response, passes the result as an argument |
|||
|
|||
### Keymaps |
|||
|
|||
- `keymap:add` - New keymap added. The new keyamp object is passed as an argument |
|||
- `keymap:remove` - Keymap removed. The removed keyamp object is passed as an argument |
|||
- `keymap:emit` - Some keymap emitted, in arguments you get keymapId, shortcutUsed, Event |
|||
- `keymap:emit:{keymapId}` - `keymapId` emitted, in arguments you get keymapId, shortcutUsed, Event |
|||
|
|||
### Style Manager |
|||
|
|||
- `styleManager:update:target` - The target (Component or CSSRule) is changed |
|||
- `styleManager:change` - Triggered on style property change from new selected component, the view of the property is passed as an argument to the callback |
|||
- `styleManager:change:{propertyName}` - As above but for a specific style property |
|||
|
|||
### Storages |
|||
|
|||
- `storage:start` - Before the storage request is started |
|||
- `storage:start:store` - Before the store request. The object to store is passed as an argumnet (which you can edit) |
|||
- `storage:start:load` - Before the load request. Items to load are passed as an argumnet (which you can edit) |
|||
- `storage:load` - Triggered when something was loaded from the storage, loaded object passed as an argumnet |
|||
- `storage:store` - Triggered when something is stored to the storage, stored object passed as an argumnet |
|||
- `storage:end` - After the storage request is ended |
|||
- `storage:end:store` - After the store request |
|||
- `storage:end:load` - After the load request |
|||
- `storage:error` - On any error on storage request, passes the error as an argument |
|||
- `storage:error:store` - Error on store request, passes the error as an argument |
|||
- `storage:error:load` - Error on load request, passes the error as an argument |
|||
|
|||
### Canvas |
|||
|
|||
- `canvas:dragenter` - When something is dragged inside the canvas, `DataTransfer` instance passed as an argument |
|||
- `canvas:dragover` - When something is dragging on canvas, `DataTransfer` instance passed as an argument |
|||
- `canvas:drop` - Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments |
|||
- `canvas:dragend` - When a drag operation is ended, `DataTransfer` instance passed as an argument |
|||
- `canvas:dragdata` - On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments. |
|||
By changing `result.content` you're able to customize what is dropped |
|||
|
|||
### Selectors |
|||
|
|||
- `selector:add` - Triggers when a new selector/class is created |
|||
|
|||
### RTE |
|||
|
|||
- `rte:enable` - RTE enabled. The view, on which RTE is enabled, is passed as an argument |
|||
- `rte:disable` - RTE disabled. The view, on which RTE is disabled, is passed as an argument |
|||
|
|||
### Modal |
|||
|
|||
- `modal:open` - Modal is opened |
|||
- `modal:close` - Modal is closed |
|||
|
|||
### Commands |
|||
|
|||
- `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview')) |
|||
- `stop:{commandName}` - Triggered when some command is called to stop (eg. editor.stopCommand('preview')) |
|||
- `run:{commandName}:before` - Triggered before the command is called |
|||
- `stop:{commandName}:before` - Triggered before the command is called to stop |
|||
- `abort:{commandName}` - Triggered when the command execution is aborted (`editor.on(`run:preview:before`, opts => opts.abort = 1);`) |
|||
- `run` - Triggered on run of any command. The id and the result are passed as arguments to the callback |
|||
- `stop` - Triggered on stop of any command. The id and the result are passed as arguments to the callback |
|||
|
|||
### General |
|||
|
|||
- `canvasScroll` - Canvas is scrolled |
|||
- `update` - The structure of the template is updated (its HTML/CSS) |
|||
- `undo` - Undo executed |
|||
- `redo` - Redo executed |
|||
- `load` - Editor is loaded |
|||
|
|||
## getConfig |
|||
|
|||
Returns configuration object |
|||
|
|||
### Parameters |
|||
|
|||
- `prop` **[string][2]?** Property name |
|||
|
|||
Returns **any** Returns the configuration object or |
|||
the value of the specified property |
|||
|
|||
## getHtml |
|||
|
|||
Returns HTML built inside canvas |
|||
|
|||
### Parameters |
|||
|
|||
- `opts` |
|||
|
|||
Returns **[string][2]** HTML string |
|||
|
|||
## getCss |
|||
|
|||
Returns CSS built inside canvas |
|||
|
|||
### Parameters |
|||
|
|||
- `opts` **[Object][3]** Options (optional, default `{}`) |
|||
|
|||
Returns **[string][2]** CSS string |
|||
|
|||
## getJs |
|||
|
|||
Returns JS of all components |
|||
|
|||
Returns **[string][2]** JS string |
|||
|
|||
## getComponents |
|||
|
|||
Return the complete tree of components. Use `getWrapper` to include also the wrapper |
|||
|
|||
Returns **Components** |
|||
|
|||
## getWrapper |
|||
|
|||
Return the wrapper and its all components |
|||
|
|||
Returns **Component** |
|||
|
|||
## setComponents |
|||
|
|||
Set components inside editor's canvas. This method overrides actual components |
|||
|
|||
### Parameters |
|||
|
|||
- `components` **([Array][4]<[Object][3]> | [Object][3] \| [string][2])** HTML string or components model |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.setComponents('<div class="cls">New component</div>'); |
|||
// or |
|||
editor.setComponents({ |
|||
type: 'text', |
|||
classes:['cls'], |
|||
content: 'New component' |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## addComponents |
|||
|
|||
Add components |
|||
|
|||
### Parameters |
|||
|
|||
- `components` **([Array][4]<[Object][3]> | [Object][3] \| [string][2])** HTML string or components model |
|||
- `opts` **[Object][3]** Options |
|||
- `opts.avoidUpdateStyle` **[Boolean][5]** If the HTML string contains styles, |
|||
by default, they will be created and, if already exist, updated. When this option |
|||
is true, styles already created will not be updated. (optional, default `false`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.addComponents('<div class="cls">New component</div>'); |
|||
// or |
|||
editor.addComponents({ |
|||
type: 'text', |
|||
classes:['cls'], |
|||
content: 'New component' |
|||
}); |
|||
``` |
|||
|
|||
Returns **[Array][4]<Component>** |
|||
|
|||
## getStyle |
|||
|
|||
Returns style in JSON format object |
|||
|
|||
Returns **[Object][3]** |
|||
|
|||
## setStyle |
|||
|
|||
Set style inside editor's canvas. This method overrides actual style |
|||
|
|||
### Parameters |
|||
|
|||
- `style` **([Array][4]<[Object][3]> | [Object][3] \| [string][2])** CSS string or style model |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.setStyle('.cls{color: red}'); |
|||
//or |
|||
editor.setStyle({ |
|||
selectors: ['cls'] |
|||
style: { color: 'red' } |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## getSelected |
|||
|
|||
Returns the last selected component, if there is one |
|||
|
|||
Returns **Model** |
|||
|
|||
## getSelectedAll |
|||
|
|||
Returns an array of all selected components |
|||
|
|||
Returns **[Array][4]** |
|||
|
|||
## getSelectedToStyle |
|||
|
|||
Get a stylable entity from the selected component. |
|||
If you select a component without classes the entity is the Component |
|||
itself and all changes will go inside its 'style' attribute. Otherwise, |
|||
if the selected component has one or more classes, the function will |
|||
return the corresponding CSS Rule |
|||
|
|||
Returns **Model** |
|||
|
|||
## select |
|||
|
|||
Select a component |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **(Component | [HTMLElement][6])** Component to select |
|||
- `opts` **[Object][3]?** Options |
|||
- `opts.scroll` **[Boolean][5]?** Scroll canvas to the selected element |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// Select dropped block |
|||
editor.on('block:drag:stop', function(model) { |
|||
editor.select(model); |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## selectAdd |
|||
|
|||
Add component to selection |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **(Component | [HTMLElement][6] \| [Array][4])** Component to select |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.selectAdd(model); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## selectRemove |
|||
|
|||
Remove component from selection |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **(Component | [HTMLElement][6] \| [Array][4])** Component to select |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.selectRemove(model); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## selectToggle |
|||
|
|||
Toggle component selection |
|||
|
|||
### Parameters |
|||
|
|||
- `el` **(Component | [HTMLElement][6] \| [Array][4])** Component to select |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.selectToggle(model); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## setDevice |
|||
|
|||
Set device to the editor. If the device exists it will |
|||
change the canvas to the proper width |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][2]** Name of the device |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.setDevice('Tablet'); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## getDevice |
|||
|
|||
Return the actual active device |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var device = editor.getDevice(); |
|||
console.log(device); |
|||
// 'Tablet' |
|||
``` |
|||
|
|||
Returns **[string][2]** Device name |
|||
|
|||
## runCommand |
|||
|
|||
Execute command |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][2]** Command ID |
|||
- `options` **[Object][3]** Custom options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.runCommand('myCommand', {someValue: 1}); |
|||
``` |
|||
|
|||
Returns **any** The return is defined by the command |
|||
|
|||
## stopCommand |
|||
|
|||
Stop the command if stop method was provided |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][2]** Command ID |
|||
- `options` **[Object][3]** Custom options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.stopCommand('myCommand', {someValue: 1}); |
|||
``` |
|||
|
|||
Returns **any** The return is defined by the command |
|||
|
|||
## store |
|||
|
|||
Store data to the current storage |
|||
|
|||
### Parameters |
|||
|
|||
- `clb` **[Function][7]** Callback function |
|||
|
|||
Returns **[Object][3]** Stored data |
|||
|
|||
## load |
|||
|
|||
Load data from the current storage |
|||
|
|||
### Parameters |
|||
|
|||
- `clb` **[Function][7]** Callback function |
|||
|
|||
Returns **[Object][3]** Stored data |
|||
|
|||
## getContainer |
|||
|
|||
Returns container element. The one which was indicated as 'container' |
|||
on init method |
|||
|
|||
Returns **[HTMLElement][6]** |
|||
|
|||
## getDirtyCount |
|||
|
|||
Return the count of changes made to the content and not yet stored. |
|||
This count resets at any `store()` |
|||
|
|||
Returns **[number][8]** |
|||
|
|||
## setCustomRte |
|||
|
|||
Replace the built-in Rich Text Editor with a custom one. |
|||
|
|||
### Parameters |
|||
|
|||
- `obj` **[Object][3]** Custom RTE Interface |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.setCustomRte({ |
|||
// Function for enabling custom RTE |
|||
// el is the HTMLElement of the double clicked Text Component |
|||
// rte is the same instance you have returned the first time you call |
|||
// enable(). This is useful if need to check if the RTE is already enabled so |
|||
// ion this case you'll need to return the RTE and the end of the function |
|||
enable: function(el, rte) { |
|||
rte = new MyCustomRte(el, {}); // this depends on the Custom RTE API |
|||
... |
|||
return rte; // return the RTE instance |
|||
}, |
|||
|
|||
// Disable the editor, called for example when you unfocus the Text Component |
|||
disable: function(el, rte) { |
|||
rte.blur(); // this depends on the Custom RTE API |
|||
} |
|||
|
|||
// Called when the Text Component is focused again. If you returned the RTE instance |
|||
// from the enable function, the enable won't be called again instead will call focus, |
|||
// in this case to avoid double binding of the editor |
|||
focus: function (el, rte) { |
|||
rte.focus(); // this depends on the Custom RTE API |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
## setCustomParserCss |
|||
|
|||
Replace the default CSS parser with a custom one. |
|||
The parser function receives a CSS string as a parameter and expects |
|||
an array of CSSRule objects as a result. If you need to remove the |
|||
custom parser, pass `null` as the argument |
|||
|
|||
### Parameters |
|||
|
|||
- `parser` **([Function][7] | null)** Parser function |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.setCustomParserCss(css => { |
|||
const result = []; |
|||
// ... parse the CSS string |
|||
result.push({ |
|||
selectors: '.someclass, div .otherclass', |
|||
style: { color: 'red' } |
|||
}) |
|||
// ... |
|||
return result; |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## setDragMode |
|||
|
|||
Change the global drag mode of components. |
|||
To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][9] |
|||
|
|||
### Parameters |
|||
|
|||
- `value` **[String][2]** Drag mode, options: 'absolute' | 'translate' |
|||
|
|||
Returns **this** |
|||
|
|||
## log |
|||
|
|||
Trigger event log message |
|||
|
|||
### Parameters |
|||
|
|||
- `msg` **any** Message to log |
|||
- `opts` **[Object][3]** Custom options (optional, default `{}`) |
|||
- `opts.ns` **[String][2]** Namespace of the log (eg. to use in plugins) (optional, default `''`) |
|||
- `opts.level` **[String][2]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
editor.log('Something done!', { ns: 'from-plugin-x', level: 'info' }); |
|||
// This will trigger following events |
|||
// `log`, `log:info`, `log-from-plugin-x`, `log-from-plugin-x:info` |
|||
// Callbacks of those events will always receive the message and |
|||
// options, as arguments, eg: |
|||
// editor.on('log:info', (msg, opts) => console.info(msg, opts)) |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## on |
|||
|
|||
Attach event |
|||
|
|||
### Parameters |
|||
|
|||
- `event` **[string][2]** Event name |
|||
- `callback` **[Function][7]** Callback function |
|||
|
|||
Returns **this** |
|||
|
|||
## once |
|||
|
|||
Attach event and detach it after the first run |
|||
|
|||
### Parameters |
|||
|
|||
- `event` **[string][2]** Event name |
|||
- `callback` **[Function][7]** Callback function |
|||
|
|||
Returns **this** |
|||
|
|||
## off |
|||
|
|||
Detach event |
|||
|
|||
### Parameters |
|||
|
|||
- `event` **[string][2]** Event name |
|||
- `callback` **[Function][7]** Callback function |
|||
|
|||
Returns **this** |
|||
|
|||
## trigger |
|||
|
|||
Trigger event |
|||
|
|||
### Parameters |
|||
|
|||
- `event` **[string][2]** Event to trigger |
|||
|
|||
Returns **this** |
|||
|
|||
## destroy |
|||
|
|||
Destroy the editor |
|||
|
|||
## render |
|||
|
|||
Render editor |
|||
|
|||
Returns **[HTMLElement][6]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/editor/config/config.js |
|||
|
|||
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[6]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
|
|||
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
|||
|
|||
[9]: https://github.com/artf/grapesjs/issues/1936 |
|||
@ -0,0 +1,140 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Keymaps |
|||
|
|||
You can customize the initial state of the module from the editor initialization |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
keymaps: { |
|||
// Object of keymaps |
|||
defaults: { |
|||
'your-namespace:keymap-name' { |
|||
keys: '⌘+z, ctrl+z', |
|||
handler: 'some-command-id' |
|||
}, |
|||
... |
|||
} |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const keymaps = editor.Keymaps; |
|||
``` |
|||
|
|||
- [getConfig][1] |
|||
- [add][2] |
|||
- [get][3] |
|||
- [getAll][4] |
|||
- [remove][5] |
|||
- [removeAll][6] |
|||
|
|||
## getConfig |
|||
|
|||
Get module configurations |
|||
|
|||
Returns **[Object][7]** Configuration object |
|||
|
|||
## add |
|||
|
|||
Add new keymap |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][8]** Keymap id |
|||
- `keys` **[string][8]** Keymap keys, eg. `ctrl+a`, `⌘+z, ctrl+z` |
|||
- `handler` **([Function][9] \| [string][8])** Keymap handler, might be a function |
|||
- `opts` **[Object][7]** Options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
// 'ns' is just a custom namespace |
|||
keymaps.add('ns:my-keymap', '⌘+j, ⌘+u, ctrl+j, alt+u', editor => { |
|||
console.log('do stuff'); |
|||
}); |
|||
// or |
|||
keymaps.add('ns:my-keymap', '⌘+s, ctrl+s', 'some-gjs-command'); |
|||
|
|||
// listen to events |
|||
editor.on('keymap:emit', (id, shortcut, e) => { |
|||
// ... |
|||
}) |
|||
``` |
|||
|
|||
Returns **[Object][7]** Added keymap |
|||
or just a command id as a string |
|||
|
|||
## get |
|||
|
|||
Get the keymap by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][8]** Keymap id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
keymaps.get('ns:my-keymap'); |
|||
// -> {keys, handler}; |
|||
``` |
|||
|
|||
Returns **[Object][7]** Keymap object |
|||
|
|||
## getAll |
|||
|
|||
Get all keymaps |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
keymaps.getAll(); |
|||
// -> {id1: {}, id2: {}}; |
|||
``` |
|||
|
|||
Returns **[Object][7]** |
|||
|
|||
## remove |
|||
|
|||
Remove the keymap by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][8]** Keymap id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
keymaps.remove('ns:my-keymap'); |
|||
// -> {keys, handler}; |
|||
``` |
|||
|
|||
Returns **[Object][7]** Removed keymap |
|||
|
|||
## removeAll |
|||
|
|||
Remove all binded keymaps |
|||
|
|||
Returns **this** |
|||
|
|||
[1]: #getconfig |
|||
|
|||
[2]: #add |
|||
|
|||
[3]: #get |
|||
|
|||
[4]: #getAll |
|||
|
|||
[5]: #remove |
|||
|
|||
[6]: #removeall |
|||
|
|||
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
@ -0,0 +1,149 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Modal |
|||
|
|||
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({ |
|||
modal: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const modal = editor.Modal; |
|||
``` |
|||
|
|||
- [open][2] |
|||
- [close][3] |
|||
- [isOpen][4] |
|||
- [setTitle][5] |
|||
- [getTitle][6] |
|||
- [setContent][7] |
|||
- [getContent][8] |
|||
- [onceClose][9] |
|||
- [onceOpen][10] |
|||
|
|||
## open |
|||
|
|||
Open the modal window |
|||
|
|||
### Parameters |
|||
|
|||
- `opts` **[Object][11]** Options (optional, default `{}`) |
|||
- `opts.title` **([String][12] \| [HTMLElement][13])?** Title to set for the modal |
|||
- `opts.content` **([String][12] \| [HTMLElement][13])?** Content to set for the modal |
|||
|
|||
Returns **this** |
|||
|
|||
## close |
|||
|
|||
Close the modal window |
|||
|
|||
Returns **this** |
|||
|
|||
## onceClose |
|||
|
|||
Execute callback when the modal will be closed. |
|||
The callback will be called one only time |
|||
|
|||
### Parameters |
|||
|
|||
- `clb` **[Function][14]** |
|||
|
|||
Returns **this** |
|||
|
|||
## onceOpen |
|||
|
|||
Execute callback when the modal will be opened. |
|||
The callback will be called one only time |
|||
|
|||
### Parameters |
|||
|
|||
- `clb` **[Function][14]** |
|||
|
|||
Returns **this** |
|||
|
|||
## isOpen |
|||
|
|||
Checks if the modal window is open |
|||
|
|||
Returns **[Boolean][15]** |
|||
|
|||
## setTitle |
|||
|
|||
Set the title to the modal window |
|||
|
|||
### Parameters |
|||
|
|||
- `title` **[string][12]** Title |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
modal.setTitle('New title'); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## getTitle |
|||
|
|||
Returns the title of the modal window |
|||
|
|||
Returns **[string][12]** |
|||
|
|||
## setContent |
|||
|
|||
Set the content of the modal window |
|||
|
|||
### Parameters |
|||
|
|||
- `content` **([string][12] \| [HTMLElement][13])** Content |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
modal.setContent('<div>Some HTML content</div>'); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## getContent |
|||
|
|||
Get the content of the modal window |
|||
|
|||
Returns **[string][12]** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/modal_dialog/config/config.js |
|||
|
|||
[2]: #open |
|||
|
|||
[3]: #close |
|||
|
|||
[4]: #isopen |
|||
|
|||
[5]: #settitle |
|||
|
|||
[6]: #gettitle |
|||
|
|||
[7]: #setcontent |
|||
|
|||
[8]: #getcontent |
|||
|
|||
[9]: #onceclose |
|||
|
|||
[10]: #onceopen |
|||
|
|||
[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/HTML/Element |
|||
|
|||
[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
@ -0,0 +1,204 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## Panels |
|||
|
|||
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({ |
|||
panels: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const panelManager = editor.Panels; |
|||
``` |
|||
|
|||
- [addPanel][2] |
|||
- [addButton][3] |
|||
- [getButton][4] |
|||
- [getPanel][5] |
|||
- [getPanels][6] |
|||
- [getPanelsEl][7] |
|||
- [removePanel][8] |
|||
- [removeButton][9] |
|||
|
|||
## getPanels |
|||
|
|||
Returns the collection of panels |
|||
|
|||
Returns **Collection** Collection of panel |
|||
|
|||
## getPanelsEl |
|||
|
|||
Returns panels element |
|||
|
|||
Returns **[HTMLElement][10]** |
|||
|
|||
## addPanel |
|||
|
|||
Add new panel to the collection |
|||
|
|||
### Parameters |
|||
|
|||
- `panel` **([Object][11] | Panel)** Object with right properties or an instance of Panel |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var newPanel = panelManager.addPanel({ |
|||
id: 'myNewPanel', |
|||
visible : true, |
|||
buttons : [...], |
|||
}); |
|||
``` |
|||
|
|||
Returns **Panel** Added panel. Useful in case passed argument was an Object |
|||
|
|||
## removePanel |
|||
|
|||
Remove a panel from the collection |
|||
|
|||
### Parameters |
|||
|
|||
- `panel` **([Object][11] | Panel | [String][12])** Object with right properties or an instance of Panel or Painel id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const newPanel = panelManager.removePanel({ |
|||
id: 'myNewPanel', |
|||
visible : true, |
|||
buttons : [...], |
|||
}); |
|||
|
|||
const newPanel = panelManager.removePanel('myNewPanel'); |
|||
``` |
|||
|
|||
Returns **Panel** Removed panel. Useful in case passed argument was an Object |
|||
|
|||
## getPanel |
|||
|
|||
Get panel by ID |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][12]** Id string |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var myPanel = panelManager.getPanel('myNewPanel'); |
|||
``` |
|||
|
|||
Returns **(Panel | null)** |
|||
|
|||
## addButton |
|||
|
|||
Add button to the panel |
|||
|
|||
### Parameters |
|||
|
|||
- `panelId` **[string][12]** Panel's ID |
|||
- `button` **([Object][11] | Button)** Button object or instance of Button |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var newButton = panelManager.addButton('myNewPanel',{ |
|||
id: 'myNewButton', |
|||
className: 'someClass', |
|||
command: 'someCommand', |
|||
attributes: { title: 'Some title'}, |
|||
active: false, |
|||
}); |
|||
// It's also possible to pass the command as an object |
|||
// with .run and .stop methods |
|||
... |
|||
command: { |
|||
run: function(editor) { |
|||
... |
|||
}, |
|||
stop: function(editor) { |
|||
... |
|||
} |
|||
}, |
|||
// Or simply like a function which will be evaluated as a single .run command |
|||
... |
|||
command: function(editor) { |
|||
... |
|||
} |
|||
``` |
|||
|
|||
Returns **(Button | null)** Added button. Useful in case passed button was an Object |
|||
|
|||
## removeButton |
|||
|
|||
Remove button from the panel |
|||
|
|||
### Parameters |
|||
|
|||
- `panelId` **[String][12]** Panel's ID |
|||
- `button` |
|||
- `buttonId` **[String][12]** Button's ID |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const removedButton = panelManager.addButton('myNewPanel',{ |
|||
id: 'myNewButton', |
|||
className: 'someClass', |
|||
command: 'someCommand', |
|||
attributes: { title: 'Some title'}, |
|||
active: false, |
|||
}); |
|||
|
|||
const removedButton = panelManager.removeButton('myNewPanel', 'myNewButton'); |
|||
``` |
|||
|
|||
Returns **(Button | null)** Removed button. |
|||
|
|||
## getButton |
|||
|
|||
Get button from the panel |
|||
|
|||
### Parameters |
|||
|
|||
- `panelId` **[string][12]** Panel's ID |
|||
- `id` **[string][12]** Button's ID |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var button = panelManager.getButton('myPanel','myButton'); |
|||
``` |
|||
|
|||
Returns **(Button | null)** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/panels/config/config.js |
|||
|
|||
[2]: #addpanel |
|||
|
|||
[3]: #addbutton |
|||
|
|||
[4]: #getbutton |
|||
|
|||
[5]: #getpanel |
|||
|
|||
[6]: #getpanels |
|||
|
|||
[7]: #getpanelsel |
|||
|
|||
[8]: #removepanel |
|||
|
|||
[9]: #removebutton |
|||
|
|||
[10]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
|
|||
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
@ -0,0 +1,139 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## RichTextEditor |
|||
|
|||
This module allows to customize the built-in toolbar of the Rich Text Editor and use commands from the [HTML Editing APIs][1]. |
|||
It's highly recommended to keep this toolbar as small as possible, especially from styling commands (eg. 'fontSize') and leave this task to the Style Manager |
|||
|
|||
You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][2] |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
rte: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const rte = editor.RichTextEditor; |
|||
``` |
|||
|
|||
- [add][3] |
|||
- [get][4] |
|||
- [getAll][5] |
|||
- [remove][6] |
|||
- [getToolbarEl][7] |
|||
|
|||
## add |
|||
|
|||
Add a new action to the built-in RTE toolbar |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][8]** Action name |
|||
- `action` **[Object][9]** Action options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
rte.add('bold', { |
|||
icon: '<b>B</b>', |
|||
attributes: {title: 'Bold'}, |
|||
result: rte => rte.exec('bold') |
|||
}); |
|||
rte.add('link', { |
|||
icon: document.getElementById('t'), |
|||
attributes: {title: 'Link',} |
|||
// Example on it's easy to wrap a selected content |
|||
result: rte => rte.insertHTML(`<a href="#">${rte.selection()}</a>`) |
|||
}); |
|||
// An example with fontSize |
|||
rte.add('fontSize', { |
|||
icon: `<select class="gjs-field"> |
|||
<option>1</option> |
|||
<option>4</option> |
|||
<option>7</option> |
|||
</select>`, |
|||
// Bind the 'result' on 'change' listener |
|||
event: 'change', |
|||
result: (rte, action) => rte.exec('fontSize', action.btn.firstChild.value), |
|||
// Callback on any input change (mousedown, keydown, etc..) |
|||
update: (rte, action) => { |
|||
const value = rte.doc.queryCommandValue(action.name); |
|||
if (value != 'false') { // value is a string |
|||
action.btn.firstChild.value = value; |
|||
} |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
## get |
|||
|
|||
Get the action by its name |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][8]** Action name |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const action = rte.get('bold'); |
|||
// {name: 'bold', ...} |
|||
``` |
|||
|
|||
Returns **[Object][9]** |
|||
|
|||
## getAll |
|||
|
|||
Get all actions |
|||
|
|||
Returns **[Array][10]** |
|||
|
|||
## remove |
|||
|
|||
Remove the action from the toolbar |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[string][8]** |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const action = rte.remove('bold'); |
|||
// {name: 'bold', ...} |
|||
``` |
|||
|
|||
Returns **[Object][9]** Removed action |
|||
|
|||
## getToolbarEl |
|||
|
|||
Get the toolbar element |
|||
|
|||
Returns **[HTMLElement][11]** |
|||
|
|||
[1]: https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand |
|||
|
|||
[2]: https://github.com/artf/grapesjs/blob/master/src/rich_text_editor/config/config.js |
|||
|
|||
[3]: #add |
|||
|
|||
[4]: #get |
|||
|
|||
[5]: #getall |
|||
|
|||
[6]: #remove |
|||
|
|||
[7]: #gettoolbarel |
|||
|
|||
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[11]: https://developer.mozilla.org/docs/Web/HTML/Element |
|||
@ -0,0 +1,152 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## SelectorManager |
|||
|
|||
Selectors in GrapesJS are used in CSS Composer inside Rules and in Components as classes. To illustrate this concept let's take |
|||
a look at this code: |
|||
|
|||
```css |
|||
span > #send-btn.btn{ |
|||
... |
|||
} |
|||
``` |
|||
|
|||
```html |
|||
<span> |
|||
<button id="send-btn" class="btn"></button> |
|||
</span> |
|||
``` |
|||
|
|||
In this scenario we get: |
|||
|
|||
- span -> selector of type `tag` |
|||
- send-btn -> selector of type `id` |
|||
- btn -> selector of type `class` |
|||
|
|||
So, for example, being `btn` the same class entity it'll be easier to refactor and track things. |
|||
|
|||
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({ |
|||
selectorManager: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const selectorManager = editor.SelectorManager; |
|||
``` |
|||
|
|||
- [getConfig][2] |
|||
- [add][3] |
|||
- [addClass][4] |
|||
- [get][5] |
|||
- [getAll][6] |
|||
|
|||
## getConfig |
|||
|
|||
Get configuration object |
|||
|
|||
Returns **[Object][7]** |
|||
|
|||
## add |
|||
|
|||
Add a new selector to collection if it's not already exists. Class type is a default one |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **([String][8] \| [Array][9])** Selector/s name |
|||
- `opts` **[Object][7]** Selector options (optional, default `{}`) |
|||
- `opts.label` **[String][8]** Label for the selector, if it's not provided the label will be the same as the name (optional, default `''`) |
|||
- `opts.type` **[String][8]** Type of the selector. At the moment, only 'class' (1) is available (optional, default `1`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const selector = selectorManager.add('selectorName'); |
|||
// Same as |
|||
const selector = selectorManager.add('selectorName', { |
|||
type: 1, |
|||
label: 'selectorName' |
|||
}); |
|||
// Multiple selectors |
|||
const selectors = selectorManager.add(['.class1', '.class2', '#id1']); |
|||
``` |
|||
|
|||
Returns **(Model | [Array][9])** |
|||
|
|||
## addClass |
|||
|
|||
Add class selectors |
|||
|
|||
### Parameters |
|||
|
|||
- `classes` **([Array][9] \| [string][8])** Array or string of classes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
sm.addClass('class1'); |
|||
sm.addClass('class1 class2'); |
|||
sm.addClass(['class1', 'class2']); |
|||
// -> [SelectorObject, ...] |
|||
``` |
|||
|
|||
Returns **[Array][9]** Array of added selectors |
|||
|
|||
## get |
|||
|
|||
Get the selector by its name |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **([String][8] \| [Array][9])** Selector name |
|||
- `type` **[String][8]** Selector type |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const selector = selectorManager.get('selectorName'); |
|||
// or get an array |
|||
const selectors = selectorManager.get(['class1', 'class2']); |
|||
``` |
|||
|
|||
Returns **(Model | [Array][9])** |
|||
|
|||
## getAll |
|||
|
|||
Get all selectors |
|||
|
|||
Returns **Collection** |
|||
|
|||
## escapeName |
|||
|
|||
Return escaped selector name |
|||
|
|||
### Parameters |
|||
|
|||
- `name` **[String][8]** Selector name to escape |
|||
|
|||
Returns **[String][8]** Escaped name |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/selector_manager/config/config.js |
|||
|
|||
[2]: #getconfig |
|||
|
|||
[3]: #add |
|||
|
|||
[4]: #addclass |
|||
|
|||
[5]: #get |
|||
|
|||
[6]: #getAll |
|||
|
|||
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
@ -0,0 +1,222 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## StorageManager |
|||
|
|||
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({ |
|||
storageManager: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const storageManager = editor.StorageManager; |
|||
``` |
|||
|
|||
- [getConfig][2] |
|||
- [isAutosave][3] |
|||
- [setAutosave][4] |
|||
- [getStepsBeforeSave][5] |
|||
- [setStepsBeforeSave][6] |
|||
- [setStepsBeforeSave][6] |
|||
- [getStorages][7] |
|||
- [getCurrent][8] |
|||
- [getCurrentStorage][9] |
|||
- [setCurrent][10] |
|||
- [add][11] |
|||
- [get][12] |
|||
- [store][13] |
|||
- [load][14] |
|||
|
|||
## getConfig |
|||
|
|||
Get configuration object |
|||
|
|||
Returns **[Object][15]** |
|||
|
|||
## isAutosave |
|||
|
|||
Checks if autosave is enabled |
|||
|
|||
Returns **[Boolean][16]** |
|||
|
|||
## setAutosave |
|||
|
|||
Set autosave value |
|||
|
|||
### Parameters |
|||
|
|||
- `v` **[Boolean][16]** |
|||
|
|||
Returns **this** |
|||
|
|||
## getStepsBeforeSave |
|||
|
|||
Returns number of steps required before trigger autosave |
|||
|
|||
Returns **[number][17]** |
|||
|
|||
## setStepsBeforeSave |
|||
|
|||
Set steps required before trigger autosave |
|||
|
|||
### Parameters |
|||
|
|||
- `v` **[number][17]** |
|||
|
|||
Returns **this** |
|||
|
|||
## add |
|||
|
|||
Add new storage |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][18]** Storage ID |
|||
- `storage` **[Object][15]** Storage wrapper |
|||
- `storage.load` **[Function][19]** Load method |
|||
- `storage.store` **[Function][19]** Store method |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
storageManager.add('local2', { |
|||
load: function(keys, clb, clbErr) { |
|||
var res = {}; |
|||
for (var i = 0, len = keys.length; i < len; i++){ |
|||
var v = localStorage.getItem(keys[i]); |
|||
if(v) res[keys[i]] = v; |
|||
} |
|||
clb(res); // might be called inside some async method |
|||
// In case of errors... |
|||
// clbErr('Went something wrong'); |
|||
}, |
|||
store: function(data, clb, clbErr) { |
|||
for(var key in data) |
|||
localStorage.setItem(key, data[key]); |
|||
clb(); // might be called inside some async method |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## get |
|||
|
|||
Returns storage by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][18]** Storage ID |
|||
|
|||
Returns **([Object][15] | null)** |
|||
|
|||
## getStorages |
|||
|
|||
Returns all storages |
|||
|
|||
Returns **[Array][20]** |
|||
|
|||
## getCurrent |
|||
|
|||
Returns current storage type |
|||
|
|||
Returns **[string][18]** |
|||
|
|||
## setCurrent |
|||
|
|||
Set current storage type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][18]** Storage ID |
|||
|
|||
Returns **this** |
|||
|
|||
## store |
|||
|
|||
Store key-value resources in the current storage |
|||
|
|||
### Parameters |
|||
|
|||
- `data` **[Object][15]** Data in key-value format, eg. {item1: value1, item2: value2} |
|||
- `clb` **[Function][19]** Callback function |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
storageManager.store({item1: value1, item2: value2}); |
|||
``` |
|||
|
|||
Returns **([Object][15] | null)** |
|||
|
|||
## load |
|||
|
|||
Load resource from the current storage by keys |
|||
|
|||
### Parameters |
|||
|
|||
- `keys` **([string][18] \| [Array][20]<[string][18]>)** Keys to load |
|||
- `clb` **[Function][19]** Callback function |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
storageManager.load(['item1', 'item2'], res => { |
|||
// res -> {item1: value1, item2: value2} |
|||
}); |
|||
storageManager.load('item1', res => { |
|||
// res -> {item1: value1} |
|||
}); |
|||
``` |
|||
|
|||
## getCurrentStorage |
|||
|
|||
Get current storage |
|||
|
|||
Returns **Storage** |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/storage_manager/config/config.js |
|||
|
|||
[2]: #getconfig |
|||
|
|||
[3]: #isautosave |
|||
|
|||
[4]: #setautosave |
|||
|
|||
[5]: #getstepsbeforesave |
|||
|
|||
[6]: #setstepsbeforesave |
|||
|
|||
[7]: #getstorages |
|||
|
|||
[8]: #getcurrent |
|||
|
|||
[9]: #getcurrentstorage |
|||
|
|||
[10]: #setcurrent |
|||
|
|||
[11]: #add |
|||
|
|||
[12]: #get |
|||
|
|||
[13]: #store |
|||
|
|||
[14]: #load |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
|||
|
|||
[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function |
|||
|
|||
[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
@ -0,0 +1,333 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## StyleManager |
|||
|
|||
With Style Manager you build categories (called sectors) of CSS properties which could be used to customize the style of components. |
|||
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({ |
|||
styleManager: { |
|||
// options |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const styleManager = editor.StyleManager; |
|||
``` |
|||
|
|||
- [getConfig][2] |
|||
- [addSector][3] |
|||
- [getSector][4] |
|||
- [removeSector][5] |
|||
- [getSectors][6] |
|||
- [addProperty][7] |
|||
- [getProperty][8] |
|||
- [removeProperty][9] |
|||
- [getProperties][10] |
|||
- [getModelToStyle][11] |
|||
- [addType][12] |
|||
- [getType][13] |
|||
- [getTypes][14] |
|||
- [createType][15] |
|||
|
|||
## getConfig |
|||
|
|||
Get configuration object |
|||
|
|||
Returns **[Object][16]** |
|||
|
|||
## addSector |
|||
|
|||
Add new sector to the collection. If the sector with the same id already exists, |
|||
that one will be returned |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Sector id |
|||
- `sector` **[Object][16]** Object representing sector |
|||
- `sector.name` **[string][17]** Sector's label (optional, default `''`) |
|||
- `sector.open` **[Boolean][18]** Indicates if the sector should be opened (optional, default `true`) |
|||
- `sector.properties` **[Array][19]<[Object][16]>** Array of properties (optional, default `[]`) |
|||
- `opts` (optional, default `{}`) |
|||
- `options` **[Object][16]** Options (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var sector = styleManager.addSector('mySector',{ |
|||
name: 'My sector', |
|||
open: true, |
|||
properties: [{ name: 'My property'}] |
|||
}, { at: 0 }); |
|||
// With `at: 0` we place the new sector at the beginning of the collection |
|||
``` |
|||
|
|||
Returns **Sector** Added Sector |
|||
|
|||
## getSector |
|||
|
|||
Get sector by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Sector id |
|||
- `opts` (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var sector = styleManager.getSector('mySector'); |
|||
``` |
|||
|
|||
Returns **(Sector | null)** |
|||
|
|||
## removeSector |
|||
|
|||
Remove a sector by id |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Sector id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const removed = styleManager.removeSector('mySector'); |
|||
``` |
|||
|
|||
Returns **Sector** Removed sector |
|||
|
|||
## getSectors |
|||
|
|||
Get all sectors |
|||
|
|||
Returns **Sectors** Collection of sectors |
|||
|
|||
## addProperty |
|||
|
|||
Add property to the sector identified by id |
|||
|
|||
### Parameters |
|||
|
|||
- `sectorId` **[string][17]** Sector id |
|||
- `property` **[Object][16]** Property object |
|||
- `property.name` **[string][17]** Name of the property (optional, default `''`) |
|||
- `property.property` **[string][17]** CSS property, eg. `min-height` (optional, default `''`) |
|||
- `property.type` **[string][17]** Type of the property: integer | radio | select | color | file | composite | stack (optional, default `''`) |
|||
- `property.units` **[Array][19]<[string][17]>** Unit of measure available, eg. ['px','%','em']. Only for integer type (optional, default `[]`) |
|||
- `property.unit` **[string][17]** Default selected unit from `units`. Only for integer type (optional, default `''`) |
|||
- `property.min` **[number][20]** Min possible value. Only for integer type (optional, default `null`) |
|||
- `property.max` **[number][20]** Max possible value. Only for integer type (optional, default `null`) |
|||
- `property.defaults` **[string][17]** Default value (optional, default `''`) |
|||
- `property.info` **[string][17]** Some description (optional, default `''`) |
|||
- `property.icon` **[string][17]** Class name. If exists no text will be displayed (optional, default `''`) |
|||
- `property.preview` **[Boolean][18]** Show layers preview. Only for stack type (optional, default `false`) |
|||
- `property.functionName` **[string][17]** Indicates if value need to be wrapped in some function, for istance `transform: rotate(90deg)` (optional, default `''`) |
|||
- `property.properties` **[Array][19]<[Object][16]>** Nested properties for composite and stack type (optional, default `[]`) |
|||
- `property.layers` **[Array][19]<[Object][16]>** Layers for stack properties (optional, default `[]`) |
|||
- `property.list` **[Array][19]<[Object][16]>** List of possible options for radio and select types (optional, default `[]`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var property = styleManager.addProperty('mySector',{ |
|||
name: 'Minimum height', |
|||
property: 'min-height', |
|||
type: 'select', |
|||
defaults: '100px', |
|||
list: [{ |
|||
value: '100px', |
|||
name: '100', |
|||
},{ |
|||
value: '200px', |
|||
name: '200', |
|||
}], |
|||
}); |
|||
``` |
|||
|
|||
Returns **(Property | null)** Added Property or `null` in case sector doesn't exist |
|||
|
|||
## getProperty |
|||
|
|||
Get property by its CSS name and sector id |
|||
|
|||
### Parameters |
|||
|
|||
- `sectorId` **[string][17]** Sector id |
|||
- `name` **[string][17]** CSS property name, eg. 'min-height' |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var property = styleManager.getProperty('mySector','min-height'); |
|||
``` |
|||
|
|||
Returns **(Property | null)** |
|||
|
|||
## removeProperty |
|||
|
|||
Remove a property from the sector |
|||
|
|||
### Parameters |
|||
|
|||
- `sectorId` **[string][17]** Sector id |
|||
- `name` **[string][17]** CSS property name, eg. 'min-height' |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const property = styleManager.removeProperty('mySector', 'min-height'); |
|||
``` |
|||
|
|||
Returns **Property** Removed property |
|||
|
|||
## getProperties |
|||
|
|||
Get properties of the sector |
|||
|
|||
### Parameters |
|||
|
|||
- `sectorId` **[string][17]** Sector id |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
var properties = styleManager.getProperties('mySector'); |
|||
``` |
|||
|
|||
Returns **Properties** Collection of properties |
|||
|
|||
## getModelToStyle |
|||
|
|||
Get what to style inside Style Manager. If you select the component |
|||
without classes the entity is the Component itself and all changes will |
|||
go inside its 'style' property. Otherwise, if the selected component has |
|||
one or more classes, the function will return the corresponding CSS Rule |
|||
|
|||
### Parameters |
|||
|
|||
- `model` **Model** |
|||
|
|||
Returns **Model** |
|||
|
|||
## addType |
|||
|
|||
Add new property type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Type ID |
|||
- `definition` **[Object][16]** Definition of the type. Each definition contains |
|||
`model` (business logic), `view` (presentation logic) |
|||
and `isType` function which recognize the type of the |
|||
passed entity |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
styleManager.addType('my-type', { |
|||
model: {}, |
|||
view: {}, |
|||
isType: (value) => { |
|||
if (value && value.type == 'my-type') { |
|||
return value; |
|||
} |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
## getType |
|||
|
|||
Get type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Type ID |
|||
|
|||
Returns **[Object][16]** Type definition |
|||
|
|||
## getTypes |
|||
|
|||
Get all types |
|||
|
|||
Returns **[Array][19]** |
|||
|
|||
## createType |
|||
|
|||
Create new property from type |
|||
|
|||
### Parameters |
|||
|
|||
- `id` **[string][17]** Type ID |
|||
- `options` **[Object][16]** Options (optional, default `{}`) |
|||
- `options.model` **[Object][16]** Custom model object (optional, default `{}`) |
|||
- `options.view` **[Object][16]** Custom view object (optional, default `{}`) |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const propView = styleManager.createType('integer', { |
|||
model: {units: ['px', 'rem']} |
|||
}); |
|||
propView.render(); |
|||
propView.model.on('change:value', ...); |
|||
someContainer.appendChild(propView.el); |
|||
``` |
|||
|
|||
Returns **PropertyView** |
|||
|
|||
## setTarget |
|||
|
|||
Select different target for the Style Manager. |
|||
It could be a Component, CSSRule, or a string of any CSS selector |
|||
|
|||
### Parameters |
|||
|
|||
- `target` **(Component | CSSRule | [String][17])** |
|||
- `opts` |
|||
|
|||
Returns **Styleable** A Component or CSSRule |
|||
|
|||
[1]: https://github.com/artf/grapesjs/blob/master/src/style_manager/config/config.js |
|||
|
|||
[2]: #getconfig |
|||
|
|||
[3]: #addsector |
|||
|
|||
[4]: #getsector |
|||
|
|||
[5]: #removesector |
|||
|
|||
[6]: #getsectors |
|||
|
|||
[7]: #addproperty |
|||
|
|||
[8]: #getproperty |
|||
|
|||
[9]: #removeproperty |
|||
|
|||
[10]: #getproperties |
|||
|
|||
[11]: #getmodeltostyle |
|||
|
|||
[12]: #addtype |
|||
|
|||
[13]: #gettype |
|||
|
|||
[14]: #gettypes |
|||
|
|||
[15]: #createtype |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String |
|||
|
|||
[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
|
|||
[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array |
|||
|
|||
[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number |
|||
@ -0,0 +1,236 @@ |
|||
<!-- Generated by documentation.js. Update this documentation by updating the source code. --> |
|||
|
|||
## UndoManager |
|||
|
|||
This module allows to manage the stack of changes applied in canvas. |
|||
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance |
|||
|
|||
```js |
|||
const um = editor.UndoManager; |
|||
``` |
|||
|
|||
- [getConfig][1] |
|||
- [add][2] |
|||
- [remove][3] |
|||
- [removeAll][4] |
|||
- [start][5] |
|||
- [stop][6] |
|||
- [undo][7] |
|||
- [undoAll][8] |
|||
- [redo][9] |
|||
- [redoAll][10] |
|||
- [hasUndo][11] |
|||
- [hasRedo][12] |
|||
- [getStack][13] |
|||
- [clear][14] |
|||
|
|||
## getConfig |
|||
|
|||
Get module configurations |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const config = um.getConfig(); |
|||
// { ... } |
|||
``` |
|||
|
|||
Returns **[Object][15]** Configuration object |
|||
|
|||
## add |
|||
|
|||
Add an entity (Model/Collection) to track |
|||
Note: New Components and CSSRules will be added automatically |
|||
|
|||
### Parameters |
|||
|
|||
- `entity` **(Model | Collection)** Entity to track |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.add(someModelOrCollection); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## remove |
|||
|
|||
Remove and stop tracking the entity (Model/Collection) |
|||
|
|||
### Parameters |
|||
|
|||
- `entity` **(Model | Collection)** Entity to remove |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.remove(someModelOrCollection); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## removeAll |
|||
|
|||
Remove all entities |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.removeAll(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## start |
|||
|
|||
Start/resume tracking changes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.start(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## stop |
|||
|
|||
Stop tracking changes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.stop(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## undo |
|||
|
|||
Undo last change |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.undo(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## undoAll |
|||
|
|||
Undo all changes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.undoAll(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## redo |
|||
|
|||
Redo last change |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.redo(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## redoAll |
|||
|
|||
Redo all changes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.redoAll(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
## hasUndo |
|||
|
|||
Checks if exists an available undo |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.hasUndo(); |
|||
``` |
|||
|
|||
Returns **[Boolean][16]** |
|||
|
|||
## hasRedo |
|||
|
|||
Checks if exists an available redo |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.hasRedo(); |
|||
``` |
|||
|
|||
Returns **[Boolean][16]** |
|||
|
|||
## getStack |
|||
|
|||
Get stack of changes |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
const stack = um.getStack(); |
|||
stack.each(item => ...); |
|||
``` |
|||
|
|||
Returns **Collection** |
|||
|
|||
## clear |
|||
|
|||
Clear the stack |
|||
|
|||
### Examples |
|||
|
|||
```javascript |
|||
um.clear(); |
|||
``` |
|||
|
|||
Returns **this** |
|||
|
|||
[1]: #getconfig |
|||
|
|||
[2]: #add |
|||
|
|||
[3]: #remove |
|||
|
|||
[4]: #removeall |
|||
|
|||
[5]: #start |
|||
|
|||
[6]: #stop |
|||
|
|||
[7]: #undo |
|||
|
|||
[8]: #undoall |
|||
|
|||
[9]: #redo |
|||
|
|||
[10]: #redoall |
|||
|
|||
[11]: #hasundo |
|||
|
|||
[12]: #hasredo |
|||
|
|||
[13]: #getstack |
|||
|
|||
[14]: #clear |
|||
|
|||
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object |
|||
|
|||
[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean |
|||
@ -0,0 +1,28 @@ |
|||
#!/usr/bin/env sh |
|||
|
|||
# abort on errors |
|||
set -e |
|||
|
|||
# build |
|||
npm run docs:build |
|||
|
|||
# navigate into the build output directory |
|||
cd docs/.vuepress/dist |
|||
|
|||
# I need to deploy all the documentation inside docs folder |
|||
mkdir docs-new |
|||
|
|||
# move all the files from the current directory in docs |
|||
mv `\ls -1 ./ | grep -v docs-new` ./docs-new |
|||
|
|||
# fetch the current site, remove the old docs dir and make current the new one |
|||
git clone -b gh-pages https://github.com/artf/grapesjs.git tmp && mv tmp/* tmp/.* . && rm -rf tmp |
|||
rm -fR docs |
|||
mv ./docs-new ./docs |
|||
|
|||
# stage all and commit |
|||
git add -A |
|||
git commit -m 'deploy docs' |
|||
git push https://github.com/artf/grapesjs.git gh-pages |
|||
# surge --domain grapesjs.surge.sh |
|||
cd - |
|||
@ -0,0 +1,7 @@ |
|||
--- |
|||
title: Faq |
|||
--- |
|||
|
|||
# FAQ |
|||
|
|||
Coming soon |
|||
@ -0,0 +1,724 @@ |
|||
--- |
|||
title: Getting Started |
|||
pageClass: page__getting-started |
|||
meta: |
|||
- name: keywords |
|||
content: grapesjs getting started |
|||
--- |
|||
|
|||
# Getting Started |
|||
|
|||
This is a step-by-step guide for anyone who wants to create their own builder with GrapesJS. This is not a comprehensive guide, just a concise overview of most common modules. Follow along to create a page builder from scratch. Skip to the end of this page to see the [final result](#final-result) |
|||
|
|||
## Import the library |
|||
|
|||
Before you start using GrapesJS, you'll have to import it. Let's import the latest version |
|||
|
|||
```html |
|||
<link rel="stylesheet" href="//unpkg.com/grapesjs/dist/css/grapes.min.css"> |
|||
<script src="//unpkg.com/grapesjs"></script> |
|||
<!-- |
|||
If you need plugins, put them below the main grapesjs script |
|||
<script src="/path/to/some/plugin.min.js"></script> |
|||
--> |
|||
``` |
|||
|
|||
or if you're in a Node environment |
|||
|
|||
```js |
|||
import 'grapesjs/dist/css/grapes.min.css'; |
|||
import grapesjs from 'grapesjs'; |
|||
// If you need plugins, put them below the main grapesjs script |
|||
// import 'grapesjs-some-plugin'; |
|||
``` |
|||
|
|||
## Start from the canvas |
|||
|
|||
The first step is to define the interface of our editor. For this purpose we gonna start with basic HTML layouts. Finding a common structure for the UI of any project is not an easy task. That's why GrapesJS prefers to keep this process as simple as possible. We provide a few helpers, but let the user define the interface. This guarantees maximum flexibility. |
|||
The main part of the GrapesJS editor is the canvas, this is where you create the structure of your templates and you can't miss it. Let's try to initiate the editor with the canvas and no panels. |
|||
|
|||
<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.html |
|||
<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.js |
|||
<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.css |
|||
<Demo> |
|||
<DemoCanvasOnly/> |
|||
</Demo> |
|||
|
|||
With just the canvas you're already able to move, copy and delete components from the structure. For now, we see the example template taken from the container. Next let's look at how to create and drag custom blocks into our canvas. |
|||
|
|||
## Add Blocks |
|||
The block in GrapesJS is just a reusable piece of HTML that you can drop in the canvas. A block can be an image, a button, or an entire section with videos, forms and iframes. Let's start by creating another container and append a few basic blocks inside of it. Later we can use this technique to build more complex structures. |
|||
|
|||
```html{4} |
|||
<div id="gjs"> |
|||
... |
|||
</div> |
|||
<div id="blocks"></div> |
|||
``` |
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
blockManager: { |
|||
appendTo: '#blocks', |
|||
blocks: [ |
|||
{ |
|||
id: 'section', // id is mandatory |
|||
label: '<b>Section</b>', // You can use HTML/SVG inside labels |
|||
attributes: { class:'gjs-block-section' }, |
|||
content: `<section> |
|||
<h1>This is a simple title</h1> |
|||
<div>This is just a Lorem text: Lorem ipsum dolor sit amet</div> |
|||
</section>`, |
|||
}, { |
|||
id: 'text', |
|||
label: 'Text', |
|||
content: '<div data-gjs-type="text">Insert your text here</div>', |
|||
}, { |
|||
id: 'image', |
|||
label: 'Image', |
|||
// Select the component once it's dropped |
|||
select: true, |
|||
// You can pass components as a JSON instead of a simple HTML string, |
|||
// in this case we also use a defined component type `image` |
|||
content: { type: 'image' }, |
|||
// This triggers `active` event on dropped components and the `image` |
|||
// reacts by opening the AssetManager |
|||
activate: true, |
|||
} |
|||
] |
|||
}, |
|||
}); |
|||
``` |
|||
```css |
|||
.gjs-block { |
|||
width: auto; |
|||
height: auto; |
|||
min-height: auto; |
|||
} |
|||
``` |
|||
<Demo> |
|||
<DemoBasicBlocks/> |
|||
</Demo> |
|||
|
|||
As you can see we add our blocks via the initial configuration. Obviously there might be a case in which you would like to add them dynamically, in this case you have to use the [Block Manager API](api/block_manager.html) |
|||
|
|||
```js |
|||
editor.BlockManager.add('my-block-id', { |
|||
label: '...', |
|||
category: '...', |
|||
// ... |
|||
}) |
|||
``` |
|||
::: tip |
|||
If you want to learn more about blocks we suggest to read its dedicated article: [Block Manager Module](modules/Blocks.html) |
|||
::: |
|||
|
|||
## Define Components |
|||
Technically, once you drop your HTML block inside the canvas each element of the content is transformed into a GrapesJS Component. A GrapesJS Component is an object containing information about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View. Therefore, if you add a new attribute to the model, it will be available in the export code (which we will learn more about later), and the element you see in the canvas will be updated with new attributes. |
|||
This isn't totally out of the ordinary, but the unique thing about Components that you can create a totally decoupled View. This means you can show the user whatever you desire regardless of what is in the Model. For example, by dragging a placeholder text you can fetch and show instead a dynamic content. If you want to learn more about Custom Components, you should check out [Component Manager Module](modules/Components.html). |
|||
|
|||
GrapesJS comes with a few [built-in Components](modules/Components.html#built-in-components) that enable different features once rendered in the canvas. For example, by double clicking on an image component you will see the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own. By double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customization and [replaceable](guides/Replace-Rich-Text-Editor.html). |
|||
|
|||
As we have seen before you can create Blocks directly as Components |
|||
```js |
|||
editor.BlockManager.add('my-block-id', { |
|||
// ... |
|||
content: { |
|||
tagName: 'div', |
|||
draggable: false, |
|||
attributes: { 'some-attribute': 'some-value' }, |
|||
components: [ |
|||
{ |
|||
tagName: 'span', |
|||
content: '<b>Some static content</b>', |
|||
}, { |
|||
tagName: 'div', |
|||
// use `content` for static strings, `components` string will be parsed |
|||
// and transformed in Components |
|||
components: '<span>HTML at some point</span>', |
|||
} |
|||
] |
|||
} |
|||
}) |
|||
``` |
|||
::: tip |
|||
Check out the [Components API](api/components.html) to learn how to interact with components dynamically |
|||
::: |
|||
|
|||
An example on how to select some inner component and replace its children with new contents |
|||
|
|||
```js |
|||
// The wrapper is the root Component |
|||
const wrapper = editor.DomComponents.getWrapper(); |
|||
const myComponent = wrapper.find('div.my-component')[0]; |
|||
myComponent.components().forEach(component => /* ... do something ... */); |
|||
myComponent.components('<div>New content</div>'); |
|||
``` |
|||
|
|||
## Panels & Buttons |
|||
Now that we have a canvas and custom blocks let's see how to create a new custom panel with some buttons inside (using [Panels API](api/panels.html)) which trigger commands (the core one or custom). |
|||
|
|||
```html{1,2,3} |
|||
<div class="panel__top"> |
|||
<div class="panel__basic-actions"></div> |
|||
</div> |
|||
<div id="gjs"> |
|||
... |
|||
</div> |
|||
<div id="blocks"></div> |
|||
``` |
|||
|
|||
```css |
|||
.panel__top { |
|||
padding: 0; |
|||
width: 100%; |
|||
display: flex; |
|||
position: initial; |
|||
justify-content: center; |
|||
justify-content: space-between; |
|||
} |
|||
.panel__basic-actions { |
|||
position: initial; |
|||
} |
|||
``` |
|||
|
|||
```js |
|||
editor.Panels.addPanel({ |
|||
id: 'panel-top', |
|||
el: '.panel__top', |
|||
}); |
|||
editor.Panels.addPanel({ |
|||
id: 'basic-actions', |
|||
el: '.panel__basic-actions', |
|||
buttons: [ |
|||
{ |
|||
id: 'visibility', |
|||
active: true, // active by default |
|||
className: 'btn-toggle-borders', |
|||
label: '<u>B</u>', |
|||
command: 'sw-visibility', // Built-in command |
|||
}, { |
|||
id: 'export', |
|||
className: 'btn-open-export', |
|||
label: 'Exp', |
|||
command: 'export-template', |
|||
context: 'export-template', // For grouping context of buttons from the same panel |
|||
}, { |
|||
id: 'show-json', |
|||
className: 'btn-show-json', |
|||
label: 'JSON', |
|||
context: 'show-json', |
|||
command(editor) { |
|||
editor.Modal.setTitle('Components JSON') |
|||
.setContent(`<textarea style="width:100%; height: 250px;"> |
|||
${JSON.stringify(editor.getComponents())} |
|||
</textarea>`) |
|||
.open(); |
|||
}, |
|||
} |
|||
], |
|||
}); |
|||
``` |
|||
|
|||
<Demo> |
|||
<DemoCustomPanels/> |
|||
</Demo> |
|||
|
|||
We have defined where to render the panel with `el: '#basic-panel'` and then for each button we added a `command` property. The command could be the id, an object with `run` and `stop` functions or simply a single function. |
|||
Try to use [Commands](api/commands.html) when possible, they allow you to track actions globally. Commands also execute callbacks before and after their execution (you can even interrupt them). |
|||
|
|||
```js |
|||
editor.on('run:export-template:before', opts => { |
|||
console.log('Before the command run'); |
|||
if (0 /* some condition */) { |
|||
opts.abort = 1; |
|||
} |
|||
}); |
|||
editor.on('run:export-template', () => console.log('After the command run')); |
|||
editor.on('abort:export-template', () => console.log('Command aborted')); |
|||
``` |
|||
|
|||
::: tip |
|||
Check out the [Panels API](api/panels.html) to see all the available methods |
|||
::: |
|||
|
|||
|
|||
## Layers |
|||
Another utility tool you might find useful when working with web elements is the layer manger. It's a tree overview of the structure nodes and enables you to manage it easier. To enable it you just have to specify where you want to render it |
|||
|
|||
```html{4,5,6,7,8,9,10,11} |
|||
<div class="panel__top"> |
|||
<div class="panel__basic-actions"></div> |
|||
</div> |
|||
<div class="editor-row"> |
|||
<div class="editor-canvas"> |
|||
<div id="gjs">...</div> |
|||
</div> |
|||
<div class="panel__right"> |
|||
<div class="layers-container"></div> |
|||
</div> |
|||
</div> |
|||
<div id="blocks"></div> |
|||
``` |
|||
<<< @/docs/.vuepress/components/demos/DemoLayers.css |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
layerManager: { |
|||
appendTo: '.layers-container' |
|||
}, |
|||
// We define a default panel as a sidebar to contain layers |
|||
panels: { |
|||
defaults: [{ |
|||
id: 'layers', |
|||
el: '.panel__right', |
|||
// Make the panel resizable |
|||
resizable: { |
|||
maxDim: 350, |
|||
minDim: 200, |
|||
tc: 0, // Top handler |
|||
cl: 1, // Left handler |
|||
cr: 0, // Right handler |
|||
bc: 0, // Bottom handler |
|||
// Being a flex child we need to change `flex-basis` property |
|||
// instead of the `width` (default) |
|||
keyWidth: 'flex-basis', |
|||
}, |
|||
}] |
|||
} |
|||
}); |
|||
``` |
|||
<Demo> |
|||
<DemoLayers/> |
|||
</Demo> |
|||
|
|||
## Style Manager |
|||
Once you have defined the structure of the template the next step is the ability to style it. To meet this need GrapesJS includes the Style Manager module which is composed by CSS style properties and sectors. To make it more clear, let's see how to define a basic set. |
|||
|
|||
Let's start by adding one more panel inside the `panel__right` and another one in `panel__top` which will contain a Layer/Style Manager switcher |
|||
|
|||
```html{3,8} |
|||
<div class="panel__top"> |
|||
<div class="panel__basic-actions"></div> |
|||
<div class="panel__switcher"></div> |
|||
</div> |
|||
... |
|||
<div class="panel__right"> |
|||
<div class="layers-container"></div> |
|||
<div class="styles-container"></div> |
|||
</div> |
|||
... |
|||
``` |
|||
```css |
|||
.panel__switcher { |
|||
position: initial; |
|||
} |
|||
``` |
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
panels: { |
|||
defaults: [ |
|||
// ... |
|||
{ |
|||
id: 'panel-switcher', |
|||
el: '.panel__switcher', |
|||
buttons: [{ |
|||
id: 'show-layers', |
|||
active: true, |
|||
label: 'Layers', |
|||
command: 'show-layers', |
|||
// Once activated disable the possibility to turn it off |
|||
togglable: false, |
|||
}, { |
|||
id: 'show-style', |
|||
active: true, |
|||
label: 'Styles', |
|||
command: 'show-styles', |
|||
togglable: false, |
|||
}], |
|||
} |
|||
] |
|||
}, |
|||
// The Selector Manager allows to assign classes and |
|||
// different states (eg. :hover) on components. |
|||
// Generally, it's used in conjunction with Style Manager |
|||
// but it's not mandatory |
|||
selectorManager: { |
|||
appendTo: '.styles-container' |
|||
}, |
|||
styleManager: { |
|||
appendTo: '.styles-container', |
|||
sectors: [{ |
|||
name: 'Dimension', |
|||
open: false, |
|||
// Use built-in properties |
|||
buildProps: ['width', 'min-height', 'padding'], |
|||
// Use `properties` to define/override single property |
|||
properties: [ |
|||
{ |
|||
// Type of the input, |
|||
// options: integer | radio | select | color | slider | file | composite | stack |
|||
type: 'integer', |
|||
name: 'The width', // Label for the property |
|||
property: 'width', // CSS property (if buildProps contains it will be extended) |
|||
units: ['px', '%'], // Units, available only for 'integer' types |
|||
defaults: 'auto', // Default value |
|||
min: 0, // Min value, available only for 'integer' types |
|||
} |
|||
] |
|||
},{ |
|||
name: 'Extra', |
|||
open: false, |
|||
buildProps: ['background-color', 'box-shadow', 'custom-prop'], |
|||
properties: [ |
|||
{ |
|||
id: 'custom-prop', |
|||
name: 'Custom Label', |
|||
property: 'font-size', |
|||
type: 'select', |
|||
defaults: '32px', |
|||
// List of options, available only for 'select' and 'radio' types |
|||
options: [ |
|||
{ value: '12px', name: 'Tiny' }, |
|||
{ value: '18px', name: 'Medium' }, |
|||
{ value: '32px', name: 'Big' }, |
|||
], |
|||
} |
|||
] |
|||
}] |
|||
}, |
|||
}); |
|||
|
|||
// Define commands |
|||
editor.Commands.add('show-layers', { |
|||
getRowEl(editor) { return editor.getContainer().closest('.editor-row'); }, |
|||
getLayersEl(row) { return row.querySelector('.layers-container') }, |
|||
|
|||
run(editor, sender) { |
|||
const lmEl = this.getLayersEl(this.getRowEl(editor)); |
|||
lmEl.style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
const lmEl = this.getLayersEl(this.getRowEl(editor)); |
|||
lmEl.style.display = 'none'; |
|||
}, |
|||
}); |
|||
editor.Commands.add('show-styles', { |
|||
getRowEl(editor) { return editor.getContainer().closest('.editor-row'); }, |
|||
getStyleEl(row) { return row.querySelector('.styles-container') }, |
|||
|
|||
run(editor, sender) { |
|||
const smEl = this.getStyleEl(this.getRowEl(editor)); |
|||
smEl.style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
const smEl = this.getStyleEl(this.getRowEl(editor)); |
|||
smEl.style.display = 'none'; |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
<Demo> |
|||
<DemoStyle/> |
|||
</Demo> |
|||
|
|||
Inside Style Manager definition we use `buildProps` which helps us create common properties from [available built-in objects](modules/Style-manager.html#built-in-properties) then in `properties` we can override same objects (eg. passing another `name` to change the label) identified by `property` name. As you can see from `custom-prop` example it's a matter of defining the CSS `property` and the input `type`. We suggest to check a more complete example of Style Manager properties usage from the [webpage preset demo](https://github.com/artf/grapesjs/blob/gh-pages/demo.html#L1000) |
|||
|
|||
::: tip |
|||
Check the [Style Manager API](api/panels.html) to see how to update sectors and properties dynamically |
|||
::: |
|||
|
|||
<!-- |
|||
To get more about style manager extension check out this guide. |
|||
Each component can also indicate what to style and what not. |
|||
|
|||
-- Example component with limit styles |
|||
--> |
|||
|
|||
## Traits |
|||
Most of the time you would style your components and place them somewhere in the structure, but sometimes your components might need custom attributes or even custom behaviors and for this need you can make use of traits. Traits are commonly used to update HTML element attributes (eg. `placeholder` for inputs or `alt` for images), but you can also define your own custom traits. Access the selected Component model and do whatever you want. For this guide, we going to show you how to render available traits, for more details on how to extend them we suggest you read the [Trait Manager Module page](modules/Traits.html). |
|||
|
|||
Let's create a new container for traits. Tell the editor where to render it and update the sidebar switcher |
|||
|
|||
```html{5} |
|||
... |
|||
<div class="panel__right"> |
|||
<div class="layers-container"></div> |
|||
<div class="styles-container"></div> |
|||
<div class="traits-container"></div> |
|||
</div> |
|||
... |
|||
``` |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
panels: { |
|||
defaults: [ |
|||
// ... |
|||
{ |
|||
id: 'panel-switcher', |
|||
el: '.panel__switcher', |
|||
buttons: [ |
|||
// ... |
|||
{ |
|||
id: 'show-traits', |
|||
active: true, |
|||
label: 'Traits', |
|||
command: 'show-traits', |
|||
togglable: false, |
|||
}], |
|||
} |
|||
] |
|||
}, |
|||
traitManager: { |
|||
appendTo: '.traits-container', |
|||
}, |
|||
}); |
|||
|
|||
// Define command |
|||
// ... |
|||
editor.Commands.add('show-traits', { |
|||
getTraitsEl(editor) { |
|||
const row = editor.getContainer().closest('.editor-row'); |
|||
return row.querySelector('.traits-container'); |
|||
}, |
|||
run(editor, sender) { |
|||
this.getTraitsEl(editor).style.display = ''; |
|||
}, |
|||
stop(editor, sender) { |
|||
this.getTraitsEl(editor).style.display = 'none'; |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
<Demo> |
|||
<DemoTraits/> |
|||
</Demo> |
|||
|
|||
Now if you switch to the Trait panel and select one of the inner components you should see its default traits. |
|||
|
|||
## Responsive templates |
|||
GrapesJS implements a module which allows you to work with responsive templates easily. Let's see how to define different devices and a button for device switching |
|||
|
|||
```html{3} |
|||
<div class="panel__top"> |
|||
<div class="panel__basic-actions"></div> |
|||
<div class="panel__devices"></div> |
|||
<div class="panel__switcher"></div> |
|||
</div> |
|||
... |
|||
``` |
|||
```css |
|||
.panel__devices { |
|||
position: initial; |
|||
} |
|||
``` |
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
deviceManager: { |
|||
devices: [{ |
|||
name: 'Desktop', |
|||
width: '', // default size |
|||
}, { |
|||
name: 'Mobile', |
|||
width: '320px', // this value will be used on canvas width |
|||
widthMedia: '480px', // this value will be used in CSS @media |
|||
}] |
|||
}, |
|||
// ... |
|||
panels: { |
|||
defaults: [ |
|||
// ... |
|||
{ |
|||
id: 'panel-devices', |
|||
el: '.panel__devices', |
|||
buttons: [{ |
|||
id: 'device-desktop', |
|||
label: 'D', |
|||
command: 'set-device-desktop', |
|||
active: true, |
|||
togglable: false, |
|||
}, { |
|||
id: 'device-mobile', |
|||
label: 'M', |
|||
command: 'set-device-mobile', |
|||
togglable: false, |
|||
}], |
|||
} |
|||
] |
|||
}, |
|||
}); |
|||
|
|||
// Commands |
|||
editor.Commands.add('set-device-desktop', { |
|||
run: editor => editor.setDevice('Desktop') |
|||
}); |
|||
editor.Commands.add('set-device-mobile', { |
|||
run: editor => editor.setDevice('Mobile') |
|||
}); |
|||
``` |
|||
|
|||
<Demo> |
|||
<DemoDevices/> |
|||
</Demo> |
|||
|
|||
As you can see from the commands definition we use the `editor.setDevice` method to change the size of the viewport. In case you need to trigger an action on device change you can setup a listener like this: |
|||
|
|||
```js |
|||
editor.on('change:device', () => console.log('Current device: ', editor.getDevice())); |
|||
``` |
|||
|
|||
What about the mobile-first approach? You can achieve it by changing your configurations in this way: |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
// ... |
|||
mediaCondition: 'min-width', // default is `max-width` |
|||
deviceManager: { |
|||
devices: [{ |
|||
name: 'Mobile', |
|||
width: '320', |
|||
widthMedia: '', |
|||
}, { |
|||
name: 'Desktop', |
|||
width: '', |
|||
widthMedia:'1024', |
|||
}] |
|||
}, |
|||
// ... |
|||
}); |
|||
|
|||
// Set initial device as Mobile |
|||
editor.setDevice('Mobile'); |
|||
``` |
|||
|
|||
::: tip |
|||
Check out the [Device Manager API](api/device_manager.html) to see all the available methods |
|||
::: |
|||
|
|||
## Store & load data |
|||
Once you have finished with defining your builder interface the next step would be to setup the storing and loading process. |
|||
GrapesJS implements 2 simple type of storages inside its Storage Manager: The local (by using `localStorage`, active by default) and the remote one. Those are enough to cover most of the cases, but it's also possible to add new implementations ([grapesjs-indexeddb](https://github.com/artf/grapesjs-indexeddb) is a good example). |
|||
Let's see how the default options work |
|||
|
|||
```js |
|||
grapesjs.init({ |
|||
// ... |
|||
storageManager: { |
|||
id: 'gjs-', // Prefix identifier that will be used inside storing and loading |
|||
type: 'local', // Type of the storage |
|||
autosave: true, // Store data automatically |
|||
autoload: true, // Autoload stored data on init |
|||
stepsBeforeSave: 1, // If autosave enabled, indicates how many changes are necessary before store method is triggered |
|||
storeComponents: true, // Enable/Disable storing of components in JSON format |
|||
storeStyles: true, // Enable/Disable storing of rules in JSON format |
|||
storeHtml: true, // Enable/Disable storing of components as HTML string |
|||
storeCss: true, // Enable/Disable storing of rules as CSS string |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
It is worth noting that the default `id` parameter adds a prefix for all keys to store. If you check the `localStorage` inside the devtool panel you'll see something like `{ 'gjs-components': '....' ...}` this way it lessens the risk of collisions. |
|||
|
|||
Let's look at the configuration required to setup the remote storage |
|||
|
|||
```js |
|||
grapesjs.init({ |
|||
// ... |
|||
storageManager: { |
|||
type: 'remote', |
|||
stepsBeforeSave: 10, |
|||
urlStore: 'http://store/endpoint', |
|||
urlLoad: 'http://load/endpoint', |
|||
params: {}, // Custom parameters to pass with the remote storage request, eg. CSRF token |
|||
headers: {}, // Custom headers for the remote storage request |
|||
} |
|||
}); |
|||
``` |
|||
As you might noticed, we've left some default options unchanged: Increased changes necessary for autosave triggering and passed remote endpoints. |
|||
If you prefer you could also disable the autosaving and you can do so using a custom command |
|||
|
|||
```js |
|||
// ... |
|||
storageManager: { |
|||
type: 'remote', |
|||
autosave: false, |
|||
// ... |
|||
}, |
|||
// ... |
|||
commands: { |
|||
defaults: [ |
|||
// ... |
|||
{ |
|||
id: 'store-data', |
|||
run(editor) { |
|||
editor.store(); |
|||
}, |
|||
} |
|||
] |
|||
} |
|||
// ... |
|||
``` |
|||
|
|||
To get a better overview of the Storage Manager and how you should store/load the template, or how to define new storages you should read the [Storage Manager Module](modules/Storage.html) page |
|||
|
|||
## Theming |
|||
One last step that might actually improve a lot your editor personality is how it's look visually. To achieve an easy theming we have adapted an atomic design for this purpose. To customize the main palette of colors all you have to do is to change few CSS rules. Alternatively if you include GrapesJS styles via SCSS you can make use of its [internal variables](https://github.com/artf/grapesjs/blob/dev/src/styles/scss/_gjs_variables.scss) and declare your variables before the import |
|||
|
|||
```scss |
|||
// Put your variables before the GrapesJS style import |
|||
|
|||
// Palette variables |
|||
$primaryColor: #444; |
|||
$secondaryColor: #ddd; |
|||
$tertiaryColor: #804f7b; |
|||
$quaternaryColor: #d278c9; |
|||
|
|||
// ... |
|||
|
|||
@import "grapesjs/src/styles/scss/main.scss"; |
|||
``` |
|||
|
|||
In case of a simple CSS you'll have to put your rules after the GrapesJS styles. |
|||
To complete our builder let's customize its color palette and to make it more visually "readable" we can replace all button labels with SVG icons |
|||
|
|||
```css |
|||
/* We can remove the border we've set at the beginnig */ |
|||
#gjs { |
|||
border: none; |
|||
} |
|||
/* Theming */ |
|||
|
|||
/* Primary color for the background */ |
|||
.gjs-one-bg { |
|||
background-color: #78366a; |
|||
} |
|||
|
|||
/* Secondary color for the text color */ |
|||
.gjs-two-color { |
|||
color: rgba(255, 255, 255, 0.7); |
|||
} |
|||
|
|||
/* Tertiary color for the background */ |
|||
.gjs-three-bg { |
|||
background-color: #ec5896; |
|||
color: white; |
|||
} |
|||
|
|||
/* Quaternary color for the text color */ |
|||
.gjs-four-color, |
|||
.gjs-four-color-h:hover { |
|||
color: #ec5896; |
|||
} |
|||
``` |
|||
|
|||
and here is our final result |
|||
|
|||
<Demo id="final-result"> |
|||
<DemoTheme/> |
|||
</Demo> |
|||
|
|||
@ -0,0 +1,247 @@ |
|||
--- |
|||
title: Use Custom CSS Parser |
|||
--- |
|||
# Use Custom CSS Parser |
|||
|
|||
If you just use GrapesJS for building templates from scratch, so you start from an empty canvas and for editing you strictly rely on the generated JSON (final HTML/CSS only for end-users) then, probably, you might skip this guide. On the other hand, if you import templates from already defined HTML/CSS or let the user embed custom codes (eg. using the [grapesjs-custom-code](https://github.com/artf/grapesjs-custom-code) plugin), then you have to know that you might face strange behaviors. |
|||
|
|||
::: warning |
|||
This guide requires GrapesJS v0.14.33 or higher |
|||
::: |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Import HTML/CSS |
|||
|
|||
Importing already defined HTML/CSS is a really good feature as it lets you start editing immediately any kind of template and obviously, GrapesJS itself promotes this kind of approach |
|||
|
|||
```html |
|||
<div id="gjs"> |
|||
<div class="txt-red">Hello world!</div> |
|||
<style>.txt-red{color: red}</style> |
|||
</div> |
|||
|
|||
<script type="text/javascript"> |
|||
const editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
fromElement: true, |
|||
}); |
|||
</script> |
|||
``` |
|||
|
|||
To work fast and easier GrapesJS needs to compile a simple string (HTML/CSS) into structured nodes (nested JS objects). Fortunately, most of the hard work (parsing) is already done by the browser itself which translates that string into its own objects ([DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model)/[CSSOM](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model)) and so we just rely on those, by traversing them and creating our nodes (unfortunately browser's objects are not enough). The fact we're able to parse our strings just by using the browser itself it's very cool, we can enable the import feature without requiring any third-party library, so... where is the problem? Well, while the generated DOM is performing quite well, as we're able to extract what we need, unfortunately, it's not the same for the CSSOM, so let's see in the next paragraph what is wrong with it. |
|||
|
|||
## CSSOM results are inconsistent |
|||
|
|||
Unfortunately, we have discovered that the CSSOM generated by browsers are highly inconsistent from what we ask to parse. To demonstrate it, we gonna create a simple example by using the built-in parser and we'll check its result. |
|||
So, for our case we just take in account a simple rule, we'll parse it and print the CSSOM result on screen. |
|||
|
|||
```html |
|||
<h1>To parse</h1> |
|||
<pre id="css-to-parse"> |
|||
.simple-class { |
|||
background-image:url("https://image1.png"), url("https://image2.jpg"); |
|||
background-attachment: fixed, scroll; |
|||
background-position:left top, center center; |
|||
background-repeat:repeat-y, no-repeat; |
|||
background-size: contain, cover; |
|||
box-shadow: 0 0 5px #9d7aa5, 0 0 10px #e6c3ee; |
|||
border: 2px solid #FF0000; |
|||
} |
|||
</pre> |
|||
|
|||
<h1>Result</h1> |
|||
<pre id="result"></pre> |
|||
|
|||
<script> |
|||
// We use ES5 just to make it more cross-browser, without the need of being compiled |
|||
|
|||
function parse(str) { |
|||
var result = []; |
|||
// Create the element which will contain the style to parse |
|||
var el = document.createElement('style'); |
|||
el.innerHTML = str; |
|||
// We have to append the style to get its CSSOM |
|||
document.head.appendChild(el); |
|||
var sheet = el.sheet; |
|||
// Now we can remove it |
|||
document.head.removeChild(el); |
|||
|
|||
return sheet; |
|||
} |
|||
|
|||
function CSSOMToString(root) { |
|||
// For the sake of brevity we just print what we need |
|||
var styleStr = ''; |
|||
var rule = root.cssRules[0]; |
|||
var style = rule.style; |
|||
// The only way we have to iterate over CSSStyleDeclaration |
|||
for (var i = 0, len = style.length; i < len; i++) { |
|||
var property = style[i]; |
|||
var value = style.getPropertyValue(property); |
|||
styleStr += "\t" + property + ': ' + value + ";\n"; |
|||
} |
|||
var result = document.getElementById('result'); |
|||
result.innerHTML = rule.selectorText + " {\n" + styleStr + "}"; |
|||
} |
|||
|
|||
var css = document.getElementById('css-to-parse').innerText; |
|||
CSSOMToString(parse(css)); |
|||
</script> |
|||
``` |
|||
|
|||
### Results |
|||
Here some results (using latest versions + IE11) |
|||
|
|||
<img :src="$withBase('/cssom-result.jpg')"> |
|||
|
|||
As you see, this is what we get for asking only 7 properties, who adds more or less, someone converts colors to rgba functions and someone else changes the order of our values (eg. `box-shadow`). Webkit-based browsers attach also properties they self don't understand |
|||
|
|||
<img :src="$withBase('/cssom-devtools.png')"> |
|||
|
|||
So it's clear that we can't rely on CSSOM objects, that's why we added the possibility to set custom CSS parser via `editor.setCustomParserCss` method or `config.Parser.parserCss` option to use on initialization. Let's see in detail how it's expected to work |
|||
|
|||
## Set CSS parser |
|||
|
|||
The custom parser you have to use it's just a function receiving 2 arguments: `css`, as the CSS string to parse, and `editor`, the instance of the current editor. As the result, you should return an array containing valid rule objects, the syntax of those objects are explained below. This is how you can set the custom parser |
|||
|
|||
```js |
|||
const parserCss = (css, editor) => { |
|||
const result = []; |
|||
// ... parse the CSS string |
|||
result.push({ |
|||
selectors: '.someclass, div .otherclass', |
|||
style: { color: 'red' } |
|||
}) |
|||
// ... |
|||
return result; // Result should be ALWAYS an array |
|||
}; |
|||
|
|||
// On initialization |
|||
// This is the recommended way, as you gonna use the parser from the beginning |
|||
const editor = grapesjs.init({ |
|||
//... |
|||
parser: { |
|||
parserCss, |
|||
} |
|||
}); |
|||
|
|||
// Or later, via editor API |
|||
editor.setCustomParserCss(parserCss); |
|||
``` |
|||
|
|||
## Rule Objects |
|||
|
|||
The syntax of rule objects is pretty straightforward, each object might contain following keys |
|||
|
|||
| Key | Description | Example | |
|||
|-|-|- |
|||
| `selectors` | Selectors of the rule. <br> **REQUIRED** return an empty string in case the rule has no selectors | `.class1, div > #someid` | |
|||
| `style` | Style declarations as an object | `{ color: 'red' }` | |
|||
| `atRule` | At-rule name | `media` | |
|||
| `params` | Parameters of the at-rule | `screen and (min-width: 480px)` | |
|||
|
|||
To make it more clear let's see a few examples |
|||
|
|||
```js |
|||
// Input |
|||
` |
|||
@font-face { |
|||
font-family: "Font Name"; |
|||
src: url("https://font-url.eot"); |
|||
} |
|||
` |
|||
// Output |
|||
[ |
|||
{ |
|||
selectors: '', |
|||
atRule: 'font-face', |
|||
style: { |
|||
'font-family': '"Font Name"', |
|||
src: 'url("https://font-url.eot")', |
|||
}, |
|||
} |
|||
] |
|||
|
|||
// Input |
|||
` |
|||
@keyframes keyframe-name { |
|||
from { opacity: 0; } |
|||
to { opacity: 1; } |
|||
} |
|||
` |
|||
// Output |
|||
[ |
|||
{ |
|||
params: 'keyframe-name', |
|||
selectors: 'from', |
|||
atRule: 'keyframes', |
|||
style: { |
|||
opacity: '0', |
|||
}, |
|||
}, { |
|||
params: 'keyframe-name', |
|||
selectors: 'to', |
|||
atRule: 'keyframes', |
|||
style: { |
|||
opacity: '1', |
|||
}, |
|||
} |
|||
] |
|||
|
|||
// Input |
|||
` |
|||
@media screen and (min-width: 480px) { |
|||
body { |
|||
background-color: lightgreen; |
|||
} |
|||
|
|||
.class-test, .class-test2:hover { |
|||
color: blue !important; |
|||
} |
|||
} |
|||
` |
|||
// Output |
|||
[ |
|||
{ |
|||
params: 'screen and (min-width: 480px)', |
|||
selectors: 'body', |
|||
atRule: 'media', |
|||
style: { |
|||
'background-color': 'lightgreen', |
|||
}, |
|||
}, { |
|||
params: 'screen and (min-width: 480px)', |
|||
selectors: '.class-test, .class-test2:hover', |
|||
atRule: 'media', |
|||
style: { |
|||
color: 'blue !important', |
|||
}, |
|||
} |
|||
] |
|||
|
|||
// Input |
|||
` |
|||
:root { |
|||
--some-color: red; |
|||
--some-width: 55px; |
|||
} |
|||
` |
|||
// Output |
|||
[ |
|||
{ |
|||
selectors: ':root', |
|||
style: { |
|||
'--some-color': 'red', |
|||
'--some-width': '55px', |
|||
}, |
|||
}, |
|||
] |
|||
``` |
|||
|
|||
## Plugins |
|||
|
|||
Below the list of current available CSS parsers as plugins, if you need to create your own we highly suggest to explore their sources |
|||
|
|||
* [grapesjs-parser-postcss](https://github.com/artf/grapesjs-parser-postcss) - Using [PostCSS](https://github.com/postcss/postcss) parser |
|||
@ -0,0 +1,125 @@ |
|||
--- |
|||
title: Replace the built-in Rich Text Editor |
|||
--- |
|||
# Replace the built-in Rich Text Editor |
|||
|
|||
As you might have noticed the default Rich Text Editor (RTE) is really tiny and so doesn't seem like a complete solution as a text editor. Instead of showing how to add new commands inside the default one we'll show how to completely replace it with another one. |
|||
|
|||
In the following guide we'll integrate the CKEditor and to accomplish this task we just need to provide few functions to the GrapesJS API method `setCustomRte` as an interface. |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Interface |
|||
|
|||
### Enable |
|||
|
|||
The first step is to indicate how to enable the third-party library and so for we gonna start with the `enable()` function. This method should take care of the first initialization of our custom RTE but also for the next time is called on the same element, this is why there is the `rte` argument. |
|||
|
|||
```js |
|||
var editor = grapesjs.init({...}); |
|||
editor.setCustomRte({ |
|||
/** |
|||
* Enabling the custom RTE |
|||
* @param {HTMLElement} el This is the HTML node which was selected to be edited |
|||
* @param {Object} rte It's the instance you'd return from the first call of enable(). |
|||
* At the first call it'd be undefined. This is useful when you need |
|||
* to check if the RTE is already enabled on the component |
|||
* @return {Object} The return should be the RTE initialized instance |
|||
*/ |
|||
enable: function(el, rte) { |
|||
// If already exists just focus |
|||
if (rte) { |
|||
this.focus(el, rte); // implemented later |
|||
return rte; |
|||
} |
|||
|
|||
// CKEditor initialization |
|||
rte = CKEDITOR.inline(el, { |
|||
// Your configurations... |
|||
toolbar: [...], |
|||
// IMPORTANT |
|||
// Generally, inline editors are attached exactly at the same position of |
|||
// the selected element but in this case it'd work until you start to scroll |
|||
// the canvas. For this reason you have to move the RTE's toolbar inside the |
|||
// one from GrapesJS. For this purpose we used a plugin which simplify |
|||
// this process and move all next CKEditor's toolbars inside our indicated |
|||
// element |
|||
sharedSpaces: { |
|||
top: editor.RichTextEditor.getToolbarEl(), |
|||
} |
|||
}); |
|||
|
|||
this.focus(el, rte); // implemented later |
|||
return rte; |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
### Disable |
|||
|
|||
Once we know how to enable the RTE let's implement the method which disable it, so let's create the `disable()` function. |
|||
|
|||
```js |
|||
editor.setCustomRte({ |
|||
// ... |
|||
/** |
|||
* The signature of the function is the same of the enable |
|||
*/ |
|||
disable: function(el, rte) { |
|||
el.contentEditable = false; |
|||
if (rte && rte.focusManager) { |
|||
rte.focusManager.blur(true); |
|||
} |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
### Focus |
|||
|
|||
The `focus()` method is just a helper used inside `enable()` and not required by the interface |
|||
|
|||
```js |
|||
editor.setCustomRte({ |
|||
// ... |
|||
focus: function (el, rte) { |
|||
// Do nothing if already focused |
|||
if (rte && rte.focusManager.hasFocus) { |
|||
return; |
|||
} |
|||
el.contentEditable = true; |
|||
rte && rte.focus(); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
## Toolbar position |
|||
|
|||
Sometimes the default top-left position of the toolbar is not always what you need. For example, when you scroll the canvas and the toolbar reaches the top, you'd like to move it down. For this purpose, you can add a listener which applies your logic in this way: |
|||
|
|||
```js |
|||
editor.on('rteToolbarPosUpdate', (pos) => { |
|||
if (pos.top <= pos.canvasTop) { |
|||
pos.top = pos.elementTop + pos.elementHeight; |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
## The built-in vs third-party |
|||
|
|||
The only one thing you have to keep in mind when using a custom RTE is that all the content and its behavior are handled by the library itself, the GrapesJS's component will just store the content as it is. |
|||
For example, when you create a link using the built-in RTE then you'll be able to select it and edit its `href` via Component Settings. With a custom RTE, it will be its own task to show the proper modal for the link editing. |
|||
Obviously, each third-party library has its own APIs and can present some limitations and drawbacks, so, a minimal knowledge of the library is a plus. |
|||
|
|||
|
|||
## Plugins |
|||
|
|||
For the CKEditor, you can find a complete plugin here [grapesjs-plugin-ckeditor](https://github.com/artf/grapesjs-plugin-ckeditor). |
|||
@ -0,0 +1,592 @@ |
|||
--- |
|||
title: Asset Manager |
|||
--- |
|||
|
|||
# Asset Manager |
|||
|
|||
<p align="center"><img src="http://grapesjs.com/img/sc-grapesjs-assets-1.jpg" alt="GrapesJS - Asset Manager" align="center"/></p> |
|||
|
|||
In this section, you will see how to setup and take the full advantage of built-in Asset Manager in GrapesJS. The Asset Manager is lightweight and implements just an `image` in its core, but as you'll see next it's easy to extend and create your own asset types. |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Configuration |
|||
|
|||
To change default configurations you'll have to pass `assetManager` property with the main configuration object |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
... |
|||
assetManager: { |
|||
assets: [...], |
|||
... |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
|
|||
You can update most of them later by using `getConfig` inside of the module |
|||
|
|||
```js |
|||
const amConfig = editor.AssetManager.getConfig(); |
|||
``` |
|||
|
|||
|
|||
Below is a list of currently available options |
|||
|
|||
```js |
|||
// Default assets |
|||
// eg. [ |
|||
// 'https://...image1.png', |
|||
// 'https://...image2.png', |
|||
// {type: 'image', src: 'https://...image3.png', someOtherCustomProp: 1}, |
|||
// .. |
|||
// ] |
|||
assets: [], |
|||
|
|||
// Content to add where there is no assets to show |
|||
// eg. 'No <b>assets</b> here, drag to upload' |
|||
noAssets: '', |
|||
|
|||
// Upload endpoint, set `false` to disable upload |
|||
// upload: 'https://endpoint/upload/assets', |
|||
// upload: false, |
|||
upload: 0, |
|||
|
|||
// The name used in POST to pass uploaded files |
|||
uploadName: 'files', |
|||
|
|||
// Custom headers to pass with the upload request |
|||
headers: {}, |
|||
|
|||
// Custom parameters to pass with the upload request, eg. csrf token |
|||
params: {}, |
|||
|
|||
// The credentials setting for the upload request, eg. 'include', 'omit' |
|||
credentials: 'include', |
|||
|
|||
// Allow uploading multiple files per request. |
|||
// If disabled filename will not have '[]' appended |
|||
multiUpload: true, |
|||
|
|||
// If true, tries to add automatically uploaded assets. |
|||
// To make it work the server should respond with a JSON containing assets |
|||
// in a data key, eg: |
|||
// { |
|||
// data: [ |
|||
// 'https://.../image.png', |
|||
// ... |
|||
// {src: 'https://.../image2.png'}, |
|||
// ... |
|||
// ] |
|||
// } |
|||
autoAdd: 1, |
|||
|
|||
// Text on upload input |
|||
uploadText: 'Drop files here or click to upload', |
|||
|
|||
// Label for the add button |
|||
addBtnText: 'Add image', |
|||
|
|||
// Custom uploadFile function |
|||
// @example |
|||
// uploadFile: (e) => { |
|||
// var files = e.dataTransfer ? e.dataTransfer.files : e.target.files; |
|||
// // ...send somewhere |
|||
// } |
|||
uploadFile: '', |
|||
|
|||
// Handle the image url submit from the built-in 'Add image' form |
|||
// @example |
|||
// handleAdd: (textFromInput) => { |
|||
// // some check... |
|||
// editor.AssetManager.add(textFromInput); |
|||
// } |
|||
handleAdd: '', |
|||
|
|||
// Enable an upload dropzone on the entire editor (not document) when dragging |
|||
// files over it |
|||
dropzone: 1, |
|||
|
|||
// Open the asset manager once files are been dropped via the dropzone |
|||
openAssetsOnDrop: 1, |
|||
|
|||
// Any dropzone content to append inside dropzone element |
|||
dropzoneContent: '', |
|||
|
|||
// Default title for the asset manager modal |
|||
modalTitle: 'Select Image', |
|||
``` |
|||
|
|||
Sometimes the code gets ahead of the docs, therefore we'd suggest to keep an eye at the current state of configurations by checking the dedicated source file [Asset Manager Config](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/config/config.js) |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Initialization |
|||
|
|||
The Asset Manager is ready to work by default, so pass few URLs to see them loaded |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
... |
|||
assetManager: { |
|||
assets: [ |
|||
'http://placehold.it/350x250/78c5d6/fff/image1.jpg', |
|||
// Pass an object with your properties |
|||
{ |
|||
type: 'image', |
|||
src: 'http://placehold.it/350x250/459ba8/fff/image2.jpg', |
|||
height: 350, |
|||
width: 250 |
|||
}, |
|||
{ |
|||
// As the 'image' is the base type of assets, omitting it will |
|||
// be set as `image` by default |
|||
src: 'http://placehold.it/350x250/79c267/fff/image3.jpg', |
|||
height: 350, |
|||
width: 250 |
|||
}, |
|||
], |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
|
|||
If you want a complete list of available properties check out the source [AssetImage Model](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/model/AssetImage.js) |
|||
|
|||
The built-in Asset Manager modal is implemented and is showing up when requested. By default, you can make it appear by dragging Image Components in canvas, double clicking on images and all other stuff related to images (eg. CSS styling) |
|||
|
|||
|
|||
<img :src="$withBase('/assets-builtin-modal.png')"> |
|||
|
|||
|
|||
Making the modal appear is registered with a command, so you can make it appear with this |
|||
|
|||
```js |
|||
// This command shows only assets with `image` type |
|||
editor.runCommand('open-assets'); |
|||
``` |
|||
|
|||
|
|||
Worth nothing that by doing this you can't do much with assets (if you double click on them nothing happens) and this is because you've not indicated any target. Try just to select an image in your canvas and run this in console (you should first make the editor globally available `window.editor = editor;` in your script) |
|||
|
|||
```js |
|||
editor.runCommand('open-assets', { |
|||
target: editor.getSelected() |
|||
}); |
|||
``` |
|||
|
|||
|
|||
Now you should be able to change the image of the component. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Customization |
|||
|
|||
If you want to customize the Asset Manager after the initialization you have to use its [APIs](API-Asset-Manager) |
|||
|
|||
```js |
|||
// Get the Asset Manager module first |
|||
const am = editor.AssetManager; |
|||
``` |
|||
|
|||
First of all, it's worth nothing that Asset Manager keeps 2 collections of assets: |
|||
* **global** - which is just the one with all available assets, you can get it with `am.getAll()` |
|||
* **visible** - this is the collection which is currently rendered by the Asset Manager, you get it with `am.getAllVisible()` |
|||
|
|||
This allows you to decide which assets to show and when. Let's say we'd like to have a category switcher, first of all you gonna add to the **global** collection all your assets (which you may already defined at init by `config.assetManager.assets = [...]`) |
|||
|
|||
```js |
|||
am.add([ |
|||
{ |
|||
// You can pass any custom property you want |
|||
category: 'c1', |
|||
src: 'http://placehold.it/350x250/78c5d6/fff/image1.jpg', |
|||
}, { |
|||
category: 'c1', |
|||
src: 'http://placehold.it/350x250/459ba8/fff/image2.jpg', |
|||
}, { |
|||
category: 'c2', |
|||
src: 'http://placehold.it/350x250/79c267/fff/image3.jpg', |
|||
} |
|||
// ... |
|||
]); |
|||
``` |
|||
|
|||
Now if you call the `render()`, without an argument, you will see all the assets rendered |
|||
|
|||
```js |
|||
// without any argument |
|||
am.render(); |
|||
|
|||
am.getAll().length // <- 3 |
|||
am.getAllVisible().length // <- 3 |
|||
``` |
|||
|
|||
Ok, now let's show only assets form the first category |
|||
|
|||
```js |
|||
const assets = am.getAll(); |
|||
|
|||
am.render(assets.filter( |
|||
asset => asset.get('category') == 'c1' |
|||
)); |
|||
|
|||
am.getAll().length // Still have 3 assets |
|||
am.getAllVisible().length // but only 2 are shown |
|||
``` |
|||
|
|||
You can also mix arrays of assets |
|||
|
|||
```js |
|||
am.render([...assets1, ...assets2, ...assets3]); |
|||
``` |
|||
|
|||
If you want to customize the asset manager container you can get its `HTMLElement` |
|||
|
|||
```js |
|||
am.getContainer().insertAdjacentHTML('afterbegin', '<div><button type="button">Click</button></div>'); |
|||
``` |
|||
|
|||
For more APIs methods check out the [API Reference](API-Asset-Manager) |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
### Define new Asset type |
|||
|
|||
Generally speaking, images aren't the only asset you'll use, it could be a `video`, `svg-icon`, or any other kind of `document`. Each type of asset is applied in our templates/pages differently. If you need to change the image of the Component all you need is another `url` in `src` attribute. However In case of a `svg-icon`, its not the same, you might want to replace the element with a new `<svg>` content. Besides this you also have to deal with the presentation/preview of the asset inside the panel/modal. For example, showing a thumbnail for big images or the possibility to preview videos. |
|||
|
|||
|
|||
Defining a new asset it means we have to push on top of the 'Stack of Types' a new layer. This stack is iterated over by the editor at any addition of the asset and tries to associate the correct type. |
|||
|
|||
```js |
|||
am.add('https://.../image.png'); |
|||
// string, url, ends with '.png' -> it's an 'image' type |
|||
|
|||
am.add('<svg ...'); |
|||
// string and starts with '<svg...' -> 'svg' type |
|||
|
|||
am.add({type: 'video', src: '...'}); |
|||
// an object, has 'video' type key -> 'video' type |
|||
``` |
|||
|
|||
It's up to you tell the editor how to recognize your type and for this purpose you should to use `isType()` method. |
|||
Let's see now an example of how we'd start to defining a type like `svg-icon` |
|||
|
|||
|
|||
```js |
|||
am.addType('svg-icon', { |
|||
// `value` is for example the argument passed in `am.add(VALUE);` |
|||
isType(value) { |
|||
// The condition is intentionally simple |
|||
if (value.substring(0, 5) == '<svg ') { |
|||
return { |
|||
type: 'svg-icon', |
|||
svgContent: value |
|||
}; |
|||
} |
|||
// Maybe you pass the `svg-icon` object already |
|||
else if (typeof value == 'object' && value.type == 'svg-icon') { |
|||
return value; |
|||
} |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
With this snippet you can already add SVGs, the asset manager will assign the appropriate type. |
|||
|
|||
```js |
|||
// Add some random SVG |
|||
am.add(`<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"> |
|||
<path d="M22,9 C22,8.4 21.5,8 20.75,8 L3.25,8 C2.5,8 2,8.4 2,9 L2,15 C2,15.6 2.5,16 3.25,16 L20.75,16 C21.5,16 22,15.6 22,15 L22,9 Z M21,15 L3,15 L3,9 L21,9 L21,15 Z"></path> |
|||
<polygon points="4 10 5 10 5 14 4 14"></polygon> |
|||
</svg>`); |
|||
``` |
|||
|
|||
|
|||
The default `open-assets` command shows only `image` assets, so to render `svg-icon` run this |
|||
|
|||
```js |
|||
am.render(am.getAll().filter( |
|||
asset => asset.get('type') == 'svg-icon' |
|||
)); |
|||
``` |
|||
|
|||
|
|||
You should see something like this |
|||
|
|||
<img :src="$withBase('/assets-empty-view.png')"> |
|||
|
|||
|
|||
The SVG asset is not rendered correctly and this is because we haven't yet configured its view |
|||
|
|||
```js |
|||
am.addType('svg-icon', { |
|||
view: { |
|||
// `getPreview()` and `getInfo()` are just few helpers, you can |
|||
// override the entire template with `template()` |
|||
// Check the base `template()` here: |
|||
// https://github.com/artf/grapesjs/blob/dev/src/asset_manager/view/AssetView.js |
|||
getPreview() { |
|||
return `<div style="text-align: center">${this.model.get('svgContent')}</div>`; |
|||
}, |
|||
getInfo() { |
|||
// You can use model's properties if you passed them: |
|||
// am.add({ |
|||
// type: 'svg-icon', |
|||
// svgContent: '<svg ...', |
|||
// name: 'Some name' |
|||
// }) |
|||
// ... then |
|||
// this.model.get('name'); |
|||
return '<div>SVG description</div>'; |
|||
}, |
|||
}, |
|||
isType(value) {...} |
|||
}) |
|||
``` |
|||
|
|||
|
|||
This is the result |
|||
|
|||
<img :src="$withBase('/assets-svg-view.png')"> |
|||
|
|||
|
|||
Now we have to deal with how to assign our `svgContent` to the selected element |
|||
|
|||
|
|||
```js |
|||
am.addType('svg-icon', { |
|||
view: { |
|||
// In our case the target is the selected component |
|||
updateTarget(target) { |
|||
const svg = this.model.get('svgContent'); |
|||
|
|||
// Just to make things bit interesting, if it's an image type |
|||
// I put the svg as a data uri, content otherwise |
|||
if (target.get('type') == 'image') { |
|||
// Tip: you can also use `data:image/svg+xml;utf8,<svg ...` but you |
|||
// have to escape few chars |
|||
target.set('src', `data:mime/type;base64,${btoa(svg)}`); |
|||
} else { |
|||
target.set('content', svg); |
|||
} |
|||
}, |
|||
... |
|||
}, |
|||
isType(value) {...} |
|||
}) |
|||
``` |
|||
|
|||
|
|||
Our custom `svg-icon` asset is ready to use. You can also add a `model` to the `addType` definition to group the business logic of your asset, but usually it's optional. |
|||
|
|||
|
|||
```js |
|||
// Just an example of model use |
|||
am.addType('svg-icon', { |
|||
model: { |
|||
// With `default` you define model's default properties |
|||
defaults: { |
|||
type: 'svg-icon', |
|||
svgContent: '', |
|||
name: 'Default SVG Name', |
|||
}, |
|||
|
|||
// You can call model's methods inside views: |
|||
// const name = this.model.getName(); |
|||
getName() { |
|||
return this.get('name'); |
|||
} |
|||
}, |
|||
view: {...}, |
|||
isType(value) {...} |
|||
}) |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
### Extend Asset Types |
|||
|
|||
Extending asset types is basically the same as adding them, you can choose what type to extend and how. |
|||
|
|||
```js |
|||
// svgIconType will contain the definition (model, view, isType) |
|||
const svgIconType = am.getType('svg-icon'); |
|||
|
|||
// Add new type and extend another one |
|||
am.addType('svg-icon2', { |
|||
view: svgIconType.view.extend({ |
|||
getInfo() { |
|||
return '<div>SVG2 description</div>'; |
|||
}, |
|||
}), |
|||
// The `isType` is important, but if you omit it the default one will be added |
|||
// isType(value) { |
|||
// if (value && value.type == id) { |
|||
// return {type: value.type}; |
|||
// } |
|||
// }; |
|||
}) |
|||
``` |
|||
|
|||
|
|||
You can also extend the already defined types (to be sure to load assets with the old type extended create a plugin for your definitions) |
|||
|
|||
```js |
|||
// Extend the original `image` and add a confirm dialog before removing it |
|||
am.addType('image', { |
|||
// As you adding on top of an already defined type you can avoid indicating |
|||
// `am.getType('image').view.extend({...` the editor will do it by default |
|||
// but you can eventually extend some other type |
|||
view: { |
|||
// If you want to see more methods to extend check out |
|||
// https://github.com/artf/grapesjs/blob/dev/src/asset_manager/view/AssetImageView.js |
|||
onRemove(e) { |
|||
e.stopPropagation(); |
|||
const model = this.model; |
|||
|
|||
if (confirm('Are you sure?')) { |
|||
model.collection.remove(model); |
|||
} |
|||
} |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Uploading assets |
|||
|
|||
Asset Manager includes an easy to use, drag-and-drop uploader with a few UI helpers. The default uploader is already visible when you open the Asset Manager. |
|||
|
|||
|
|||
<img :src="$withBase('/assets-uploader.png')"> |
|||
|
|||
|
|||
You can click on the uploader to select your files or just drag them directly from your computer to trigger the uploader. Obviously, before it will work you have to setup your server to receive your assets and specify the upload endpoint in your configuration |
|||
|
|||
|
|||
```js |
|||
let editor = grapesjs.init({ |
|||
... |
|||
assetManager: { |
|||
... |
|||
// Upload endpoint, set `false` to disable upload, default `false` |
|||
upload: 'https://endpoint/upload/assets', |
|||
|
|||
// The name used in POST to pass uploaded files, default: `'files'` |
|||
uploadName: 'files', |
|||
... |
|||
}, |
|||
... |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
### Listeners |
|||
|
|||
If you want to execute an action before/after the uploading process (eg. loading animation) or even on response, you can make use of these listeners |
|||
|
|||
```js |
|||
// The upload is started |
|||
editor.on('asset:upload:start', () => { |
|||
... |
|||
startAnimation(); |
|||
}); |
|||
|
|||
// The upload is ended (completed or not) |
|||
editor.on('asset:upload:end', () => { |
|||
... |
|||
endAnimation(); |
|||
}); |
|||
|
|||
// Error handling |
|||
editor.on('asset:upload:error', (err) => { |
|||
... |
|||
notifyError(err); |
|||
}); |
|||
|
|||
// Do something on response |
|||
editor.on('asset:upload:response', (response) => { |
|||
... |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
### Response |
|||
|
|||
When the uploading is over, by default (via config parameter `autoAdd: 1`), the editor expects to receive a JSON blob of uploaded assets in a `data` key as a response and tries to add them to the main collection. The JSON might look like this: |
|||
|
|||
```js |
|||
{ |
|||
data: [ |
|||
'https://.../image.png', |
|||
// ... |
|||
{ |
|||
src: 'https://.../image2.png', |
|||
type: 'image', |
|||
height: 100, |
|||
width: 200, |
|||
}, |
|||
// ... |
|||
] |
|||
} |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
### Setup Dropzone |
|||
|
|||
There is another helper which improves the uploading of assets: A full-width editor dropzone. |
|||
|
|||
<img :src="$withBase('/assets-full-dropzone.gif')"> |
|||
|
|||
|
|||
All you have to do is to activate it and possibly set a custom content (you might also want to hide the default uploader) |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
... |
|||
assetManager: { |
|||
..., |
|||
dropzone: 1, |
|||
dropzoneContent: '<div class="dropzone-inner">Drop here your assets</div>' |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Events |
|||
|
|||
Currently available events you can listen to |
|||
|
|||
* `asset:add` - New asset added |
|||
* `asset:remove` - Asset removed |
|||
* `asset:upload:start` - Before the upload is started |
|||
* `asset:upload:end` - After the upload is ended |
|||
* `asset:upload:error` - On any error in upload, passes the error as an argument |
|||
* `asset:upload:response` - On upload response, passes the result as an argument |
|||
|
|||
@ -0,0 +1,127 @@ |
|||
--- |
|||
title: Block Manager |
|||
--- |
|||
|
|||
# Block Manager |
|||
|
|||
<p align="center"><img src="http://grapesjs.com/img/sc-grapesjs-blocks-prp.jpg" alt="GrapesJS - Block Manager" height="400" align="center"/></p> |
|||
|
|||
[[toc]] |
|||
|
|||
The Block is a group of [Components] and can be easily reused inside templates. |
|||
|
|||
The difference between components and blocks: The component is more atomic, so a single image, a text box or a map is a component. The block is what the end user will drag inside the canvas, so it could contain a single image (single Component) or the entire section like, for example, the footer with a lot of components inside (texts, images, inputs, etc). |
|||
|
|||
Check out the [Components] page to see the list of built-in components and how to create your own. |
|||
|
|||
Let's see how to add a new block to the editor using the [Blocks API] |
|||
|
|||
```js |
|||
var editor = grapesjs.init({...}); |
|||
var blockManager = editor.BlockManager; |
|||
|
|||
// 'my-first-block' is the ID of the block |
|||
blockManager.add('my-first-block', { |
|||
label: 'Simple block', |
|||
content: '<div class="my-block">This is a simple block</div>', |
|||
}); |
|||
``` |
|||
|
|||
With this snippet a new block will be added to the collection. You can also update existent blocks |
|||
|
|||
```js |
|||
blockManager.get('my-first-block').set({ |
|||
label: 'Updated simple block', |
|||
attributes: { |
|||
title: 'My title' |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
As you see a simple HTML string is enough to create a block, the editor will do the rest. |
|||
If you want you could also pass an object representing the [Component]. |
|||
|
|||
```js |
|||
blockManager.add('my-map-block', { |
|||
label: 'Simple map block', |
|||
content: { |
|||
type: 'map', // Built-in 'map' component |
|||
style: { |
|||
height: '350px' |
|||
}, |
|||
removable: false, // Once inserted it can't be removed |
|||
} |
|||
}) |
|||
``` |
|||
|
|||
From v0.3.70 it's also possible to pass the HTML string with Component's properties as attributes. |
|||
|
|||
```js |
|||
blockManager.add('the-row-block', { |
|||
label: '2 Columns', |
|||
content: '<div class="row" data-gjs-droppable=".row-cell" data-gjs-custom-name="Row">' + |
|||
'<div class="row-cell" data-gjs-draggable=".row"></div>' + |
|||
'<div class="row-cell" data-gjs-draggable=".row"></div>' + |
|||
'</div>', |
|||
}); |
|||
``` |
|||
|
|||
In the example above you're defining a row component which will accept only elements which match '.row-cell' selector and cells which could be dragged only inside '.row' elements. We're also defining the custom name which will be seen inside the Layers panel. |
|||
If you want to check the complete list of available Component's properties, check directly the Component model source: |
|||
[https://github.com/artf/grapesjs/blob/dev/src/dom_components/model/Component.js](https://github.com/artf/grapesjs/blob/dev/src/dom_components/model/Component.js) |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Custom render <Badge text="0.14.55+"/> |
|||
|
|||
If you need to customize the aspect of each block you can pass a `render` callback function in the block definition. Let's see how it works. |
|||
|
|||
As a first option, you can return a simple HTML string, which will be used as a new inner content of the block. As an argument of the callback you will get an object containing the following properties: |
|||
|
|||
* `model` - Block's model (so you can use any passed property to it) |
|||
* `el` - Current rendered HTMLElement of the block |
|||
* `className` - The base class name used for blocks (useful if you follow BEM, so you can create classes like `${className}__elem`) |
|||
|
|||
```js |
|||
blockManager.add('some-block-id', { |
|||
label: `<div> |
|||
<img src="https://picsum.photos/70/70"/> |
|||
<div class="my-label-block">Label block</div> |
|||
</div>`, |
|||
content: '<div>...</div>', |
|||
render: ({ model, className }) => `<div class="${className}__my-wrap"> |
|||
Before label |
|||
${model.get('label')} |
|||
After label |
|||
</div>`, |
|||
}); |
|||
``` |
|||
|
|||
<img :src="$withBase('/block-custom-render.jpg')"> |
|||
|
|||
|
|||
Another option would be to avoid returning from the callback (in that case nothing will be replaced) and edit only the current `el` block element |
|||
|
|||
```js |
|||
blockManager.add('some-block-id', { |
|||
// ... |
|||
render: ({ el }) => { |
|||
const btn = document.createElement('button'); |
|||
btn.innerHTML = 'Click me'; |
|||
btn.addEventListener('click', () => alert('Do something')) |
|||
el.appendChild(btn); |
|||
}, |
|||
}); |
|||
``` |
|||
<img :src="$withBase('/block-custom-render2.jpg')"> |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
[Component]: </api/component.html> |
|||
[Components]: <Components.html> |
|||
[Blocks API]: </api/block_manager.html> |
|||
@ -0,0 +1,320 @@ |
|||
--- |
|||
title: Commands |
|||
--- |
|||
|
|||
# Commands |
|||
|
|||
A basic command in GrapesJS it's a simple function, but you will see in this guide how powerful they can be. The main goal of the Command module is to centralize functions and be easily reused across the editor. Another big advantage of using commands is the ability to track them, extend or even interrupt beside some conditions. |
|||
|
|||
::: warning |
|||
This guide is referring to GrapesJS v0.14.61 or higher |
|||
::: |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Basic configuration |
|||
|
|||
You can create your commands already from the initialization step by passing them in the `commands.defaults` options: |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
... |
|||
commands: { |
|||
defaults: [ |
|||
{ |
|||
// id and run are mandatory in this case |
|||
id: 'my-command-id', |
|||
run() { |
|||
alert('This is my command'); |
|||
}, |
|||
}, { |
|||
id: '...', |
|||
// ... |
|||
} |
|||
], |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
For all other available options check directly the [configuration source file](https://github.com/artf/grapesjs/blob/dev/src/commands/config/config.js). |
|||
|
|||
Most commonly commands are created dynamically post-initialization, in that case, you'll need to use the [Commands API](/api/commands.html) (eg. this is what you need if you create a plugin) |
|||
|
|||
```js |
|||
const commands = editor.Commands; |
|||
commands.add('my-command-id', editor => { |
|||
alert('This is my command'); |
|||
}); |
|||
|
|||
// or it would be the same... |
|||
commands.add('my-command-id', { |
|||
run(editor) { |
|||
alert('This is my command'); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
As you see the definition is quite easy, you just add an ID and the callback function. The [Editor](/api/editor.html) instance is passed as the first argument to the callback so you can access any other module or API method. |
|||
|
|||
Now if you want to call that command you should just run this |
|||
|
|||
```js |
|||
editor.runCommand('my-command-id'); |
|||
``` |
|||
|
|||
::: tip |
|||
The method `editor.runCommand` is an alias of `editor.Commands.run` |
|||
::: |
|||
|
|||
You could also pass options if you need |
|||
|
|||
```js |
|||
editor.runCommand('my-command-id', { some: 'option' }); |
|||
``` |
|||
|
|||
Then you can get the same object as a third argument of the callback. |
|||
|
|||
```js |
|||
commands.add('my-command-id', (editor, sender, options = {}) => { |
|||
alert(`This is my command ${options.some}`); |
|||
}); |
|||
``` |
|||
|
|||
The second argument, `sender`, just indicates who requested the command, in our case will be always the `editor` |
|||
|
|||
|
|||
Until now there is nothing exciting except a common entry point for functions, but we'll see later its real advantages. |
|||
|
|||
|
|||
|
|||
|
|||
## Default commands |
|||
|
|||
GrapesJS comes along with some default set of commands and you can get a list of all currently available commands via `editor.Commands.getAll()`. This will give you an object of all available commands, so, also those added later, like via plugins. You can recognize default commands by their namespace `core:*`, we also recommend to use namespaces in your own custom commands, but let's get a look more in detail here: |
|||
|
|||
* [`core:canvas-clear`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/CanvasClear.js) - Clear all the content from the canvas (HTML and CSS) |
|||
* [`core:component-delete`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentDelete.js) - Delete a component |
|||
* [`core:component-enter`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentEnter.js) - Select the first children component of the selected one |
|||
* [`core:component-exit`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentExit.js) - Select the parent component of the current selected one |
|||
* [`core:component-next`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentNext.js) - Select the next sibling component |
|||
* [`core:component-prev`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentPrev.js) - Select the previous sibling component |
|||
* [`core:component-outline`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/SwitchVisibility.js) - Enable outline border on components |
|||
* [`core:component-offset`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ShowOffset.js) - Enable components offset (margins, paddings) |
|||
* [`core:component-select`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/SelectComponent.js) - Enable the process of selecting components in the canvas |
|||
* [`core:copy`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/CopyComponent.js) - Copy the current selected component |
|||
* [`core:paste`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/PasteComponent.js) - Paste copied component |
|||
* [`core:preview`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/Preview.js) - Show the preview of the template in canvas |
|||
* [`core:fullscreen`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/Fullscreen.js) - Set the editor fullscreen |
|||
* [`core:open-code`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ExportTemplate.js) - Open a default panel with the template code |
|||
* [`core:open-layers`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenLayers.js) - Open a default panel with layers |
|||
* [`core:open-styles`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenStyleManager.js) - Open a default panel with the style manager |
|||
* [`core:open-traits`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenTraitManager.js) - Open a default panel with the trait manager |
|||
* [`core:open-blocks`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenBlocks.js) - Open a default panel with the blocks |
|||
* [`core:open-assets`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenAssets.js) - Open a default panel with the assets |
|||
* `core:undo` - Call undo operation |
|||
* `core:redo` - Call redo operation |
|||
<!-- * `core:canvas-move` --> |
|||
<!-- * `core:component-drag` --> |
|||
<!-- * `core:component-style-clear` --> |
|||
<!-- tlb-clone tlb-delete tlb-move --> |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Stateful commands |
|||
|
|||
As we've already seen the command is just a function and once executed nothing is left behind, but in some cases, we'd like to keep a track of executed commands. GrapesJS can handle by default this case and to enable it you just need to declare a command as an object with the `run` and `stop` methods |
|||
|
|||
```js |
|||
commands.add('my-command-state', { |
|||
run(editor) { |
|||
alert('This command is now active'); |
|||
}, |
|||
stop(editor) { |
|||
alert('This command is disabled'); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
So if we now run `editor.runCommand('my-command-state')` the command will be registered as active. To check the state of the command you can use `commands.isActive('my-command-state')` or you can even get the list of all active commands via `commands.getActive()`, in our case the result would be something like this |
|||
|
|||
```js |
|||
{ |
|||
... |
|||
'my-command-state': undefined |
|||
} |
|||
``` |
|||
|
|||
The key of the result object tells you the active command, the value is the last return of the `run` command, in our case is `undefined` because we didn't return anything, but it's up to your implementation decide what to return and if you actually need it. |
|||
|
|||
```js |
|||
// Let's return something |
|||
... |
|||
run(editor) { |
|||
alert('This command is now active'); |
|||
return { |
|||
activated: new Date(), |
|||
} |
|||
}, |
|||
... |
|||
// Now instead of the `undefined` you'll see the object from the run method |
|||
``` |
|||
|
|||
To disable the command use `editor.stopCommand` method, so in our case it'll be `editor.stopCommand('my-command-state')`. As for the `runCommand` you can pass an options object as a second argument and use them in your `stop` method. |
|||
|
|||
Once the command is active, if you try to run `editor.runCommand('my-command-state')` again you'll notice that that the `run` is not triggering. This behavior is useful to prevent executing multiple times the activation process which might lead to an inconsistent state (think about, for instance, having a counter, which should be increased on `run` and decreased on `stop`). If you need to run a command multiple times probably you're dealing with a not stateful command, so try to use it without the `stop` method, but in case you're aware of your application state you can actually force the execution with `editor.runCommand('my-command-state', { force: true })`. The same logic applies to the `stopCommand` method. |
|||
|
|||
<br/> |
|||
|
|||
::: danger WARNING |
|||
|
|||
::: |
|||
|
|||
If you deal with UI in your stateful commands, be careful to keep the state coherent with your logic. Let's take, for example, the use of a modal as an indicator of the command state. |
|||
|
|||
```js |
|||
commands.add('my-command-modal', { |
|||
run(editor) { |
|||
editor.Modal.open({ |
|||
title: 'Modal example', |
|||
content: 'My content', |
|||
}); |
|||
}, |
|||
stop(editor) { |
|||
editor.Modal.close(); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
If you run it, close the modal (eg. by clicking the 'x' on top) and then try to run it again you'll see that the modal is not opening anymore. This happens because the command is still active (you should see it in `commands.getActive()`) and to fix it you have to disable it once the modal is closed. |
|||
|
|||
```js |
|||
... |
|||
run(editor) { |
|||
editor.Modal.open({ |
|||
title: 'Modal example', |
|||
content: 'My content', |
|||
}).onceClose(() => this.stopCommand()); |
|||
}, |
|||
... |
|||
``` |
|||
|
|||
In the example above, we make use of few helper methods from the Modal module (`onceClose`) and the command itself (`stopCommand`) but obviously, the logic might be different due to your requirements and specific UI. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Extending |
|||
|
|||
Another big advantage of commands is the possibility to easily extend or override them with another command. |
|||
Let's take a simple example |
|||
|
|||
```js |
|||
commands.add('my-command-1', editor => { |
|||
alert('This is command 1'); |
|||
}); |
|||
``` |
|||
|
|||
If you need to overwrite this command with another one, just add it and keep the same id. |
|||
|
|||
```js |
|||
commands.add('my-command-1', editor => { |
|||
alert('This is command 1 overwritten'); |
|||
}); |
|||
``` |
|||
|
|||
Let's see now instead how can we extend one |
|||
|
|||
```js |
|||
commands.add('my-command-2', { |
|||
someFunction1() { |
|||
alert('This is function 1'); |
|||
}, |
|||
someFunction2() { |
|||
alert('This is function 2'); |
|||
}, |
|||
run() { |
|||
this.someFunction1(); |
|||
this.someFunction2(); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
to extend it just use `extend` method by passing the id |
|||
|
|||
```js |
|||
commands.extend('my-command-2', { |
|||
someFunction2() { |
|||
alert('This is function 2 extended'); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Events |
|||
|
|||
The Commands module offers also a set of events that you can use to intercept the command flow for adding more functionality or even interrupting it. |
|||
|
|||
|
|||
### Intercept run and stop |
|||
|
|||
By using our previosly created `my-command-modal` command let's see which events we can listen to |
|||
|
|||
```js |
|||
editor.on('run:my-command-modal', () => { |
|||
console.log('After `my-command-modal` execution'); |
|||
// For example, you can add extra content to the modal |
|||
const modalContent = editor.Modal.getContentEl(); |
|||
modalContent.insertAdjacentHTML('beforeEnd', '<div>Some content</div>'); |
|||
}); |
|||
editor.on('run:my-command-modal:before', () => { |
|||
console.log('Before `my-command-modal` execution'); |
|||
}); |
|||
// for stateful commands |
|||
editor.on('stop:my-command-modal', () => { |
|||
console.log('After `my-command-modal` is stopped'); |
|||
}); |
|||
editor.on('stop:my-command-modal:before', () => { |
|||
console.log('Before `my-command-modal` is stopped'); |
|||
}); |
|||
``` |
|||
|
|||
If you need, you can also listen to all commands |
|||
|
|||
```js |
|||
editor.on('run', commandId => { |
|||
console.log('Run', commandId); |
|||
}); |
|||
|
|||
editor.on('stop', commandId => { |
|||
console.log('Stop', commandId); |
|||
}); |
|||
``` |
|||
|
|||
|
|||
### Interrupt command flow |
|||
|
|||
Sometimes you might need to interrupt the execution of an existant command due to some condition. In that case, you have to use `run:{COMMAND-ID}:before` event and set to `true` the abort option |
|||
|
|||
```js |
|||
const condition = 1; |
|||
|
|||
editor.on('run:my-command-modal:before', options => { |
|||
if (condition) { |
|||
options.abort = true; |
|||
console.log('Prevent `my-command-modal` from execution'); |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
|
|||
|
|||
## Conclusion |
|||
|
|||
The Commands module is quite simple but, at the same time, really powerful if used correctly. So, if you're creating a plugin for GrapesJS, use commands as much as possible, this will allow higher reusability and control over your logic. |
|||
@ -0,0 +1,466 @@ |
|||
--- |
|||
title: Component Manager |
|||
--- |
|||
|
|||
# Component Manager |
|||
|
|||
The Component is the base element for template composition. It is atomic, so elements like images, text boxes, maps, etc. fit the definition of a Component. The concept of the component was made to allow the developer to bind different behaviors to different elements. Like for example, opening the Asset Manager on double click of the image. |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Built-in components |
|||
* default (Basic) |
|||
* wrapper |
|||
* text |
|||
* textnode |
|||
* svg |
|||
* script |
|||
* image |
|||
* video |
|||
* label |
|||
* link |
|||
* map |
|||
* table |
|||
* row (for the table) |
|||
* cell (for the table) |
|||
|
|||
|
|||
|
|||
## How Components work? |
|||
|
|||
When we pass an HTML string to the editor like this: |
|||
|
|||
```html |
|||
<div> |
|||
<img src="https://path/image" /> |
|||
<span title="foo">bar</span> |
|||
</div> |
|||
``` |
|||
|
|||
For each DOM element (`div`, `img`, `span`, etc.) the editor will create and store an object representation. Every future change to the template will be made on top of this structure, which will then reflect on the canvas. So each object, usually called *Model* (or state/store), will be the source of truth for the template, but what exactly does that mean? |
|||
|
|||
In more practical example, once the template is rendered on the canvas, if you try to remove one of its elements (eg. by using the browser inspector) and ask the editor to print the HTML (using `editor.getHtml()`) you'll see that the element will still be there. This is because the editor relies on Models and not on the DOM elements inside the canvas. This approach allows us to be extremely flexible on how we generate the final code (from the *Model*) and how to render it inside the canvas (from the *View*). |
|||
|
|||
|
|||
|
|||
# Manage Components |
|||
|
|||
## Component recognition |
|||
|
|||
But now, how does the editor recognize which Component to bind to the `img` element and what to do with the `span` one? |
|||
Each Component inherits, from the base one, a particular static method |
|||
|
|||
```js |
|||
/** |
|||
* @param {HTMLElement} el |
|||
* @return {Object} |
|||
*/ |
|||
isComponent: function(el) { |
|||
... |
|||
} |
|||
``` |
|||
|
|||
This method gives us the possibility to recognize and bind component types to each HTMLElement (div, img, iframe, etc.). Each **HTML string/element** introduced inside the canvas will be processed by `isComponent` of all available types and if it matches, the object represented the type should be returned. The method `isComponent` **is skipped** if you add the component object (`{ type: 'my-custom-type', tagName: 'div', attribute: {...}, ...}`) or declare the type explicitly on the element (`<div data-gjs-type="my-custom-type">...</div>`) |
|||
|
|||
For example, with the image component this method looks like: |
|||
|
|||
```js |
|||
// Image component |
|||
isComponent: function(el) { |
|||
if(el.tagName == 'IMG') |
|||
return {type: 'image'}; |
|||
} |
|||
``` |
|||
|
|||
Let's try with something that might look a little bit tricky. What about a Google Map?!? Google Maps are generally embedded as `iframe`s, but the template can be composed by a lot of different `iframe`s. How can I tell the editor that a particular iframe is actually a Google's Map? Well, you'll have to figure out the right pattern, you have the `HTMLElement` so you can make all the checks you want. In this particular case this pattern is used: |
|||
|
|||
```js |
|||
// Map component |
|||
isComponent: function(el) { |
|||
if(el.tagName == 'IFRAME' && /maps\.google\.com/.test(el.src)) { |
|||
return {type: 'map', src: el.src}; |
|||
} |
|||
}, |
|||
``` |
|||
|
|||
In addition to `tagName` check, we also used the `src` property, but you can actually override it with your own logic by extending the built-in component. |
|||
|
|||
|
|||
|
|||
## Define new Component |
|||
|
|||
Let's see an example with another HTML element that is not handled by default Component types. What about `input` elements? |
|||
|
|||
With the default GrapesJS configuration `input`s are treated like any other element; you can move it around, style it, etc. However, we'd like to handle this type of element more specifically. In this case, we have to create a new Component type. |
|||
|
|||
Let's define few specs for our new *Input* type: |
|||
|
|||
* Can be dropped only inside `form` elements |
|||
* Can't drop other elements inside it |
|||
* Can change the type of the input (text, password, email, etc.) |
|||
* Can make it required for the form |
|||
|
|||
To define a new Component type you need to choose from which built-in Component inherit its properties, in our case we just gonna choose the default one. Let's see a complete example of the new type definition |
|||
|
|||
```js |
|||
// Get DomComponents module |
|||
var comps = editor.DomComponents; |
|||
|
|||
// Get the model and the view from the default Component type |
|||
var defaultType = comps.getType('default'); |
|||
var defaultModel = defaultType.model; |
|||
var defaultView = defaultType.view; |
|||
|
|||
var inputTypes = [ |
|||
{value: 'text', name: 'Text'}, |
|||
{value: 'email', name: 'Email'}, |
|||
{value: 'password', name: 'Password'}, |
|||
{value: 'number', name: 'Number'}, |
|||
]; |
|||
|
|||
// The `input` will be the Component type ID |
|||
comps.addType('input', { |
|||
// Define the Model |
|||
model: defaultModel.extend({ |
|||
// Extend default properties |
|||
defaults: Object.assign({}, defaultModel.prototype.defaults, { |
|||
// Can be dropped only inside `form` elements |
|||
draggable: 'form, form *', |
|||
// Can't drop other elements inside it |
|||
droppable: false, |
|||
// Traits (Settings) |
|||
traits: ['name', 'placeholder', { |
|||
// Change the type of the input (text, password, email, etc.) |
|||
type: 'select', |
|||
label: 'Type', |
|||
name: 'type', |
|||
options: inputTypes, |
|||
},{ |
|||
// Can make it required for the form |
|||
type: 'checkbox', |
|||
label: 'Required', |
|||
name: 'required', |
|||
}], |
|||
}), |
|||
}, |
|||
// The second argument of .extend are static methods and we'll put inside our |
|||
// isComponent() method. As you're putting a new Component type on top of the stack, |
|||
// not declaring isComponent() might probably break stuff, especially if you extend |
|||
// the default one. |
|||
{ |
|||
isComponent: function(el) { |
|||
if(el.tagName == 'INPUT'){ |
|||
return {type: 'input'}; |
|||
} |
|||
}, |
|||
}), |
|||
|
|||
// Define the View |
|||
view: defaultType.view, |
|||
}); |
|||
``` |
|||
|
|||
The code above is pretty much self-explanatory and as you see a lot of work is basically done on top of the Model properties. |
|||
The *View* is just extending the default one, so to cover also this part let's add some random behavior. |
|||
|
|||
```js |
|||
comps.addType('input', { |
|||
model: {...}, |
|||
view: defaultType.view.extend({ |
|||
// Bind events |
|||
events: { |
|||
// If you want to bind the event to children elements |
|||
// 'click .someChildrenClass': 'methodName', |
|||
click: 'handleClick', |
|||
dblclick: function(){ |
|||
alert('Hi!'); |
|||
} |
|||
}, |
|||
|
|||
// It doesn't make too much sense this method inside the component |
|||
// but it's ok as an example |
|||
randomHex: function() { |
|||
return '#' + Math.floor(Math.random()*16777216).toString(16); |
|||
}, |
|||
|
|||
handleClick: function(e) { |
|||
this.model.set('style', {color: this.randomHex()}); // <- Affects the final HTML code |
|||
this.el.style.backgroundColor = this.randomHex(); // <- Doesn't affect the final HTML code |
|||
// Tip: updating the model will reflect the changes to the view, so, in this case, |
|||
// if you put the model change after the DOM one this will override the backgroundColor |
|||
// change made before |
|||
}, |
|||
|
|||
// The render() should return 'this' |
|||
render: function () { |
|||
// Extend the original render method |
|||
defaultType.view.prototype.render.apply(this, arguments); |
|||
this.el.placeholder = 'Text here'; // <- Doesn't affect the final HTML code |
|||
return this; |
|||
}, |
|||
}), |
|||
}); |
|||
``` |
|||
|
|||
From the example above you can notice few interesting things: how to bind events, how to update directly the DOM and how to update the model. The difference between updating the DOM and the model is that the HTML code (the one you get with `editor.getHtml()`) is generated from the *Model* so updating directly the DOM will not affect it, it's just the change for the canvas. |
|||
|
|||
|
|||
|
|||
## Update Component type |
|||
|
|||
Here an example of how easily you can update/override the component |
|||
|
|||
```js |
|||
var originalMap = comps.getType('map'); |
|||
|
|||
comps.addType('map', { |
|||
model: originalMap.model.extend({ |
|||
// Override how the component is rendered to HTML |
|||
toHTML: function() { |
|||
return '<div>My Custom Map</div>'; |
|||
}, |
|||
}, { |
|||
isComponent: function(el) { |
|||
// ... new logic for isComponent |
|||
}, |
|||
}), |
|||
view: originalMap.view |
|||
}); |
|||
``` |
|||
|
|||
## Improvement over addType <Badge text="0.14.50+"/> |
|||
|
|||
Now, with the [0.14.50](https://github.com/artf/grapesjs/releases/tag/v0.14.50) release, defining new components or extending them is a bit easier (without breaking the old process) |
|||
|
|||
* If you don't specify the type to extend, the `default` one will be used. In that case, you just |
|||
use objects for `model` and `view` |
|||
* The `defaults` property, in the `model`, will be merged automatically with defaults of the parent component |
|||
* If you use an object in `model` you can specify `isComponent` outside or omit it. In this case, |
|||
the `isComponent` is not mandatory but without it means the parser won't be able to identify the component |
|||
if not explicitly declared (eg. `<div data-gjs-type="new-component">...</div>`) |
|||
|
|||
**Before** |
|||
```js |
|||
const defaultType = comps.getType('default'); |
|||
|
|||
comps.addType('new-component', { |
|||
model: defaultType.model.extend({ |
|||
defaults: { |
|||
...defaultType.model.prototype.defaults, |
|||
someprop: 'somevalue', |
|||
}, |
|||
... |
|||
}, { |
|||
// Even if it returns false, declaring isComponent is mandatory |
|||
isComponent(el) { |
|||
return false; |
|||
}, |
|||
}), |
|||
view: defaultType.view.extend({ ... }); |
|||
}); |
|||
``` |
|||
|
|||
**After** |
|||
```js |
|||
comps.addType('new-component', { |
|||
// We can even omit isComponent here, as `false` return will be the default behavior |
|||
isComponent: el => false, |
|||
model: { |
|||
defaults: { |
|||
someprop: 'somevalue', |
|||
}, |
|||
... |
|||
}, |
|||
view: { ... }; |
|||
}); |
|||
``` |
|||
* If you need to extend some component, you can use `extend` and `extendView` property. |
|||
* You can now omit `view` property if you don't need to change it |
|||
|
|||
**Before** |
|||
```js |
|||
const originalMap = comps.getType('map'); |
|||
|
|||
comps.addType('map', { |
|||
model: originalMap.model.extend({ |
|||
... |
|||
}, { |
|||
isComponent(el) { |
|||
// ... usually, you'd reuse the same logic |
|||
}, |
|||
}), |
|||
// Even if I do nothing in view, I have to specify it |
|||
view: originalMap.view |
|||
}); |
|||
``` |
|||
**After** |
|||
|
|||
The `map` type is already defined, so it will be used as a base for the model and view. |
|||
We can skip `isComponent` if the recognition logic is the same of the extended component. |
|||
```js |
|||
comps.addType('map', { |
|||
model: { ... }, |
|||
}); |
|||
``` |
|||
Extend the `model` and `view` with some other, already defined, components. |
|||
```js |
|||
comps.addType('map', { |
|||
extend: 'other-defined-component', |
|||
model: { ... }, // Will extend 'other-defined-component' |
|||
view: { ... }, // Will extend 'other-defined-component' |
|||
// `isComponent` will be taken from `map` |
|||
}); |
|||
``` |
|||
```js |
|||
comps.addType('map', { |
|||
extend: 'other-defined-component', |
|||
model: { ... }, // Will extend 'other-defined-component' |
|||
extendView: 'other-defined-component-2', |
|||
view: { ... }, // Will extend 'other-defined-component-2' |
|||
// `isComponent` will be taken from `map` |
|||
}); |
|||
``` |
|||
|
|||
### Extend parent functions <Badge text="0.14.60+"/> |
|||
|
|||
When you need to reuse functions, of the parent you're extending, you can avoid writing something like this in any function: |
|||
```js |
|||
domc.getType('parent-type').model.prototype.init.apply(this, arguments); |
|||
``` |
|||
by using `extendFn` and `extendFnView` arrays: |
|||
```js |
|||
domc.addType('new-type', { |
|||
extend: 'parent-type', |
|||
extendFn: ['init'], // array of model functions to extend |
|||
model: { |
|||
init() { |
|||
// do something; |
|||
}, |
|||
} |
|||
}); |
|||
``` |
|||
The same would be for the view by using `extendFnView` |
|||
|
|||
|
|||
|
|||
## Lifecycle Hooks |
|||
|
|||
Each component triggers different lifecycle hooks, which allows you to add custom actions at their specific stages. |
|||
We can distinguish 2 different types of hooks: **global** and **local**. |
|||
You define **local** hooks when you create/extend a component type (usually via some `model`/`view` method) and the reason is to react to an event of that |
|||
particular component type. Instead, the **global** one, will be called indistinctly on any component (you listen to them via `editor.on`) and you can make |
|||
use of them for a more generic use case or also listen to them inside other components. |
|||
|
|||
Let's see below the flow of all hooks: |
|||
|
|||
* **Local hook**: `model.init()` method, executed once the model of the component is initiliazed |
|||
* **Global hook**: `component:create` event, called right after `model.init()`. The model is passed as an argument to the callback function. |
|||
Es. `editor.on('component:create', model => console.log('created', model))` |
|||
* **Local hook**: `view.init()` method, executed once the view of the component is initiliazed |
|||
* **Local hook**: `view.onRender()` method, executed once the component is rendered on the canvas |
|||
* **Global hook**: `component:mount` event, called right after `view.onRender()`. The model is passed as an argument to the callback function. |
|||
* **Local hook**: `model.updated()` method, executes when some property of the model is updated. |
|||
* **Global hook**: `component:update` event, called after `model.updated()`. The model is passed as an argument to the callback function. |
|||
You can also listen to specific property change via `component:update:{propertyName}` |
|||
* **Local hook**: `model.removed()` method, executed when the component is removed. |
|||
* **Global hook**: `component:remove` event, called after `model.removed()`. The model is passed as an argument to the callback function. |
|||
|
|||
Below you can find an example usage of all the hooks |
|||
|
|||
```js |
|||
editor.DomComponents.addType('test-component', { |
|||
model: { |
|||
defaults: { |
|||
testprop: 1, |
|||
}, |
|||
init() { |
|||
console.log('Local hook: model.init'); |
|||
this.listenTo(this, 'change:testprop', this.handlePropChange); |
|||
// Here we can listen global hooks with editor.on('...') |
|||
}, |
|||
updated(property, value, prevValue) { |
|||
console.log('Local hook: model.updated', |
|||
'property', property, 'value', value, 'prevValue', prevValue); |
|||
}, |
|||
removed() { |
|||
console.log('Local hook: model.removed'); |
|||
}, |
|||
handlePropChange() { |
|||
console.log('The value of testprop', this.get('testprop')); |
|||
} |
|||
}, |
|||
view: { |
|||
init() { |
|||
console.log('Local hook: view.init'); |
|||
}, |
|||
onRender() { |
|||
console.log('Local hook: view.onRender'); |
|||
}, |
|||
}, |
|||
}); |
|||
|
|||
// A block for the custom component |
|||
editor.BlockManager.add('test-component', { |
|||
label: 'Test Component', |
|||
content: '<div data-gjs-type="test-component">Test Component</div>', |
|||
}); |
|||
|
|||
// Global hooks |
|||
editor.on(`component:create`, model => console.log('Global hook: component:create', model.get('type'))); |
|||
editor.on(`component:mount`, model => console.log('Global hook: component:mount', model.get('type'))); |
|||
editor.on(`component:update:testprop`, model => console.log('Global hook: component:update:testprop', model.get('type'))); |
|||
editor.on(`component:remove`, model => console.log('Global hook: component:remove', model.get('type'))); |
|||
``` |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Components & JS |
|||
|
|||
If you want to know how to create Components with javascript attached (eg. counters, galleries, slideshows, etc.) check the dedicated page |
|||
[Components & JS](Components-js.html) |
|||
|
|||
|
|||
|
|||
|
|||
## Hints |
|||
|
|||
```html |
|||
<div id="gjs"> |
|||
... |
|||
<cutom-element></cutom-element> |
|||
... |
|||
</div> |
|||
|
|||
<script> |
|||
var editor = grapesjs.init({ |
|||
container : '#gjs', |
|||
fromElement: true, |
|||
}); |
|||
|
|||
editor.DomComponents.addType('cutom-element-type', {...}); |
|||
</script> |
|||
``` |
|||
|
|||
In the example above the editor will not get the new type from the HTML because the content is already parsed and appended, so it'll get it only with new components (eg. from Blocks) |
|||
|
|||
Solution 1: turn off `autorender` |
|||
|
|||
```html |
|||
<script> |
|||
var editor = grapesjs.init({ |
|||
autorender: 0, |
|||
container : '#gjs', |
|||
fromElement: true, |
|||
}); |
|||
|
|||
editor.DomComponents.addType('cutom-element-type', {...}); |
|||
|
|||
// after all new types |
|||
editor.render(); |
|||
</script> |
|||
``` |
|||
Solution 2: put all the stuff inside a plugin ([Creating plugins](Plugins.html)) |
|||
|
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue