Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/apostrophecms/rich-text-example-extensions

Last synced: 9 days ago
JSON representation

Host: GitHub
URL: https://github.com/apostrophecms/rich-text-example-extensions
Owner: apostrophecms
Created: 2023-02-18T14:21:32.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-05-02T15:05:50.000Z (8 months ago)
Last Synced: 2024-12-19T18:15:26.868Z (15 days ago)
Language: JavaScript
Size: 169 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

README

ApostropheCMS Rich Text Widget Example Extensions

This module bundle adds three new extensions to the `@apostrophecms/rich-text-widget`. While you may find these new extensions useful, they are also a great learning resource and the basis for a series of upcoming tutorials.

### Typography
The first extension, `@apostrophecms/typography` adds a whole series of autocomplete actions to your editor. One example, typing `(tm)` will autoconvert to `™`. For a whole list check out the [documentation](https://tiptap.dev/api/extensions/typography). Note that some auto-convert rules (like fractions) won't work if you have the insert menu turned on. You can configure this module either at the project level in the `modules/@apostrophecms/rich-text-editor/index.js` file, or in the configuration section for the rich-text-widget of individual areas.
Example:
```js
widgets: {
'@apostrophecms/rich-text': {
insert: [
...
],
toolbar: [
...
],
styles: [
...
],
typoConfig: {
// Will no longer convert `(tm)` to ™
trademark: false,
// Will convert `->` to `=>`
rightArrow: '=>'
}
},
'@apostrophecms/image': {},
'@apostrophecms/video': {}
}
```

Wow! Cool! Neat! But... why? Because this extension shows how to take an existing tiptap extension, that doesn't require a new button or any other control element, and add it to the rich text editor.

### Smilies 😀
The second extension, `@apostrophecms/smilies` adds a host of keyboard shortcuts for smilie emojis, plus my favorite non-emoji ( `:ashrug `, `¯\_(ツ)_/¯`). You can see the full list in [the code](modules/@apostrophecms/smilies/lib/replacementEmojis.js). Wow! Cool! Neat! But... isn't there a keyboard shortcut for that now? Yup, but this extension is a great way to learn how to create your own small tiptap extension and add it to the rich-text-widget! You can configure this module either at the project level in the `modules/@apostrophecms/rich-text-editor/index.js` file, or in the configuration section for the rich-text-widget of individual areas to select what skin tone (1 = lightest, 5 = darkest) for the replacement emojis. Note that not all operating systems can display skin tone emojis correctly, so some may not appear as expected.
Example:

```js
widgets: {
'@apostrophecms/rich-text': {
insert: [
...
],
toolbar: [
...
],
styles: [
...
],
smiliesConfig: {
tone: 2
}
},
'@apostrophecms/image': {},
'@apostrophecms/video': {}
}
```

### Character Count
The third extension, `@apostrophecms/characterCount` allows you to display how many characters and words you have typed in your editor box. You can either open the box from the toolbar or the insert menu. If you add it to the toolbar, it will also tell you how many characters you have highlighted. You can limit the number of characters that can be added to the editor box through the configuration.

```js
widgets: {
'@apostrophecms/rich-text': {
insert: [
'table',
'image',
// optionally, add here to have it appear on the insert menu
'characterCount'
],
toolbar: [
...
// optionally, add it here to have it appear on the toolbar
'characterCount',
],
styles: [
...
],
charCountConfig: {
// How X!
limit: 280
}
},
'@apostrophecms/image': {},
'@apostrophecms/video': {}
}
```

Wow... okay, okay. Even I can't get that excited about this one. So, why? This extension will show you how to implement a new button on the toolbar or item in the insert menu to bring up the character count box. It will also give you a basic overview of how you would implement the Vue components for each.

## Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

```
npm install @apostrophecms/rich-text-example-extensions
```

## Usage

Configure the modules in the `app.js` file:

```javascript
require('apostrophe')({
shortName: 'my-project',
// Activate the bundle -> subject to change with renaming/ownership change
bundles: [ '@apostrophecms/rich-text-example-extensions' ],
modules: {
// The typography module
'@apostrophecms/typography': {},
// The smilies module
'@apostrophecms/smilies': {},
// The character count module
'@apostrophecms/characterCount': {}
}
});
```

Enabling any of these modules will improve the rich-text-widget, making them available without additional configurations. You will only need to add the `characterCount` to the toolbar or insert menu (or both!) configuration as shown above.