Merge pull request #26 from leekelleher/develop

Preparing v1.0.0-beta

.github/CONTRIBUTING.md

@@ -1,5 +1,9 @@
 This project is governed by a [Code of Conduct](CODE_OF_CONDUCT.md).
 
+First, before writing any code, [please open an issue](https://github.com/leekelleher/umbraco-contentment/issues), let's have a discussion about any features or ideas that you may have.
+
+Once the feature or idea is fleshed out, let's hack!
+
 1. Fork it
 2. Branch it
 3. Hack it

.github/IDEAS.md

@@ -1,4 +1,6 @@
-# Contentment Ideas
+<img src="../docs/assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
+
+# Ideas for Contentment
 
 ## Data Editors
 

.github/ISSUE_TEMPLATE/ISSUE_BUG_REPORT.md

@@ -23,7 +23,7 @@ assignees: "leekelleher"
 ### Please tell us about your set-up:
 
 - Contentment version: [1.0.0]
-- Umbraco version: [8.4.0]
+- Umbraco version: [8.6.1]
 - Browser _(if applicable?)_: [all | Chrome XX | Firefox XX | Edge XX | Safari XX ]
 
 

.github/README.md

@@ -1,8 +1,8 @@
-<img src="../docs/assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../docs/assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 
-> contentment /kənˈtɛntm(ə)nt/ - a shoebox of happiness and satisfaction
+> contentment /kənˈtɛntm(ə)nt/ - a state of happiness and satisfaction
 
 ### What is it?
 
@@ -19,20 +19,20 @@ No pressure or marketing spin from me.
 
 #### What's on offer?
 
-Let's open the shoebox and take a look inside...
+Let's take a look inside...
 
 ##### Property Editors
 
-- [Bytes](../docs/editors/bytes.md)
-- [Data List](../docs/editors/data-list.md)
-- [Icon Picker](../docs/editors/icon-picker.md)
-- [Notes](../docs/editors/notes.md)
-- [Render Macro](../docs/editors/render-macro.md)
+- [Bytes](../docs/editors/bytes.md) - a read-only label to display file sizes in relative bytes.
+- [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.
+- [Render Macro](../docs/editors/render-macro.md) - a read-only label dynamically generated from an Umbraco Macro.
 
 
 #### Release status
 
-My aim to have a private v1.0 beta release ready soon, with a public release by end of Q1 (March) 2020.
+My aim to have a v1.0 release by end of Q2 (June) 2020.
 
 Downloads will be made available, (in due course), on the [releases page](https://github.com/leekelleher/umbraco-contentment/releases).
 
@@ -47,7 +47,7 @@ _There are currently no known issues with the Contentment package._
 [Documentation for each of the components - with screenshots, use-cases and code examples - can be found in the /docs folder](../docs/).
 
 Please note, you may find other components within Contentment that have not yet been documented.<br>
-_Let's call those "undocumented features"._
+_Let's call those "life's little surprises"._
 
 
 ### Support
@@ -58,13 +58,13 @@ I reserve the right to address bug reports or feature requests in my own time, o
 
 **Any feedback is warmly welcome.** But please keep in mind, I am not your personal support developer.
 
-If you are really suck, do remember that the Umbraco community is amongst the friendliest on our planet, learn to embrace it.<br>
+If you are really stuck, do remember that the Umbraco community is amongst the friendliest on our planet, learn to embrace it.<br>
 Ask for help on the [Our Umbraco support forum](https://our.umbraco.com/), I am sure someone can help you there.
 
 
 ### Contributions, collaborations, rules of engagement
 
-If you would like to contribute to this project, please do feel free to send over any pull requests. I'll be happy to discuss.
+If you would like to contribute to this project, please start a discussion before spending time on a pull request. Your time is precious.
 
 Please make sure that you read the [CONTRIBUTING](CONTRIBUTING.md) guidelines.
 
@@ -73,7 +73,7 @@ This project is governed by a [Code of Conduct](CODE_OF_CONDUCT.md). **Play nice
 If you are unhappy with the project or documentation, please help to identify specific issues and work towards resolving them.
 Otherwise you are completely free to not use this software, complain on your favourite social network, or shout into the void.
 
-Unacceptable behaviour towards myself or contributors may result in being blocked from accessing this repository.
+Unacceptable behaviour towards myself (or contributors) may result in being blocked from accessing this repository.
 
 
 ### License
@@ -101,7 +101,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>720+ hours</b> (between 2019-03-13 to 2020-05-22)</summary>
+<summary>Current development effort: <b>746+ hours</b> (between 2019-03-13 to 2020-06-11)</summary>
 
 _To give you an idea of how much human developer time/effort has been put into making this package._
 
@@ -112,8 +112,3 @@ _To give you an idea of how much human developer time/effort has been put into m
 
 - Thank you to [Umbrella](https://umbrellainc.co.uk) for facilitating the time and resource to help me develop this project.
 
-
-#### Logo
-
-The package logo uses the [Shoebox](https://thenounproject.com/term/shoebox/79857/) (by [Jordynn Alexander](https://thenounproject.com/jordynn2/)) icon from the [Noun Project](https://thenounproject.com), licensed under [CC BY 3.0 US](https://creativecommons.org/licenses/by/3.0/us/).
-

.github/ROADMAP.md

@@ -1,4 +1,4 @@
-<img src="../docs/assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../docs/assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 # Umbraco Contentment - Roadmap
 
@@ -21,6 +21,7 @@ Initial release. Property Editors are:
 ### v1.1
 
 - Content Blocks _(a StackedContent-esque editor)_
+- Data List: Umbraco Content _(a data source for selecting nodes)_
 
 ### v1.2
 

build/build-pkgs.ps1

@@ -96,7 +96,7 @@ if (!(Test-Path -Path $umbFolder)) {New-Item -Path $umbFolder -Type Directory;}
 
 $umbracoManifest = Join-Path -Path $buildFolder -ChildPath 'manifest-umbraco.xml';
 $umbracoPackageXml = [xml](Get-Content $umbracoManifest);
-$umbracoPackageXml.umbPackage.info.package.version = "$($semver.Major).$($semver.Minor).$($semver.Patch)";
+$umbracoPackageXml.umbPackage.info.package.version = "$($semver.VersionString)";
 $umbracoPackageXml.umbPackage.info.package.name = $packageName;
 $umbracoPackageXml.umbPackage.info.package.iconUrl = $iconUrl;
 $umbracoPackageXml.umbPackage.info.package.license.set_InnerText($licenseName);

docs/README.md

@@ -1,4 +1,4 @@
-<img src="assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 
@@ -8,11 +8,11 @@
 
 Here is the documentation for the Contentment property-editors...
 
-- [Bytes](../docs/editors/bytes.md)
-- [Data List](../docs/editors/data-list.md)
-- [Icon Picker](../docs/editors/icon-picker.md)
-- [Notes](../docs/editors/notes.md)
-- [Render Macro](../docs/editors/render-macro.md)
+- [Bytes](../docs/editors/bytes.md) - a read-only label to display file sizes in relative bytes.
+- [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.
+- [Render Macro](../docs/editors/render-macro.md) - a read-only label dynamically generated from an Umbraco Macro.
 
 
 ##### Prerequisite

docs/editors/bytes.md

@@ -1,4 +1,4 @@
-<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 

docs/editors/data-list.md

@@ -1,4 +1,4 @@
-<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 
@@ -19,13 +19,13 @@ The two main fields are "**Data source**" and "**List editor**".
 
 ![Configuration Editor for Data List - empty state](data-list--configuration-editor-01.png)
 
-Selecting the **Data source**, you will be presented with a selection of data sources, including .NET enumeration, file system, SQL, Umbraco entities, XML data.
+Selecting the **Data source**, you will be presented with a selection of data sources, including .NET enumeration, file system, SQL, CSV, JSON and XML data.
 
 ![Configuration Editor for Data List - available data sources](data-list--configuration-editor-02.png)
 
-For our example, let's choose **Umbraco Entity**. You will then be presented with configuration options for this data source.
+For our example, let's choose **File System**. You will then be presented with configuration options for this data source.
 
-![Configuration Editor for Data List - data source configuration (for Umbraco Entity)](data-list--configuration-editor-03.png)
+![Configuration Editor for Data List - data source configuration (for File System)](data-list--configuration-editor-03.png)
 
 Once you have configured the data source, press the **Done** button at the bottom of the overlay.
 
@@ -66,9 +66,9 @@ You can extend Data List with your own custom data sources and list editors.
 
 #### Extending with your own custom data source
 
-For creating your own custom data source, you will need to create a new C# class that implements the `Umbraco.Community.Contentment.DataEditors.IDataListSource` interface.
+For creating your own custom data source, you will need to create a new C# class that implements the [`Umbraco.Community.Contentment.DataEditors.IDataListSource`](https://github.com/leekelleher/umbraco-contentment/blob/master/src/Umbraco.Community.Contentment/DataEditors/DataList/IDataListSource.cs) interface.
 
-This interface contains one method called `GetItems()`, which must return a `IEnumerable<DataListItem>` object type.
+This interface contains one method called `GetItems(config)`, which must return a `IEnumerable<DataListItem>` object type.
 
 The `DataListItem` model is made up of four `string` properties: `Name`, `Value`, `Description` _(optional)_ and `Icon` _(optional)_.
 
@@ -83,7 +83,13 @@ public class TimeZoneDataSource : IDataListSource
 
     public string Icon => "icon-globe";
 
-    public IEnumerable<DataListItem> GetItems()
+    public OverlaySize OverlaySize => OverlaySize.Small;
+
+    public Dictionary<string, object> DefaultValues => default;
+
+    public IEnumerable<ConfigurationField> Fields => default;
+
+    public IEnumerable<DataListItem> GetItems(Dictionary<string, object> config)
     {
         var items = new List<DataListItem>();
 
@@ -101,26 +107,34 @@ public class TimeZoneDataSource : IDataListSource
 }
 ```
 
-If you require extra configuration options on your custom data source, this can be done by adding extra properties on the class itself, and marking them with Umbraco's [`ConfigurationFieldAttribute`](https://github.com/umbraco/Umbraco-CMS/blob/release-8.0.0/src/Umbraco.Core/PropertyEditors/ConfigurationFieldAttribute.cs).
+If you require extra configuration options on your custom data source, this can be done by adding properties on the `Fields` property. A property is defined using Umbraco's [`ConfigurationField`](https://github.com/umbraco/Umbraco-CMS/blob/release-8.0.0/src/Umbraco.Core/PropertyEditors/ConfigurationField.cs) model.
 
 ```csharp
-[ConfigurationField("alias", "Label (name)", "textstring", Description = "[Add a friendly description]")]
-public string ConfigOption { get; set; }
+public IEnumerable<ConfigurationField> Fields => new ConfigurationField[]
+{
+    new ConfigurationField
+    {
+        Key = "alias",
+        Name = "Label (name)",
+        Description = "[Add a friendly description]",
+        View = "textstring"
+    }
+}
 ```
 
 
 #### Extending with your own custom list editor
 
-For creating your own custom list editor, you will need to create a new C# class that implements the `Umbraco.Community.Contentment.DataEditors.IContentmentListItem` interface.
+For creating your own custom list editor, you will need to create a new C# class that implements the [`Umbraco.Community.Contentment.DataEditors.IDataListEditor`](https://github.com/leekelleher/umbraco-contentment/blob/master/src/Umbraco.Community.Contentment/DataEditors/DataList/IDataListEditor.cs) interface.
 
-This interface contains two properties, `View` and `DefaultConfig` _(optional)_.
+This interface contains two properties, `View` and `DefaultConfig` _(optional)_, and one method `HasMultipleValues(config)` returning a boolean value for whether the list editor can select multiple or single values.
 
-The `View` property should set the path of the AngularJS view file. This can be whatever you want it to be. The only prerequisite is that the AngularJS controller (for the view) will be passed the data source items, (an object array - a serialization of the `DataListItem` model), accessed by `$scope.model.config.items`.
+The `View` property should set the path of the AngularJS view file. This can be whatever you want it to be. The only requirement is that the AngularJS controller (for the view) will be passed the data source items, (an object array - a serialization of the `DataListItem` model), accessible by `$scope.model.config.items`.
 
 
 ### How to get the value?
 
-The value for the Data List is an `IEnumerable<string>`, _(regardless of whether it's a single value or multiple values)._
+The value for the Data List will either be a single value (`string`) or multiple values (`IEnumerable<string>`), _(depending on how the list-editor implements the `HasMultipleValues(config)` method)._
 
 To use this in your view templates, here are some examples.
 
@@ -145,7 +159,7 @@ Here's an example of strongly-typed...
 
 ```cshtml
 <ul>
-    @foreach (var item in @(Model.Value<string>("dataList")))
+    @foreach (var item in @(Model.Value<IEnumerable<string>>("dataList")))
     {
         <li>@item</li>
     }

docs/editors/icon-picker.md

@@ -1,4 +1,4 @@
-<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 

docs/editors/notes.md

@@ -1,4 +1,4 @@
-<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 

docs/editors/render-macro.md

@@ -1,4 +1,4 @@
-<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A shoebox of Umbraco happiness." height="130" align="right">
+<img src="../assets/img/logo.png" alt="Umbraco Contentment Logo" title="A state of Umbraco happiness." height="130" align="right">
 
 ## Umbraco Contentment
 

src/Umbraco.Community.Contentment.sln

@@ -7,9 +7,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Umbraco.Community.Contentme
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{D4F87338-D989-4C50-BF8E-EF4AF179B459}"
 	ProjectSection(SolutionItems) = preProject
-		.editorconfig = .editorconfig
 		..\LICENSE = ..\LICENSE
-		Umbraco.Community.Contentment.sln.licenseheader = Umbraco.Community.Contentment.sln.licenseheader
 		..\VERSION = ..\VERSION
 	EndProjectSection
 EndProject
@@ -55,6 +53,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ISSUE_TEMPLATE", "ISSUE_TEM
 		..\.github\ISSUE_TEMPLATE\ISSUE_FEATURE_REQUEST.md = ..\.github\ISSUE_TEMPLATE\ISSUE_FEATURE_REQUEST.md
 	EndProjectSection
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Visual Studio", "Visual Studio", "{7E3CB058-A757-42C9-9277-EB949E1D7D0E}"
+	ProjectSection(SolutionItems) = preProject
+		.editorconfig = .editorconfig
+		Umbraco.Community.Contentment.sln.licenseheader = Umbraco.Community.Contentment.sln.licenseheader
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -75,6 +79,7 @@ Global
 		{9C956438-0434-40DD-BBA0-7F837E8FF1C8} = {D4F87338-D989-4C50-BF8E-EF4AF179B459}
 		{A5294B30-2ED5-4BBA-A2DE-A07103DAE78F} = {9C956438-0434-40DD-BBA0-7F837E8FF1C8}
 		{02357F6B-DA34-47CC-BA3E-A737CEC66B0D} = {49BDDD3C-6B40-4BE9-BD7E-10C85E55A59F}
+		{7E3CB058-A757-42C9-9277-EB949E1D7D0E} = {D4F87338-D989-4C50-BF8E-EF4AF179B459}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {A8F86B45-B473-45E7-85C7-863A10E21554}

src/Umbraco.Community.Contentment/Constants.cs

@@ -37,6 +37,8 @@ internal static partial class ConfigurationFieldAliases
                 public const string DefaultValue = "defaultValue";
 
                 public const string Items = "items";
+
+                public const string OverlayView = "overlayView";
             }
 
             internal static partial class PropertyGroups