CodeEditor - documentation

leekelleher · Apr 7, 2021 · 69524ec · 69524ec
1 parent 2141194
commit 69524ec
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 2 deletions.
diff --git a/.github/README.md b/.github/README.md
@@ -24,6 +24,7 @@ Let's take a look inside...
 ##### Property Editors
 
 - [Bytes](../docs/editors/bytes.md) - a read-only label to display file sizes in relative bytes.
+- [Code Editor](../docs/editors/code-editor.md) - a code snippet editor, _(using the ACE library that is bundled with Umbraco)._
 - [Content Blocks](../docs/editors/content-blocks.md) - a block editor, configurable using element types.
 - [Data List](../docs/editors/data-list.md) - an editor that combines a custom data source with a custom list editor.
 - [Icon Picker](../docs/editors/icon-picker.md) - an editor to select an icon (from the Umbraco icon library).

diff --git a/docs/README.md b/docs/README.md
@@ -13,6 +13,7 @@
 Here is the documentation for the Contentment property-editors...
 
 - [Bytes](../docs/editors/bytes.md) - a read-only label to display file sizes in relative bytes.
+- [Code Editor](../docs/editors/code-editor.md) - a code snippet editor, _(using the ACE library that is bundled with Umbraco)._
 - [Content Blocks](../docs/editors/content-blocks.md) - a block editor, configurable using element types.
 - [Data List](../docs/editors/data-list.md) - an editor that combines a custom data source with a custom list editor.
 - [Icon Picker](../docs/editors/icon-picker.md) - an editor to select an icon (from the Umbraco icon library).

diff --git a/docs/editors/code-editor--configuration-editor.png b/docs/editors/code-editor--configuration-editor.png
diff --git a/docs/editors/code-editor--property-editor-01.png b/docs/editors/code-editor--property-editor-01.png
diff --git a/docs/editors/code-editor.md b/docs/editors/code-editor.md
@@ -4,16 +4,69 @@
 
 ### Code Editor
 
+Code Editor is a property-editor that is used to enter code snippets (as content), makes use of [AWS Cloud 9's Ace editor](https://ace.c9.io/) library that is distributed with Umbraco.
 
 
 ### How to configure the editor?
 
+In your new Data Type, selected the "[Contentment] Code Editor" option. You will see the following configuration fields.
+
+![Configuration Editor for Code Editor](code-editor--configuration-editor.png)
+
+The first field is **Language mode**, this is used to select the programming language mode, for code syntax highlighting. The default mode is "Razor", meaning that you can use a combination of HTML, CSS, JavaScript and Razor syntax.
+
+The next field is **Theme**, which is used to set the visual appearance of the code editor. The default _(and only)_ theme is "Chrome".
+
+> **Please note,** by default, Umbraco ships a streamlined set of programming language modes and themes.
+> 
+> If you would like to add more modes and themes, you can do this by [downloading the latest pre-packaged version of the Ace editor](https://github.com/ajaxorg/ace-builds/releases) and copy any of the `mode-*` or `theme-*` files from the `src-min-noconflict` folder over to the `~/umbraco/lib/ace-builds/src-min-noconflict/` folder in you Umbraco installation.
+> 
+> Once you've done this, you can reload the Data Type screen, and the new programming language modes and themes will appear in the dropdown options for the fields above.
+
+
+The **Font size** field is used to set the font size, the value must be a [valid CSS font-size value](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size), e.g. `14px`, `80%`, `0.8em`, etc. The default size is "`small`".
+
+The **Word wrapping** option can enable the code editor to wrap the text around to the following line.
+
+The next two fields, **Minimum lines** and **Maximum lines**, are used to set the default height size of the code editor. If you would like the height to auto-scale forever, then set the maximum number to something ridiculously high. If left empty, the height of the code editor will remain at a fixed height and not auto-scale.
 
 
 ### How to use the editor?
 
+Once you have added the configured Data Type to your Document Type, the Code Editor editor will be displayed on the content page's property panel.
+
+![Code Editor property-editor](code-editor--property-editor-01.png)
 
 
 ### How to get the value?
 
+The value for the Code Editor is a `string`.
+
+Programmatically, you would access the value exactly the same as Umbraco's Textarea editor, [see Umbraco's documentation for code snippet examples](https://our.umbraco.com/Documentation/Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Textarea/#mvc-view-example).
+
+If you are wanting to display the code content as a pre-formatted code snippet, I would recommend using the `<pre>` and `<code>` tags.
+
+Using Umbraco's Models Builder...
+
+```cshtml
+<pre><code>@Html.Raw(Model.CodeEditor)</code></pre>
+```
+
+Without ModelsBuilder...
+
+Weakly-typed...
+
+```cshtml
+<pre><code>@Html.Raw(Model.Value("codeEditor"))</code></pre>
+```
+
+Strongly-typed...
+
+```cshtml
+<pre><code>@Html.Raw(Model.Value<string>("codeEditor"))</code></pre>
+```
+
+For code syntax highlighting, the following JavaScript libraries are quite popular:
 
+- [Prism.js](https://prismjs.com/)
+- [highlight.js](https://highlightjs.org/)
diff --git a/docs/telemetry.md b/docs/telemetry.md
@@ -15,8 +15,12 @@ Here is an example of the JSON data that is sent.
     "dataType": "4E7D6B3A-F959-42E4-921E-081BC0E9E7EE",
     "editorAlias": "DataList",
     "umbracoId": "0403E47E-EFE7-4CF2-8E97-148681DAFC10",
-    "umbracoVersion": "8.6.6",
-    "contentmentVersion": "1.2.0",
+    "umbracoVersion": "8.6.8",
+    "contentmentVersion": "1.3.0",
+    "dataTypeConfig": {
+        "dataSource": "EnumDataListSource",
+        "listEditor": "CheckboxListDataListEditor",
+    }
 }
 ```