Merge pull request #6738 from sachatrauwaen/dev-pageservice

Priority-based IPageService for page metadata, head tags, and messages

Author: mitchelsellers

DNN Platform/DotNetNuke.Abstractions/Pages/IPageService.cs

@@ -0,0 +1,109 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information
+
+namespace DotNetNuke.Abstractions.Pages
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Text;
+
+    /// <summary>
+    /// Provides services for managing page content with priority-based storage.
+    /// </summary>
+    public interface IPageService
+    {
+        /// <summary>
+        /// Set the Page Title.
+        /// </summary>
+        /// <param name="value">The title value to set.</param>
+        /// <param name="priority">The priority of this title (lower number = higher priority).</param>
+        void SetTitle(string value, int priority = PagePriority.Default);
+
+        /// <summary>
+        /// Set the Page Description.
+        /// </summary>
+        /// <param name="value">The description value to set.</param>
+        /// <param name="priority">The priority of this description (lower number = higher priority).</param>
+        void SetDescription(string value, int priority = PagePriority.Default);
+
+        /// <summary>
+        /// Set the Page Keywords.
+        /// </summary>
+        /// <param name="value">The keywords value to set.</param>
+        /// <param name="priority">The priority of these keywords (lower number = higher priority).</param>
+        void SetKeyWords(string value, int priority = PagePriority.Default);
+
+        /// <summary>
+        /// Set the Page Canonical Link URL.
+        /// </summary>
+        /// <param name="value">The canonical link URL value to set.</param>
+        /// <param name="priority">The priority of this canonical link URL (lower number = higher priority).</param>
+        void SetCanonicalLinkUrl(string value, int priority = PagePriority.Default);
+
+        /// <summary>
+        /// Add a tag to the header of the page.
+        /// </summary>
+        /// <param name="tagItem">Priority item containing the tag and priority information.</param>
+        void AddToHead(PageTag tagItem);
+
+        /// <summary>
+        /// Add a standard meta header tag.
+        /// </summary>
+        /// <param name="metaItem">Priority meta item containing the meta tag information and priority.</param>
+        void AddMeta(PageMeta metaItem);
+
+        /// <summary>
+        /// Add a message to be displayed on the page.
+        /// </summary>
+        /// <param name="messageItem">Priority message item containing the message information and priority.</param>
+        void AddMessage(PageMessage messageItem);
+
+        /// <summary>
+        /// Gets the current title value with highest priority.
+        /// </summary>
+        /// <returns>The title value or null if not set.</returns>
+        string GetTitle();
+
+        /// <summary>
+        /// Gets the current description value with highest priority.
+        /// </summary>
+        /// <returns>The description value or null if not set.</returns>
+        string GetDescription();
+
+        /// <summary>
+        /// Gets the current keywords value with highest priority.
+        /// </summary>
+        /// <returns>The keywords value or null if not set.</returns>
+        string GetKeyWords();
+
+        /// <summary>
+        /// Gets the canonical link URL.
+        /// </summary>
+        /// <returns>The canonical link URL or null if not set.</returns>
+        string GetCanonicalLinkUrl();
+
+        /// <summary>
+        /// Gets all head tags ordered by priority (lowest priority first).
+        /// </summary>
+        /// <returns>List of head tags ordered by priority.</returns>
+        IEnumerable<PageTag> GetHeadTags();
+
+        /// <summary>
+        /// Gets all meta tags ordered by priority (lowest priority first).
+        /// </summary>
+        /// <returns>List of meta tags ordered by priority.</returns>
+        IEnumerable<PageMeta> GetMetaTags();
+
+        /// <summary>
+        /// Gets all messages ordered by priority (lowest priority first).
+        /// </summary>
+        /// <returns>List of messages ordered by priority.</returns>
+        IEnumerable<PageMessage> GetMessages();
+
+        /// <summary>
+        /// Clears all stored page data. Useful for testing or resetting state.
+        /// </summary>
+        void Clear();
+    }
+}

DNN Platform/DotNetNuke.Abstractions/Pages/PageMessage.cs

@@ -0,0 +1,100 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information
+
+namespace DotNetNuke.Abstractions.Pages
+{
+    /// <summary>
+    /// Represents a message with priority information for display on a page.
+    /// Messages can include success notifications, warnings, errors, or informational content.
+    /// </summary>
+    /// <remarks>
+    /// This class is used to store messages that will be displayed to users on a page.
+    /// Priority determines the order in which messages are displayed, with lower numbers having higher priority.
+    /// Common priority values are defined in <see cref="PagePriority"/>.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Create a success message with high priority
+    /// var successMessage = new PriorityMessage(
+    ///     "Operation Successful",
+    ///     "The data has been saved successfully.",
+    ///     MessageType.Success,
+    ///     "/images/success-icon.png",
+    ///     PagePriority.Site);
+    ///
+    /// // Create an error message with default priority
+    /// var errorMessage = new PriorityMessage(
+    ///     "Validation Error",
+    ///     "Please check the required fields.",
+    ///     MessageType.Error,
+    ///     "",
+    ///     PagePriority.Default);
+    /// </code>
+    /// </example>
+    public class PageMessage
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PageMessage"/> class.
+        /// </summary>
+        /// <param name="heading">The heading text for the message.</param>
+        /// <param name="message">The message text content. Cannot be null or empty.</param>
+        /// <param name="messageType">The type/severity of the message.</param>
+        /// <param name="iconSrc">The optional icon source URL for the message. Use empty string if no icon is needed.</param>
+        /// <param name="priority">The priority of the message. Use values from <see cref="PagePriority"/> for consistency.</param>
+        public PageMessage(string heading, string message, PageMessageType messageType, string iconSrc, int priority)
+        {
+            this.Heading = heading;
+            this.Message = message;
+            this.MessageType = messageType;
+            this.IconSrc = iconSrc;
+            this.Priority = priority;
+        }
+
+        /// <summary>
+        /// Gets or sets the heading text for the message.
+        /// </summary>
+        /// <value>
+        /// A string containing the heading text that will be displayed prominently.
+        /// This should be a concise summary of the message.
+        /// </value>
+        public string Heading { get; set; }
+
+        /// <summary>
+        /// Gets or sets the message text content.
+        /// </summary>
+        /// <value>
+        /// A string containing the detailed message content that will be displayed to the user.
+        /// This can contain HTML markup for formatting.
+        /// </value>
+        public string Message { get; set; }
+
+        /// <summary>
+        /// Gets or sets the type/severity of the message.
+        /// </summary>
+        /// <value>
+        /// A <see cref="MessageType"/> value indicating the severity or type of the message.
+        /// This affects how the message is styled and displayed to the user.
+        /// </value>
+        public PageMessageType MessageType { get; set; }
+
+        /// <summary>
+        /// Gets or sets the optional icon source URL for the message.
+        /// </summary>
+        /// <value>
+        /// A string containing the URL or path to an icon image, or an empty string if no icon is needed.
+        /// The icon will be displayed alongside the message to provide visual context.
+        /// </value>
+        public string IconSrc { get; set; }
+
+        /// <summary>
+        /// Gets or sets the priority of the message (lower number = higher priority).
+        /// </summary>
+        /// <value>
+        /// An integer representing the display priority of the message.
+        /// Messages with lower priority numbers will be displayed before those with higher numbers.
+        /// Use constants from <see cref="PagePriority"/> for consistent priority values.
+        /// </value>
+        public int Priority { get; set; }
+    }
+}

DNN Platform/DotNetNuke.Abstractions/Pages/PageMessageType.cs

@@ -0,0 +1,73 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information
+
+namespace DotNetNuke.Abstractions.Pages
+{
+    /// <summary>
+    /// Defines the types and severity levels for page messages.
+    /// Message types determine how messages are styled and presented to users.
+    /// </summary>
+    /// <remarks>
+    /// These enumeration values are used to categorize messages by their purpose and severity.
+    /// The UI layer typically uses these values to apply appropriate styling, colors, and icons
+    /// to provide visual context to users about the nature of the message.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Success message for completed operations
+    /// var successMsg = new PageMessage("Operation Complete", "Data saved successfully", MessageType.Success, "", PagePriority.Default);
+    ///
+    /// // Warning message for potential issues
+    /// var warningMsg = new PageMessage("Warning", "This action cannot be undone", MessageType.Warning, "", PagePriority.Default);
+    ///
+    /// // Error message for failed operations
+    /// var errorMsg = new PageMessage("Error", "Failed to save data", MessageType.Error, "", PagePriority.Default);
+    ///
+    /// // Informational message for general notifications
+    /// var infoMsg = new PageMessage("Notice", "System maintenance scheduled", MessageType.Info, "", PagePriority.Default);
+    /// </code>
+    /// </example>
+    public enum PageMessageType
+    {
+        /// <summary>
+        /// Success message type.
+        /// Used for messages indicating successful completion of operations.
+        /// Typically displayed with green styling and success icons.
+        /// </summary>
+        /// <example>
+        /// Use for: Data saved, user created, operation completed, etc.
+        /// </example>
+        Success = 0,
+
+        /// <summary>
+        /// Warning message type.
+        /// Used for messages indicating potential issues or important notices that require user attention.
+        /// Typically displayed with yellow/orange styling and warning icons.
+        /// </summary>
+        /// <example>
+        /// Use for: Validation warnings, deprecation notices, cautionary information, etc.
+        /// </example>
+        Warning = 1,
+
+        /// <summary>
+        /// Error message type.
+        /// Used for messages indicating failed operations or critical issues.
+        /// Typically displayed with red styling and error icons.
+        /// </summary>
+        /// <example>
+        /// Use for: Validation errors, operation failures, system errors, etc.
+        /// </example>
+        Error = 2,
+
+        /// <summary>
+        /// Informational message type.
+        /// Used for general notifications and informational content.
+        /// Typically displayed with blue styling and info icons.
+        /// </summary>
+        /// <example>
+        /// Use for: General notifications, tips, system status updates, etc.
+        /// </example>
+        Info = 3,
+    }
+}

DNN Platform/DotNetNuke.Abstractions/Pages/PageMeta.cs

@@ -0,0 +1,84 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information
+
+namespace DotNetNuke.Abstractions.Pages
+{
+    /// <summary>
+    /// Represents a meta tag with priority information for inclusion in the HTML head section.
+    /// Meta tags provide metadata about the HTML document and are used by search engines and browsers.
+    /// </summary>
+    /// <remarks>
+    /// This class is used to store meta tag information that will be rendered in the HTML head section.
+    /// Priority determines the order in which meta tags are rendered, with lower numbers having higher priority.
+    /// Common priority values are defined in <see cref="PagePriority"/>.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Create a description meta tag with page priority
+    /// var descriptionMeta = new PriorityMeta(
+    ///     "description",
+    ///     "This is the page description for SEO purposes.",
+    ///     PagePriority.Page);
+    ///
+    /// // Create a keywords meta tag with default priority
+    /// var keywordsMeta = new PriorityMeta(
+    ///     "keywords",
+    ///     "DNN, CMS, content management",
+    ///     PagePriority.Default);
+    ///
+    /// // Create a viewport meta tag with site priority
+    /// var viewportMeta = new PriorityMeta(
+    ///     "viewport",
+    ///     "width=device-width, initial-scale=1.0",
+    ///     PagePriority.Site);
+    /// </code>
+    /// </example>
+    public class PageMeta
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PageMeta"/> class.
+        /// </summary>
+        /// <param name="name">The name attribute of the meta tag. Cannot be null or empty.</param>
+        /// <param name="content">The content attribute of the meta tag. Cannot be null.</param>
+        /// <param name="priority">The priority of the meta tag (lower number = higher priority). Use values from <see cref="PagePriority"/> for consistency.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when name or content is null.</exception>
+        /// <exception cref="System.ArgumentException">Thrown when name is empty.</exception>
+        public PageMeta(string name, string content, int priority)
+        {
+            this.Name = name;
+            this.Content = content;
+            this.Priority = priority;
+        }
+
+        /// <summary>
+        /// Gets or sets the name attribute of the meta tag.
+        /// </summary>
+        /// <value>
+        /// A string containing the name attribute value for the meta tag.
+        /// Common values include "description", "keywords", "author", "viewport", etc.
+        /// This will be rendered as: &lt;meta name="[Name]" content="[Content]" /&gt;.
+        /// </value>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// Gets or sets the content attribute of the meta tag.
+        /// </summary>
+        /// <value>
+        /// A string containing the content attribute value for the meta tag.
+        /// This contains the actual metadata information associated with the name attribute.
+        /// The content should be appropriate for the specified name attribute.
+        /// </value>
+        public string Content { get; set; }
+
+        /// <summary>
+        /// Gets or sets the priority of the meta tag (lower number = higher priority).
+        /// </summary>
+        /// <value>
+        /// An integer representing the rendering priority of the meta tag in the HTML head section.
+        /// Meta tags with lower priority numbers will be rendered before those with higher numbers.
+        /// Use constants from <see cref="PagePriority"/> for consistent priority values.
+        /// </value>
+        public int Priority { get; set; }
+    }
+}