Formatting Settings

Overview

The Formatting Settings feature of the SiticoneHumanizerDateTime control allows developers to customize the presentation of the humanized date/time output. Developers can choose from predefined format styles or define a custom format, decide whether to include relative day expressions (like "today" or "yesterday"), include milliseconds for higher precision, use abbreviated time unit names, and add seasonal context to the output.

Property	Description
UseRelativeDays	Enables smart day references (e.g., "today", "yesterday", "tomorrow") when the time span is close to the current day.
IncludeMilliseconds	Controls whether milliseconds are included in the time span display, useful for high-precision output.
TimeFormat	Sets the format style for time span display using one of the enumerated values: Standard, Detailed, Concise, Natural, or Custom.
UseAbbreviations	Toggles the use of abbreviated unit names (e.g., "yr" instead of "year") for a more compact output.
UseSeasonalContext	Adds seasonal context (e.g., "in winter") to the output for a more enriched natural language description.
CustomFormat	Provides a custom format pattern for output when the TimeFormat is set to Custom, allowing for personalized token replacement.

Key Points

Aspect	Detail
Relative Days	UseRelativeDays helps to automatically replace dates that are very close to today with natural language terms such as "today", "yesterday", or "tomorrow".
Milliseconds Inclusion	IncludeMilliseconds allows the output to display milliseconds, adding precision when necessary.
Time Format Style	TimeFormat lets you select from multiple predefined styles, impacting the granularity and style of the output string.
Abbreviated Units	UseAbbreviations determines whether full unit names or their abbreviated forms are used in the output.
Seasonal Context	UseSeasonalContext appends season-related information to the output, enhancing the natural language feel.
Custom Format Pattern	CustomFormat provides the flexibility to define output patterns with tokens for various time components.

Best Practices

Practice	Recommendation
Define Format Style Early	Choose an appropriate TimeFormat early in the design process to match the application's UI/UX requirements.
Enable Relative Days	Enable UseRelativeDays for user-friendly date descriptions when the date difference is minimal.
Use Abbreviations Judiciously	Toggle UseAbbreviations based on the available space in your UI; use full unit names when space is ample.
Customize When Needed	Use CustomFormat only when the predefined format options do not meet your specific requirements.
Consider Precision Requirements	Use IncludeMilliseconds only if your application demands high-precision time measurements.

Common Pitfalls

Pitfall	Explanation
Overcomplicating Output	Overuse of custom formats or too many enabled options can make the output confusing for end users.
Misaligned Abbreviation Settings	Enabling UseAbbreviations without considering consistency across the application can lead to mismatched displays.
Ignoring Seasonal Context	Adding seasonal context (UseSeasonalContext) when not appropriate may distract from the main information.
Unnecessary Millisecond Detail	Including milliseconds in contexts where such precision is not needed can clutter the output and reduce readability.

Usage Scenarios

Scenario	Details
Basic Time Span Display	Use Standard or Natural TimeFormat to present a simple and clear humanized date/time string.
High-Precision Time Display	Enable IncludeMilliseconds to display milliseconds when the exact time difference is critical.
Compact UI Displays	Use Concise format with UseAbbreviations enabled to save space in the UI.
Custom Formatted Output	Define a custom format using CustomFormat for unique application needs when the default formats do not suffice.

Real Life Usage Scenarios

Scenario	Details
Dashboard Notifications	Use Natural format along with UseRelativeDays to show recent events in a user-friendly manner (e.g., "today" or "yesterday").
Mobile Applications	In space-constrained interfaces, use Concise format with abbreviations to provide quick, readable time summaries.
Detailed Log Analysis	For debugging or log analysis, enable IncludeMilliseconds and Detailed format to capture precise time differences.
Seasonal Promotions	For applications with seasonal content, enable UseSeasonalContext to dynamically append season-related context to dates (e.g., "in summer").

Troubleshooting Tips

Issue	Solution
Output Appears Too Cluttered	Review the combination of enabled properties; consider disabling IncludeMilliseconds or using a simpler TimeFormat if the output is too detailed.
Inconsistent Abbreviation Usage	Ensure that UseAbbreviations is set uniformly across all instances where humanized dates are displayed.
Custom Format Not Working	Verify that the CustomFormat string contains valid tokens (e.g., {Y}, {M}, {D}, etc.) and that TimeFormat is set to Custom.
Missing Seasonal Context	If the expected seasonal context is not appearing, ensure UseSeasonalContext is enabled and that the date falls within a defined season range.

Code Samples and Integration Examples

Basic Formatting Settings Example

using System;
using System.Globalization;
using SiticoneNetFrameworkUI;

namespace FormattingDemo
{
    public class BasicDemo
    {
        public static void Main()
        {
            // Create an instance of the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Set a sample date for demonstration
            humanizer.Date = DateTime.Now.AddDays(-1).AddHours(-3);

            // Enable relative day expressions
            humanizer.UseRelativeDays = true;

            // Set the time format style to Natural
            humanizer.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Natural;

            // Set culture for localized output
            humanizer.Culture = new CultureInfo("en-US");

            // Retrieve and print the humanized output
            Console.WriteLine("Formatted Date: " + humanizer.Humanize);
        }
    }
}

Custom Format Example

using System;
using System.Globalization;
using SiticoneNetFrameworkUI;

namespace CustomFormatDemo
{
    public class CustomDemo
    {
        public static void Main()
        {
            // Instantiate the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Set the date to be humanized
            humanizer.Date = DateTime.Now.AddHours(-2).AddMinutes(-45);

            // Choose the Custom format mode
            humanizer.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Custom;

            // Define a custom format pattern
            humanizer.CustomFormat = "{H} hours and {m} minutes {DIR}";

            // Optionally, disable relative day expressions for custom formatting
            humanizer.UseRelativeDays = false;

            // Set culture for formatting
            humanizer.Culture = new CultureInfo("en-US");

            // Output the custom formatted humanized date
            Console.WriteLine("Custom Formatted Date: " + humanizer.Humanize);
        }
    }
}

Abbreviated and Concise Format Example

using System;
using System.Globalization;
using SiticoneNetFrameworkUI;

namespace ConciseDemo
{
    public class AbbreviatedDemo
    {
        public static void Main()
        {
            // Initialize the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Assign a date value
            humanizer.Date = DateTime.Now.AddMinutes(-90);

            // Set the time format to Concise
            humanizer.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Concise;

            // Enable abbreviated time unit names
            humanizer.UseAbbreviations = true;

            // Set culture for consistency
            humanizer.Culture = new CultureInfo("en-US");

            // Display the humanized output in a concise format
            Console.WriteLine("Concise Date: " + humanizer.Humanize);
        }
    }
}

Review

Aspect	Comment
Functionality	Formatting Settings offer versatile options to tailor the humanized output to match application design and user experience.
Integration	Seamlessly integrates with other control properties, enabling a mix-and-match approach to display options.
Flexibility	Provides both predefined and custom formatting options, ensuring the control can handle a wide range of presentation requirements.

Summary

Summary Aspect	Description
Customization	Formatting Settings allow developers to choose how detailed or concise the humanized output should be.
User Experience	Options like relative days, abbreviated units, and seasonal context enhance readability and user engagement.
Integration Ease	With multiple predefined format styles and custom formatting support, this feature can be adapted easily for various application needs.

Frequently Asked Questions (FAQ)

Question	Answer
What is the effect of enabling UseRelativeDays?	It replaces dates close to today with terms like "today", "yesterday", or "tomorrow" for improved readability.
How do I apply a custom output format?	Set TimeFormat to Custom and define the CustomFormat string with valid tokens such as {H} for hours and {DIR} for the time direction.
When should I use IncludeMilliseconds?	Enable IncludeMilliseconds only when you require high precision in the time difference output.

Tips for Developers

Tip	Recommendation
Test Different Formats	Experiment with various TimeFormat settings and custom formats to find the best fit for your application's needs.
Maintain Consistent Formatting	Use centralized configuration for formatting settings across your application to ensure a consistent user experience.
Validate Culture Settings	Always set the Culture property explicitly when localizing the output for international users.

---

By following this documentation for Formatting Settings, developers can effectively integrate and customize the SiticoneHumanizerDateTime control to display humanized date/time outputs that meet their application's design and functionality requirements.