Preparing v3.0.0 release

.github/CONTRIBUTING.md

@@ -1,8 +1,10 @@
 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.
+### General gist
 
-Once the feature or idea is fleshed out, let's hack!
+First, before writing any code, [please open an issue](https://github.com/leekelleher/umbraco-contentment/issues), or [let's have a discussion](https://github.com/leekelleher/umbraco-contentment/discussions) about any features or ideas that you may have.
+
+Once the feature or idea is fleshed out, it's hacking time!
 
 1. Fork it
 2. Branch it
@@ -15,7 +17,18 @@ 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.
+### Branching information
+
+Given there are now multiple versions of Contentment that support multiple versions of Umbraco, please make note of the branching structure.
+
+- The main [`develop`](https://github.com/leekelleher/umbraco-contentment/tree/develop) branch is where the latest work happens. This defaults to the most recent version of Contentment, (at the time of writing, this is v3.x).
+- The [`dev/v1.x`](https://github.com/leekelleher/umbraco-contentment/tree/dev/v1.x) branch is for Contentment **v1.4.x** patch releases, this targets Umbraco **v8.6.1**.
+- The [`dev/v2.x`](https://github.com/leekelleher/umbraco-contentment/tree/dev/v2.x) branch is for Contentment **v2.2.x** patch releases, this targets Umbraco **v8.14.0**.
+- The [`dev/v3.x`](https://github.com/leekelleher/umbraco-contentment/tree/dev/v3.x) branch is for Contentment **v3.x** (current) releases, this targets both Umbraco **v8.17.0** and **v9.0.0**.
+
+
+### 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 down the conversation, this is most likely the rationale behind it.
 

.github/README.md

@@ -46,21 +46,25 @@ Downloads are available on the [releases page](https://github.com/leekelleher/um
 
 _**Please note...**_
 
-- v3.x has been developed against **Umbraco v9.0-RC001** and will support that version and above.
-- v2.x has been developed against **Umbraco v8.14.0** and will support that and future Umbraco v8.x releases.
+- v3.x has been developed against **Umbraco v8.17.0** and **Umbraco v9.0.0** and will support those versions and above.
+- v2.x has been developed against **Umbraco v8.14.0** and it will still work on current Umbraco v8.x releases.
 - v1.x has been developed against **Umbraco v8.6.1**, it will still work on current Umbraco v8.x releases.
 
-With Contentment v3.x (Umbraco v9.0 / .NET 5), you can only install a package from the [NuGet package repository](https://www.nuget.org/packages/Our.Umbraco.Community.Contentment). For previous Contentment versions, the package can be installed from either [Our Umbraco](https://our.umbraco.com/packages/backoffice-extensions/contentment/) or NuGet package repositories, or build manually from the source-code:
+With Contentment v3.x on Umbraco v9.0 (.NET 5), you can only install a package from the [NuGet package repository](https://www.nuget.org/packages/Our.Umbraco.Community.Contentment). For Umbraco v8.x, the package can still be installed from either [Our Umbraco](https://our.umbraco.com/packages/backoffice-extensions/contentment/) or NuGet package repositories.
 
 ##### 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
 
+...or if you are using the `dotnet` command line interface?
+
+    dotnet add package Our.Umbraco.Community.Contentment
+
 ##### Our Umbraco package repository
 
-For Contentment v1.x and v2.x, you can install from Our Umbraco, please download the package from:
+If you are using Umbraco v8.x, and prefer to install Contentment from the backoffice, the package can be downloaded from the Our Umbraco package repository:
 
 > <https://our.umbraco.com/packages/backoffice-extensions/contentment/>
 
@@ -69,6 +73,7 @@ For Contentment v1.x and v2.x, you can install from Our Umbraco, please download
 - **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.](https://github.com/leekelleher/umbraco-contentment/issues/30)
   - When using the Umbraco Content data source with an XPath query that contains a `$` prefix parameter, the preview will not display the items. [See #120 for details.](https://github.com/leekelleher/umbraco-contentment/issues/120)
+  - With Umbraco v9 (Contentment v3), SQL data source does not support querying SQL CE. [See #172 for details.]()
 
 
 ### Documentation
@@ -135,7 +140,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>1050+ hours</b> (between 2019-03-13 to 2021-07-09)</summary>
+<summary>Current development effort: <b>1097+ hours</b> (between 2019-03-13 to 2021-10-15)</summary>
 
 _To give you an idea of how much human developer time/effort has been put into making this package._
 

.github/ROADMAP.md

@@ -60,16 +60,16 @@ Property Editors are:
 
 - [Templated Label](https://github.com/leekelleher/umbraco-contentment/discussions/100)
 
-### v2.3
-
-- [Data List: Groups](https://github.com/leekelleher/umbraco-contentment/discussions/90)
-
 
 ## v3
 
 ### v3.0
 
-- A breaking-change release of latest v2.x features that compiles against Umbraco CMS v9.0 (.NET 5).
+- _Under active development!_ [See my developer's journal for the latest updates.](https://github.com/leekelleher/umbraco-contentment/discussions/105) A breaking-change release _(following SemVer guidelines),_ of v2.x features that will compile against both Umbraco v8.17 and v9.0.
+
+### v3.1
+
+- [Data List: Groups](https://github.com/leekelleher/umbraco-contentment/discussions/90)
 
 
 ## Future feature releases

.gitignore

@@ -16,6 +16,5 @@ build/assets/
 src/packages/*/**
 /tools/*.exe
 /build/__umb/*
-/build/__nuget/*
 /build/build-push-nuget.ps1
 /build/build-push-umb.ps1

VERSION

@@ -1 +1 @@
-2.2.1
+3.0.0

build/_nuget-post-install.targets

@@ -0,0 +1,35 @@
+<!-- Copyright © 2021 Bjarke Berg.
+   - This Source Code has been derived from Bjarke Berg's Open Street Map.
+   - https://github.com/bergmania/Bergmania.OpenStreetMap/blob/main/Bergmania.OpenStreetMap/build/Bergmania.OpenStreetMap.targets
+   - Modified under the permissions of the MIT License.
+   - Modifications are licensed under the Mozilla Public License.
+   - Copyright © 2021 Lee Kelleher.
+   - This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at https://mozilla.org/MPL/2.0/. -->
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+    <PropertyGroup>
+        <ContentmentPackageContentFilesPath>$(MSBuildThisFileDirectory)..\content\App_Plugins\Contentment\**\*.*</ContentmentPackageContentFilesPath>
+    </PropertyGroup>
+
+    <Target Name="CopyContentmentPackageAssets" BeforeTargets="Build">
+        <ItemGroup>
+            <ContentmentPackageContentFiles Include="$(ContentmentPackageContentFilesPath)" />
+        </ItemGroup>
+        <Message Text="Copying Contentment package files: $(ContentmentPackageContentFilesPath) - #@(ContentmentPackageContentFiles->Count()) files" Importance="high" />
+        <Copy
+            SourceFiles="@(ContentmentPackageContentFiles)"
+            DestinationFiles="@(ContentmentPackageContentFiles->'$(MSBuildProjectDirectory)\App_Plugins\Contentment\%(RecursiveDir)%(Filename)%(Extension)')"
+            SkipUnchangedFiles="true" />
+    </Target>
+
+    <Target Name="ClearContentmentPackageAssets" BeforeTargets="Clean">
+        <ItemGroup>
+            <ContentmentPackageDir Include="$(MSBuildProjectDirectory)\App_Plugins\Contentment\" />
+        </ItemGroup>
+        <Message Text="Clear old Contentment package files" Importance="high" />
+        <RemoveDir Directories="@(ContentmentPackageDir)" />
+    </Target>
+
+</Project>

build/build-assets.ps1

@@ -4,26 +4,27 @@
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 param(
-    [string]$SolutionDir,
+    [string]$TargetFramework,
     [string]$TargetDir,
     [string]$ProjectName,
     [string]$ProjectDir,
     [string]$ConfigurationName
 );
 
-. "${SolutionDir}_vars.ps1";
+$rootDir = "${ProjectDir}..\..";
+. "${rootDir}\src\_vars.ps1";
 
 Write-Host $ConfigurationName;
 
 if ($ConfigurationName -eq 'Debug') {
-    Write-Host $SolutionDir;
+    Write-Host $TargetFramework;
     Write-Host $TargetDir;
     Write-Host $ProjectName;
     Write-Host $ProjectDir;
     Write-Host $TargetDevWebsite;
 }
 
-$targetFolder = "${SolutionDir}..\build\assets";
+$targetFolder = "${rootDir}\build\assets";
 
 # If it already exists, delete it
 if (Test-Path -Path $targetFolder) {
@@ -32,9 +33,11 @@ if (Test-Path -Path $targetFolder) {
 
 # Copy DLL / PDB
 $binFolder = "${targetFolder}\bin";
-
 if (!(Test-Path -Path $binFolder)) {New-Item -Path $binFolder -Type Directory;}
-Copy-Item -Path "${TargetDir}${ProjectName}.*" -Destination $binFolder;
+Copy-Item -Path "${ProjectDir}\bin\${ConfigurationName}\net472\${ProjectName}.*" -Destination $binFolder;
+$net50Folder = "${targetFolder}\net50";
+if (!(Test-Path -Path $net50Folder)) {New-Item -Path $net50Folder -Type Directory;}
+Copy-Item -Path "${ProjectDir}\bin\${ConfigurationName}\net50\${ProjectName}.*" -Destination $net50Folder;
 
 # Copy package front-end files assets
 $pluginFolder = "${targetFolder}\App_Plugins\Contentment\";
@@ -61,14 +64,14 @@ foreach($razorFile in $razorFiles){
 # CSS - Bundle & Minify
 $targetCssPath = "${pluginFolder}contentment.css";
 Get-Content -Raw -Path "${ProjectDir}**\**\*.css" | Set-Content -Encoding UTF8 -Path $targetCssPath;
-& "${SolutionDir}..\tools\AjaxMinifier.exe" $targetCssPath -o $targetCssPath
+& "${rootDir}\tools\AjaxMinifier.exe" $targetCssPath -o $targetCssPath
 
 # JS - Bundle & Minify
 $targetJsPath = "${pluginFolder}contentment.js";
 Get-Content -Raw -Path "${ProjectDir}**\**\*.js" | Set-Content -Encoding UTF8 -Path $targetJsPath;
-& "${SolutionDir}..\tools\AjaxMinifier.exe" $targetJsPath -o $targetJsPath
+& "${rootDir}\tools\AjaxMinifier.exe" $targetJsPath -o $targetJsPath
 
 # In debug mode, copy the assets over to the local dev website
 if ($ConfigurationName -eq 'Debug' -AND -NOT($TargetDevWebsite -eq '')) {
-    Copy-Item -Path "${targetFolder}\*" -Force -Recurse -Destination $TargetDevWebsite;
+    Copy-Item -Path "${targetFolder}\*" -Force -Recurse -Destination $TargetDevWebsite | Where { $_.FullName -NotLike "*\net50\*" };
 }

build/build-pkgs.ps1

@@ -10,14 +10,14 @@ $nugetPackageId = 'Our.Umbraco.Community.Contentment';
 $projectNamespace = 'Umbraco.Community.Contentment';
 $packageName = 'Contentment';
 $nugetTitle = "${packageName} for Umbraco";
-$packageDescription = "${packageName}, a collection of components for Umbraco 8.";
+$packageDescription = "${packageName}, a collection of components for Umbraco.";
 $packageUrl = 'https://github.com/leekelleher/umbraco-contentment';
 $iconUrl = 'https://raw.githubusercontent.com/leekelleher/umbraco-contentment/master/docs/assets/img/logo.png';
 $licenseName = 'Mozilla Public License Version 2.0';
 $licenseUrl = 'https://mozilla.org/MPL/2.0/';
 $authorName = 'Lee Kelleher';
 $authorUrl = 'https://leekelleher.com/';
-$minUmbracoVersion = 8,14,0;
+$minUmbracoVersion = 8,17,0;
 $copyright = "Copyright " + [char]0x00A9 + " " + (Get-Date).year + " $authorName";
 $tags = "umbraco";
 
@@ -81,7 +81,7 @@ $umbracoPackageXml.umbPackage.info.readme."#cdata-section" = $packageDescription
 
 $filesXml = $umbracoPackageXml.CreateElement("files");
 
-$assetFiles = Get-ChildItem -Path $assetsFolder -File -Recurse;
+$assetFiles = Get-ChildItem -Path $assetsFolder -File -Recurse | Where { $_.FullName -NotLike "*\net50\*" };
 foreach($assetFile in $assetFiles){
 
     $hash = Get-FileHash -Path $assetFile.FullName -Algorithm MD5;
@@ -106,8 +106,9 @@ Compress-Archive -Path "${umbFolder}\*" -DestinationPath "${artifactsFolder}\Con
 # Populate the NuGet package manifest
 
 Copy-Item -Path "${rootFolder}\docs\assets\img\logo.png" -Destination "${assetsFolder}\icon.png";
-& $nuget_exe pack "${buildFolder}\manifest-nuget-core.nuspec" -BasePath $assetsFolder -OutputDirectory $artifactsFolder -Version "$version" -Properties "id=$nugetPackageId;version=$version;title=$nugetTitle;authors=$authorName;owners=$authorName;projectUrl=$packageUrl;requireLicenseAcceptance=false;description=$packageDescription;copyright=$copyright;license=MPL-2.0;language=en;tags=$tags;minUmbracoVersion=$($minUmbracoVersion[0]).$($minUmbracoVersion[1]).$($minUmbracoVersion[2]);repositoryUrl=$packageUrl;"
-& $nuget_exe pack "${buildFolder}\manifest-nuget-web.nuspec" -BasePath $assetsFolder -OutputDirectory $artifactsFolder -Version "$version" -Properties "id=$nugetPackageId;version=$version;title=$nugetTitle;authors=$authorName;owners=$authorName;projectUrl=$packageUrl;requireLicenseAcceptance=false;description=$packageDescription;copyright=$copyright;license=MPL-2.0;language=en;tags=$tags;minUmbracoVersion=$($minUmbracoVersion[0]).$($minUmbracoVersion[1]).$($minUmbracoVersion[2]);repositoryUrl=$packageUrl;"
+Copy-Item -Path "${buildFolder}\_nuget-post-install.targets" -Destination "${assetsFolder}\${nugetPackageId}.targets";
+& $nuget_exe pack "${buildFolder}\manifest-nuget-core.nuspec" -BasePath $assetsFolder -OutputDirectory $artifactsFolder -Version "$version" -Properties "id=$nugetPackageId;version=$version;title=$nugetTitle;authors=$authorName;owners=$authorName;projectUrl=$packageUrl;requireLicenseAcceptance=false;description=$packageDescription;copyright=$copyright;license=MPL-2.0;language=en;tags=$tags;repositoryUrl=$packageUrl;"
+& $nuget_exe pack "${buildFolder}\manifest-nuget-web.nuspec" -BasePath $assetsFolder -OutputDirectory $artifactsFolder -Version "$version" -Properties "id=$nugetPackageId;version=$version;title=$nugetTitle;authors=$authorName;owners=$authorName;projectUrl=$packageUrl;requireLicenseAcceptance=false;description=$packageDescription;copyright=$copyright;license=MPL-2.0;language=en;tags=$tags;repositoryUrl=$packageUrl;"
 
 
 # Tidy up folders

build/manifest-nuget-core.nuspec

@@ -17,13 +17,17 @@
     <repository type="git" url="$repositoryUrl$" />
     <dependencies>
       <group targetFramework="net472">
-        <dependency id="UmbracoCms.Core" version="[$minUmbracoVersion$, 9.0.0)" />
-        <dependency id="UmbracoCms.Web" version="[$minUmbracoVersion$, 9.0.0)" />
+        <dependency id="UmbracoCms.Web" version="[8.17.0, 9.0.0)" />
+      </group>
+      <group targetFramework="net50">
+        <dependency id="Umbraco.Cms.Web.Website" version="[9.0.0, 10.0.0)" />
+        <dependency id="Umbraco.Cms.Web.BackOffice" version="[9.0.0, 10.0.0)" />
       </group>
     </dependencies>
   </metadata>
   <files>
-    <file src="bin\*.*" target="lib\net472" />
+    <file src="bin\*.dll" target="lib\net472" />
+    <file src="net50\*.dll" target="lib\net5.0" />
     <file src="icon.png" target="" />
   </files>
 </package>

build/manifest-nuget-web.nuspec

@@ -21,6 +21,7 @@
   </metadata>
   <files>
     <file src="App_Plugins\**\*.*" target="content\App_Plugins" />
+    <file src="*.targets" target="buildTransitive\" />
     <file src="icon.png" target="" />
   </files>
 </package>

docs/README.md

@@ -38,3 +38,6 @@ If you are unfamiliar with how to do this, then please refer to documentation, g
 
 Information about Contentment's [telemetry feature](../docs/telemetry.md).
 
+#### Tree Dashboard
+
+Information about Contentment's [tree dashboard](../docs/tree-dashboard.md).

docs/telemetry.md

@@ -35,6 +35,12 @@ For information about the data and analysis, please go to: <https://leekelleher.
 
 If you would prefer to disable the telemetry feature completely, you can use this code snippet to disable it.
 
+##### For Umbraco v8
+
+Code snippet to disable Contentment telemetry.
+
+Copy the C# class below. You can either save this to your `~/App_Code/` folder, or add it to your own code library.
+
 ```csharp
 using Umbraco.Core.Composing;
 
@@ -52,3 +58,20 @@ namespace Our.Umbraco.Web
 
 If you already have your own composer class, you can add the `composition.DisableContentmentTelemetry();` line to it.
 
+##### For Umbraco v9+
+
+Configuration to disable Contentment telemetry.
+
+In your `appsettings.json` file, add this option inside the `"Umbraco"` section, add the following.
+
+```json
+{
+    "Umbraco": {
+        "Contentment": {
+            "DisableTelemetry": true
+        }
+    }
+}
+```
+
+If you prefer to use a strongly-typed configuration in C# code, you can do this with the `.AddContentment(opts => { opts.DisableTelemetry = true; })` extension method in your `Startup.cs` file `ConfigureServices()` method.

docs/tree-dashboard.md

@@ -0,0 +1,53 @@
+<img src="assets/img/logo.png" alt="Contentment for Umbraco logo" title="A state of Umbraco happiness." height="130" align="right">
+
+## Contentment for Umbraco
+
+### Tree Dashboard
+
+By default, the package will display a Contentment tree item in the Settings section. Currently, this is used for promotional purposes, to give information about the package itself, newsletter sign-up, etc.
+
+
+#### Disable tree dashboard
+
+If you would prefer to disable the tree dashboard completely, you can use this code snippet to disable it.
+
+##### For Umbraco v8
+
+Code snippet to disable Contentment tree dashboard.
+
+Copy the C# class below. You can either save this to your `~/App_Code/` folder, or add it to your own code library.
+
+```csharp
+using Umbraco.Core.Composing;
+
+namespace Our.Umbraco.Web
+{
+    public class DisableContentmentTreeComposer : IUserComposer
+    {
+        public void Compose(Composition composition)
+        {
+            composition.DisableContentmentTree();
+        }
+    }
+}
+```
+
+If you already have your own composer class, you can add the `composition.DisableContentmentTree();` line to it.
+
+##### For Umbraco v9+
+
+Configuration to disable Contentment tree dashboard.
+
+In your `appsettings.json` file, add this option inside the `"Umbraco"` section, add the following.
+
+```json
+{
+    "Umbraco": {
+        "Contentment": {
+            "DisableTree": true
+        }
+    }
+}
+```
+
+If you prefer to use a strongly-typed configuration in C# code, you can do this with the `.AddContentment(opts => { opts.DisableTree = true; })` extension method in your `Startup.cs` file `ConfigureServices()` method.