Documentation changes before release

Author: robdmoore

BREAKING_CHANGES.md

@@ -2,7 +2,94 @@
 
 This file has all breaking changes across ChameleonForms versions.
 
-# Version 4.0.0-beta
+# Version 4.0.0-beta0002
+
+## `HTMLAttributes.Attrs` now appends CSS classes rather than replacing them
+
+Previously the following would output `class="second"`, not it will output `class="first second"`:
+
+```cshtml
+    @(new HtmlAttributes().AddClass("first").Attrs(new Dictionary<string, string>{{"class", "second"}}))
+```
+
+### Reason
+
+Allowing CSS classes to be additive was an important need to implement tag helpers.
+
+### Workaround
+
+If you don't want this behaviour you can override the class using `Attr` instead of `Attrs` for the `class` attribute.
+
+
+## Removed `Partial` and non-async `PartialFor` from `Form` and `Section` and replaced `this.Form()`, `this.FormSection()` and `this.IsInFormSection()` in partial views and removed `this.PartialModelExpression()` from partial views
+
+In order to uplift the partial view capabilities of ChameleonForms and make them easier to use a number of changes have been made:
+
+* All non-async methods of invoking partial views have been removed to [prevent possible deadlocks](https://github.com/aspnet/Mvc/issues/7083)
+* Changes have been made as part of introducing tag helpers that means you don't need a special `Partial` method on forms and sections when you are keeping the form model the same; you can now just use the built-in ASP.NET Core partial functionality (i.e. `@Html.PartialAsync` or `<partial>`)
+* The ability to determine whether you are in a Form or Section has been expanded to include detection of whether you are within a Field, NAvigation or Message as well and has been implemented so it works anywhere, not just within a partial view. This facilitates tag helper syntax and also allows you to switch between tag helpers and HTML helper syntax if you want
+* `PartialModelExpression` is no longer needed with the new functionality
+
+See [the documentation](https://mrcollective.github.io/ChameleonForms/docs/partials.html) for more information.
+
+### Reason
+
+Per above.
+
+### Workaround
+
+* Invoking partial with same model as the parent (use built-in partial functionality)
+    ```cshtml
+        <partial name="_PartialWithSameModelAsParent" />
+
+        @* or *@
+
+        @await Html.PartialAsync("_PartialWithSameModelAsParent")
+    ```
+
+* Invoking partial with child property as model, but binding against parent model (use ChameleonForms partial functionality)
+    ```cshtml
+        <form-partial for="ChildProperty" name="_PartialWithChildModelBindingToParent" />
+
+        @* Or, when not in a form section *@
+        @(await f.PartialForAsync(m => m.ChildProperty, "_PartialWithChildModelBindingToParent"))
+
+        @* Or, when in a form section *@
+        @(await s.PartialForAsync(m => m.ChildProperty, "_PartialWithChildModelBindingToParent"))
+    ```
+
+* Invoking partial with child property as model and binding against that child model (use built-in partial functionality)
+    ```cshtml
+        <partial name="_PartialWithChildAsModel" model="Model?.ChildProperty" />
+
+        @* or *@
+
+        @await Html.PartialAsync("_PartialWithChildAsModel", Model?.ChildProperty)
+    ```
+
+* Invoking partial with a different model entirely from the parent (use built-in partial functionality)
+    ```cshtml
+        <partial name="_PartialWithOtherModel" model="new OtherModel()" />
+
+        @* or *@
+
+        @await Html.PartialAsync("_PartialWithOtherModel", new OtherModel())
+    ```
+
+* Accessing the current form
+    ```cs
+        Html.IsInChameleonForm()
+        Html.GetChameleonForm()
+    ```
+
+* Accessing the current form section
+    ```cs
+        Html.IsInChameleonFormsSection()
+        Html.GetChameleonFormsSection()
+    ```
+
+
+# Version 4.0.0-beta0001
 
 ## .NET Framework no longer supported
 
@@ -14,7 +101,7 @@ ChameleonForms has been upgraded to support ASP.NET Core MVC. It's much easier t
 
 ### Workaround
 
-If you want to support .NET Full Framework with MVC 5 then check out v3.0.3 of the [NuGet package](https://www.nuget.org/packages/ChameleonForms/3.0.3) and [documentation](https://chameleonforms.readthedocs.io/en/3.0.3/). If you want to use a different version of .NET Core then [raise an issue](https://github.com/MRCollective/ChameleonForms/issues) to discuss adding that support.
+If you want to support .NET Full Framework with MVC 5 then check out v3.0.3 of the [NuGet package](https://www.nuget.org/packages/ChameleonForms/3.0.3) and [documentation](hhttps://chameleonforms.readthedocs.io/). If you want to use a different version of .NET Core then [raise an issue](https://github.com/MRCollective/ChameleonForms/issues) to discuss adding that support.
 
 ## DisplayFormatString no longer used
 

ChameleonForms/ServiceCollectionExtensions.cs

@@ -14,8 +14,6 @@
 namespace ChameleonForms
 {
     // todo: 4.0 non-beta release
-    // Doco: antiforgery, HtmlAttrs Dictionary<string, string>, TagHelpers for everything, partials - new syntax, can use them natively, need special one when changing model, Html.GetChameleonFormsSection etc. extensions
-    // Breaking changes: Removed non-async partial and non `For` partial - can just use partials directly, removed WebViewPage.Form / .FormSection / .IsInFormSection / .PartialModelExpression, merge attributes now adds class
     // Build-in DI support e.g. fieldgeneratorrouter
     // Review the datetime "g" and current culture things - remove? client side validation for non / separators?
     // Update all dependencies to latest versions

README.md

@@ -31,7 +31,7 @@ It's ideally suited for situations where you want to **quickly** build forms tha
 
 ### Prerequisites
 
-This library works against netcoreapp3.1. If you are using a different version of .NET Core or are running ASP.NET Core against Full Framework then feel free to [raise an issue](https://github.com/MRCollective/ChameleonForms/issues) to discuss opening up broader support. If you are using ASP.NET MVC 5 then check out v3.0.3 of the [NuGet package](https://www.nuget.org/packages/ChameleonForms/3.0.3) and [documentation](https://chameleonforms.readthedocs.io/en/3.0.3/).
+This library works against netcoreapp3.1. If you are using a different version of .NET Core or are running ASP.NET Core against Full Framework then feel free to [raise an issue](https://github.com/MRCollective/ChameleonForms/issues) to discuss opening up broader support. If you are using ASP.NET MVC 5 then check out v3.0.3 of the [NuGet package](https://www.nuget.org/packages/ChameleonForms/3.0.3) and [documentation](https://chameleonforms.readthedocs.io/).
 
 This library works against ASP.NET Core MVC - if you want to use it for Blazor or Razor Pages then feel free to [raise an issue](https://github.com/MRCollective/ChameleonForms/issues) to discuss.
 

docs/html-attributes.md

@@ -33,6 +33,15 @@ The `HtmlAttributes` class looks like this and is in the `ChameleonForms` namesp
         /// <param name="attributes">A dictionary of attributes</param>
         public HtmlAttributes(IDictionary<string, object> attributes);
 
+        /// <summary>
+        /// Constructs a <see cref="HtmlAttributes"/> object using a dictionary to express the attributes.
+        /// </summary>
+        /// <example>
+        /// var h = new HtmlAttributes(new Dictionary&lt;string, string&gt; {{"style", "width: 100%;"}, {"cellpadding", "0"}, {"class", "class1 class2"}, {"src", "http://url/"}, {"data-somedata", "\"rubbi&amp;h\""}});
+        /// </example>
+        /// <param name="attributes">A dictionary of attributes</param>
+        public HtmlAttributes(IDictionary<string, string> attributes);
+
         /// <summary>
         /// Constructs a <see cref="HtmlAttributes"/> object using an anonymous object to express the attributes.
         /// </summary>
@@ -120,13 +129,27 @@ The `HtmlAttributes` class looks like this and is in the `ChameleonForms` namesp
         /// <returns>The <see cref="HtmlAttributes"/> attribute to allow for method chaining</returns>
         public HtmlAttributes Attrs(object attributes);
 
+        /// <summary>
+        /// Adds or updates a set of HTML attributes using a dictionary to express the attributes.
+        /// </summary>
+        /// <param name="attributes">A dictionary of attributes</param>
+        /// <returns>The <see cref="HtmlAttributes"/> attribute to allow for method chaining</returns>
+        public HtmlAttributes Attrs(IDictionary<string, string> attributes);
+
         /// <summary>
         /// Implicitly convert from a dictionary to a new <see cref="HtmlAttributes"/> object.
         /// </summary>
         /// <param name="attributes">The dictionary of HTML attributes</param>
         /// <returns>The new <see cref="HtmlAttributes"/> object</returns>
         public static implicit operator HtmlAttributes(Dictionary<string, object> attributes);
 
+        /// <summary>
+        /// Implicitly convert from a dictionary to a new <see cref="HtmlAttributes"/> object.
+        /// </summary>
+        /// <param name="attributes">The dictionary of HTML attributes</param>
+        /// <returns>The new <see cref="HtmlAttributes"/> object</returns>
+        public static implicit operator HtmlAttributes(Dictionary<string, string> attributes);
+
         /// <inheritdoc />
         public virtual void WriteTo(TextWriter writer, HtmlEncoder encoder);
 
@@ -163,7 +186,8 @@ Most `HTMLAttributes` methods map to a tag helper attribute by convention - `Upp
 | `Attr(string key, object value)`                      | `attr-{key}="{value}"`                                |
 | `Attr(Func<object, object> attribute)`                | *No equivalent*                                       |
 | `Attrs(params Func<object, object>[] attributes)`     | *No equivalent*                                       |
-| `Attrs(IDictionary<string, object> attributes)`       | `attrs="{attributes}"`                                |
+| `Attrs(IDictionary<string, object> attributes)`       | *No equivalent*                                       |
+| `Attrs(IDictionary<string, string> attributes)`       | `attrs="{attributes}"`                                |
 | `Attrs(object attributes)`                            | *No equivalent*                                       |
 | `Disabled(bool disabled = true)`                      | `disabled="{disabled}"`                               |
 | `Readonly(bool @readonly = true)`                     | *No equivalent*                                       |
@@ -236,6 +260,7 @@ You can convert a dictionary to a HTML Attributes object, e.g.:
 
 ```cs
 new Dictionary<string, object>{ {"class", "form"}, {"id", "someForm"} }.ToHtmlAttributes()
+new Dictionary<string, string>{ {"class", "form"}, {"id", "someForm"} }.ToHtmlAttributes()
 ```
 
 ## Outputting HTML Attributes

docs/the-form.md

@@ -93,7 +93,7 @@ The `BeginChameleonForm` extension method looks like this:
 
 ***
 
-By default a self-submitting form, against the page model type, that performs a HTTP post with the browser's default `enctype` (usually `application/x-www-form-urlencoded`) is outputted, but you can change the submit location, HTTP verb, `enctype` and add any [HTML attributes you like](html-attributes.md) using the appropriate parameters, e.g.:
+By default a self-submitting form, against the page model type, that performs a HTTP post with the browser's default `enctype` (usually `application/x-www-form-urlencoded`) is outputted, but you can change the submit location, HTTP verb, `enctype`, presence of anti forgery token and add any [HTML attributes you like](html-attributes.md) using the appropriate parameters, e.g.:
 
 # [Tag Helpers variant](#tab/configure-form-th)
 
@@ -162,6 +162,7 @@ If you want to override this behaviour you can configure your own form template.
 
 ```html
 <form action="%action%" method="%method%" (enctype="%enctype%") (%htmlAttributes%) novalidate="novalidate">
+    (%antiforgery token%)
 ```
 
 ### End HTML