From c99c6a12b980a38760882b41e9c835710aaa234a Mon Sep 17 00:00:00 2001 From: Warren Buckley Date: Fri, 12 May 2023 10:20:22 +0100 Subject: [PATCH] Just push the changes of our-self-host and revert the out of sync changes --- README.md | 193 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 134 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 8e57beb..7a9f1a6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # Our Umbraco TagHelpers -A community project of C# ASP.NET TagHelpers for the Open Source CMS Umbraco +A community project of C# ASP.NET TagHelpers for the Open Source CMS Umbraco ## Installing + Add the following Nuget Package to your Umbraco website project `Our.Umbraco.TagHelpers` with Visual Studio, Rider or with the dotnet CLI tool as follows when inside the directory with the .CSProj file for the Umbraco website project. ``` @@ -14,18 +15,20 @@ dotnet add package Our.Umbraco.TagHelpers With the Nuget package added you need to register the collection of TagHelpers for Razor views and partials to use them. Browse to `/Views/_ViewImports.cshtml` in your Umbraco project and add the following line at the bottom + ```cshtml @addTagHelper *, Our.Umbraco.TagHelpers ``` ## `` + This is a tag helper element `` that will use the current page's request Language/Culture to use a dictionary translation from the Umbraco translation section. -* Find dictionary key -* Find translation for Current Culture/Language of the page -* If no translation found see if we have fallback attribute set fallback-lang or umb-dictionary-fallback-lang -* Attempt to find dictionary item for that ISO language fallback -* No translation found - leave default/value inside tag untouched for final fallback +- Find dictionary key +- Find translation for Current Culture/Language of the page +- If no translation found see if we have fallback attribute set fallback-lang or umb-dictionary-fallback-lang +- Attempt to find dictionary item for that ISO language fallback +- No translation found - leave default/value inside tag untouched for final fallback ```cshtml

My Header

@@ -33,15 +36,18 @@ This is a tag helper element `` that will use the current page's ``` ## `our-if` + This is a tag helper attribute that can be applied to any DOM element in the razor template or partial. It will include its element and children on the page if the expression inside the `our-if` attribute evaluates to true. ### Simple Example + ```cshtml
This will only render during even minutes.
This will only render during odd minutes.
``` ### Example Before + ```cshtml @if (Model.ContentPickerThing != null) { @@ -57,6 +63,7 @@ This is a tag helper attribute that can be applied to any DOM element in the raz ``` ### Example After + ```cshtml @Model.ContentPickerThing.Name @@ -65,6 +72,7 @@ This is a tag helper attribute that can be applied to any DOM element in the raz ``` ## `` + This tag helper element `` will render an Umbraco Macro Partial View and will use the current page/request for the Macro rendering & context. If you wish, you can modify this behaviour and pass the context/content node that the Macro will render with using an optional attribute `content` on the `` tag and passing an `IPublishedContent` into the attribute. This allows the same Macro Partial View Macro code/snippet to work in various scenarios when the content node/context is changed. @@ -81,11 +89,13 @@ So to pass/set a value for the macro parameter `startNodeId` then I will need to ``` ## BeginUmbracoForm Replacement + This is to make it easier to create a HTML `
` that uses an Umbraco SurfaceController and would be an alternative of using the `@Html.BeginUmbracoForm` approach. This taghelper runs against the `` element along with these attributes `our-controller`and `our-action` to help generate a hidden input field of `ufprt` containing the encoded path that this form needs to route to. https://our.umbraco.com/Documentation/Fundamentals/Code/Creating-Forms/ ### Before + ```cshtml @using (Html.BeginUmbracoForm("ContactForm", "Submit", FormMethod.Post, new { @id ="customerForm", @class = "needs-validation", @novalidate = "novalidate" })) { @@ -112,6 +122,7 @@ https://our.umbraco.com/Documentation/Fundamentals/Code/Creating-Forms/ ``` ### After + ```cshtml
@@ -137,12 +148,14 @@ https://our.umbraco.com/Documentation/Fundamentals/Code/Creating-Forms/ ``` ## `` + This tag helper element `` will create a simple unordered list of all languages and domains, in order to create a simple language switcher. -As this produces alot of HTML markup that is opionated with certain class names and elements, you may wish to change and control the markup it produces. +As this produces alot of HTML markup that is opionated with certain class names and elements, you may wish to change and control the markup it produces. With this tag helper the child DOM elements inside the `` element is used as a Mustache templating language to control the markup. ### Example + ```cshtml
@@ -165,6 +178,7 @@ With this tag helper the child DOM elements inside the `` ele ``` If you do not specify a template and use `` it will use the following Mustache template + ```mustache
    {{#Languages}} @@ -177,20 +191,22 @@ If you do not specify a template and use `` it will use the
``` - ## `` + This tag helper element `` will read the file contents of an SVG file and output it as an inline SVG in the DOM. It can be used in one of two ways, either by specifying the `src` attribute to a physcial static file served from wwwRoot or by specifying the `media-item` attribute to use a picked IPublishedContent Media Item. ### Basic usage: + ```cshtml ``` -### Advanced usage: *(as of version 1.x.x) +### Advanced usage: \*(as of version 1.x.x) + +Additional properties have been added to cache the output and also to ensure the SVG contains a viewbox property instead of the width & height properties to aid in making the vector image responsive within a parent HTML element. -Additional properties have been added to cache the output and also to ensure the SVG contains a viewbox property instead of the width & height properties to aid in making the vector image responsive within a parent HTML element. ```cshtml @@ -218,9 +234,8 @@ Applying any of the below configurations within your `appsettings.json` file wil > **Note:** SVG caches are cleared on application restart, or by resaving the media in the media library. - - ## `` + This tag helper element `` uses the same fallback mode logic that is only available on the `Value()` method of the `IPublishedContent` interface that uses a string for the property name to lookup. In addition if the fallback value from a language or ancestors is not available we are still able to fallback to the content inside the tag. ```cshtml @@ -228,10 +243,11 @@ This tag helper element `` uses the same fallback mode logic that @Model.Value("Header", fallback:Fallback.ToLanguage)

I do NOT have a DK culture variant of this property

-

I do NOT have a Header property set on ANY parent and ancestors

+

I do NOT have a Header property set on ANY parent and ancestors

``` ## `` + This tag helper element `` prints out version number for a given Assembly name loaded into the current AppDomain or if none is given then the EntryAssembly version is displayed, which would be the Umbraco website project you are building. ```cshtml @@ -243,11 +259,13 @@ This tag helper element `` prints out version number for a given As ``` ## `our-member-include` and `our-member-exclude` + This is a tag helper attribute that can be applied to any DOM element in the razor template or partial. It will show or hide its element and children on the page when passing a comma seperated string of member groups that the current logged in member for the exclude or include variants. There are two special Member Groups you can use: -* `*` - All anonymous users -* `?` - All authenticated users + +- `*` - All anonymous users +- `?` - All authenticated users ```cshtml
Only members of Staff Member Group will see this.
@@ -283,11 +301,13 @@ Use the alias of the User Group ``` ## `` -This is a tag helper element which renders an edit link on the front end only if the current user is logged into umbraco and has access to the content section. + +This is a tag helper element which renders an edit link on the front end only if the current user is logged into umbraco and has access to the content section. The link will open the current page in the umbraco backoffice. You can override the umbraco url if you are using a different url for the backoffice. ### Simple example + This is the most basic example. The link will render wherever you put it in the HTML. ```html @@ -326,12 +346,14 @@ If you want the edit link to open in a new tab, just add the `target="_blank"` a ``` ## `our-active-class` + This is a tag helper attribute that can be applied to `` element in the razor template or partial. It will use the value inside the attribute and append it to the class attribute of the ``. If the link inside the href attribute can be found by its route as a content node, if so then it will check with the current page being rendered if its the same node or an ancestor. This allows for the navigation item to still have the class added to it when a child or grandchildren page is the currently page being rendered. ### Simple Example + ```cshtml @foreach (var item in Model.Root().Children) { @@ -347,17 +369,19 @@ Alternatively you can use the `our-active-class` attribute in conjuction with `o {
  • @item.Name -
    • + } ``` ## `` + This tag helper element `` will create a simple anchor tag using the Umbraco Multi Url Picker property editor that uses the C# Model `Umbraco.Cms.Core.Models.Link` Note if the link set is an external link and you set the target of the link to be `_blank`, then the link will have the noopener attribute added to the link. ### Simple Example + ```cshtml

    Hi There

    @@ -372,12 +396,35 @@ Alternatively if you use the `` without child DOM elements then it wil With this tag helper the child DOM elements inside the `` is wrapped with the `` tag +### Making the link optional + +You can also add `Fallback` for the link to become optional, if there is no link and there is child content, this content is still rendered, you can also replace the wrapping element by using `FallbackElement`. + +```cshtml + + some text + + +@*No link will result in*@ +
    + some text +
    + + + some text + + +@*No link and no fallback HTML tag name specified will result in*@ +some text +``` + ## `` + This tag helper element `` is a wrapper around the [DotNet CacheTagHelper](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/built-in/cache-tag-helper?view=aspnetcore-6.0) - it operates in exactly the same way, with the same options as the DotNet CacheTagHelper, except, it is automatically 'not enabled', when you are in Umbraco Preview or Umbraco Debug mode. ### Without this tag helper -Essentially this is a convenience for setting +Essentially this is a convenience for setting ```cshtml [Your Long Running Expensive Code Here] @@ -390,23 +437,29 @@ Essentially this is a convenience for setting ``` ### Clearing the Cache 'on publish' + The Umbraco convention with other Cache Helpers, eg Html.CachedPartial is to clear all memory caches whenever any item is published in the Umbraco Backoffice. By default the our-cache tag helper will do the same, however you can turn this part off on an individual TagHelper basis by setting update-cache-key-on-publish="false". ```cshtml [Your Long Running Expensive Code Here] ``` + is the same as: + ```cshtml [Your Long Running Expensive Code Here] ``` + But to turn it off: + ```cshtml [Your Long Running Expensive Code Here] ``` -(NB if you had a thousand tag helpers on your site, all caching large amounts of content, and new publishes to the site occurring every second - this might be detrimental to performance, so do think of the context of your site before allowing the cache to be cleared on each publish) +(NB if you had a thousand tag helpers on your site, all caching large amounts of content, and new publishes to the site occurring every second - this might be detrimental to performance, so do think of the context of your site before allowing the cache to be cleared on each publish) ### Examples + All examples will skip the cache for Umbraco preview mode and debug mode, and evict cache items anytime Umbraco publishes content, media or dictionary items. ```cshtml @@ -424,55 +477,31 @@ All examples will skip the cache for Umbraco preview mode and debug mode, and ev ``` + This example will turn off the automatic clearing of the tag helper cache if 'any page' is published, but still clear the cache if the individual page is published: + ```cshtml

    @DateTime.Now - A set Date in time

     ``` -## `our-self-host` -This is a tag helper attribute that can be applied to any element using a `src` or `href` attribute in the razor template or partial. It will automatically download and self hosting of third party assets, like javascript, css or images. - -### Simple Example -```cshtml -