From a9a8c36a134ccf047abafc812e5c61a9e3527313 Mon Sep 17 00:00:00 2001 From: jensp Date: Thu, 18 Jan 2018 16:01:33 +0000 Subject: [PATCH] CCM NG: Documentation for the ccm-editor module git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@5202 8810af33-2d31-482b-a856-94f89814c4df --- ccm-editor/src/site/markdown/index.md | 159 ++++++++++++++++++++++++++ ccm-editor/src/site/site.xml | 19 +++ 2 files changed, 178 insertions(+) create mode 100644 ccm-editor/src/site/markdown/index.md create mode 100644 ccm-editor/src/site/site.xml diff --git a/ccm-editor/src/site/markdown/index.md b/ccm-editor/src/site/markdown/index.md new file mode 100644 index 000000000..9bfd9c97c --- /dev/null +++ b/ccm-editor/src/site/markdown/index.md @@ -0,0 +1,159 @@ +The CCM Editor modul +-------------------- + +# Overview + +The CCM Editor modules provides a simple HTML editor written in TypeScript +for use in the backend of LibreCCM. TypeScript is super set of JavaScript. +Along with features from the newest versions ECMA Script standard which are not +yet implemented by the browsers it also is a strongly typed programming +language. This helps to avoid some types of mistakes which can easily occur +For more information about TypeScript please +refer to the the [TypeScript homepage](http://www.typescriptlang.org). +The TypeScript compiler (or better transpiler) creates JavaScript from +TypeScript. + +In addition to TypeScript this module also uses NPM as package manager for +JavaScript libraries and Grunt as a TaskRunner. To build this module +you don't need to install any of these tools. +They are integrated +into the build process of Maven by the +[frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin). +This plugin for Maven downloads and installs an local copy of NPM, invokes +NPM to download the dependencies using NPM and calls Grunt to run the +TypeScript compiler. + +The editor uses the `contenteditable` attribute from HTML 5 also with several +other features. Modern browsers provide almost necessary basic funtions for +an editor, this module only provides a UI for them. + +Supported browsers are: + +* Mozilla Firefox (52 and later) +* Google Chrome (58 and later) +* Microsoft Edge (all versions) +* Apple Safari (10 and later) +* other based WebKit Browsers should also work (with recent versions of WebKit) + +# Integration into a bundle + +To integrate the editor into a bundle first declare a dependency to the +`ccm-editor` module in the `pom.xml` file of the bundle: + + + org.libreccm + ccm-editor + ${project.parent.version} + + +In the Maven module of bundle which generates the WAR part in add the following +the to configuration of the `maven-war-plugin`: + + ... + + ... + + + org.apache.maven.plugins + maven-war-plugin + + + + org.libreccm + ccm-editor + jar + + ... + + + ... + + + ... + + ... + +In the WAR module add a folder `ccm-editor` to the `src/main/webapp` folder +and create a file similar to the following one: + + requirejs(["./ccm-editor", + "../node_modules/requirejs-domready/domReady!"], + function(editor, doc) { + + editor.addEditor(".editor", { + "actionGroups": [ + { + "name": "blocks", + "title": "Format blocks", + "actions": [ + editor.FormatBlockAction + ] + }, + { + "name": "format-text", + "title": "Format text", + "actions": [ + editor.MakeBoldAction, + editor.MakeItalicAction, + editor.MakeUnderlineAction, + editor.StrikeThroughAction, + editor.SubscriptAction, + editor.SuperscriptAction, + editor.RemoveFormatAction, + editor.InsertExternalLinkAction + ] + }, + { + "name": "insert-list", + "title": "Insert list", + "actions": [ + editor.InsertUnorderedListAction, + editor.InsertOrderedListAction + ] + }, + { + "name": "html", + "title": "HTML", + "actions": [editor.ToggleHtmlAction] + } + ], + "settings": { + "formatBlock.blocks": [ + { + "element": "h3", + "title": "Heading 3" + }, + { + "element": "h4", + "title": "Heading 4" + }, + { + "element": "h5", + "title": "Heading 5" + }, + { + "element": "h6", + "title": "Heading 6" + }, + { + "element": "p", + "title": "Paragraph" + } + ] + } + }); + }); + +This will load the editor using `require.js` (the editor is provided as a +AMD JavaScript module) and call the wrapped function when the DOM tree is ready. +The function calls the `addEditor` function from the editor module and applies +the editor to all `textarea` elements with the class `.editor`. The parameter +is a CSS selector which you can modify according to your needs. + +The editor is initialised with a configuration. The configuration is described +at the [configuration](configuration.html) page. The editor itself has no +hardcoded functions. Instead all controls in its toolbar are provided as +(TypeScript) classes which can be added by the configuration. The editor +module provides several standard actions like formated block elements. Please +refer to the [Standard Actions](actions.html) for more information about these +actions. \ No newline at end of file diff --git a/ccm-editor/src/site/site.xml b/ccm-editor/src/site/site.xml new file mode 100644 index 000000000..9cae03589 --- /dev/null +++ b/ccm-editor/src/site/site.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + +