|
| 1 | +# Angular-Markdown-Editor |
| 2 | +[](https://opensource.org/licenses/MIT) |
| 3 | +[](http://www.typescriptlang.org/) |
| 4 | +[](https://badge.fury.io/js/angular-markdown-editor.svg) |
| 5 | + |
| 6 | +In this package we will use a few libraries and tools to make a more convenient "all in one" WYSIWYG Markdown Editor with preview. All of that with a simple Angular Component. This can be useful for online documentation and many other reasons (docs, blog, ...). |
| 7 | + |
| 8 | +#### AngularJS (previous version) |
| 9 | +If you still have AngularJS project, you can still get the older version `1.1.5` from [NPM](https://www.npmjs.com/package/angular-markdown-editor/v/1.1.5), however please note that support has stopped and only the new version `2.x` will be supported. |
| 10 | + |
| 11 | +### Dependencies |
| 12 | +Here is the list of dependencies, which are required |
| 13 | +- [Bootstrap-Markdown](http://www.codingdrama.com/bootstrap-markdown/) (editor) itself |
| 14 | +- [jQuery](http://jquery.com/) _(required for Bootstrap-Markdown editor)_ |
| 15 | +- [Bootstrap 3.x](https://getbootstrap.com/docs/3.3/). |
| 16 | + - If anyone needs `Bootstrap 4` support and has time to add the necessary code, [PR](https://github.com/ghiscoding/angular-markdown-editor/pulls) (Pull Request) are certainly welcome. |
| 17 | + |
| 18 | +### Nice to have Dependencies |
| 19 | +It's a "nice to have" but not a deep dependencies, which is the [ngx-markdown](https://github.com/jfcere/ngx-markdown) lib. It is used in the demo of this lib, but technically you could plug any other lib you wish for dealing with the markdown preview. |
| 20 | + |
| 21 | +### Demo page |
| 22 | +- [Bootstrap 3 demo](https://ghiscoding.github.io/angular-markdown-editor) / [examples repo](https://github.com/ghiscoding/angular-markdown-editor/tree/master/src/app/examples) |
| 23 | + |
| 24 | + |
| 25 | +## Installation |
| 26 | + |
| 27 | +### NPM Package |
| 28 | +[Angular-Markdown-Editor on NPM](https://www.npmjs.com/package/angular-markdown-editor) |
| 29 | + |
| 30 | +Install through `NPM` or `Yarn` |
| 31 | +```bash |
| 32 | +npm install angular-markdown-editor |
| 33 | + |
| 34 | +# or with Yarn |
| 35 | +yarn add angular-markdown-editor |
| 36 | +``` |
| 37 | + |
| 38 | +### Modify the `.angular-cli.json` file |
| 39 | +You need to add CSS Styles for the Bootstrap, Markdown Editor and Font-Awesome (the latter is optional). |
| 40 | + |
| 41 | +```json |
| 42 | +"styles": [ |
| 43 | + "../node_modules/bootstrap/dist/css/bootstrap.css", |
| 44 | + "../node_modules/bootstrap-markdown/css/bootstrap-markdown.min.css", |
| 45 | + "../node_modules/font-awesome/css/font-awesome.css" |
| 46 | +], |
| 47 | +"scripts": [ |
| 48 | + "../node_modules/jquery/dist/jquery.js", |
| 49 | + "../node_modules/bootstrap-markdown/js/bootstrap-markdown.js" |
| 50 | +], |
| 51 | +``` |
| 52 | + |
| 53 | +#### When using `ngx-markdown` and/or Prism.js |
| 54 | +`Prism.js` uses separate javascript file for each language, so you'll need to add them yourself. |
| 55 | +For example, below we are adding the highlight for `C#`, `JavaScript` and `TypeScript`: |
| 56 | +```json |
| 57 | +"styles": [ |
| 58 | + "../node_modules/prismjs/themes/prism.css" |
| 59 | +], |
| 60 | +"scripts": [ |
| 61 | + "../node_modules/prismjs/prism.js", |
| 62 | + "../node_modules/prismjs/components/prism-css.min.js", |
| 63 | + "../node_modules/prismjs/components/prism-javascript.min.js", |
| 64 | + "../node_modules/prismjs/components/prism-typescript.min.js" |
| 65 | +], |
| 66 | +``` |
| 67 | + |
| 68 | +### Input attributes |
| 69 | +You can pass the following input attribute: |
| 70 | + |
| 71 | +| attribute | type | required | comments | |
| 72 | +| ------------- | ------------- | -------- | ------- | |
| 73 | +| **textareaId** | string | yes | id of the textarea DOM element used by the lib | |
| 74 | +| **rows** | number | no | number of rows for the textarea, defaults to 10 | |
| 75 | +| **options** | mixed | no | markdown Editor Options to pass to the element | |
| 76 | +| **locale** | EditorLocale | no | locale set that has a language and dictionary that can be added as an alternative language. Can be 1 or more dictionaries | |
| 77 | + |
| 78 | +### Global Options |
| 79 | +The library comes with it's own Global Editor Options, these propertoes can be overriden at any by the `options` attribute. Click to see the [Global Options]() defined. |
| 80 | + |
| 81 | +### Event Hooks |
| 82 | +You can hook to any of the [Bootstrap Markdown Editor Events](http://www.codingdrama.com/bootstrap-markdown/) through 2 ways, just choose the one you prefer: |
| 83 | + |
| 84 | +#### 1. Dispatch of Custom Event |
| 85 | +Each of the events are available in the View from a Custom Event as `(onX)="doSomething()"`, for example: |
| 86 | +```html |
| 87 | +<angular-markdown-editor |
| 88 | + textareaId="editor1" rows="12" |
| 89 | + name="markdownText" [(ngModel)]="markdownText" |
| 90 | + (onFullscreenExit)="hidePreview()"> |
| 91 | +</angular-markdown-editor> |
| 92 | +``` |
| 93 | +```typescript |
| 94 | +export class MyComponent { |
| 95 | + hidePreview() { console.log(e.getContent()); } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +You can also pass the Event returned by the Editor via `$event.detail.eventData` |
| 100 | + |
| 101 | +```html |
| 102 | +<angular-markdown-editor |
| 103 | + textareaId="editor1" rows="12" |
| 104 | + name="markdownText" [(ngModel)]="markdownText" |
| 105 | + (onChange)="onChange($event.detail.eventData)"> |
| 106 | +</angular-markdown-editor> |
| 107 | +``` |
| 108 | +```typescript |
| 109 | +export class MyComponent { |
| 110 | + ngOnInit() { |
| 111 | + onChange(e) { console.log(e.getContent()); } |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +#### 2. Editor Option Callbacks |
| 117 | +The second way is to use the callback directly when defining the Editor Options. |
| 118 | +```html |
| 119 | +<angular-markdown-editor |
| 120 | + textareaId="editor1" rows="12" |
| 121 | + name="markdownText" [(ngModel)]="markdownText" |
| 122 | + [options]="editorOptions"> |
| 123 | +</angular-markdown-editor> |
| 124 | +``` |
| 125 | +```typescript |
| 126 | +import { EditorOption } from 'angular-markdown-editor'; |
| 127 | +export class MyComponent { |
| 128 | + ngOnInit() { |
| 129 | + this.editorOptions: EditorOption = { |
| 130 | + iconlibrary: 'fa', |
| 131 | + onChange: (e) => console.log(e.getContent()), |
| 132 | + onFullscreenExit: () => this.hidePreview() |
| 133 | + }; |
| 134 | + } |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +#### List of Event Hooks |
| 139 | +- onPreview |
| 140 | +- onPreviewEnd |
| 141 | +- onSave |
| 142 | +- onBlur |
| 143 | +- onFocus |
| 144 | +- onFullscreen |
| 145 | +- onFullscreenExit |
| 146 | +- onChange |
| 147 | +- onSelect |
| 148 | +- onShow |
| 149 | + |
| 150 | +### API - Editor Methods |
| 151 | +The editor API is quite dense and I will not list the entire set of methods, but you can see the entire list [here](). |
| 152 | +To call any of the Editor Methods, you will have to first get a reference to the Editor's instance which you can get from the `onShow` callback. |
| 153 | + |
| 154 | +Get the Editor's instance through the `onShow`, via the Custom Event (from the View) or Editor Option callback (just choose the one you prefer). Below shows how to get it through the latter option. |
| 155 | + |
| 156 | +###### View |
| 157 | +```html |
| 158 | +<button (click)="showFullScreen()">Show Full Screen</button> |
| 159 | +<angular-markdown-editor |
| 160 | + textareaId="editor1" rows="12" |
| 161 | + name="markdownText" [(ngModel)]="markdownText" |
| 162 | + [options]="editorOptions"> |
| 163 | +</angular-markdown-editor> |
| 164 | +``` |
| 165 | + |
| 166 | +###### Component |
| 167 | +```typescript |
| 168 | +import { EditorInstance, EditorOption } from 'angular-markdown-editor'; |
| 169 | +export class MyComponent { |
| 170 | + bsEditorInstance: EditorInstance; |
| 171 | + |
| 172 | + ngOnInit() { |
| 173 | + this.editorOptions = { |
| 174 | + iconlibrary: 'fa', |
| 175 | + onShow: (e) => this.bsEditorInstance = e |
| 176 | + }; |
| 177 | + } |
| 178 | + |
| 179 | + showFullScreen() { |
| 180 | + this.bsEditorInstance.setFullscreen(true); |
| 181 | + } |
| 182 | +} |
| 183 | +``` |
| 184 | + |
| 185 | +### Preview Button (need a Parser) |
| 186 | +For the "Preview" button to work, you will need to provide a `parser` to the Editor Options. This lib has no deep dependencies to any Markdown Parser (you could use `marked.js` or any other parser). But assuming we are using `ngx-markdown`, we can add the parser this way: |
| 187 | + |
| 188 | +###### Component |
| 189 | +```typescript |
| 190 | +import { MarkdownService } from 'ngx-markdown'; |
| 191 | + |
| 192 | +export class TestComponent implements OnInit { |
| 193 | + constructor(private markdownService: MarkdownService) {} |
| 194 | + |
| 195 | + ngOnInit() { |
| 196 | + this.editorOptions = { |
| 197 | + parser: (val) => this.markdownService.compile(val.trim()) |
| 198 | + }; |
| 199 | + } |
| 200 | +} |
| 201 | +``` |
| 202 | + |
| 203 | +### Additional Editor Buttons |
| 204 | +I really thought that some buttons were missing to go a great job (~~Strikethrough~~ & **Table**). So I added them directly in the [Global Options](). If you want to add your own, then just look at how it was done in the [Global Options]() and read the section `additionalButtons` of [Bootstrap Markdown](http://www.codingdrama.com/bootstrap-markdown/) website. |
| 205 | + |
| 206 | +### Adding Locale |
| 207 | +You can add a locale to the editor but passing a `locale` object (and bind it in the View) which contain a `language` and the dictionary of words used by the editor. The entire list of words can be seen in the example below. So for example, if we want to add French locale, we will do the following (you can see [demo code]()): |
| 208 | + |
| 209 | +###### View |
| 210 | +```html |
| 211 | +<button (click)="showFullScreen()">Show Full Screen</button> |
| 212 | +<angular-markdown-editor |
| 213 | + textareaId="editor1" rows="12" |
| 214 | + name="markdownText" [(ngModel)]="markdownText" |
| 215 | + [locale]="locale" |
| 216 | + [options]="editorOptions"> |
| 217 | +</angular-markdown-editor> |
| 218 | +``` |
| 219 | + |
| 220 | +###### Component |
| 221 | +```typescript |
| 222 | +import { EditorInstance, EditorLocale, EditorOption } from 'angular-markdown-editor'; |
| 223 | +export class MyComponent { |
| 224 | + locale: EditorLocale = { |
| 225 | + language: 'fr', |
| 226 | + dictionary: { |
| 227 | + 'Bold': 'Gras', |
| 228 | + 'Italic': 'Italique', |
| 229 | + 'Heading': 'Titre', |
| 230 | + 'URL/Link': 'Insérer un lien HTTP', |
| 231 | + 'Image': 'Insérer une image', |
| 232 | + 'List': 'Liste à puces', |
| 233 | + 'Ordered List': 'Liste ordonnée', |
| 234 | + 'Unordered List': 'Liste non-ordonnée', |
| 235 | + 'Code': 'Code', |
| 236 | + 'Quote': 'Citation', |
| 237 | + 'Preview': 'Prévisualiser', |
| 238 | + 'Strikethrough': 'Caractères barrés', |
| 239 | + 'Table': 'Table', |
| 240 | + 'strong text': 'texte important', |
| 241 | + 'emphasized text': 'texte souligné', |
| 242 | + 'heading text': 'texte d\'entête', |
| 243 | + 'enter link description here': 'entrez la description du lien ici', |
| 244 | + 'Insert Hyperlink': 'Insérez le lien hypertexte', |
| 245 | + 'enter image description here': 'entrez la description de l\'image ici', |
| 246 | + 'Insert Image Hyperlink': 'Insérez le lien hypertexte de l\'image', |
| 247 | + 'enter image title here': 'entrez le titre de l\'image ici', |
| 248 | + 'list text here': 'texte à puce ici' |
| 249 | + } |
| 250 | + }; |
| 251 | + |
| 252 | + // if you want to pass multiple locales, just pass it as an array |
| 253 | + /* |
| 254 | + locale: EditorLocale[] = [ |
| 255 | + { language: 'fr', dictionary: { 'Bold': 'Gras', ... |
| 256 | + { language: 'en', dictionary: { 'Bold': 'Bold', ... |
| 257 | + ]; |
| 258 | + */ |
| 259 | + |
| 260 | + ngOnInit() { |
| 261 | + this.editorOptions = { |
| 262 | + language: 'fr', // also set the language option to French |
| 263 | + onShow: (e) => this.bsEditorInstance = e |
| 264 | + }; |
| 265 | + } |
| 266 | +} |
| 267 | +``` |
| 268 | + |
| 269 | +**Note** I could not find a way to change the language dynamically, so it seems that we would have to destroy the component and re-create it for switching the language/locale. |
| 270 | + |
| 271 | +### License |
| 272 | +[MIT License](LICENSE) |
| 273 | + |
| 274 | +## Use it, like it? |
| 275 | +You like and use this great library `Angular-Markdown-Editor`? You can always upvote :star: and/or contribute :) |
| 276 | + |
| 277 | +## Like my work? |
| 278 | +If you like my work, you can also support me with caffeine :smile: |
| 279 | +[Buy Me a Coffee](https://ko-fi.com/N4N679OT) |
0 commit comments