From 77066a3ade6a7afbd0ceb12889a2b19a4a3c335c Mon Sep 17 00:00:00 2001 From: dougbu Date: Sat, 9 Aug 2014 01:12:06 -0700 Subject: [PATCH] Improve XML comments in `HtmlHelper` and related classes and interfaces - #847 line 1: copy XML comments from interfaces to extension methods - lots of wording changes to be more consistent - core text split from PR #866, where @rynowak and I hashed out the words - to extent possible, reuse words between method descriptions - add a few missing `` and `` elements and fill in empty ones - display more HTML elements as tags - use `true|false|null` more often - add `` describing behaviour of input helpers e.g. `CheckBox()` - add `` explaining "renders" - add `` containing example expression names nits: - "The expression" -> "An expression" - make examples for `ObjectToDictionary()` and `AnonymousObjectToHtmlAttributes()` more consistent - move `` elements (that existed) after all `` elements - explain "checked" attributes better, removing some duplicated words from the `RadioButton[For]()` descriptions - correct `routeValues` description in `GenerateForm()` comments --- .../Rendering/Html/HtmlHelper.cs | 17 +- .../Rendering/HtmlHelperDisplayExtensions.cs | 300 ++++++ .../HtmlHelperDisplayNameExtensions.cs | 2 +- .../Rendering/HtmlHelperEditorExtensions.cs | 300 ++++++ .../Rendering/HtmlHelperFormExtensions.cs | 149 +++ .../Rendering/HtmlHelperInputExtensions.cs | 899 ++++++++++++++++++ .../Rendering/HtmlHelperLabelExtensions.cs | 78 ++ .../Rendering/HtmlHelperLinkExtensions.cs | 157 +++ .../Rendering/HtmlHelperPartialExtensions.cs | 83 +- .../Rendering/HtmlHelperSelectExtensions.cs | 190 ++++ .../HtmlHelperValidationExtensions.cs | 314 ++++++ .../Rendering/HtmlHelperValueExtensions.cs | 4 +- .../Rendering/IHtmlHelper.cs | 610 ++++++++---- .../Rendering/IHtmlHelperOfT.cs | 378 +++++--- 14 files changed, 3141 insertions(+), 340 deletions(-) diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs index b10421fb8f..5cd4d9a0c7 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs @@ -126,7 +126,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// If the object is already an instance, then it is /// returned as-is. /// - /// new { property_name = "value" } will translate to the entry { "property_name" , "value" } + /// new { data_name="value" } will translate to the entry { "data_name", "value" } /// in the resulting dictionary. /// /// @@ -144,7 +144,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// If the object is already an instance, then it is /// returned as-is. /// - /// new { data_name="value" } will translate to the entry { "data-name" , "value" } + /// new { data_name="value" } will translate to the entry { "data-name", "value" } /// in the resulting dictionary. /// /// @@ -633,16 +633,21 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// The name of the action method. /// The name of the controller. - /// An object that contains the parameters for a route. The parameters are retrieved - /// through reflection by examining the properties of the object. This object is typically created using object - /// initializer syntax. Alternatively, an instance containing the - /// route parameters. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route parameters. + /// /// The HTTP method for processing the form, either GET or POST. /// An instance containing HTML /// attributes to set for the element. /// /// An instance which emits the </form> end tag when disposed. /// + /// + /// In this context, "renders" means the method writes its output using . + /// protected virtual MvcForm GenerateForm(string actionName, string controllerName, object routeValues, FormMethod method, IDictionary htmlAttributes) { diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayExtensions.cs index c1a8055b19..ccac3b81b7 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayExtensions.cs @@ -6,13 +6,62 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Display-related extensions for and . + /// public static class HtmlHelperDisplayExtensions { + /// + /// Returns HTML markup for the , using a display template. The template is found + /// using the 's . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. + /// + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Display([NotNull] this IHtmlHelper html, string expression) { return html.Display(expression, templateName: null, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using a display template and specified + /// additional view data. The template is found using the 's + /// . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. + /// + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Display( [NotNull] this IHtmlHelper html, string expression, @@ -22,6 +71,28 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using a display template. The template is found + /// using the or the 's + /// . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. + /// + /// The name of the template used to create the HTML markup. + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Display( [NotNull] this IHtmlHelper html, string expression, @@ -30,6 +101,33 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.Display(expression, templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using a display template and specified + /// additional view data. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. + /// + /// The name of the template used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Display( [NotNull] this IHtmlHelper html, string expression, @@ -39,6 +137,32 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.Display(expression, templateName, htmlFieldName: null, additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using a display template and specified HTML + /// field name. The template is found using the or the + /// 's. + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. + /// + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Display( [NotNull] this IHtmlHelper html, string expression, @@ -48,6 +172,19 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.Display(expression, templateName, htmlFieldName, additionalViewData: null); } + /// + /// Returns HTML markup for the , using a display template. The template is found + /// using the 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// public static HtmlString DisplayFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression) { @@ -55,6 +192,25 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: null); } + /// + /// Returns HTML markup for the , using a display template and specified + /// additional view data. The template is found using the 's + /// . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// public static HtmlString DisplayFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, object additionalViewData) @@ -63,6 +219,21 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using a display template. The template is found + /// using the or the 's + /// . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template used to create the HTML markup. + /// The type of the model. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// public static HtmlString DisplayFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName) @@ -70,6 +241,26 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.DisplayFor(expression, templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using a display template and specified + /// additional view data. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// public static HtmlString DisplayFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName, @@ -79,6 +270,25 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using a display template and specified HTML + /// field name. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for properties + /// that have the same name. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// public static HtmlString DisplayFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName, @@ -88,23 +298,76 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using a display template. The template is found using the + /// model's . + /// + /// The instance this method extends. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html) { return html.Display(expression: null, templateName: null, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using a display template and specified additional view data. The + /// template is found using the model's . + /// + /// The instance this method extends. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html, object additionalViewData) { return html.Display(expression: null, templateName: null, htmlFieldName: null, additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the current model, using a display template. The template is found using the + /// or the model's . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel([NotNull] this IHtmlHelper html, string templateName) { return html.Display(expression: null, templateName: templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using a display template and specified additional view data. The + /// template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel( [NotNull] this IHtmlHelper html, string templateName, @@ -114,6 +377,22 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the current model, using a display template and specified HTML field name. The + /// template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel( [NotNull] this IHtmlHelper html, string templateName, @@ -123,6 +402,27 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using a display template, specified HTML field name, and + /// additional view data. The template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// current model. + /// public static HtmlString DisplayForModel( [NotNull] this IHtmlHelper html, string templateName, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs index aead4fcb00..201df16063 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs @@ -29,7 +29,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// The instance this method extends. /// - /// The expression to be evaluated against an item in the current model. + /// An expression to be evaluated against an item in the current model. /// The type of items in the model collection. /// The type of the result. /// A containing the display name. diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperEditorExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperEditorExtensions.cs index e4911c9ad6..16bb253ec5 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperEditorExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperEditorExtensions.cs @@ -6,42 +6,198 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Editor-related extensions for and . + /// public static class HtmlHelperEditorExtensions { + /// + /// Returns HTML markup for the , using an editor template. The template is found + /// using the 's . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. + /// + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression) { return html.Editor(expression, templateName: null, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using an editor template and specified + /// additional view data. The template is found using the 's + /// . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. + /// + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, object additionalViewData) { return html.Editor(expression, templateName: null, htmlFieldName: null, additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using an editor template. The template is found + /// using the or the 's + /// . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. + /// + /// The name of the template used to create the HTML markup. + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName) { return html.Editor(expression, templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using an editor template and specified + /// additional view data. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. + /// + /// The name of the template used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName, object additionalViewData) { return html.Editor(expression, templateName, htmlFieldName: null, additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using an editor template and specified HTML + /// field name. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. + /// + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// public static HtmlString Editor([NotNull] this IHtmlHelper html, string expression, string templateName, string htmlFieldName) { return html.Editor(expression, templateName, htmlFieldName, additionalViewData: null); } + /// + /// Returns HTML markup for the , using an editor template. The template is found + /// using the 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression) { return html.EditorFor(expression, templateName: null, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using an editor template and specified + /// additional view data. The template is found using the 's + /// . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, object additionalViewData) { @@ -49,12 +205,47 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using an editor template. The template is found + /// using the or the 's + /// . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template that is used to create the HTML markup. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName) { return html.EditorFor(expression, templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the , using an editor template and specified + /// additional view data. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template that is used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName, object additionalViewData) { @@ -62,29 +253,101 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the , using an editor template and specified HTML + /// field name. The template is found using the or the + /// 's . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The name of the template that is used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for properties + /// that have the same name. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string templateName, string htmlFieldName) { return html.EditorFor(expression, templateName, htmlFieldName, additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using an editor template. The template is found using the + /// model's . + /// + /// The instance this method extends. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html) { return html.Editor(expression: null, templateName: null, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using an editor template and specified additional view data. The + /// template is found using the model's . + /// + /// The instance this method extends. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the current model. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, object additionalViewData) { return html.Editor(expression: null, templateName: null, htmlFieldName: null, additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the current model, using an editor template. The template is found using the + /// or the model's . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the current model. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName) { return html.Editor(expression: null, templateName: templateName, htmlFieldName: null, additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using an editor template and specified additional view data. The + /// template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the current model. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName, object additionalViewData) { @@ -92,6 +355,22 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: additionalViewData); } + /// + /// Returns HTML markup for the current model, using an editor template and specified HTML field name. The + /// template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the current model. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName, string htmlFieldName) { @@ -99,6 +378,27 @@ namespace Microsoft.AspNet.Mvc.Rendering additionalViewData: null); } + /// + /// Returns HTML markup for the current model, using an editor template, specified HTML field name, and + /// additional view data. The template is found using the or the model's + /// . + /// + /// The instance this method extends. + /// The name of the template used to create the HTML markup. + /// + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. + /// + /// + /// An anonymous or + /// that can contain additional view data that will be merged into the + /// instance created for the template. + /// + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the current model. + /// public static HtmlString EditorForModel([NotNull] this IHtmlHelper html, string templateName, string htmlFieldName, object additionalViewData) { diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperFormExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperFormExtensions.cs index 7afcba095d..fbfda8af2a 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperFormExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperFormExtensions.cs @@ -3,8 +3,23 @@ namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// DisplayName-related extensions for . + /// public static class HtmlHelperFormExtensions { + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by same action. That is the rendered URL will match the current + /// request. + /// + /// The instance this method extends. + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper) { // Generates
. @@ -12,12 +27,41 @@ namespace Microsoft.AspNet.Mvc.Rendering method: FormMethod.Post, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The HTTP method for processing the form, either GET or POST. + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper, FormMethod method) { return htmlHelper.BeginForm(actionName: null, controllerName: null, routeValues: null, method: method, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The HTTP method for processing the form, either GET or POST. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, FormMethod method, @@ -27,12 +71,43 @@ namespace Microsoft.AspNet.Mvc.Rendering method: method, htmlAttributes: htmlAttributes); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm([NotNull] this IHtmlHelper htmlHelper, object routeValues) { return htmlHelper.BeginForm(actionName: null, controllerName: null, routeValues: routeValues, method: FormMethod.Post, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The name of the action method. + /// The name of the controller. + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, string actionName, @@ -42,6 +117,26 @@ namespace Microsoft.AspNet.Mvc.Rendering method: FormMethod.Post, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The name of the action method. + /// The name of the controller. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, string actionName, @@ -52,6 +147,20 @@ namespace Microsoft.AspNet.Mvc.Rendering FormMethod.Post, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The name of the action method. + /// The name of the controller. + /// The HTTP method for processing the form, either GET or POST. + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, string actionName, @@ -62,6 +171,27 @@ namespace Microsoft.AspNet.Mvc.Rendering method: method, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The name of the action method. + /// The name of the controller. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// The HTTP method for processing the form, either GET or POST. + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, string actionName, @@ -73,6 +203,25 @@ namespace Microsoft.AspNet.Mvc.Rendering method, htmlAttributes: null); } + /// + /// Renders a <form> start tag to the response. When the user submits the form, + /// the request will be processed by an action method. + /// + /// The instance this method extends. + /// The name of the action method. + /// The name of the controller. + /// The HTTP method for processing the form, either GET or POST. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// + /// An instance which renders the </form> end tag when disposed. + /// + /// + /// In this context, "renders" means the method writes its output using . + /// public static MvcForm BeginForm( [NotNull] this IHtmlHelper htmlHelper, string actionName, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperInputExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperInputExtensions.cs index 4167966776..ce11c67d7d 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperInputExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperInputExtensions.cs @@ -6,13 +6,88 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Input-related extensions for and . + /// public static class HtmlHelperInputExtensions { + /// + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <input> elements. + /// + /// + /// Combines and to set checkbox + /// element's "name" attribute. Sanitizes to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is true; does not include the attribute otherwise. + /// + /// public static HtmlString CheckBox([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.CheckBox(name, isChecked: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If true, checkbox is initially checked. + /// A new containing the <input> elements. + /// + /// + /// Combines and to set checkbox + /// element's "name" attribute. Sanitizes to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is true; does not include the attribute otherwise. + /// + /// public static HtmlString CheckBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -21,6 +96,47 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.CheckBox(name, isChecked, htmlAttributes: null); } + /// + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// An that contains the HTML attributes for the checkbox element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <input> elements. + /// + /// + /// Combines and to set checkbox + /// element's "name" attribute. Sanitizes to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Existing "checked" entry in if any. + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the and default cases, includes a "checked" attribute with + /// value "checked" if the values is true; does not include the attribute otherwise. + /// + /// public static HtmlString CheckBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -29,17 +145,111 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.CheckBox(name, isChecked: null, htmlAttributes: htmlAttributes); } + /// + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// A new containing the <input> elements. + /// + /// + /// Combines and the string representation of the + /// to set checkbox element's "name" attribute. Sanitizes the string + /// representation of the to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is true; does not include the attribute otherwise. + /// + /// public static HtmlString CheckBoxFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.CheckBoxFor(expression, htmlAttributes: null); } + /// + /// Returns an <input> element of type "hidden" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString Hidden([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.Hidden(name, value: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "hidden" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString Hidden( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -48,17 +258,74 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.Hidden(name, value, htmlAttributes: null); } + /// + /// Returns an <input> element of type "hidden" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString HiddenFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.HiddenFor(expression, htmlAttributes: null); } + /// + /// Returns an <input> element of type "password" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <input> element. + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. Sets <input> element's "value" attribute to string.Empty. + /// public static HtmlString Password([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.Password(name, value: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "password" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// if non-null. + /// Otherwise, string.Empty. + /// + /// public static HtmlString Password( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -67,12 +334,73 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.Password(name, value, htmlAttributes: null); } + /// + /// Returns an <input> element of type "password" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString PasswordFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.PasswordFor(expression, htmlAttributes: null); } + /// + /// Returns an <input> element of type "radio" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// Value to include in the element. Must not be null. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. Sets <input> element's "value" attribute to . + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// or is true (for that case); does not include + /// the attribute otherwise. + /// + /// public static HtmlString RadioButton( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -81,6 +409,59 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.RadioButton(name, value, isChecked: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "radio" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// If non-null, value to include in the element. Must not be null if no "checked" entry exists + /// in . + /// + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines element's "value" attribute based on the following precedence: + /// + /// if non-null. + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// Existing "checked" entry in if any. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the and default cases, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// or is true (for that case); does not include + /// the attribute otherwise. + /// + /// public static HtmlString RadioButton( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -90,6 +471,58 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.RadioButton(name, value, isChecked: null, htmlAttributes: htmlAttributes); } + /// + /// Returns an <input> element of type "radio" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// If non-null, value to include in the element. Must not be null if + /// is also null. + /// + /// + /// If true, radio button is initially selected. Must not be null if + /// is also null. + /// + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines element's "value" attribute based on the following precedence: + /// + /// if non-null. + /// Otherwise, string.Empty. + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// otherwise. + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// or is true (for that case); does not include + /// the attribute otherwise. + /// + /// public static HtmlString RadioButton( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -99,6 +532,39 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.RadioButton(name, value, isChecked, htmlAttributes: null); } + /// + /// Returns an <input> element of type "radio" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// Value to include in the element. Must not be null. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. Converts the + /// to a to set element's "value" attribute. + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the default case, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// ; does not include the attribute otherwise. + /// + /// public static HtmlString RadioButtonFor( [NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, @@ -107,11 +573,77 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.RadioButtonFor(expression, value, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBox([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.TextBox(name, value: null, format: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// if non-null. + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -120,6 +652,48 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.TextBox(name, value, format: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// if non-null. Formats using + /// or converts to a directly if + /// is null or empty. + /// + /// + /// entry for (converted to a fully-qualified name) if + /// entry exists and can be converted to a . Formats entry using + /// or converts entry to a directly if is null or empty. + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. Formats result using or converts result to a + /// directly if is null or empty. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -129,6 +703,47 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.TextBox(name, value, format, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// if non-null. + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -138,54 +753,338 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.TextBox(name, value, format: null, htmlAttributes: htmlAttributes); } + /// + /// Returns an <input> element of type "text" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBoxFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.TextBoxFor(expression, format: null, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// Formats result using or converts result to a directly if + /// is null or empty. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBoxFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, string format) { return htmlHelper.TextBoxFor(expression, format, htmlAttributes: null); } + /// + /// Returns an <input> element of type "text" for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextBoxFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, object htmlAttributes) { return htmlHelper.TextBoxFor(expression, format: null, htmlAttributes: htmlAttributes); } + /// + /// Returns a <textarea> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <textarea> element. + /// + /// + /// Combines and to set + /// <textarea> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextArea([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.TextArea(name, value: null, rows: 0, columns: 0, htmlAttributes: null); } + /// + /// Returns a <textarea> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <textarea> element. + /// + /// + /// Combines and to set + /// <textarea> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextArea([NotNull] this IHtmlHelper htmlHelper, string name, object htmlAttributes) { return htmlHelper.TextArea(name, value: null, rows: 0, columns: 0, htmlAttributes: htmlAttributes); } + /// + /// Returns a <textarea> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// A new containing the <textarea> element. + /// + /// + /// Combines and to set + /// <textarea> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextArea([NotNull] this IHtmlHelper htmlHelper, string name, string value) { return htmlHelper.TextArea(name, value, rows: 0, columns: 0, htmlAttributes: null); } + /// + /// Returns a <textarea> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <textarea> element. + /// + /// + /// Combines and to set + /// <textarea> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for (converted to a + /// fully-qualified name) if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextArea([NotNull] this IHtmlHelper htmlHelper, string name, string value, object htmlAttributes) { return htmlHelper.TextArea(name, value, rows: 0, columns: 0, htmlAttributes: htmlAttributes); } + /// + /// Returns a <textarea> element for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <textarea> element. + /// + /// + /// Combines and the string representation of the + /// to set <textarea> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextAreaFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.TextAreaFor(expression, rows: 0, columns: 0, htmlAttributes: null); } + /// + /// Returns a <textarea> element for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <textarea> element. + /// + /// + /// Combines and the string representation of the + /// to set <textarea> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Otherwise, string.Empty. + /// + /// public static HtmlString TextAreaFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, object htmlAttributes) { diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLabelExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLabelExtensions.cs index e954be8553..d5c4ead307 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLabelExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLabelExtensions.cs @@ -6,8 +6,17 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Label-related extensions for and . + /// public static class HtmlHelperLabelExtensions { + /// + /// Returns a <label> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <label> element. public static HtmlString Label([NotNull] this IHtmlHelper html, string expression) { return html.Label(expression, @@ -15,17 +24,41 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns a <label> element for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// The inner text of the element. + /// A new containing the <label> element. public static HtmlString Label([NotNull] this IHtmlHelper html, string expression, string labelText) { return html.Label(expression, labelText, htmlAttributes: null); } + /// + /// Returns a <label> element for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// A new containing the <label> element. public static HtmlString LabelFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression) { return html.LabelFor(expression, labelText: null, htmlAttributes: null); } + /// + /// Returns a <label> element for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The inner text of the element. + /// The type of the model. + /// The type of the result. + /// A new containing the <label> element. public static HtmlString LabelFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, string labelText) @@ -33,6 +66,19 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.LabelFor(expression, labelText, htmlAttributes: null); } + /// + /// Returns a <label> element for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <label> element. public static HtmlString LabelFor([NotNull] this IHtmlHelper html, [NotNull] Expression> expression, object htmlAttributes) @@ -40,21 +86,53 @@ namespace Microsoft.AspNet.Mvc.Rendering return html.LabelFor(expression, labelText: null, htmlAttributes: htmlAttributes); } + /// + /// Returns a <label> element for the current model. + /// + /// The instance this method extends. + /// A new containing the <label> element. public static HtmlString LabelForModel([NotNull] this IHtmlHelper html) { return html.Label(expression: null, labelText: null, htmlAttributes: null); } + /// + /// Returns a <label> element for the current model. + /// + /// The instance this method extends. + /// The inner text of the element. + /// A new containing the <label> element. public static HtmlString LabelForModel([NotNull] this IHtmlHelper html, string labelText) { return html.Label(expression: null, labelText: labelText, htmlAttributes: null); } + /// + /// Returns a <label> element for the current model. + /// + /// The instance this method extends. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <label> element. public static HtmlString LabelForModel([NotNull] this IHtmlHelper html, object htmlAttributes) { return html.Label(expression: null, labelText: null, htmlAttributes: htmlAttributes); } + /// + /// Returns a <label> element for the current model. + /// + /// The instance this method extends. + /// The inner text of the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the <label> element. public static HtmlString LabelForModel( [NotNull] this IHtmlHelper html, string labelText, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLinkExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLinkExtensions.cs index e1b9174ef2..889d0069d9 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLinkExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperLinkExtensions.cs @@ -3,8 +3,18 @@ namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Link-related extensions for . + /// public static class HtmlHelperLinkExtensions { + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -21,6 +31,20 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -38,6 +62,25 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -56,6 +99,14 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: htmlAttributes); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// The name of the controller. + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -73,6 +124,21 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// The name of the controller. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -91,6 +157,26 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified action. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the action. + /// The name of the controller. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the anchor element. public static HtmlString ActionLink( [NotNull] this IHtmlHelper helper, [NotNull] string linkText, @@ -110,6 +196,19 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: htmlAttributes); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified route. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// A new containing the anchor element. public static HtmlString RouteLink( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string linkText, @@ -125,6 +224,13 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified route. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the route. + /// A new containing the anchor element. public static HtmlString RouteLink( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string linkText, @@ -140,6 +246,20 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified route. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the route. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// A new containing the anchor element. public static HtmlString RouteLink( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string linkText, @@ -156,6 +276,24 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: null); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified route. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the anchor element. public static HtmlString RouteLink( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string linkText, @@ -172,6 +310,25 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: htmlAttributes); } + /// + /// Returns an anchor (<a>) element that contains a URL path to the specified route. + /// + /// The instance this method extends. + /// The inner text of the anchor element. Must not be null. + /// The name of the route. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route + /// parameters. + /// + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// A new containing the anchor element. public static HtmlString RouteLink( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string linkText, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperPartialExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperPartialExtensions.cs index e529a1de8c..de88d2a585 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperPartialExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperPartialExtensions.cs @@ -5,15 +5,21 @@ using System.Threading.Tasks; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// PartialView-related extensions for . + /// public static class HtmlHelperPartialExtensions { /// - /// Renders the partial view with the parent's view data and model to a string. + /// Returns HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// /// - /// A that represents when rendering to the has completed. + /// A that on completion returns a new containing + /// the created HTML. /// public static Task PartialAsync( [NotNull] this IHtmlHelper htmlHelper, @@ -23,15 +29,16 @@ namespace Microsoft.AspNet.Mvc.Rendering } /// - /// Renders the partial view with the given view data and, implicitly, the given view data's model to a string. + /// Returns HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. - /// - /// The that is provided to the partial view that will be rendered. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. /// + /// A to pass into the partial view. /// - /// A that represents when rendering to the has completed. + /// A that on completion returns a new containing + /// the created HTML. /// public static Task PartialAsync( [NotNull] this IHtmlHelper htmlHelper, @@ -42,13 +49,16 @@ namespace Microsoft.AspNet.Mvc.Rendering } /// - /// Renders the partial view with an empty view data and the given model to a string. + /// Returns HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. - /// The model to provide to the partial view that will be rendered. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// + /// A model to pass into the partial view. /// - /// A that represents when rendering to the has completed. + /// A that on completion returns a new containing + /// the created HTML. /// public static Task PartialAsync( [NotNull] this IHtmlHelper htmlHelper, @@ -59,11 +69,16 @@ namespace Microsoft.AspNet.Mvc.Rendering } /// - /// Renders the partial view with the parent's view data and model. + /// Renders HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. - /// A that represents when rendering has completed. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// + /// A that renders the created HTML when it executes. + /// + /// In this context, "renders" means the method writes its output using . + /// public static Task RenderPartialAsync( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string partialViewName) @@ -73,14 +88,17 @@ namespace Microsoft.AspNet.Mvc.Rendering } /// - /// Renders the partial view with the given view data and, implicitly, the given view data's model. + /// Renders HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. - /// - /// The that is provided to the partial view that will be rendered. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. /// - /// A that represents when rendering has completed. + /// A to pass into the partial view. + /// A that renders the created HTML when it executes. + /// + /// In this context, "renders" means the method writes its output using . + /// public static Task RenderPartialAsync( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string partialViewName, @@ -90,12 +108,17 @@ namespace Microsoft.AspNet.Mvc.Rendering } /// - /// Renders the partial view with an empty view data and the given model. + /// Renders HTML markup for the specified partial view. /// - /// The instance that this method extends. - /// The name of the partial view to render. - /// The model to provide to the partial view that will be rendered. - /// A that represents when rendering has completed. + /// The instance this method extends. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// + /// A model to pass into the partial view. + /// A that renders the created HTML when it executes. + /// + /// In this context, "renders" means the method writes its output using . + /// public static Task RenderPartialAsync( [NotNull] this IHtmlHelper htmlHelper, [NotNull] string partialViewName, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperSelectExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperSelectExtensions.cs index c522e798fb..7eef96d5ee 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperSelectExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperSelectExtensions.cs @@ -7,18 +7,63 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Select-related extensions for and . + /// public static class HtmlHelperSelectExtensions { + /// + /// Returns a single-selection HTML <select> element for the expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString DropDownList([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.DropDownList(name, selectList: null, optionLabel: null, htmlAttributes: null); } + /// + /// Returns a single-selection HTML <select> element for the expression , + /// using the option label. + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// The text for a default empty item. Does not include such an item if argument is null. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString DropDownList([NotNull] this IHtmlHelper htmlHelper, string name, string optionLabel) { return htmlHelper.DropDownList(name, selectList: null, optionLabel: optionLabel, htmlAttributes: null); } + /// + /// Returns a single-selection HTML <select> element for the expression , + /// using the specified list items. + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString DropDownList( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -27,6 +72,26 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.DropDownList(name, selectList, optionLabel: null, htmlAttributes: null); } + /// + /// Returns a single-selection HTML <select> element for the expression , + /// using the specified list items and HTML attributes. + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// An that contains the HTML attributes for the <select> element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString DropDownList( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -36,6 +101,25 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.DropDownList(name, selectList, optionLabel: null, htmlAttributes: htmlAttributes); } + /// + /// Returns a single-selection HTML <select> element for the expression , + /// using the specified list items and option label. + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// The text for a default empty item. Does not include such an item if argument is null. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString DropDownList( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -45,12 +129,52 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.DropDownList(name, selectList, optionLabel, htmlAttributes: null); } + /// + /// Returns a single-selection HTML <select> element for the , using the + /// specified list items. + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// public static HtmlString DropDownListFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, IEnumerable selectList) { return htmlHelper.DropDownListFor(expression, selectList, optionLabel: null, htmlAttributes: null); } + /// + /// Returns a single-selection HTML <select> element for the , using the + /// specified list items and HTML attributes. + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// An that contains the HTML attributes for the <select> element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// public static HtmlString DropDownListFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, IEnumerable selectList, object htmlAttributes) @@ -59,6 +183,27 @@ namespace Microsoft.AspNet.Mvc.Rendering htmlAttributes: htmlAttributes); } + /// + /// Returns a single-selection HTML <select> element for the , using the + /// specified list items and option label. + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// The text for a default empty item. Does not include such an item if argument is null. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// public static HtmlString DropDownListFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, IEnumerable selectList, string optionLabel) @@ -66,11 +211,38 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.DropDownListFor(expression, selectList, optionLabel, htmlAttributes: null); } + /// + /// Returns a multi-selection <select> element for the expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString ListBox([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.ListBox(name, selectList: null, htmlAttributes: null); } + /// + /// Returns a multi-selection <select> element for the expression , using the + /// specified list items. + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// public static HtmlString ListBox( [NotNull] this IHtmlHelper htmlHelper, string name, @@ -79,6 +251,24 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ListBox(name, selectList, htmlAttributes: null); } + /// + /// Returns a multi-selection <select> element for the , using the + /// specified list items. + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// The type of the model. + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// public static HtmlString ListBoxFor( [NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValidationExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValidationExtensions.cs index 5da8962d1d..7982c600e4 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValidationExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValidationExtensions.cs @@ -6,14 +6,48 @@ using System.Linq.Expressions; namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Validation-related extensions for and . + /// public static class HtmlHelperValidationExtensions { + /// + /// Returns the validation message if an error exists in the + /// object for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// + /// + /// Method extracts an error string from the object. Message + /// will always be visible but client-side validation may update the associated CSS class. + /// public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper, string expression) { return htmlHelper.ValidationMessage(expression, message: null, htmlAttributes: null, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper, string expression, string message) @@ -21,6 +55,27 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessage(expression, message, htmlAttributes: null, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// An that contains the HTML attributes for the + /// () element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// + /// + /// Method extracts an error string from the object. Message + /// will always be visible but client-side validation may update the associated CSS class. + /// public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper, string expression, object htmlAttributes) @@ -28,6 +83,25 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessage(expression, message: null, htmlAttributes: htmlAttributes, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// A new containing a element. null if the + /// expression is valid and client-side validation is disabled. + /// public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper, string expression, string message, @@ -36,6 +110,28 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessage(expression, message, htmlAttributes: null, tag: tag); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// An that contains the HTML attributes for the + /// () element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// public static HtmlString ValidationMessage([NotNull] this IHtmlHelper htmlHelper, string expression, string message, @@ -44,12 +140,47 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessage(expression, message, htmlAttributes, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// The type of the model. + /// The type of the result. + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// + /// + /// Method extracts an error string from the object. Message + /// will always be visible but client-side validation may update the associated CSS class. + /// public static HtmlString ValidationMessageFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.ValidationMessageFor(expression, message: null, htmlAttributes: null, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// The type of the model. + /// The type of the result. + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// public static HtmlString ValidationMessageFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, string message) @@ -57,6 +188,30 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes: null, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// An that contains the HTML attributes for the + /// () element. Alternatively, an + /// instance containing the HTML + /// attributes. + /// + /// The type of the model. + /// The type of the result. + /// + /// A new containing a element. + /// null if the expression is valid and client-side validation is + /// disabled. + /// public static HtmlString ValidationMessageFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, string message, @@ -65,6 +220,27 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes, tag: null); } + /// + /// Returns the validation message if an error exists in the + /// object for the specified . + /// + /// The instance this method extends. + /// An expression to be evaluated against the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// The type of the model. + /// The type of the result. + /// + /// A new containing the element. null if the + /// is valid and client-side validation is disabled. + /// public static HtmlString ValidationMessageFor([NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression, string message, @@ -73,6 +249,15 @@ namespace Microsoft.AspNet.Mvc.Rendering return htmlHelper.ValidationMessageFor(expression, message, htmlAttributes: null, tag: tag); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// + /// New containing a <div> element wrapping the <ul> element. + /// if the current model is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper) { return htmlHelper.ValidationSummary(excludePropertyErrors: false, @@ -81,6 +266,18 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: null); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// + /// If true, display model-level errors only; otherwise display all errors. + /// + /// + /// New containing a <div> element wrapping the <ul> element. + /// if the current model is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, bool excludePropertyErrors) { return htmlHelper.ValidationSummary(excludePropertyErrors, @@ -89,6 +286,18 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: null); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// The message to display with the validation summary. + /// + /// New containing a <div> element wrapping the + /// element (which wraps the + /// ) and the <ul> element. if the current model + /// is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message) { return htmlHelper.ValidationSummary(excludePropertyErrors: false, @@ -97,6 +306,21 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: null); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// The message to display with the validation summary. + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// New containing a <div> element wrapping the element + /// and the <ul> element. if the current model is valid and client-side + /// validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message, string tag) { return htmlHelper.ValidationSummary(excludePropertyErrors: false, @@ -105,6 +329,21 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: tag); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// + /// If true, display model-level errors only; otherwise display all errors. + /// + /// The message to display with the validation summary. + /// + /// New containing a <div> element wrapping the + /// element (which, in turn, wraps the + /// ) and the <ul> element. if the current model + /// is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, bool excludePropertyErrors, string message) @@ -115,6 +354,23 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: null); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// The message to display with the validation summary. + /// + /// An that contains the HTML attributes for the topmost (<div>) element. + /// Alternatively, an instance containing + /// the HTML attributes. + /// + /// + /// New containing a <div> element wrapping the + /// element (which wraps the + /// ) and the <ul> element. if the current model + /// is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message, object htmlAttributes) @@ -123,6 +379,26 @@ namespace Microsoft.AspNet.Mvc.Rendering excludePropertyErrors: false, message: message, htmlAttributes: htmlAttributes, tag: null); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// The message to display with the validation summary. + /// + /// An that contains the HTML attributes for the topmost (<div>) element. + /// Alternatively, an instance containing + /// the HTML attributes. + /// + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// New containing a <div> element wrapping the element + /// and the <ul> element. if the current model is valid and client-side + /// validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, string message, object htmlAttributes, @@ -132,6 +408,24 @@ namespace Microsoft.AspNet.Mvc.Rendering excludePropertyErrors: false, message: message, htmlAttributes: htmlAttributes, tag: tag); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// + /// If true, display model-level errors only; otherwise display all errors. + /// + /// The message to display with the validation summary. + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// New containing a <div> element wrapping the element + /// and the <ul> element. if the current model is valid and client-side + /// validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, bool excludePropertyErrors, string message, @@ -143,6 +437,26 @@ namespace Microsoft.AspNet.Mvc.Rendering tag: tag); } + /// + /// Returns an unordered list (<ul> element) of validation messages that are in the + /// object. + /// + /// The instance this method extends. + /// + /// If true, display model-level errors only; otherwise display all errors. + /// + /// The message to display with the validation summary. + /// + /// An that contains the HTML attributes for the topmost (<div>) element. + /// Alternatively, an instance containing + /// the HTML attributes. + /// + /// + /// New containing a <div> element wrapping the + /// element (which wraps the + /// ) and the <ul> element. if the current model + /// is valid and client-side validation is disabled). + /// public static HtmlString ValidationSummary([NotNull] this IHtmlHelper htmlHelper, bool excludePropertyErrors, string message, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs index af78126237..d79b23b25c 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs @@ -18,7 +18,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// Expression name, relative to the current model. /// A containing the formatted value. /// - /// Converts the expression result to a directly. + /// Converts the expression result to a directly. /// public static string Value([NotNull] this IHtmlHelper htmlHelper, string name) { @@ -29,7 +29,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// Returns the formatted value for the specified . /// /// The instance this method extends. - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// The type of the model. /// The type of the result. /// A containing the formatted value. diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs index a12daa2e09..03ce4f1d68 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs @@ -45,26 +45,25 @@ namespace Microsoft.AspNet.Mvc.Rendering ViewDataDictionary ViewData { get; } /// - /// Returns an anchor element (a element) that contains a URL path to the specified action. + /// Returns an anchor (<a>) element that contains a URL path to the specified action. /// - /// The inner text of the anchor element. + /// The inner text of the anchor element. Must not be null. /// The name of the action. /// The name of the controller. /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. /// The URL fragment name (the anchor name). /// - /// An object that contains the parameters for a route. The parameters are retrieved through reflection by - /// examining the properties of the object. This object is typically created using object initializer syntax. - /// Alternatively, an instance containing the route parameters. + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route parameters. /// /// - /// An object that contains the HTML attributes to set for the element. Alternatively, an + /// An that contains the HTML attributes for the element. Alternatively, an /// instance containing the HTML attributes. /// - /// - /// An anchor element (a element). - /// + /// A new containing the anchor element. HtmlString ActionLink( [NotNull] string linkText, string actionName, @@ -76,11 +75,10 @@ namespace Microsoft.AspNet.Mvc.Rendering object htmlAttributes); /// - /// Generates a hidden form field (anti-forgery token) that is validated when the form is submitted. + /// Returns a <hidden> element (anti-forgery token) that will be validated when the containing + /// <form> is submitted. /// - /// - /// The generated form field (anti-forgery token). - /// + /// A new containing the <hidden> element. HtmlString AntiForgeryToken(); /// @@ -89,17 +87,23 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// The name of the action method. /// The name of the controller. - /// An object that contains the parameters for a route. The parameters are retrieved - /// through reflection by examining the properties of the object. This object is typically created using object - /// initializer syntax. Alternatively, an instance containing the - /// route parameters. + /// + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route parameters. + /// /// The HTTP method for processing the form, either GET or POST. - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// /// /// An instance which renders the </form> end tag when disposed. /// + /// + /// In this context, "renders" means the method writes its output using . + /// MvcForm BeginForm( string actionName, string controllerName, @@ -108,39 +112,78 @@ namespace Microsoft.AspNet.Mvc.Rendering object htmlAttributes); /// - /// Render an input element of type "checkbox" with value "true" and an input element of type "hidden" with - /// value "false". + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". /// - /// - /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data - /// only if value is not in submitted data and is null. + /// Expression name, relative to the current model. + /// If true, checkbox is initially checked. + /// + /// An that contains the HTML attributes for the checkbox element. Alternatively, an + /// instance containing the HTML attributes. /// - /// - /// If true, checkbox is initially checked. Ignore if named value is found in submitted data. Finally - /// fall back to an existing "checked" value in . - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// A new containing the <input> elements. + /// + /// + /// Combines and to set checkbox + /// element's "name" attribute. Sanitizes to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Existing "checked" entry in if any. + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the and default cases, includes a "checked" attribute with + /// value "checked" if the values is true; does not include the attribute otherwise. + /// + /// HtmlString CheckBox(string name, bool? isChecked, object htmlAttributes); /// - /// Returns HTML markup for each property in the object that is represented by the expression, using the - /// specified template, HTML field ID, and additional view data. + /// Returns HTML markup for the , using a display template, specified HTML field + /// name, and additional view data. The template is found using the or the + /// 's . /// - /// An expression that identifies the object that contains the properties to display. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to display. /// - /// The name of the template that is used to render the object. + /// The name of the template used to create the HTML markup. /// - /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties - /// that have the same name. + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. /// /// - /// An anonymous object or dictionary that can contain additional view data that will be merged into the - /// instance that is created for the template. + /// An anonymous or that can contain additional + /// view data that will be merged into the instance created for the + /// template. /// - /// The HTML markup for each property in the object that is represented by the expression. + /// A new containing the created HTML. + /// + /// + /// For example the default display template includes markup for each property in the + /// 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// HtmlString Display( string expression, string templateName, @@ -165,20 +208,27 @@ namespace Microsoft.AspNet.Mvc.Rendering string DisplayText(string name); /// - /// Returns a single-selection HTML <select> element using the specified name of the form field, - /// list items, option label, and HTML attributes. + /// Returns a single-selection HTML <select> element for the expression , + /// using the specified list items, option label, and HTML attributes. /// - /// The name of the form field to return. - /// A collection of objects that are used to populate the - /// drop-down list. - /// The text for a default empty item. This parameter can be null. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// The text for a default empty item. Does not include such an item if argument is null. + /// /// - /// An object that contains the HTML attributes to set for the <select> element. Alternatively, an + /// An that contains the HTML attributes for the <select> element. Alternatively, an /// instance containing the HTML attributes. /// - /// - /// An HTML <select> element with an <option> subelement for each item in the list. - /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// HtmlString DropDownList( string name, IEnumerable selectList, @@ -186,83 +236,131 @@ namespace Microsoft.AspNet.Mvc.Rendering object htmlAttributes); /// - /// Returns an HTML input element for each property in the object that is represented by the expression, using - /// the specified template, HTML field ID, and additional view data. + /// Returns HTML markup for the , using an editor template, specified HTML field + /// name, and additional view data. The template is found using the or the + /// 's . /// - /// An expression that identifies the object that contains the properties to edit. + /// + /// Expression name, relative to the current model. May identify a single property or an + /// that contains the properties to edit. /// - /// The name of the template that is used to render the object. + /// The name of the template used to create the HTML markup. /// - /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties - /// that have the same name. + /// A used to disambiguate the names of HTML elements that are created for + /// properties that have the same name. /// /// - /// An anonymous object or dictionary that can contain additional view data that will be merged into the - /// instance that is created for the template. + /// An anonymous or that can contain additional + /// view data that will be merged into the instance created for the + /// template. /// - /// The HTML markup for the input elements for each property in the object that is represented by the - /// expression. + /// A new containing the <input> element(s). + /// + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the 's value. + /// + /// + /// Example s include string.Empty which identifies the current model and + /// "prop" which identifies the current model's "prop" property. + /// + /// HtmlString Editor(string expression, string templateName, string htmlFieldName, object additionalViewData); /// - /// Converts the value of the specified object to an HTML-encoded string. + /// Converts the to an HTML-encoded . /// - /// The object to encode. - /// The HTML-encoded string. + /// The to encode. + /// The HTML-encoded . string Encode(object value); /// - /// Converts the specified string to an HTML-encoded string. + /// Converts the specified to an HTML-encoded . /// - /// The string to encode. - /// The HTML-encoded string. + /// The to encode. + /// The HTML-encoded . string Encode(string value); /// /// Renders the </form> end tag to the response. /// + /// + /// In this context, "renders" means the method writes its output using . + /// void EndForm(); /// /// Formats the value. /// /// The value. - /// The format string. - /// The formatted value. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// A containing the formatted value. + /// + /// Converts to a directly if + /// is null or empty. + /// string FormatValue(object value, string format); /// - /// Creates an HTML element ID using the specified element name. + /// Returns an HTML element Id for the specified expression . /// - /// The name of the HTML element. - /// The ID of the HTML element. + /// + /// Fully-qualified expression name, ignoring the current model. Must not be null. + /// + /// A containing the element Id. string GenerateIdFromName([NotNull] string name); /// - /// Returns information about about client validation rules for the given or + /// Returns information about about client validation rules for the specified or /// . Intended for use in extension methods. /// /// Metadata about the of interest. - /// Expression name, relative to the current model. Used to determine - /// when is null; ignored - /// otherwise. + /// + /// Expression name, relative to the current model. Used to determine when + /// is null; ignored otherwise. + /// /// An containing the relevant rules. IEnumerable GetClientValidationRules(ModelMetadata metadata, string name); /// - /// Render an input element of type "hidden". + /// Returns an <input> element of type "hidden" for the specified expression . /// - /// - /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data - /// only if value is not in submitted data and is null. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// - /// If non-null, value to include in the element. Ignore if named value is found in submitted data. - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString Hidden(string name, object value, object htmlAttributes); /// @@ -273,30 +371,36 @@ namespace Microsoft.AspNet.Mvc.Rendering string Id(string name); /// - /// Returns an HTML label element and the property name of the property that is represented by the specified - /// expression. + /// Returns a <label> element for the specified expression . /// - /// An expression that identifies the property to display. - /// The label text. - /// An object that contains the HTML attributes to set for the element. - /// - /// An HTML label element and the property name of the property that is represented by the expression. - /// + /// Expression name, relative to the current model. + /// The inner text of the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// A new containing the <label> element. HtmlString Label(string expression, string labelText, object htmlAttributes); /// - /// Returns a multi-selection HTML <select> element using the specified name of the form field, - /// list items, and HTML attributes. + /// Returns a multi-selection <select> element for the expression , using the + /// specified list items and HTML attributes. /// - /// The name of the form field to return. - /// A collection of objects that are used to populate the - /// drop-down list. - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// Expression name, relative to the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. /// - /// - /// An HTML <select> element with an <option> subelement for each item in the list. - /// + /// + /// An that contains the HTML attributes for the <select> element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// A new containing the <select> element. + /// + /// Combines and to set + /// <select> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// HtmlString ListBox(string name, IEnumerable selectList, object htmlAttributes); /// @@ -307,99 +411,153 @@ namespace Microsoft.AspNet.Mvc.Rendering string Name(string name); /// - /// Returns a partial view in string format. + /// Returns HTML markup for the specified partial view. /// - /// The name of the partial view to render and return. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// /// A model to pass into the partial view. /// A to pass into the partial view. - /// A task that represents when rendering of the partial view into a string has completed. + /// + /// A that on completion returns a new containing + /// the created HTML. + /// Task PartialAsync([NotNull] string partialViewName, object model, ViewDataDictionary viewData); /// - /// Render an input element of type "password". + /// Returns an <input> element of type "password" for the specified expression . /// - /// - /// Rendered element's name. Also use this name to find value in view data. Use view data - /// only if value is not in submitted data and is null. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// - /// If non-null, value to include in the element. - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// if non-null. + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString Password(string name, object value, object htmlAttributes); /// - /// Render an input element of type "radio". + /// Returns an <input> element of type "radio" for the specified expression . /// - /// - /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data - /// only if value is not in submitted data and is null. - /// + /// Expression name, relative to the current model. /// - /// If non-null, value to include in the element. May be null only if - /// is also null. Also compared to value in submitted data or view data to - /// determine if that parameter is null. Ignore if named value is found in - /// submitted data. + /// If non-null, value to include in the element. Must not be null if + /// is also null and no "checked" entry exists in + /// . /// /// - /// If true, radio button is initially selected. Ignore if named value is found in submitted data. Fall - /// back to comparing with view data if this parameter is null. Finally - /// fall back to an existing "checked" value in . + /// If true, radio button is initially selected. Must not be null if + /// is also null and no "checked" entry exists in + /// . /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// New containing the rendered HTML. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines element's "value" attribute based on the following precedence: + /// + /// if non-null. + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// if non-null. + /// Existing "checked" entry in if any. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the and default cases, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// or is true (for that case); does not include + /// the attribute otherwise. + /// + /// HtmlString RadioButton(string name, object value, bool? isChecked, object htmlAttributes); /// - /// Wraps HTML markup in an , which will enable HTML markup to be - /// rendered to the output without getting HTML encoded. + /// Wraps HTML markup in an , without HTML-encoding the specified + /// . /// - /// HTML markup string. - /// An that represents HTML markup. + /// HTML markup . + /// A new containing the wrapped . HtmlString Raw(string value); /// - /// Wraps HTML markup from the string representation of an object in an , - /// which will enable HTML markup to be rendered to the output without getting HTML encoded. + /// Wraps HTML markup from the string representation of an in an + /// , without HTML-encoding the string representation. /// - /// object with string representation as HTML markup. - /// An that represents HTML markup. + /// The to wrap. + /// A new containing the wrapped string representation. HtmlString Raw(object value); /// - /// Renders a partial view. + /// Renders HTML markup for the specified partial view. /// - /// The name of the partial view to render. + /// + /// The name of the partial view used to create the HTML markup. Must not be null. + /// /// A model to pass into the partial view. /// A to pass into the partial view. - /// A task that represents when rendering has completed. + /// A that renders the created HTML when it executes. + /// + /// In this context, "renders" means the method writes its output using . + /// Task RenderPartialAsync([NotNull] string partialViewName, object model, ViewDataDictionary viewData); /// - /// Returns an anchor element (a element) that contains a URL path to the specified route. + /// Returns an anchor (<a>) element that contains a URL path to the specified route. /// - /// The inner text of the anchor element. + /// The inner text of the anchor element. Must not be null. /// The name of the route. /// The protocol for the URL, such as "http" or "https". /// The host name for the URL. /// The URL fragment name (the anchor name). /// - /// An object that contains the parameters for a route. The parameters are retrieved through reflection by - /// examining the properties of the object. This object is typically created using object initializer syntax. - /// Alternatively, an instance containing the route parameters. + /// An that contains the parameters for a route. The parameters are retrieved through + /// reflection by examining the properties of the . This is typically + /// created using initializer syntax. Alternatively, an + /// instance containing the route parameters. /// /// - /// An object that contains the HTML attributes to set for the element. Alternatively, an + /// An that contains the HTML attributes for the element. Alternatively, an /// instance containing the HTML attributes. /// - /// - /// An anchor element (a element). - /// + /// A new containing the anchor element. HtmlString RouteLink( [NotNull] string linkText, string routeName, @@ -410,67 +568,137 @@ namespace Microsoft.AspNet.Mvc.Rendering object htmlAttributes); /// - /// Render a textarea. + /// Returns a <textarea> element for the specified expression . /// - /// - /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data - /// only if value is not in submitted data and is null. - /// - /// - /// If non-null, value to include in the element. Ignore if named value is found in submitted data. - /// + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. /// Number of rows in the textarea. /// Number of columns in the textarea. - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// New containing the rendered HTML. + /// A new containing the <textarea> element. + /// + /// + /// Combines and to set + /// <textarea> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// if non-null. + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. + /// + /// Otherwise, string.Empty. + /// + /// HtmlString TextArea(string name, string value, int rows, int columns, object htmlAttributes); /// - /// Render an input element of type "text". + /// Returns an <input> element of type "text" for the specified expression . /// - /// - /// Rendered element's name. Also use this name to find value in submitted data or view data. Use view data - /// only if value is not in submitted data and is null. + /// Expression name, relative to the current model. + /// If non-null, value to include in the element. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). /// - /// - /// If non-null, value to include in the element. Ignore if named value is found in submitted data. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// A new containing the <input> element. + /// + /// + /// Combines and to set + /// <input> element's "name" attribute. Sanitizes to set element's "id" + /// attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for (converted to a fully-qualified name) + /// if entry exists and can be converted to a . + /// + /// + /// if non-null. Formats using + /// or converts to a directly if + /// is null or empty. + /// + /// + /// entry for (converted to a fully-qualified name) if entry + /// exists and can be converted to a . Formats entry using or + /// converts entry to a directly if is null or empty. + /// + /// + /// Linq expression based on (converted to a fully-qualified name) run against current + /// model if result is non-null and can be converted to a . For example + /// string.Empty identifies the current model and "prop" identifies the current model's "prop" + /// property. Formats result using or converts result to a + /// directly if is null or empty. + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString TextBox(string name, object value, string format, object htmlAttributes); /// - /// Returns the validation message if an error exists in the object. + /// Returns the validation message if an error exists in the object + /// for the specified expression . /// - /// The name of the property that is being validated. - /// The message to be displayed. This will always be visible but client-side - /// validation may update the associated CSS class. - /// An object that contains the HTML attributes to set for the element. + /// Expression name, relative to the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side validation may + /// update the associated CSS class. + /// + /// + /// An that contains the HTML attributes for the element. /// Alternatively, an instance containing the HTML attributes. /// - /// The tag to wrap the in the generated HTML. - /// Its default value is . - /// An that contains the validation message + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// A new containing a element. null if the + /// expression is valid and client-side validation is disabled. + /// HtmlString ValidationMessage(string modelName, string message, object htmlAttributes, string tag); /// - /// Returns an unordered list (ul element) of validation messages that are in the + /// Returns an unordered list (<ul> element) of validation messages that are in the /// object. /// - /// true to have the summary display model-level errors only, or false to - /// have the summary display all errors. + /// + /// If true, display model-level errors only; otherwise display all errors. + /// /// The message to display with the validation summary. - /// An object that contains the HTML attributes to set for the element. + /// + /// An that contains the HTML attributes for the topmost (<div>) element. /// Alternatively, an instance containing the HTML attributes. /// - /// The tag to wrap the in the generated HTML. - /// Its default value is . - /// An that contains an unordered list (ul element) of validation messages. + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// + /// New containing a <div> element wrapping the element + /// and the <ul> element. if the current model is valid and client-side + /// validation is disabled). /// HtmlString ValidationSummary( bool excludePropertyErrors, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs index 6600fa1cc1..4e755f152b 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs @@ -19,35 +19,63 @@ namespace Microsoft.AspNet.Mvc.Rendering new ViewDataDictionary ViewData { get; } /// - /// Render an input element of type "checkbox" with value "true" and an input element of type "hidden" with - /// value "false". + /// Returns an <input> element of type "checkbox" with value "true" and an <input> element of type + /// "hidden" with value "false". /// - /// - /// An expression that identifies the object that contains the properties to render. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the checkbox element. Alternatively, an + /// instance containing the HTML attributes. /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// A new containing the <input> elements. + /// + /// + /// Combines and the string representation of the + /// to set checkbox element's "name" attribute. Sanitizes the string + /// representation of the to set checkbox element's "id" attribute. + /// + /// Determines checkbox element's "checked" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Existing "checked" entry in if any. + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the case, includes a "checked" attribute with value "checked" + /// if the values is true; does not include the attribute otherwise. + /// + /// HtmlString CheckBoxFor([NotNull] Expression> expression, object htmlAttributes); /// - /// Returns HTML markup for each property in the object that is represented by the specified expression, using - /// the template, an HTML field ID, and additional view data. + /// Returns HTML markup for the , using a display template, specified HTML field + /// name, and additional view data. The template is found using the or the + /// 's . /// - /// The type of the value. - /// An expression that identifies the object that contains the properties to display. - /// - /// The name of the template that is used to render the object. + /// An expression to be evaluated against the current model. + /// The name of the template used to create the HTML markup. /// - /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties + /// A used to disambiguate the names of HTML elements that are created for properties /// that have the same name. /// /// - /// An anonymous object or dictionary that can contain additional view data that will be merged into the - /// instance that is created for the template. + /// An anonymous or that can contain additional + /// view data that will be merged into the instance created for the + /// template. /// - /// The HTML markup for each property in the object that is represented by the expression. + /// The type of the result. + /// A new containing the created HTML. + /// + /// For example the default display template includes markup for each property in the + /// result. + /// HtmlString DisplayFor([NotNull] Expression> expression, string templateName, string htmlFieldName, @@ -56,7 +84,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// Returns the display name for the specified . /// - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// The type of the result. /// A containing the display name. string DisplayNameFor([NotNull] Expression> expression); @@ -65,7 +93,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// Returns the display name for the specified /// if the current model represents a collection. /// - /// The expression to be evaluated against an item in the current model. + /// An expression to be evaluated against an item in the current model. /// The type of items in the model collection. /// The type of the result. /// A containing the display name. @@ -75,7 +103,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// Returns the simple display text for the specified . /// - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// The type of the result. /// /// A containing the simple display text. @@ -85,21 +113,28 @@ namespace Microsoft.AspNet.Mvc.Rendering string DisplayTextFor([NotNull] Expression> expression); /// - /// Returns a single-selection HTML <select> element for the object that is represented - /// by the specified expression using the specified list items, option label, and HTML attributes. + /// Returns a single-selection HTML <select> element for the , using the + /// specified list items, option label, and HTML attributes. /// - /// The type of the value. - /// An expression that identifies the value to display. - /// A collection of objects that are used to populate the - /// drop-down list. - /// The text for a default empty item. This parameter can be null. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. + /// + /// + /// The text for a default empty item. Does not include such an item if argument is null. + /// /// - /// An object that contains the HTML attributes to set for the <select> element. Alternatively, an + /// An that contains the HTML attributes for the <select> element. Alternatively, an /// instance containing the HTML attributes. /// - /// - /// An HTML <select> element with an <option> subelement for each item in the list. - /// + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// HtmlString DropDownListFor( [NotNull] Expression> expression, IEnumerable selectList, @@ -107,78 +142,108 @@ namespace Microsoft.AspNet.Mvc.Rendering object htmlAttributes); /// - /// Returns an HTML input element for each property in the object that is represented by the specified - /// expression, using the specified template, an HTML field ID, and additional view data. + /// Returns HTML markup for the , using an editor template, specified HTML field + /// name, and additional view data. The template is found using the or the + /// 's . /// - /// The type of the value. - /// An expression that identifies the object that contains the properties to edit. - /// - /// The name of the template that is used to render the object. + /// An expression to be evaluated against the current model. + /// The name of the template that is used to create the HTML markup. /// - /// A string that is used to disambiguate the names of HTML input elements that are rendered for properties + /// A used to disambiguate the names of HTML elements that are created for properties /// that have the same name. /// /// - /// An anonymous object or dictionary that can contain additional view data that will be merged into the - /// instance that is created for the template. + /// An anonymous or that can contain additional + /// view data that will be merged into the instance created for the + /// template. /// - /// The HTML markup for the input elements for each property in the object that is represented by the - /// expression. + /// The type of the result. + /// A new containing the <input> element(s). + /// + /// For example the default editor template includes <label> and <input> + /// elements for each property in the result. + /// HtmlString EditorFor([NotNull] Expression> expression, string templateName, string htmlFieldName, object additionalViewData); /// - /// Render an input element of type "hidden". + /// Returns an <input> element of type "hidden" for the specified . /// - /// - /// An expression that identifies the object that contains the properties to render. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString HiddenFor([NotNull] Expression> expression, object htmlAttributes); /// /// Returns the HTML element Id for the specified . /// - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// The type of the result. /// A containing the element Id. string IdFor([NotNull] Expression> expression); /// - /// Returns an HTML label element and the property name of the property that is represented by the specified - /// expression. + /// Returns a <label> element for the specified . /// - /// An expression that identifies the property to display. - /// An object that contains the HTML attributes to set for the element. - /// The type of the value. - /// - /// An HTML label element and the property name of the property that is represented by the expression. - /// + /// An expression to be evaluated against the current model. + /// The inner text of the element. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// The type of the result. + /// A new containing the <label> element. HtmlString LabelFor([NotNull] Expression> expression, string labelText, object htmlAttributes); /// - /// Returns a multi-selection HTML <select> element for the object that is represented by the specified - /// expression using the specified list items and HTML attributes. + /// Returns a multi-selection <select> element for the , using the + /// specified list items and HTML attributes. /// - /// The type of the property. - /// An expression that identifies the object that contains the properties to - /// display. - /// A collection of objects that are used to populate the - /// drop-down list. - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// An expression to be evaluated against the current model. + /// + /// A collection of objects used to populate the <select> element with + /// <optgroup> and <option> elements. /// - /// - /// An HTML <select> element with an <option> subelement for each item in the list. - /// + /// + /// An that contains the HTML attributes for the <select> element. Alternatively, an + /// instance containing the HTML attributes. + /// + /// The type of the result. + /// A new containing the <select> element. + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// HtmlString ListBoxFor( [NotNull] Expression> expression, IEnumerable selectList, @@ -187,81 +252,174 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// Returns the full HTML element name for the specified . /// - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// The type of the result. /// A containing the element name. string NameFor([NotNull] Expression> expression); /// - /// Render an input element of type "password". + /// Returns an <input> element of type "password" for the specified . /// - /// - /// An expression that identifies the object that contains the properties to render. + /// An expression to be evaluated against the current model. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// result if it is non-null and can be parsed as a + /// . + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString PasswordFor([NotNull] Expression> expression, object htmlAttributes); /// - /// Render an input element of type "radio". + /// Returns an <input> element of type "radio" for the specified . /// - /// - /// An expression that identifies the object that contains the properties to render. + /// An expression to be evaluated against the current model. + /// Value to include in the element. Must not be null. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// - /// Value to compare with current expression value to determine whether radio button is checked. - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. - /// - /// New containing the rendered HTML. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <select> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. Converts the + /// to a to set element's "value" attribute. + /// + /// Determines <input> element's "checked" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Existing "checked" entry in if any. + /// Otherwise, does not include a "checked" attribute. + /// + /// + /// In all but the and default cases, includes a "checked" attribute with + /// value "checked" if the values is equal to a converted for + /// ; does not include the attribute otherwise. + /// + /// HtmlString RadioButtonFor( [NotNull] Expression> expression, [NotNull] object value, object htmlAttributes); /// - /// Render a textarea. + /// Returns a <textarea> element for the specified . /// - /// An expression, relative to the current model. + /// An expression to be evaluated against the current model. /// Number of rows in the textarea. /// Number of columns in the textarea. - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// New containing the rendered HTML. + /// The type of the result. + /// A new containing the <textarea> element. + /// + /// + /// Combines and the string representation of the + /// to set <textarea> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <textarea> element's content based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// + /// Otherwise, string.Empty. + /// + /// HtmlString TextAreaFor([NotNull] Expression> expression, int rows, int columns, object htmlAttributes); /// - /// Render an input element of type "text". + /// Returns an <input> element of type "text" for the specified . /// - /// - /// An expression that identifies the object that contains the properties to render. + /// An expression to be evaluated against the current model. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). /// - /// - /// An object that contains the HTML attributes to set for the element. - /// Alternatively, an instance containing the HTML attributes. + /// + /// An that contains the HTML attributes for the element. Alternatively, an + /// instance containing the HTML attributes. /// - /// New containing the rendered HTML. + /// The type of the result. + /// A new containing the <input> element. + /// + /// + /// Combines and the string representation of the + /// to set <input> element's "name" attribute. Sanitizes the string + /// representation of the to set element's "id" attribute. + /// + /// Determines <input> element's "value" attribute based on the following precedence: + /// + /// + /// entry for the string representation of the + /// if entry exists and can be converted to a . + /// + /// + /// result if it is non-null and can be parsed as a . + /// Formats result using or converts result to a directly if + /// is null or empty. + /// + /// Existing "value" entry in if any. + /// Otherwise, string.Empty. + /// + /// HtmlString TextBoxFor([NotNull] Expression> expression, string format, object htmlAttributes); /// - /// Returns the validation message for the specified expression + /// Returns the validation message if an error exists in the + /// object for the specified . /// - /// An expression, relative to the current model. - /// The message to be displayed. This will always be visible but client-side - /// validation may update the associated CSS class. - /// An object that contains the HTML attributes to set for the element. + /// An expression to be evaluated against the current model. + /// + /// The message to be displayed. If null or empty, method extracts an error string from the + /// object. Message will always be visible but client-side + /// validation may update the associated CSS class. + /// + /// + /// An that contains the HTML attributes for the element. /// Alternatively, an instance containing the HTML attributes. /// - /// The tag to wrap the in the generated HTML. - /// Its default value is . - /// An that contains the validation message + /// + /// The tag to wrap the in the generated HTML. Its default value is + /// . + /// + /// The type of the result. + /// + /// A new containing the element. null if the + /// is valid and client-side validation is disabled. + /// HtmlString ValidationMessageFor([NotNull] Expression> expression, string message, object htmlAttributes, @@ -270,7 +428,7 @@ namespace Microsoft.AspNet.Mvc.Rendering /// /// Returns the formatted value for the specified . /// - /// The expression to be evaluated against the current model. + /// An expression to be evaluated against the current model. /// /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). ///