Text Editor - 图1

Text Editor

Framework7 comes with a touch-friendly Rich Text Editor component. It is based on modern “contenteditable” API so it should work everywhere as is.

It comes with the basic set of formatting features. But its functionality can be easily extended and customized to fit any requirements.

Text Editor Layout

1. <div class="text-editor">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

To make editor resizable (when its height will fit to its content), we need to add text-editor-resizable class to editor element:

1. <!-- additional "text-editor-resizable" class -->
2. <div class="text-editor text-editor-resizable">
3. <div class="text-editor-content" contenteditable></div>
4. </div>

Text Editor App Methods

Let’s look at related App methods to work with Text Editor:

app.textEditor.create(parameters)- create Text Editor instance

  • parameters - object. Object with Text Editor parameters

Method returns created Text Editor instance

app.textEditor.destroy(el)- destroy Text Editor instance

  • el - HTMLElement or string (with CSS Selector) or object. Text Editor element or Text Editor instance to destroy.

app.textEditor.get(el)- get Text Editor instance by HTML element

  • el - HTMLElement or string (with CSS Selector). Text Editor element.

Method returns Text Editor’s instance

For example:

1. var textEditor = app.textEditor.create({
2. el: '#my-text-editor',
3. value: <code><p>Hello</p></code>,
4. });

Text Editor Parameters

Let’s look on list of all available Text Editor parameters:

Parameter Type Default Description
el HTMLElement string Text Editor element. HTMLElement or string with CSS selector of editor element
value string Text editor initial html content value. Initial value can also be placed as inner HTML content of text-editor-content element, e.g.: 1. <div class=”text-editor”> 2. <div class=”text-editor-content” contenteditable> 3. <p>Initial HTML value</p> 4. </div> 5. </div>
placeholder string Editor placeholder content displayed when it is empty. By default it is not specified
mode string toolbar Text editor buttons mode. Can be: - toolbar - it will add toolbar with editor buttons in text editor container element - popover - it will show popover bubble with editor buttons on top of the selected text in editor - keyboard-toolbar - toolbar with editor buttons will appear on top of virtual keyboard when editor is in the focus. It is supported only in iOS, Android cordova apps and in Android Chrome. When not supported it will fallback to popover mode.
buttons array Array with editor buttons, or array of arrays (groups) with editor buttons. By default all buttons enabled and its default value is: 1. [ 2. [‘bold’, ‘italic’, ‘underline’, ‘strikeThrough’], 3. [‘orderedList’, ‘unorderedList’], 4. [‘link’, ‘image’], 5. [‘paragraph’, ‘h1’, ‘h2’, ‘h3’], 6. [‘alignLeft’, ‘alignCenter’, ‘alignRight’, ‘alignJustify’], 7. [‘subscript’, ‘superscript’], 8. [‘indent’, ‘outdent’], 9. ]
dividers boolean true Adds visual divider between buttons group
imageUrlText string Insert image URL Prompt text that appears on image url request
linkUrlText string Insert link URL Prompt text that appears on link url request
clearFormattingOnPaste boolean true When enabled it will clear any formatting on paste from clipboard
customButtons object Object with custom buttons. Object property key is the button id that should be used in buttons to enable it. For example to specify custom button that will add <hr> we can use following declaration: 1. var textEditor = app.textEditor.create({ 2. el: ‘.my-text-editor’, 3. customButtons: { 4. // property key is the button id 5. hr: { 6. // button html content 7. content: ‘&lt;hr&gt;’, 8. // button click handler 9. onClick(event, buttonEl) { 10. document.execCommand(‘insertHorizontalRule’, false); 11. } 12. } 13. }, 14. // now we use custom button id “hr” to add it to buttons 15. buttons: [‘bold’, ‘italic’, ‘hr’] 16. })
on object Object with events handlers. For example: 1. var textEditor = app.textEditor.create({ 2. … 3. on: { 4. change: function () { 5. console.log(‘Text Editor value changed’) 6. } 7. } 8. })

Note that all following parameters can be used in global app parameters under textEditor property to set defaults for all text editors. For example:

1. var app = new Framework7({
2. textEditor: {
3. buttons: ['bold', 'italic'],
4. }
5. });

Text Editor Methods & Properties

After we initialize Text Editor we have its initialized instance in variable (like textEditor variable in examples above) with helpful methods and properties:

Properties
textEditor.app Link to global app instance
textEditor.el Text Editor container HTML element
textEditor.$el Dom7 instance with Text Editor container HTML element
textEditor.contentEl Text Editor content (contenteditalbe) HTML element
textEditor.$contentEl Dom7 instance with Text Editor content (contenteditalbe) HTML element
textEditor.value HTML value of the Text Editor
textEditor.params Object with initialization parameters
Methods
textEditor.setValue(value) Set new Text Editor value. value is the HTML string.
textEditor.getValue() Returns current Text Editor value
textEditor.getSelectionRange() Returns current selection Range
textEditor.setSelectionRange(range) Set selection based on passed Range
textEditor.destroy() Destroy Text Editor instance and remove all events
textEditor.on(event, handler) Add event handler
textEditor.once(event, handler) Add event handler that will be removed after it was fired
textEditor.off(event, handler) Remove event handler
textEditor.off(event) Remove all handlers for specified event
textEditor.emit(event, …args) Fire event on instance

Text Editor Events

Text Editor will fire the following DOM events on text editor element and events on app andtext editor instance:

DOM Events

Event Description
texteditor:init Event will be triggered when on editor initialization
texteditor:change Event will be triggered when editor value has been changed
texteditor:input Event will be triggered on editor’s content “input” event
texteditor:focus Event will be triggered on editor’s content focus
texteditor:blur Event will be triggered on editor’s content blur
texteditor:buttonclick Event will be triggered on editor button click
texteditor:keyboardopen Event will be triggered when editor keyboard toolbar appears
texteditor:keyboardclose Event will be triggered when editor keyboard toolbar disappears
texteditor:popoveropen Event will be triggered on editor popover open
texteditor:popoverclose Event will be triggered on editor popover close
texteditor:beforedestroy Event will be triggered right before Text Editor instance will be destroyed

App and Text Editor Instance Events

Text Editor instance emits events on both self instance and app instance. App instance events has same names prefixed with textEditor.

Event Target Arguments Description
init textEditor (editor) Event will be triggered when on editor initialization.
textEditorInit app
change textEditor (editor) Event will be triggered when on editor initialization.
textEditorChange app
input textEditor (editor) Event will be triggered on editor’s content “input” event.
textEditorInput app
focus textEditor (editor) Event will be triggered on editor’s content focus.
textEditorFocus app
blur textEditor (editor) Event will be triggered on editor’s content blur.
textEditorBlur app
buttonClick textEditor (editor, button) Event will be triggered on editor button click. As second argument event handler receives id of the clicked button, e.g. bold
textEditorButtonClick app
keyboardOpen textEditor (editor) Event will be triggered when editor keyboard toolbar appears.
textEditorKeyboardOpen app
keyboardClose textEditor (editor) Event will be triggered when editor keyboard toolbar disappears.
textEditorKeyboardClose app
popoverOpen textEditor (editor) Event will be triggered on editor popover open.
textEditorPopoverOpen app
popoverClose textEditor (editor) Event will be triggered on editor popover close.
textEditorPopoverClose app
beforeDestroy textEditor (editor) Event will be triggered right before Text Editor instance will be destroyed.
textEditorBeforeDestroy app

Text Editor Auto Initialization

If you don’t need to use Text Editor API and your Text Editor is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional text-editor-init class:

1. <!-- Add text-editor-init class -->
2. <div class="text-editor text-editor-init">
3. <div class="text-editor-content" contenteditable></div>
4. </div>

In this case if you need to access created Text Editor instance you can use the app.textEditor.get app method:

1. var textEditor = app.textEditor.get('.my-text-editor');

3. if (!textEditor.value) {
4. // do something
5. }

When using auto init you may need to pass additional parameters. It can be done with data- attributes on panel element.

1. <!-- parameters set via data- attributes -->
2. <div
3. class="text-editor text-editor-init"
4. data-mode="popover"
5. data-placeholder="Description"
6. >
7. ...
8. </div>

Parameters used in camelCase, for example imageUrlText, in data- attributes should be used in kebab-case as data-image-url-text

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

1. :root {
2. --f7-text-editor-font-size: inherit;
3. --f7-text-editor-font-weight: inherit;
4. --f7-text-editor-border-width: 1px;
5. --f7-text-editor-height: 250px;
6. --f7-text-editor-margin: 16px;
7. --f7-text-editor-padding: 8px;
8. --f7-text-editor-button-bg-color: transparent;
9. --f7-text-editor-button-size: 28px;
10. --f7-text-editor-button-icon-size: 20px;
11. --f7-text-editor-button-margin: 2px;
12. --f7-text-editor-button-border-radius: 2px;
13. --f7-text-editor-text-color: #000;
14. --f7-text-editor-bg-color: #fff;
15. --f7-text-editor-border-color: rgba(0, 0, 0, 0.1);
16. --f7-text-editor-toolbar-bg-color: #fff;
17. --f7-text-editor-button-text-color: #333;
18. --f7-text-editor-button-divider-color: rgba(0, 0, 0, 0.15);
19. --f7-text-editor-placeholder-color: rgba(0, 0, 0, 0.35);
20. }
21. :root .theme-dark,
22. :root.theme-dark {
23. --f7-text-editor-bg-color: #121212;
24. --f7-text-editor-border-color: rgba(255, 255, 255, 0.1);
25. --f7-text-editor-toolbar-bg-color: #202020;
26. --f7-text-editor-text-color: #fff;
27. --f7-text-editor-placeholder-color: rgba(255, 255, 255, 0.35);
28. --f7-text-editor-button-text-color: #fff;
29. --f7-text-editor-button-divider-color: rgba(255, 255, 255, 0.15);
30. }
31. .ios {
32. --f7-text-editor-toolbar-padding: 6px;
33. --f7-text-editor-toolbar-border-color: rgba(0, 0, 0, 0.25);
34. }
35. .ios .theme-dark,
36. .ios.theme-dark {
37. --f7-text-editor-toolbar-bg-color: #121212;
38. --f7-text-editor-toolbar-border-color: rgba(255, 255, 255, 0.1);
39. }
40. .md {
41. --f7-text-editor-toolbar-padding: 8px;
42. --f7-text-editor-toolbar-box-shadow: 0px 2px 3px -1px rgba(0, 0, 0, 0.25);
43. }
44. .aurora {
45. --f7-text-editor-toolbar-padding: 3px;
46. --f7-text-editor-toolbar-border-color: rgba(0, 0, 0, 0.25);
47. }
48. .aurora .theme-dark,
49. .aurora.theme-dark {
50. --f7-text-editor-toolbar-border-color: rgba(255, 255, 255, 0.1);
51. }

Examples

Default Setup

1. <div class="text-editor text-editor-init">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

With Placeholder

1. <div class="text-editor text-editor-init" data-placeholder="Enter text...">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

With Default Value

1. <div class="text-editor text-editor-init" data-placeholder="Enter text...">
2. <div class="text-editor-content" contenteditable>
3. <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Consequatur sunt, ...</p>
4. </div>
5. </div>

Specific Buttons

1. <div class="text-editor text-editor-init" data-placeholder="Enter text..." data-buttons='[["bold", "italic", "underline", "strikeThrough"], ["orderedList", "unorderedList"]]'>
2. <div class="text-editor-content" contenteditable></div>
3. </div>

Custom Button

1. <div class="text-editor text-editor-custom-buttons">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

1. var textEditorCustomButtons = app.textEditor.create({
2. el: '.text-editor-custom-buttons',
3. // define custom "hr" button
4. customButtons: {
5. hr: {
6. content: '&lt;hr&gt;',
7. onClick(editor, buttonEl) {
8. document.execCommand('insertHorizontalRule', false);
9. },
10. },
11. },
12. buttons: [["bold", "italic", "underline", "strikeThrough"], "hr"],
13. });

Resizable

1. <div class="text-editor text-editor-init text-editor-resizable" data-placeholder="Enter text..." data-buttons='["bold", "italic", "underline", "strikeThrough"]'>
2. <div class="text-editor-content" contenteditable></div>
3. </div>

Popover Mode

1. <div class="text-editor text-editor-init" data-placeholder="Enter text..." data-buttons='["bold", "italic", "underline", "strikeThrough"]' data-mode="popover" style="--f7-text-editor-height: 150px">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

Keyboard Toolbar Mode

1. <div class="text-editor text-editor-init" data-placeholder="Enter text..." data-mode="keyboard-toolbar" style="--f7-text-editor-height: 150px">
2. <div class="text-editor-content" contenteditable></div>
3. </div>

As List Input

1. <div class="list">
2. <ul>
3. <li class="item-content item-input">
4. <div class="item-media">
5. <i class="icon demo-list-icon"></i>
6. </div>
7. <div class="item-inner">
8. <div class="item-title item-label">Name</div>
9. <div class="item-input-wrap">
10. <input type="text" placeholder="Your name">
11. </div>
12. </div>
13. </li>
14. <li class="item-content item-input">
15. <div class="item-media">
16. <i class="icon demo-list-icon"></i>
17. </div>
18. <div class="item-inner">
19. <div class="item-title item-label">About</div>
20. <div class="item-input-wrap">
21. <div class="text-editor text-editor-init text-editor-resizable" data-placeholder="About" data-buttons='["bold", "italic", "underline", "strikeThrough"]' data-mode="popover">
22. <div class="text-editor-content" contenteditable></div>
23. </div>
24. </div>
25. </div>
26. </li>
27. </ul>
28. </div>

← Tabs

Timeline →