From 1103d3630b9776f456115a4170de74662a3e9a03 Mon Sep 17 00:00:00 2001 From: dougbu Date: Fri, 1 Aug 2014 12:13:22 -0700 Subject: [PATCH] `@Html.DisplayName()`, `.DisplayText()`, `.Id()`, `.Name()`, `.Value()` return `string` - fixes #566 and part of #847 - allows compositions such as `@Html.Label("property", Html.Id("property"))` and `@Html.Raw(Html.DisplayText("property"))` (this one is not recommended) - adjust XML comments to match - add missing XML comments to `HtmlHelperValueExtensions` - nit: `TInnerModel` -> `TModelItem` - increase XML comment consistency for changed methods - generally make wording more consistent e.g. how we use words such as "returns" - use `` more --- .../Rendering/Html/HtmlHelper.cs | 31 ++++---- .../Rendering/Html/HtmlHelperOfT.cs | 18 ++--- .../HtmlHelperDisplayNameExtensions.cs | 32 ++++---- .../Rendering/HtmlHelperNameExtensions.cs | 18 ++--- .../Rendering/HtmlHelperValueExtensions.cs | 55 +++++++++++-- .../Rendering/IHtmlHelper.cs | 54 +++++++------ .../Rendering/IHtmlHelperOfT.cs | 77 ++++++++++--------- 7 files changed, 171 insertions(+), 114 deletions(-) diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs index 19b13152bb..74e41c16ba 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs @@ -248,17 +248,16 @@ public string GenerateIdFromName([NotNull] string name) } /// - public HtmlString DisplayName(string expression) + public string DisplayName(string expression) { var metadata = ExpressionMetadataProvider.FromStringExpression(expression, ViewData, MetadataProvider); return GenerateDisplayName(metadata, expression); } /// - public HtmlString DisplayText(string name) + public string DisplayText(string name) { var metadata = ExpressionMetadataProvider.FromStringExpression(name, ViewData, MetadataProvider); - return GenerateDisplayText(metadata); } @@ -295,7 +294,7 @@ public HtmlString Hidden(string name, object value, object htmlAttributes) } /// - public HtmlString Id(string name) + public string Id(string name) { return GenerateId(name); } @@ -318,7 +317,7 @@ public HtmlString ListBox(string name, IEnumerable selectList, o } /// - public HtmlString Name(string name) + public string Name(string name) { return GenerateName(name); } @@ -484,7 +483,7 @@ public HtmlString TextBox(string name, object value, string format, IDictionary< } /// - public HtmlString Value([NotNull] string name, string format) + public string Value([NotNull] string name, string format) { return GenerateValue(name, value: null, format: format, useViewData: true); } @@ -594,7 +593,7 @@ protected object GetModelStateValue(string key, Type destinationType) htmlAttributes: htmlAttributeDictionary); } - protected virtual HtmlString GenerateDisplayName([NotNull] ModelMetadata metadata, string htmlFieldName) + protected virtual string GenerateDisplayName([NotNull] ModelMetadata metadata, string htmlFieldName) { // We don't call ModelMetadata.GetDisplayName here because // we want to fall back to the field name rather than the ModelType. @@ -606,12 +605,12 @@ protected virtual HtmlString GenerateDisplayName([NotNull] ModelMetadata metadat string.IsNullOrEmpty(htmlFieldName) ? string.Empty : htmlFieldName.Split('.').Last(); } - return new HtmlString(Encode(resolvedDisplayName)); + return resolvedDisplayName; } - protected virtual HtmlString GenerateDisplayText(ModelMetadata metadata) + protected virtual string GenerateDisplayText(ModelMetadata metadata) { - return new HtmlString(metadata.SimpleDisplayText); + return metadata.SimpleDisplayText ?? string.Empty; } protected HtmlString GenerateDropDown(ModelMetadata metadata, string expression, @@ -722,9 +721,9 @@ protected virtual HtmlString GenerateDisplayText(ModelMetadata metadata) htmlAttributes: htmlAttributeDictionary); } - protected virtual HtmlString GenerateId(string expression) + protected virtual string GenerateId(string expression) { - return new HtmlString(Encode(ViewData.TemplateInfo.GetFullHtmlFieldName(expression))); + return ViewData.TemplateInfo.GetFullHtmlFieldName(expression); } protected virtual HtmlString GenerateLabel([NotNull] ModelMetadata metadata, @@ -786,10 +785,10 @@ protected virtual HtmlString GenerateId(string expression) htmlAttributes: htmlAttributes); } - protected virtual HtmlString GenerateName(string name) + protected virtual string GenerateName(string name) { var fullName = ViewData.TemplateInfo.GetFullHtmlFieldName(name); - return new HtmlString(Encode(fullName)); + return fullName; } protected virtual HtmlString GeneratePassword(ModelMetadata metadata, string name, object value, @@ -1301,7 +1300,7 @@ protected virtual HtmlString GenerateName(string name) return divBuilder.ToHtmlString(TagRenderMode.Normal); } - protected virtual HtmlString GenerateValue(string name, object value, string format, bool useViewData) + protected virtual string GenerateValue(string name, object value, string format, bool useViewData) { var fullName = ViewData.TemplateInfo.GetFullHtmlFieldName(name); var attemptedValue = (string)GetModelStateValue(fullName, typeof(string)); @@ -1332,7 +1331,7 @@ protected virtual HtmlString GenerateValue(string name, object value, string for resolvedValue = FormatValue(value, format); } - return new HtmlString(Encode(resolvedValue)); + return resolvedValue; } /// diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelperOfT.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelperOfT.cs index f52d9932cf..195ff48697 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelperOfT.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelperOfT.cs @@ -88,19 +88,19 @@ public override void Contextualize([NotNull] ViewContext viewContext) } /// - public HtmlString DisplayNameFor([NotNull] Expression> expression) + public string DisplayNameFor([NotNull] Expression> expression) { var metadata = GetModelMetadata(expression); return GenerateDisplayName(metadata, ExpressionHelper.GetExpressionText(expression)); } /// - public HtmlString DisplayNameForInnerType( - [NotNull] Expression> expression) + public string DisplayNameForInnerType( + [NotNull] Expression> expression) { - var metadata = ExpressionMetadataProvider.FromLambdaExpression( + var metadata = ExpressionMetadataProvider.FromLambdaExpression( expression, - new ViewDataDictionary(MetadataProvider), + new ViewDataDictionary(MetadataProvider), MetadataProvider); var expressionText = ExpressionHelper.GetExpressionText(expression); @@ -113,7 +113,7 @@ public HtmlString DisplayNameFor([NotNull] Expression - public HtmlString DisplayTextFor([NotNull] Expression> expression) + public string DisplayTextFor([NotNull] Expression> expression) { return GenerateDisplayText(GetModelMetadata(expression)); } @@ -144,7 +144,7 @@ public HtmlString DisplayTextFor([NotNull] Expression - public HtmlString IdFor([NotNull] Expression> expression) + public string IdFor([NotNull] Expression> expression) { return GenerateId(GetExpressionName(expression)); } @@ -172,7 +172,7 @@ public HtmlString IdFor([NotNull] Expression> } /// - public HtmlString NameFor([NotNull] Expression> expression) + public string NameFor([NotNull] Expression> expression) { var expressionName = GetExpressionName(expression); return Name(expressionName); @@ -242,7 +242,7 @@ protected ModelMetadata GetModelMetadata([NotNull] Expression - public HtmlString ValueFor(Expression> expression, string format) + public string ValueFor([NotNull] Expression> expression, string format) { var metadata = GetModelMetadata(expression); return GenerateValue(ExpressionHelper.GetExpressionText(expression), metadata.Model, format, diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs index cb40f12361..8e19e8dc8c 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs @@ -8,32 +8,36 @@ namespace Microsoft.AspNet.Mvc.Rendering { /// - /// DisplayName-related extensions for and . + /// DisplayName-related extensions for and . /// public static class HtmlHelperDisplayNameExtensions { /// - /// Gets the display name for the current model. + /// Returns the display name for the current model. /// - /// An that represents HTML markup. - public static HtmlString DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper) + /// The instance this method extends. + /// A containing the display name. + public static string DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper) { return htmlHelper.DisplayName(string.Empty); } /// - /// Gets the display name for the model. + /// Returns the display name for the specified + /// if the current model represents a collection. /// - /// The instance that this method extends. - /// An expression that identifies the object that contains the display name. - /// - /// The display name for the model. - /// - public static HtmlString DisplayNameFor( - [NotNull] this IHtmlHelper> htmlHelper, - [NotNull] Expression> expression) + /// + /// The instance this method extends. + /// + /// The expression to be evaluated against an item in the current model. + /// The of items in the model collection. + /// The of the result. + /// A containing the display name. + public static string DisplayNameFor( + [NotNull] this IHtmlHelper> htmlHelper, + [NotNull] Expression> expression) { - return htmlHelper.DisplayNameForInnerType(expression); + return htmlHelper.DisplayNameForInnerType(expression); } } } diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperNameExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperNameExtensions.cs index 2d46b7ff0e..eb1b714dd3 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperNameExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperNameExtensions.cs @@ -4,26 +4,26 @@ namespace Microsoft.AspNet.Mvc.Rendering { /// - /// Name-related extensions for and . + /// Name-related extensions for . /// public static class HtmlHelperNameExtensions { /// - /// Gets the full HTML field name for the current model. + /// Returns the full HTML element name for the current model. /// - /// The instance that this method extends. - /// An that represents HTML markup. - public static HtmlString NameForModel([NotNull] this IHtmlHelper htmlHelper) + /// The instance this method extends. + /// A containing the element name. + public static string NameForModel([NotNull] this IHtmlHelper htmlHelper) { return htmlHelper.Name(string.Empty); } /// - /// Gets the full HTML field id for the current model. + /// Returns the HTML element Id for the current model. /// - /// The instance that this method extends. - /// An that represents HTML markup. - public static HtmlString IdForModel([NotNull] this IHtmlHelper htmlHelper) + /// The instance this method extends. + /// A containing the element Id. + public static string IdForModel([NotNull] this IHtmlHelper htmlHelper) { return htmlHelper.Id(string.Empty); } diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs index 0eea6e8b82..646157b5af 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs @@ -6,28 +6,71 @@ namespace Microsoft.AspNet.Mvc.Rendering { + /// + /// Value-related extensions for and . + /// public static class HtmlHelperValueExtensions { - public static HtmlString Value([NotNull] this IHtmlHelper htmlHelper, string name) + /// + /// Returns the formatted value for the specified expression . + /// + /// The instance this method extends. + /// Expression name, relative to the current model. + /// A containing the formatted value. + /// + /// Converts the expression result to a directly. + /// + public static string Value([NotNull] this IHtmlHelper htmlHelper, string name) { return htmlHelper.Value(name, format: null); } - public static HtmlString ValueFor( + /// + /// Returns the formatted value for the specified . + /// + /// The instance this method extends. + /// The expression to be evaluated against the current model. + /// The of the model. + /// The of the result. + /// A containing the formatted value. + /// + /// Converts the result to a directly. + /// + public static string ValueFor( [NotNull] this IHtmlHelper htmlHelper, [NotNull] Expression> expression) { return htmlHelper.ValueFor(expression, format: null); } - public static HtmlString ValueForModel([NotNull] this IHtmlHelper htmlHelper) + /// + /// Returns the formatted value for the current model. + /// + /// The instance this method extends. + /// A containing the formatted value. + /// + /// Converts the model value to a directly. + /// + public static string ValueForModel([NotNull] this IHtmlHelper htmlHelper) { - return ValueForModel(htmlHelper, format: null); + return htmlHelper.Value(name: string.Empty, format: null); } - public static HtmlString ValueForModel([NotNull] this IHtmlHelper htmlHelper, string format) + /// + /// Returns the formatted value for the current model. + /// + /// The instance this method extends. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// A containing the formatted value. + /// + /// Converts the model value to a directly if + /// is or empty. + /// + public static string ValueForModel([NotNull] this IHtmlHelper htmlHelper, string format) { - return htmlHelper.Value(string.Empty, format); + return htmlHelper.Value(name: string.Empty, format: format); } } } diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs index cee689b0b4..8c46d4c83b 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs @@ -146,23 +146,21 @@ public interface IHtmlHelper object additionalViewData); /// - /// Gets the display name. + /// Returns the display name for the specified expression . /// - /// An expression that identifies the object that contains the display name. - /// - /// The display name. - /// - HtmlString DisplayName(string expression); + /// Expression name, relative to the current model. + /// A containing the display name. + string DisplayName(string expression); - /// Returns the HtmlString corresponding to the property in the model specified by the name. + /// + /// Returns the simple display text for the specified expression . /// - /// - /// The string which identifies the object for which the HtmlString should be returned. + /// Expression name, relative to the current model. /// - /// New containing the display text. If the value is null, - /// then it returns the ModelMetadata.NullDisplayText. + /// A containing the simple display text. + /// If the expression result is , returns . /// - HtmlString DisplayText(string name); + string DisplayText(string name); /// /// Returns a single-selection HTML {select} element using the specified name of the form field, @@ -263,11 +261,11 @@ public interface IHtmlHelper HtmlString Hidden(string name, object value, object htmlAttributes); /// - /// Gets the Id of the given string. + /// Returns the HTML element Id for the specified expression . /// - /// The string which identifies the object for which the Id should be returned. - /// New containing the Id. - HtmlString Id(string name); + /// Expression name, relative to the current model. + /// A containing the element Id. + string Id(string name); /// /// Returns an HTML label element and the property name of the property that is represented by the specified @@ -295,11 +293,11 @@ public interface IHtmlHelper HtmlString ListBox(string name, IEnumerable selectList, object htmlAttributes); /// - /// Gets the full HTML field name for the given expression . + /// Returns the full HTML element name for the specified expression . /// - /// Name of an expression, relative to the current model. - /// An that represents HTML markup. - HtmlString Name(string name); + /// Expression name, relative to the current model. + /// A containing the element name. + string Name(string name); /// /// Returns a partial view in string format. @@ -472,11 +470,17 @@ public interface IHtmlHelper string tag); /// - /// Returns the model value for the given expression . + /// Returns the formatted value for the specified expression . /// - /// Name of an expression, relative to the current model. - /// The optional format string to apply to the value. - /// An that represents HTML markup. - HtmlString Value([NotNull] string name, string format); + /// Expression name, relative to the current model. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// A containing the formatted value. + /// + /// Converts the expression result to a directly if + /// is or empty. + /// + string Value([NotNull] string name, string format); } } diff --git a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs index 7b934507cd..938398d4da 100644 --- a/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs +++ b/src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs @@ -54,36 +54,35 @@ public interface IHtmlHelper : IHtmlHelper object additionalViewData); /// - /// Gets the display name for the model. + /// Returns the display name for the specified . /// - /// An expression that identifies the object that contains the display name. - /// The type of the value. - /// - /// The display name for the model. - /// - HtmlString DisplayNameFor([NotNull] Expression> expression); + /// The expression to be evaluated against the current model. + /// The of the result. + /// A containing the display name. + string DisplayNameFor([NotNull] Expression> expression); /// - /// Gets the display name for the inner model if the current model represents a collection. + /// Returns the display name for the specified + /// if the current model represents a collection. /// - /// The type of the inner model - /// The type of the value. - /// An expression that identifies the object that contains the display name. - /// The display name for the inner model. - HtmlString DisplayNameForInnerType( - [NotNull] Expression> expression); + /// The expression to be evaluated against an item in the current model. + /// The of items in the model collection. + /// The of the result. + /// A containing the display name. + string DisplayNameForInnerType( + [NotNull] Expression> expression); /// - /// Returns the HtmlString corresponding to the expression specified. + /// Returns the simple display text for the specified . /// - /// - /// The expression identifies the object for which the HtmlString should be returned. - /// + /// The expression to be evaluated against the current model. + /// The of the result. /// - /// New containing the display text. If the value is null, - /// then it returns the ModelMetadata.NullDisplayText. + /// A containing the simple display text. + /// If the result is , returns + /// . /// - HtmlString DisplayTextFor([NotNull] Expression> expression); + string DisplayTextFor([NotNull] Expression> expression); /// /// Returns a single-selection HTML {select} element for the object that is represented @@ -141,11 +140,12 @@ public interface IHtmlHelper : IHtmlHelper object htmlAttributes); /// - /// Gets the Id of the given expression. + /// Returns the HTML element Id for the specified . /// - /// The expression identifies the object for which the Id should be returned. - /// New containing the Id. - HtmlString IdFor([NotNull] Expression> expression); + /// The expression to be evaluated against the current model. + /// The 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 @@ -180,12 +180,12 @@ public interface IHtmlHelper : IHtmlHelper object htmlAttributes); /// - /// Gets the full HTML field name for the given . + /// Returns the full HTML element name for the specified . /// - /// The the returns. - /// An expression, relative to the current model. - /// An that represents HTML markup. - HtmlString NameFor([NotNull] Expression> expression); + /// The expression to be evaluated against the current model. + /// The of the result. + /// A containing the element name. + string NameFor([NotNull] Expression> expression); /// /// Render an input element of type "password". @@ -262,11 +262,18 @@ public interface IHtmlHelper : IHtmlHelper string tag); /// - /// Returns the model value for the given expression . + /// Returns the formatted value for the specified . /// - /// An expression, relative to the current model. - /// The optional format string to apply to the value. - /// An that represents HTML markup. - HtmlString ValueFor([NotNull] Expression> expression, string format); + /// The expression to be evaluated against the current model. + /// + /// The composite format (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx). + /// + /// The of the result. + /// A containing the formatted value. + /// + /// Converts the result to a directly if + /// is or empty. + /// + string ValueFor([NotNull] Expression> expression, string format); } }