> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/data-formatting-and-display/siticone-humanizer-date../formatting-settings.md).

# 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.

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

### Key Points

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

### Best Practices

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

### Common Pitfalls

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

### Usage Scenarios

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

### Real Life Usage Scenarios

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

### Troubleshooting Tips

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

### Code Samples and Integration Examples

#### Basic Formatting Settings Example

```csharp
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

```csharp
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

```csharp
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

<table><thead><tr><th width="152">Aspect</th><th>Comment</th></tr></thead><tbody><tr><td>Functionality</td><td>Formatting Settings offer versatile options to tailor the humanized output to match application design and user experience.</td></tr><tr><td>Integration</td><td>Seamlessly integrates with other control properties, enabling a mix-and-match approach to display options.</td></tr><tr><td>Flexibility</td><td>Provides both predefined and custom formatting options, ensuring the control can handle a wide range of presentation requirements.</td></tr></tbody></table>

### Summary

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

### 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

<table><thead><tr><th width="285">Tip</th><th>Recommendation</th></tr></thead><tbody><tr><td>Test Different Formats</td><td>Experiment with various <code>TimeFormat</code> settings and custom formats to find the best fit for your application's needs.</td></tr><tr><td>Maintain Consistent Formatting</td><td>Use centralized configuration for formatting settings across your application to ensure a consistent user experience.</td></tr><tr><td>Validate Culture Settings</td><td>Always set the <code>Culture</code> property explicitly when localizing the output for international users.</td></tr></tbody></table>

***

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.