@arsedizioni/ars-utils 22.5.8 → 22.5.11

package/ui.tinymce/README.md

@@ -1,12 +1,82 @@
-in application:
-1) install tinymce (npm install tinymce)
-1) install @tinymce/tinymce-angular (npm install @tinymce/tinymce-angular)
-2) setup assets in angular.json
-    {
-        "glob": "**/*",
-        "input": "node_modules/tinymce",
-        "output": "assets/tinymce"
-    }
-3) download language from 
-https://github.com/tinymce/tinymce/blob/develop/modules/tinymce/src/langs/it.js and put it in
-"assets/tinymce/langs/it.js"
+# ui.tinymce
+
+L'editor ricco della libreria: la direttiva `[tinymceEditor]`, il caricatore a runtime e i
+profili di configurazione.
+
+Non c'e' nessun wrapper Angular di mezzo. `@tinymce/tinymce-angular` era una dipendenza in piu'
+da tenere allineata ad Angular ad ogni major, e in cambio dava un componente `<editor>` che non
+sa fare il `ControlValueAccessor` come lo vogliamo noi: la direttiva sta su una `<textarea>`
+normale, quindi `[(ngModel)]`, `required` e lo stato pristine/dirty funzionano come su qualunque
+altro controllo.
+
+## Nell'applicazione
+
+1) `npm install tinymce` (peer dependency opzionale, versione 8)
+
+2) pubblicare il pacchetto fra gli asset, in `angular.json`:
+
+```json
+{
+  "glob": "**/*",
+  "input": "node_modules/tinymce",
+  "output": "assets/tinymce"
+}
+```
+
+3) la lingua italiana non sta dentro il pacchetto npm: `langs/it.js` e' committato in questo
+   entry point, va copiato in `src/assets/tinymce/langs/it.js`.
+
+Nient'altro: **non** serve nessun `<script>` in `index.html`. `TinymceLoaderService` inietta
+`assets/tinymce/tinymce.min.js` la prima volta che un editor viene creato, risolvendo l'URL
+contro il base href del documento (quindi funziona anche se l'applicazione e' servita da un
+sotto-percorso), e le chiamate successive riusano lo stesso script.
+
+## Uso
+
+```html
+<textarea tinymceEditor [(ngModel)]="item.text" name="text" required></textarea>
+```
+
+Con un profilo e un uploader di immagini:
+
+```html
+<textarea tinymceEditor
+          [tinymceConfig]="config"
+          [tinymceImageUploader]="upload"
+          (ready)="onReady($event)"
+          (failed)="onFailed($event)"
+          [(ngModel)]="item.text" name="text"></textarea>
+```
+
+```typescript
+protected readonly config = TinymceUtils.TinymceCompactConfig;
+protected readonly upload = (file: File) => this.api.upload(file); // torna l'URL dell'immagine
+```
+
+`tinymceToolbarMode="inline"` edita l'elemento sul posto invece di sostituirlo: richiede un
+`<div>`, non una `<textarea>`, e la direttiva lo dice esplicitamente se ci si sbaglia.
+
+## Profili
+
+`TinymceUtils` espone tre configurazioni, ognuna restituita come copia fresca ad ogni lettura:
+
+| Profilo | Per cosa |
+|---|---|
+| `TinymceConfig` | editor a tutta pagina, tutti i plugin open source di TinyMCE 8 |
+| `TinymceCompactConfig` | campo dentro una form: cresce col testo, toolbar in basso raggruppata |
+| `TinymceCompactExtendedConfig` | come sopra, piu' schermo intero, gruppo inserisci e vista sorgente |
+
+Descrivono **cosa offre l'editor** e nient'altro: caricamento (`base_url`, `language`,
+`license_key`) e tema (`skin`, `content_css`) li decidono il loader e la direttiva, che li
+risolvono contro il base href e contro `ThemeService`. Anche le opzioni di upload seguono
+`tinymceImageUploader`, cosi' un editor senza handler non puo' mostrare una scheda di caricamento
+che non porta da nessuna parte.
+
+I profili si passano a `[tinymceConfig]` e vincono sui default della direttiva; restano suoi
+`target`, `base_url`, `inline` e `setup`, che e' quello che tiene l'editor agganciato alla form.
+
+## Il dialog
+
+`TinyMceEditorComponent` e' un dialog che contiene solo un editor: riceve un testo, ne
+restituisce uno modificato tramite l'output `saving`. Usa il profilo compatto esteso, con la
+toolbar senza schermo intero — il dialog e' gia' tutto lo spazio disponibile.