Wholething.FallbackTextProperty 1.3.0

.NET 5.0 .NET Framework 4.7.2
Install-Package Wholething.FallbackTextProperty -Version 1.3.0
dotnet add package Wholething.FallbackTextProperty --version 1.3.0
<PackageReference Include="Wholething.FallbackTextProperty" Version="1.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Wholething.FallbackTextProperty --version 1.3.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Wholething.FallbackTextProperty, 1.3.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Wholething.FallbackTextProperty as a Cake Addin
#addin nuget:?package=Wholething.FallbackTextProperty&version=1.3.0

// Install Wholething.FallbackTextProperty as a Cake Tool
#tool nuget:?package=Wholething.FallbackTextProperty&version=1.3.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Wholething Fallback Text Property

This Umbraco package provides two custom text property editors, "Textstring with Fallback" and "Textarea with Fallback", that allow developers to enter "fallback value", rendered from a Mustache template.

The fallback can be built from other node properties and properties of other specific nodes in the content tree.

If you like this property editor you may also like Wholething.FallbackImagePickerProperty.

🛠👷‍♀️ Known issues

There are a number of known issues so please check the issue tracker when in doubt.

Blocks and nested content

Blocks and nested content only have limited support since we can't retrieve an element's parent/owner in the value converter. The following references do work:

  • Referring to other nodes by ID
  • root and url functions

Use-case

The use-case for this package is simple: editors often want the option to override images/values but it is unclear what the default value is. We feel it's a significant improvement in experience for editors to be able to see the default value before deciding to override it.

Team

This property editor is a collaboration between Harry Gordon and Wholething (Dean Leigh and Ault Nathanielsz).

Installation

You can find the package on NuGet: https://www.nuget.org/packages/Wholething.FallbackTextProperty/

Configuration and editor experience

When you configure a "Textstring with Fallback" or "Textarea with Fallback" property you must configure a Mustache template to generate the fallback value.

fallback-text-1

In the example we use the following template: {{1104:heroHeader}} - {{pageTitle}} - Bar. In this case pageTitle refers to the nodes own property, 1104:heroHeader refers to the site home node's property heroHeader and the rest is literal. The result can be seen below:

fallback-text-2

Referring to other nodes

The fallback template supports the following node references:

  • Node ID: {{1069:propertyAlias}}
  • Node key: {{25eb6a38-50e0-4c1b-95d8-1526d54b06e5:propertyAlias}}
  • Parent node: {{parent:propertyAlias}}
  • Root node: {{root:propertyAlias}}
  • Ancestor by content type alias: {{ancestor(blogPost):propertyAlias}}
  • Node by URL: {{url(/global-settings/):propertyAlias}}

Debugging

As of version 1.3 we now log any template rendering errors to the Umbraco log.

Implementation

The implementation is fairly straight-forward and involves the following:

  • The property editor builds a dictionary of node properties and their values and does the same for any other nodes mentioned in the template.
  • The property editor renders the fallback template but does not store that in the field value (to avoid "caching" dependent values).
  • There is a value converter that returns either the entered value or renders the fallback value.

Limitations

There are a few notable limitations:

  • The fallback template can only handle simple properties. For example referring to other fallback properties in a fallback template wouldn't work.
  • The fallback template rendering does not currently use live values, just whatever is in the model when the editor is loaded.

Development notes

Packaging

The package is built in Azure DevOps but in the event that you need build it locally you can use the following command (replacing local-package-path and version):

dotnet pack Wholething.FallbackTextProperty\Wholething.FallbackTextProperty.csproj --output {local-package-path} /p:Configuration=Debug /p:PackageVersion={version}-local --include-symbols
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Framework net472 net48
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.3.0 67 7/18/2022
1.2.0 89 6/16/2022
1.1.25 198 2/17/2022
1.1.22 195 2/14/2022
1.1.16 1,227 12/1/2021
0.2.26 686 9/9/2021
0.1.23 189 3/24/2021
0.1.21 181 3/24/2021
0.1.11 161 2/3/2021
0.1.6 158 1/27/2021

### Version 1.3
- Improved block support: node references and some functions work but nothing tree-related (e.g. parent, ancestor, referencing properties on the node that owns the block)
- Nodes can now be referenced by GUID (e.g. `{{25eb6a38-50e0-4c1b-95d8-1526d54b06e5:propertyAlias}}`)
- Added a resolver for referencing nodes by URL (e.g. `{{url(\global-settings\):propertyAlias}}`)
- Added logging for template rendering errors, should be very helpful

### Version 1.2
- Fixed issues around multi-language sites that meant some fallback values were not rendering
- Fallbacks inside blocks/nested elements are still not supported but shouldn't cause errors

### Version 1.1
- Added SourceLink support