diff --git a/.github/README.md b/.github/README.md index 3e6ec3c7..227c46db 100644 --- 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 index 259cb34e..8c44072d 100644 --- 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 new file mode 100644 index 00000000..57d3c351 Binary files /dev/null and b/docs/editors/code-editor--configuration-editor.png differ diff --git a/docs/editors/code-editor--property-editor-01.png b/docs/editors/code-editor--property-editor-01.png new file mode 100644 index 00000000..57d3c351 Binary files /dev/null and b/docs/editors/code-editor--property-editor-01.png differ diff --git a/docs/editors/code-editor.md b/docs/editors/code-editor.md index db15ca0e..8f8a6f9c 100644 --- 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 `
` and `` tags.
+
+Using Umbraco's Models Builder...
+
+```cshtml
+
@Html.Raw(Model.CodeEditor)

+```
+
+Without ModelsBuilder...
+
+Weakly-typed...
+
+```cshtml
+
@Html.Raw(Model.Value("codeEditor"))

+```
+
+Strongly-typed...
+
+```cshtml
+
@Html.Raw(Model.Value("codeEditor"))

+```
+
+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
index 26f996e3..220cfdd4 100644
--- 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",
+    }
 }
 ```