Construa um plugin de newsletter para CKEditor 5

# NewsletterPlugin for CKEditor 5 ## Architecture Overview This plugin migrates a legacy CKEditor 4 newsletter plugin to CKEditor 5 architecture. The key differences: - **CKEditor 4**: Direct DOM manipulation, jQuery-style event handling, HTML string injection - **CKEditor 5**: Model-view-controller architecture, schema-based content model, widget API, command pattern ## Plugin Structure ``` newsletter/ ├── newsletterplugin.ts # Main plugin entry point ├── newsletterediting.ts # Editing engine integration ├── newsletterui.ts # UI components (button, dialog) └── newslettercommand.ts # Command for inserting/updating newsletter ``` ## Complete Plugin Code ### newsletterplugin.ts ```typescript /** * @module newsletter/newsletterplugin */ import { Plugin, type Editor } from 'ckeditor5'; import NewsletterEditing from './newsletterediting'; import NewsletterUI from './newsletterui'; /** * The newsletter plugin. * * This is the main plugin class that orchestrates the editing and UI parts. */ export default class NewsletterPlugin extends Plugin { public static get pluginName(): string { return 'NewsletterPlugin'; } public static get requires(): Array { return [ NewsletterEditing, NewsletterUI ]; } /** * Initialize the plugin. */ public init(): void { const editor = this.editor; // Log plugin initialization console.log('NewsletterPlugin was initialized'); } } ``` ### newsletterediting.ts ```typescript /** * @module newsletter/newsletterediting */ import { Plugin, type Editor } from 'ckeditor5'; import { toWidget, toWidgetEditable } from 'ckeditor5/src/widget'; import { Widget } from 'ckeditor5/src/widget'; import NewsletterCommand from './newslettercommand'; /** * The newsletter editing feature. * * Handles the model-view conversion and widget behavior. */ export default class NewsletterEditing extends Plugin { public static get pluginName(): string { return 'NewsletterEditing'; } public static get requires(): Array { return [ Widget ]; } /** * Initialize the editing feature. */ public init(): void { this._defineSchema(); this._defineConverters(); this._defineCommands(); this._defineEventHandlers(); } /** * Define the schema for the newsletter block. */ private _defineSchema(): void { const schema = this.editor.model.schema; // Register the newsletterBlock element schema.register('newsletterBlock', { isObject: true, allowWhere: '$block', allowContentOf: '$root', allowAttributes: ['class', 'id', 'data-newsletter'], isSelectable: true }); // Allow newsletterBlock in root schema.extend('$root', { allowIn: ['newsletterBlock'] }); // Allow paragraphs and other content inside newsletterBlock schema.extend('$block', { allowIn: ['newsletterBlock'] }); // Allow specific attributes on elements inside newsletter schema.addAttributeCheck((context, attributeName) => { // Allow class and id attributes on elements within newsletterBlock if (context.endsWith('newsletterBlock') && ['class', 'id', 'href'].includes(attributeName)) { return true; } }); } /** * Define converters for upcast and downcast. */ private _defineConverters(): void { const editor = this.editor; const conversion = editor.conversion; // Upcast: HTML to model conversion.for('upcast').elementToElement({ view: { name: 'div', classes: 'newsletter' }, model: (viewElement, { writer }) => { return writer.createElement('newsletterBlock', { class: 'newsletter', 'data-newsletter': 'true' }); } }); // Downcast: Model to HTML conversion.for('downcast').elementToElement({ model: 'newsletterBlock', view: (modelElement, { writer }) => { const div = writer.createContainerElement('div', { class: 'newsletter', 'data-newsletter': 'true' }); // Convert to widget return toWidget(div, writer, { label: 'Newsletter block' }); } }); // Upcast: Tab list conversion.for('upcast').elementToElement({ view: { name: 'ul', classes: 'newsletter-tabs' }, model: (viewElement, { writer }) => { return writer.createElement('newsletterTabs', { class: 'newsletter-tabs' }); } }); // Downcast: Tab list conversion.for('downcast').elementToElement({ model: 'newsletterTabs', view: (modelElement, { writer }) => { return writer.createContainerElement('ul', { class: 'newsletter-tabs' }); } }); // Upcast: Tab item conversion.for('upcast').elementToElement({ view: { name: 'li', classes: 'newsletter-tab' }, model: (viewElement, { writer }) => { return writer.createElement('newsletterTab', { class: 'newsletter-tab' }); } }); // Downcast: Tab item conversion.for('downcast').elementToElement({ model: 'newsletterTab', view: (modelElement, { writer }) => { return writer.createContainerElement('li', { class: 'newsletter-tab' }); } }); // Upcast: Tab link conversion.for('upcast').elementToElement({ view: { name: 'a', attributes: { href: /^#tab-/ } }, model: (viewElement, { writer }) => { return writer.createElement('newsletterTabLink', { href: viewElement.getAttribute('href'), class: viewElement.getAttribute('class') }); } }); // Downcast: Tab link conversion.for('downcast').elementToElement({ model: 'newsletterTabLink', view: (modelElement, { writer }) => { const link = writer.createContainerElement('a', { href: modelElement.getAttribute('href'), class: modelElement.getAttribute('class') }); // Make the link widget-editable return toWidgetEditable(link, writer); } }); // Upcast: Tab content conversion.for('upcast').elementToElement({ view: { name: 'div', classes: 'tab-pane' }, model: (viewElement, { writer }) => { return writer.createElement('newsletterTabContent', { class: viewElement.getAttribute('class'), id: viewElement.getAttribute('id') }); } }); // Downcast: Tab content conversion.for('downcast').elementToElement({ model: 'newsletterTabContent', view: (modelElement, { writer }) => { return writer.createContainerElement('div', { class: modelElement.getAttribute('class'), id: modelElement.getAttribute('id') }); } }); // Attribute conversions conversion.for('upcast').attributeToAttribute({ view: { name: 'div', classes: 'newsletter' }, model: { key: 'class', value: (viewElement) => viewElement.getAttribute('class') } }); conversion.for('downcast').attributeToAttribute({ model: 'class', view: 'class' }); } /** * Define commands. */ private _defineCommands(): void { const editor = this.editor; editor.commands.add('newsletter', new NewsletterCommand(editor)); } /** * Define event handlers for click and double-click. */ private _defineEventHandlers(): void { const editor = this.editor; const viewDocument = editor.editing.view.document; // Handle single click on tab links viewDocument.on('click', (eventInfo, domEventData) => { const target = domEventData.target; // Check if clicked element is a tab link if (target && target.hasClass('newsletter-tab-link')) { eventInfo.stop(); this._handleTabClick(target); } }); // Handle double-click on newsletter block viewDocument.on('dblclick', (eventInfo, domEventData) => { const target = domEventData.target; // Find the newsletter block ancestor const newsletterBlock = target.findAncestor('newsletterBlock'); if (newsletterBlock) { eventInfo.stop(); this._handleNewsletterDoubleClick(newsletterBlock); } }); } /** * Handle tab click - switch active tab. */ private _handleTabClick(tabLink: any): void { const editor = this.editor; const model = editor.model; model.change((writer) => { // Get the tab link model element const modelTabLink = editor.editing.mapper.toModelElement(tabLink); if (!modelTabLink) { return; } // Get parent tab item const tabItem = modelTabLink.parent; const tabsList = tabItem.parent; const newsletterBlock = tabsList.parent; // Find all tab links and tab contents const tabLinks = []; const tabContents = []; // Iterate through tabs list children for (const child of tabsList.getChildren()) { if (child.name === 'newsletterTab') { const link = child.getChild(0); if (link) { tabLinks.push(link); } } } // Find tab contents in newsletter block const contentDiv = newsletterBlock.getChild(1); if (contentDiv) { for (const child of contentDiv.getChildren()) { if (child.name === 'newsletterTabContent') { tabContents.push(child); } } } // Remove active class from all tabs for (const link of tabLinks) { const classes = link.getAttribute('class') || ''; const newClasses = classes.replace(/\bactive\b/g, '').trim(); writer.setAttribute('class', newClasses, link); } // Remove active class from all contents for (const content of tabContents) { const classes = content.getAttribute('class') || ''; const newClasses = classes.replace(/\bactive\b/g, '').trim(); writer.setAttribute('class', newClasses, content); } // Add active class to clicked tab const clickedClasses = modelTabLink.getAttribute('class') || ''; writer.setAttribute('class', `${clickedClasses} active`.trim(), modelTabLink); // Add active class to corresponding content const href = modelTabLink.getAttribute('href'); const targetId = href.replace('#', ''); for (const content of tabContents) { if (content.getAttribute('id') === targetId) { const contentClasses = content.getAttribute('class') || ''; writer.setAttribute('class', `${contentClasses} active`.trim(), content); } } }); } /** * Handle double-click on newsletter block - open dialog for editing. */ private _handleNewsletterDoubleClick(newsletterBlock: any): void { const editor = this.editor; // Extract data from the newsletter block const data = this._extractNewsletterData(newsletterBlock); // Execute command with data to open dialog editor.execute('newsletter', { ...data, isEdit: true }); } /** * Extract data from newsletter block for editing. */ private _extractNewsletterData(newsletterBlock: any): any { const data = { title: '', description: '', tabs: [] }; // Find title and description const children = Array.from(newsletterBlock.getChildren()); // Look for title and description elements for (const child of children) { if (child.name === 'paragraph') { // Check if it's title or description based on position if (!data.title) { data.title = this._getTextContent(child); } else if (!data.description) { data.description = this._getTextContent(child); } } } // Find tabs const tabsList = children.find((child: any) => child.name === 'newsletterTabs'); const contentDiv = children.find((child: any) => child.name === 'newsletterTabContent'); if (tabsList) { for (const tab of tabsList.getChildren()) { if (tab.name === 'newsletterTab') { const link = tab.getChild(0); const tabData = { tabTitle: '', tabContent: '' }; if (link) { tabData.tabTitle = this._getTextContent(link); } data.tabs.push(tabData); } } } // Extract tab contents if (contentDiv) { const tabContents = Array.from(contentDiv.getChildren()) .filter((child: any) => child.name === 'newsletterTabContent'); for (let i = 0; i < tabContents.length; i++) { if (data.tabs[i]) { data.tabs[i].tabContent = this._getHTMLContent(tabContents[i]); } } } return data; } /** * Get text content from a model element. */ private _getTextContent(element: any): string { let text = ''; for (const child of element.getChildren()) { if (child.is('text')) { text += child.data; } else if (child.is('element')) { text += this._getTextContent(child); } } return text; } /** * Get HTML content from a model element. */ private _getHTMLContent(element: any): string { const editor = this.editor; const viewElement = editor.editing.mapper.toViewElement(element); if (viewElement) { return editor.editing.view.domConverter.viewToDom(viewElement).innerHTML; } return ''; } } ``` ### newsletterui.ts ```typescript /** * @module newsletter/newsletterui */ import { Plugin, type Editor } from 'ckeditor5'; import { ButtonView, View, InputTextView, LabeledFieldView, createLabeledInputText, createLabeledTextarea, ViewCollection } from 'ckeditor5/src/ui'; import { icons } from 'ckeditor5/src/core'; /** * The newsletter UI feature. * * Handles the toolbar button and dialog. */ export default class NewsletterUI extends Plugin { public static get pluginName(): string { return 'NewsletterUI'; } /** * Initialize the UI feature. */ public init(): void { const editor = this.editor; // Register the toolbar button editor.ui.componentFactory.add('newsletter', (locale) => { const button = new ButtonView(locale); button.set({ label: 'Newsletter', icon: icons.newsletter, tooltip: true }); // Execute command on click this.listenTo(button, 'execute', () => { editor.execute('newsletter'); }); return button; }); // Listen for command execution to open dialog const command = editor.commands.get('newsletter'); if (command) { this.listenTo(command, 'execute', (eventInfo, args) => { this._showDialog(args); }); } } /** * Show the newsletter dialog. */ private _showDialog(data: any = {}): void { const editor = this.editor; const t = editor.t; // Create dialog view const dialog = new View(); // Create form elements const titleInput = new LabeledFieldView(editor.locale, createLabeledInputText); titleInput.label = t('Newsletter Title'); titleInput.fieldView.value = data.title || ''; const descriptionInput = new LabeledFieldView(editor.locale, createLabeledTextarea); descriptionInput.label = t('Newsletter Description'); descriptionInput.fieldView.value = data.description || ''; // Create tabs container const tabsContainer = new ViewCollection(); const tabsView = new View(); tabsView.setTemplate({ tag: 'div', attributes: { class: 'newsletter-tabs-editor' }, children: tabsContainer }); // Add tab button const addTabButton = new ButtonView(editor.locale); addTabButton.set({ label: t('Add Tab'), withText: true, class: 'ck-button-action' }); addTabButton.on('execute', () => { this._addTabRow(tabsContainer, {}); }); // Create dialog content const dialogContent = new View(); dialogContent.setTemplate({ tag: 'div', attributes: { class: 'newsletter-dialog' }, children: [ titleInput, descriptionInput, tabsView, addTabButton ] }); // Create dialog buttons const cancelButton = new ButtonView(editor.locale); cancelButton.set({ label: t('Cancel'), withText: true, class: 'ck-button-cancel' }); const okButton = new ButtonView(editor.locale); okButton.set({ label: t('OK'), withText: true, class: 'ck-button-action' }); // Create dialog const dialogView = new View(editor.locale); dialogView.setTemplate({ tag: 'div', attributes: { class: 'ck-dialog' }, children: [ dialogContent, new ViewCollection([cancelButton, okButton]) ] }); // Add existing tabs if editing if (data.tabs && data.tabs.length > 0) { data.tabs.forEach((tab: any) => { this._addTabRow(tabsContainer, tab); }); } else { // Add default empty tab this._addTabRow(tabsContainer, {}); } // Handle OK button okButton.on('execute', () => { const formData = this._collectFormData(titleInput, descriptionInput, tabsContainer); this._insertNewsletter(formData, data.isEdit); dialogView.element?.remove(); }); // Handle Cancel button cancelButton.on('execute', () => { dialogView.element?.remove(); }); // Append dialog to body document.body.appendChild(dialogView.element!); } /** * Add a tab row to the tabs container. */ private _addTabRow(container: ViewCollection, tabData: any): void { const editor = this.editor; const t = editor.t; const tabRow = new View(); // Tab title input const tabTitleInput = new LabeledFieldView(editor.locale, createLabeledInputText); tabTitleInput.label = t('Tab Title'); tabTitleInput.fieldView.value = tabData.tabTitle || ''; // Tab content textarea const tabContentInput = new LabeledFieldView(editor.locale, createLabeledTextarea); tabContentInput.label = t('Tab Content'); tabContentInput.fieldView.value = tabData.tabContent || ''; // Remove button const removeButton = new ButtonView(editor.locale); removeButton.set({ label: t('Remove Tab'), withText: true, class: 'ck-button-remove' }); removeButton.on('execute', () => { tabRow.element?.remove(); }); // Create tab row template tabRow.setTemplate({ tag: 'div', attributes: { class: 'newsletter-tab-row' }, children: [ tabTitleInput, tabContentInput, removeButton ] }); container.add(tabRow); } /** * Collect form data from dialog. */ private _collectFormData(titleInput: any, descriptionInput: any, tabsContainer: ViewCollection): any { const tabs = []; // Iterate through tab rows for (const tabRow of tabsContainer) { const inputs = tabRow.element?.querySelectorAll('input, textarea'); if (inputs && inputs.length >= 2) { tabs.push({ tabTitle: inputs[0].value, tabContent: inputs[1].value }); } } return { title: titleInput.fieldView.value, description: descriptionInput.fieldView.value, tabs: tabs }; } /** * Insert newsletter into editor. */ private _insertNewsletter(data: any, isEdit: boolean): void { const editor = this.editor; if (isEdit) { // Update existing newsletter editor.execute('newsletter', { ...data, isEdit: true }); } else { // Insert new newsletter editor.execute('newsletter', data); } } } ``` ### newslettercommand.ts ```typescript /** * @module newsletter/newslettercommand */ import { Command, type Editor } from 'ckeditor5'; /** * The newsletter command. * * Inserts or updates a newsletter block in the editor. */ export default class NewsletterCommand extends Command { /** * Execute the command. */ public execute(options: any = {}): void { const editor = this.editor; const model = editor.model; model.change((writer) => { if (options.isEdit) { // Find existing newsletter block const selection = model.document.selection; const selectedElement = selection.getSelectedElement(); if (selectedElement && selectedElement.name === 'newsletterBlock') { this._updateNewsletter(writer, selectedElement, options); } } else { // Insert new newsletter block this._insertNewsletter(writer, options); } }); } /** * Insert a new newsletter block. */ private _insertNewsletter(writer: any, data: any): void { const editor = this.editor; // Create newsletter block const newsletterBlock = writer.createElement('newsletterBlock', { class: 'newsletter', 'data-newsletter': 'true' }); // Add title if provided if (data.title) { const titleParagraph = writer.createElement('paragraph'); writer.appendText(data.title, titleParagraph); writer.append(titleParagraph, newsletterBlock); } // Add description if provided if (data.description) { const descParagraph = writer.createElement('paragraph'); writer.appendText(data.description, descParagraph); writer.append(descParagraph, newsletterBlock); } // Create tabs list const tabsList = writer.createElement('newsletterTabs', { class: 'newsletter-tabs' }); // Create tab contents container const contentDiv = writer.createElement('newsletterTabContent', { class: 'newsletter-content' }); // Add tabs data.tabs.forEach((tab: any, index: number) => { const tabItem = writer.createElement('newsletterTab', { class: index === 0 ? 'newsletter-tab active' : 'newsletter-tab' }); const tabLink = writer.createElement('newsletterTabLink', { href: `#tab-${index + 1}`, class: index === 0 ? 'active' : '' }); writer.appendText(tab.tabTitle || `Tab ${index + 1}`, tabLink); writer.append(tabLink, tabItem); writer.append(tabItem, tabsList); // Create tab content const tabContent = writer.createElement('newsletterTabContent', { id: `tab-${index + 1}`, class: index === 0 ? 'tab-pane active' : 'tab-pane' }); // Parse HTML content const parsedContent = this._parseHTMLContent(tab.tabContent || ''); // Add content to tab if (parsedContent) { writer.append(parsedContent, tabContent); } writer.append(tabContent, contentDiv); }); // Append tabs list and content to newsletter block writer.append(tabsList, newsletterBlock); writer.append(contentDiv, newsletterBlock); // Insert newsletter block at current position editor.model.insertContent(newsletterBlock); } /** * Update an existing newsletter block. */ private _updateNewsletter(writer: any, newsletterBlock: any, data: any): void { // Remove existing children const children = Array.from(newsletterBlock.getChildren()); for (const child of children) { writer.remove(child); } // Re-insert with new data this._insertNewsletter(writer, data); } /** * Parse HTML content string to model elements. */ private _parseHTMLContent(html: string): any { const editor = this.editor; // Create a temporary div to parse HTML const tempDiv = document.createElement('div'); tempDiv.innerHTML = html; // Convert HTML to view elements const viewFragment = editor.editing.view.domConverter.domToView(tempDiv); // Convert view to model const modelFragment = editor.data.processor.toModel(viewFragment); return modelFragment; } } ``` ## Configuration ### Editor Configuration ```typescript // editor-config.ts import NewsletterPlugin from './newsletter/newsletterplugin'; const editorConfig = { plugins: [ NewsletterPlugin, ... ], // Enable General HTML Support htmlSupport: { allow: [ { name: 'div', classes: ['newsletter', 'newsletter-tabs', 'newsletter-content', 'tab-pane', 'active'], attributes: ['id', 'data-newsletter'] }, { name: 'ul', classes: ['newsletter-tabs'] }, { name: 'li', classes: ['newsletter-tab', 'active'] }, { name: 'a', classes: ['active'], attributes: ['href'] }, { name: 'span', classes: ['newsletter-title', 'newsletter-description'] } ] }, toolbar: { items: [ 'newsletter', // ... other toolbar items ] } }; ``` ### Plugin Registration ```typescript // main.ts import { ClassicEditor } from 'ckeditor5'; import NewsletterPlugin from './newsletter/newsletterplugin'; ClassicEditor .create(document.querySelector('#editor'), { plugins: [ NewsletterPlugin, ... ], // ... other config }) .then(editor => { console.log('Editor initialized with NewsletterPlugin'); }) .catch(error => { console.error(error); }); ``` ## Migration Differences from CKEditor 4 1. **Model-View Separation**: CKEditor 5 uses a model-view architecture where all content is stored in a model and rendered to views. CKEditor 4 manipulated DOM directly. 2. **Schema-Based Content**: CKEditor 5 requires explicit schema registration for custom elements. CKEditor 4 allowed arbitrary HTML. 3. **Command Pattern**: CKEditor 5 uses commands for all actions. CKEditor 4 used direct DOM manipulation. 4. **Widget API**: CKEditor 5 uses widgets for complex content blocks. CKEditor 4 used inline HTML. 5. **Event Handling**: CKEditor 5 uses the editing view document for events. CKEditor 4 used jQuery-style event binding. 6. **Conversion System**: CKEditor 5 requires explicit upcast/downcast converters. CKEditor 4 used automatic HTML parsing. 7. **UI Framework**: CKEditor 5 uses a component-based UI framework. CKEditor 4 used jQuery UI. ## General HTML Support Configuration The `htmlSupport` configuration in CKEditor 5 allows custom HTML elements and attributes: ```typescript htmlSupport: { allow: [ { name: /^div$/, classes: ['newsletter', 'tab-pane', 'active'], attributes: ['id', 'data-*'] }, { name: /^ul$/, classes: ['newsletter-tabs'] }, { name: /^li$/, classes: ['newsletter-tab'] }, { name: /^a$/, attributes: ['href'] } ], disallow: [ // Any disallowed elements ] } ``` This configuration ensures that the editor preserves custom classes and attributes when loading and saving content.

Construa um plugin de newsletter para CKEditor 5

Conteúdo do PromptSalvar

Uso

Referências

Discussão