Merge pull request #72 from leekelleher/dev/v1.2

Preparing v1.2.0 release

.github/CONTRIBUTING.md

@@ -14,3 +14,8 @@ Once the feature or idea is fleshed out, let's hack!
 
 > The above is respectively taken from the [Clearwater framework repository](https://github.com/clearwater-rb/clearwater/blob/master/README.md#contributing).<br>
 > Kudos to [Jamie Gaskins](https://github.com/jgaskins) for framing the guidelines so succinctly.
+
+---
+
+Further reading, I've been thinking a lot about Jeff Geerling's post ["Why I close PRs (OSS project maintainer notes)"](https://www.jeffgeerling.com/blog/2016/why-i-close-prs-oss-project-maintainer-notes) lately. If you do submit a PR and feel that I'm closing it down, this is probably the rationale behind it.
+

.github/IDEAS.md

@@ -2,20 +2,50 @@
 
 # Ideas for Contentment
 
+
 ## Data Editors
 
 - TinyMCE - push the boundaries beyond Umbraco's defaults?
   - How's about a TinyMCE that is 30px height, Distraction Free mode, all menu items disabled.
   - Only keyboard shortcuts would be enabled. Try to make it become a single-line rich-textbox.
 
+- Data List: Groups
+  - https://github.com/leekelleher/umbraco-contentment/issues/51
+
+- Data List: Value Converters
+  - https://github.com/leekelleher/umbraco-contentment/issues/29
+
 - Text Input - Change Font-Size within Input Field Based on Length (similar to Facebook's post experience, after 85 chars)
   - https://web-design-weekly.com/snippets/change-font-size-within-input-field-based-on-length/
 
 - Nested Content - Reimagined. Reach for its heart, imagine a new landscape, another atmosphere, and see how it goes.
 
-- 
+### Internally used editors
+
+Could these internally used editors have potential as standalone property editors?
+
+- Configuration Editor
+- Data Table
+- Macro Picker
+
+### Validation
+
+None of the editors have explicit validation implemented, (only because I've never researched it). Let's explore the validation approaches for the editors.
+
+
+## Localization
+
+Remove hard-coded English labels, move them to the language XML file.
+
 
 ## Tracking
 
-- v8.6+ IDataValueReferenceFactory, IDataValueReference
+- v8.6+ `IDataValueReferenceFactory`, `IDataValueReference`
+
+
+## Deprecation considerations
+
+It's good to re-evaluate whether certain features are still relevant.
 
+- Icon Picker editor. The more I think about it, the more I don't see it being relevant as a standalone editor.
+  - For internal Umbraco use - yes; For external public (outside Umbraco) use - no.

.github/ISSUE_TEMPLATE/ISSUE_BUG_REPORT.md

@@ -9,21 +9,22 @@ assignees: "leekelleher"
 **Note: for support questions, please use the [Umbraco Community forum](https://our.umbraco.com)**. This repository's issues are reserved for bug reports and feature requests.
 
 
-### What is the current behavior?
+### What is the current behaviour?
 
 
 
-### What is the expected behavior?
+### What is the expected behaviour?
 
 
 
-### What is the motivation / use case for changing the behavior?
+### What is the motivation / use case for changing the behaviour?
 
 
 ### Please tell us about your set-up:
 
 - Contentment version: [1.0.0]
 - Umbraco version: [8.6.1]
+- Umbraco ModelsBuilder _(if applicable?)_ is: [enabled | disabled]
 - Browser _(if applicable?)_: [all | Chrome XX | Firefox XX | Edge XX | Safari XX ]
 
 

.github/README.md

@@ -28,18 +28,40 @@ Let's take a look inside...
 - [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).
 - [Notes](../docs/editors/notes.md) - a read-only label to display rich-text instructional messages for content editors.
+- [Number Input](../docs/editors/number-input.md) - a numeric editor, with sizing configurations.
 - [Render Macro](../docs/editors/render-macro.md) - a read-only label dynamically generated from an Umbraco Macro.
+- [Text Input](../docs/editors/text-input.md) - a textstring editor, configurable with HTML5 options.
 
+##### Telemetry
+
+Information about the [telemetry feature](../docs/telemetry.md).
 
 #### Releases
 
 Downloads are available on the [releases page](https://github.com/leekelleher/umbraco-contentment/releases).
 
+#### Installation
+
+> *Note:* Contentment has been developed against **Umbraco v8.6.1** and will support that version and above.
+
+Contentment can be installed from either Our Umbraco or NuGet package repositories, or build manually from the source-code:
+
+##### Our Umbraco package repository
+
+To install from Our Umbraco, please download the package from:
+
+> <https://our.umbraco.com/packages/backoffice-extensions/contentment/>
+
+##### NuGet package repository
+
+To [install from NuGet](https://www.nuget.org/packages/Our.Umbraco.Community.Contentment), you can run the following command from within Visual Studio:
+
+    PM> Install-Package Our.Umbraco.Community.Contentment
 
 #### Known issues
 
 - **Data List**
-  - When using the Umbraco Content data source with an XPath query, inside a Nested Content editor, it will not be able to identify the contextual containing node ID. e.g. your XPath query will not work. See #30 for details.
+  - When using the Umbraco Content data source with an XPath query, inside a Nested Content editor, it will not be able to identify the contextual containing node ID. e.g. your XPath query will not work. [See #30 for details.](https://github.com/leekelleher/umbraco-contentment/issues/30)
 
 
 ### Documentation
@@ -50,6 +72,11 @@ Please note, you may find other components within Contentment that have not yet
 _Let's call those "life's little surprises"._
 
 
+### Roadmap
+
+If you would like to know what is coming up in future releases, then take a look at the [roadmap](ROADMAP.md).
+
+
 ### Support
 
 I've been doing open source for a long time. I have suffered my fair share of burnout and empathy fatigue.
@@ -101,7 +128,7 @@ For more information about the Mozilla Public License, please visit: <https://ww
 - [Lee Kelleher](https://leekelleher.com) - ([GitHub](https://github.com/leekelleher), [Twitter](https://twitter.com/leekelleher))
 
 <details>
-<summary>Current development effort: <b>810+ hours</b> (between 2019-03-13 to 2020-08-28)</summary>
+<summary>Current development effort: <b>860+ hours</b> (between 2019-03-13 to 2020-12-03)</summary>
 
 _To give you an idea of how much human developer time/effort has been put into making this package._
 

.github/ROADMAP.md

@@ -7,10 +7,13 @@ Here is a _provisional_ roadmap for the Contentment for Umbraco package, to be a
 
 ## v1
 
-
 ### v1.0
 
-Initial release. Property Editors are:
+Initial release.
+
+Compiles against Umbraco CMS v8.6.1, _(this was the latest version at the time of initial release)._
+
+Property Editors are:
 
 - [Bytes](../docs/editors/bytes.md)
 - [Data List](../docs/editors/data-list.md)
@@ -25,38 +28,32 @@ Initial release. Property Editors are:
 
 ### v1.2
 
-- Text Input _(a reimagining of the textstring editor)_
-- Number Input _(a reimagining of the numeric editor)_
+- [Text Input](../docs/editors/text-input.md) _(a reimagining of the textstring editor)_
+- [Number Input](../docs/editors/number-input.md) _(a reimagining of the numeric editor)_
 - Data List: Templated List _(use custom AngularJS markup to render items)_
+- Telemetry
 
 ### v1.3
 
 - Code Editor _(using ACE bundled with Umbraco)_
+- Data List: Preview _(a real time preview of the configured Data Source and List Editor)_
+- Data List: Tags _(list editor, visually similar to Umbraco Tags editor)_
 
-### v1.4
-
-- Cascading Dropdown List _(uses API endpoints to populate the dropdowns)_
 
-### v1.x-future
-
-**Internally used editors** that could potentially be made into standalone property editors.
+## v2
 
-- Checkbox _(includes "Inline Checkbox" option)_
-- Configuration Editor
-- Data Table
+### v2.0
 
-**Localization**
+- _(At the time of writing),_ a breaking-change release _(following SemVer guidelines),_ of v1.3 features that compiles against Umbraco CMS v8.12.
 
-Remove hard-coded English labels, move them to the language XML file.
+### v2.1
 
-**Validation exploration**
+- Cascading Dropdown List _(uses API endpoints to populate the dropdowns)_
 
-None of the editors have explicit validation implemented, (only because I've never researched it).<br>
-Could be an interesting to explore the validation approaches for the Contentment editors.
 
+## Future feature releases
 
-## v2
+_Who knows?!_ `¯\_(ツ)_/¯`
 
-- _Who knows?!_ `¯\_(ツ)_/¯`
-- Let's see if new ideas can be sparked from Umbraco v8.7+!
+**There are [plenty of ideas](IDEAS.md)!**
 

VERSION

@@ -1 +1 @@
-1.1.3
+1.2.0

build/build-assets.ps1

@@ -43,26 +43,28 @@ Copy-Item -Path "${ProjectDir}Web\UI\App_Plugins\Contentment\*" -Force -Recurse
 # HTML (Property Editors) - Copy and Minify (or just remove comments)
 $htmlFiles = Get-ChildItem -Path "${ProjectDir}DataEditors" -Recurse -Force -Include *.html;
 foreach($htmlFile in $htmlFiles){
-    $contents = Get-Content -Path $htmlFile.FullName;
-    $minifiedHtml = [Regex]::Replace($contents, "^<!--.*?-->", "");
+    $contents = Get-Content -Raw -Path $htmlFile.FullName;
+    $minifiedHtml = [Regex]::Replace($contents, "^<!--.*?-->", "", "Singleline");
+    $minifiedHtml = [Regex]::Replace($minifiedHtml, "^`r`n`r`n", "", "Singleline");
+    $minifiedHtml = [Regex]::Replace($minifiedHtml, "`r`n$", "", "Singleline");
     [IO.File]::WriteAllLines("${pluginFolder}\editors\$($htmlFile.Name)", $minifiedHtml);
 }
 
 # Razor Templates - Copy
 $razorFiles = Get-ChildItem -Path "${ProjectDir}DataEditors" -Recurse -Force -Include *.cshtml;
 foreach($razorFile in $razorFiles){
-    $contents = Get-Content -Path $razorFile.FullName;
+    $contents = Get-Content -Raw -Path $razorFile.FullName;
     [IO.File]::WriteAllLines("${pluginFolder}\render\$($razorFile.Name)", $contents);
 }
 
 # CSS - Bundle & Minify
 $targetCssPath = "${pluginFolder}contentment.css";
-Get-Content -Path "${ProjectDir}**\**\*.css" | Set-Content -Path $targetCssPath;
+Get-Content -Raw -Path "${ProjectDir}**\**\*.css" | Set-Content -Path $targetCssPath;
 & "${SolutionDir}..\tools\AjaxMinifier.exe" $targetCssPath -o $targetCssPath
 
 # JS - Bundle & Minify
 $targetJsPath = "${pluginFolder}contentment.js";
-Get-Content -Path "${ProjectDir}**\**\*.js" | Set-Content -Path $targetJsPath;
+Get-Content -Raw -Path "${ProjectDir}**\**\*.js" | Set-Content -Path $targetJsPath;
 & "${SolutionDir}..\tools\AjaxMinifier.exe" $targetJsPath -o $targetJsPath
 
 # In debug mode, copy the assets over to the local dev website

docs/README.md

@@ -17,7 +17,9 @@ Here is the documentation for the Contentment property-editors...
 - [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).
 - [Notes](../docs/editors/notes.md) - a read-only label to display rich-text instructional messages for content editors.
+- [Number Input](../docs/editors/number-input.md) - a numeric editor, with sizing configurations.
 - [Render Macro](../docs/editors/render-macro.md) - a read-only label dynamically generated from an Umbraco Macro.
+- [Text Input](../docs/editors/text-input.md) - a textstring editor, configurable with HTML5 options.
 
 
 ##### Prerequisite
@@ -29,3 +31,8 @@ If you are unfamiliar with how to do this, then please refer to documentation, g
 - [Our Umbraco - Getting Started - Data](https://our.umbraco.com/Documentation/Getting-Started/Data/)
 - [Our Umbraco - Getting Started - Data - Defining content](https://our.umbraco.com/Documentation/Getting-Started/Data/Defining-content/)
 - [Our Umbraco - Getting Started - Data - Customizing Data Types](https://our.umbraco.com/Documentation/Getting-Started/Data/Data-Types/)
+
+#### Telemetry
+
+Information about Contentment's [telemetry feature](../docs/telemetry.md).
+

docs/editors/content-blocks.md

@@ -101,17 +101,22 @@ To use your own custom preview partial-views, you must use the following convent
 
 When developing your own preview partial-view template, the declaration can be one of the following...
 
+- `@inherits UmbracoViewPage<IPublishedElement>`
+  This uses Umbraco's `UmbracoViewPage` declaration, you must set the type to either be `IPublishedElement` or if you are using Umbraco's ModelsBuilder feature, you can set the Element Type model. _(If you do not set an Element Type, you will get an error!)_ The element is accessible with `@Model`. The current page is available on `@ViewData["content"]`.
+
 - `@inherits Umbraco.Web.Mvc.ContentBlockPreviewView`
   This is the default declaration. This will give you access to `@Model.Content` (the current page as `IPublishedContent`), and `@Model.Element` (the content block item as `IPublishedElement`).
 
 - `@inherits ContentBlockPreviewModel<TPublishedContent, TPublishedElement>`
   This is advanced syntax, _(note, may require some trial-and-error, and sense of play)._ This can be used if you are using Umbraco's ModelsBuilder feature, where you know the object-type of the current Content Type page and Element Type item. As above, you can have strongly-typed access to the current page with `@Model.Content`, and the content block item with `@Model.Element`.
 
-To aid the preview, there are a number of additional properties available in the partial-view's `ViewData` dictionary.
+To aid the preview, when using the `ContentBlockPreviewModel` declaration, there are additional properties available on the partial-view's model.
+
+- `@Model.ElementIndex` - This is the index (`int`) of the content block item's position in the list.
+- `@Model.ElementTypeIcon` - This is the Element Type's icon, _(since the icon is not available on `Model.Element.ContentType`)._
+- `@Model.ContentTypeIcon` - This is the Content Type's icon, _(since the icon is not available on `Model.Content.ContentType`)._
 
-- `ViewData["elementIndex"]` - This is the index (`int`) of the content block item's position in the list.
-- `ViewData["elementIcon"]` - This is the Element Type's icon, _(since the icon is not available on `Model.Element.ContentType`)._
-- `ViewData["contentIcon"]` - This is the Content Type's icon, _(since the icon is not available on `Model.Content.ContentType`)._
+If you are using the `UmbracoViewPage` declaration, the additional properties are available on the `ViewData` object: `@ViewData["elementIndex"]`, `@ViewData["elementIcon"]`, and `@ViewData["contentIcon"]`.
 
 > **Note:** The preview feature **does not work** on a freshly created new unsaved page. This is because the preview has no context of the page itself.
 
@@ -163,4 +168,5 @@ There are several alternative block-based editors that you could use with Umbrac
 For further reading, here are a selection of insights...
 
 - [Paul Marden's **Landing Page article** on Skrift](https://skrift.io/issues/part-1-landing-pages/) - part of a wider series on exploring common practices.
-- [Cogworks' post on **How to Pick a Block Style Editor**](https://www.wearecogworks.com/blog/umbraco-v8-how-to-pick-a-block-style-editor/)
+- [Building with blocks. Which Umbraco block builder is right for you?](https://24days.in/umbraco-cms/2020/umbraco-block-builders/) - Peter Gregory's 24 Days In Umbraco article.
+- [How to Pick a Block Style Editor](https://www.wearecogworks.com/blog/umbraco-v8-how-to-pick-a-block-style-editor/) - by Marcin Zajkowski on the Cogworks blog.

docs/editors/number-input.md

@@ -0,0 +1,41 @@
+<img src="../assets/img/logo.png" alt="Contentment for Umbraco logo" title="A state of Umbraco happiness." height="130" align="right">
+
+## Contentment for Umbraco
+
+### Number Input
+
+Number Input is a property-editor that is used to enter a numeric value.
+
+
+### How to configure the editor?
+
+In your new Data Type, selected the "[Contentment] Text Input" option. You will see the following configuration fields.
+
+![Configuration Editor for Number Input](number-input--configuration-editor.png)
+
+The first field is **Numeric size**, this is used to determine how big the number will get for the input. The size ranges from small, to extra large.
+
+The next field is **Placeholder text**, which is used to add initial instructional information for the number input, this is not a default value.
+
+> For technical users, from a HTML5 perspective, this is the [`<input>`'s `placeholder` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number#placeholder).
+
+
+### How to use the editor?
+
+Once you have added the configured Data Type to your Document Type, the Number Input editor will be displayed on the content page's property panel.
+
+![Number Input property-editor](number-input--property-editor-01.png)
+
+
+### How to get the value?
+
+The value for the Text Input is an `int` (integer).
+
+Programmatically, you would access the value exactly the same as Umbraco's Numeric editor, [see Umbraco's documentation for code snippet examples](https://our.umbraco.com/Documentation/Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Numeric/#mvc-view-examples).
+
+
+### Further reading
+
+- [Umbraco documentation on built-in **Numeric** property editor](https://our.umbraco.com/Documentation/Getting-Started/Backoffice/Property-Editors/Built-in-Property-Editors/Numeric/)
+- [MDN Web documentation on `<input type="number">` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number)
+