Data Extraction & Display

This feature provides developers with robust mechanisms to retrieve, format, and present the input code data in multiple forms, ensuring that the information is easily accessible and ready to process.

Overview

Data Extraction & Presentation allows the retrieval of the entered code in its raw or formatted state. Developers can access the complete code as a string or integer, extract individual digits, and leverage various formatting options to display the data with placeholders or custom separators.

---

Key Points

Key Point	Description
Raw Data Access	The control exposes properties like Value, Digits, and individual digit access via the indexer for granular control over the entered data.
Formatted Output	With properties such as FormattedCode and FormattedFilledCode, developers can display the input with custom separators and placeholders, offering a clear visual presentation.
Type Conversion Methods	Methods like GetCodeAsString, GetCodeAsInt, and TryGetCodeAs provide flexible data extraction and conversion, enabling seamless integration with business logic.
Real-Time Data Reflection	The control’s design ensures that both partial and complete code states are accessible, allowing for dynamic UI updates and validation workflows.

---

Best Practices

Best Practice	Recommendation
Use Formatted Output for User Feedback	Leverage properties such as FormattedCode to provide users with a visual representation of the input, including placeholders for missing digits, to improve clarity during data entry.
Validate Data Before Processing	Always verify that the code is complete (using the IsComplete property) before converting or processing it, to avoid errors in business logic.
Use TryGetCodeAs for Safe Conversion	Employ the TryGetCodeAs method to attempt type-safe conversions of the entered code, ensuring graceful handling of conversion failures.
Monitor Changes with ValueChanged and InputCompleted Events	Subscribe to events like ValueChanged and InputCompleted to trigger data extraction logic immediately after the code input is modified or fully completed.

---

Common Pitfalls

Pitfall	Explanation	Mitigation
Processing Incomplete Data	Attempting to retrieve or convert the code when not all digit boxes are filled may lead to unexpected results (e.g., empty string or -1 for integer conversion).	Always check the IsComplete property before processing the extracted code.
Overlooking Placeholder Usage	Ignoring the use of placeholders in the formatted output may result in ambiguous displays, especially when some digit boxes are empty.	Use CodeWithPlaceholders or FormattedCode to provide a complete view of the input, highlighting missing digits.
Type Conversion Failures	Directly converting the code without error handling may lead to exceptions if the data is not in the expected format (e.g., non-numeric characters when expecting an integer).	Utilize the TryGetCodeAs method to safely handle conversion attempts and verify success before further processing.

---

Usage Scenarios

Scenario	Description	Implementation Example
Displaying an OTP Code	When showing the complete OTP code to the user, you can extract it as a string and also format it with separators for a clearer presentation.	Use GetCodeAsString to retrieve the raw code, and FormattedCode to display it with a specified separator.
Processing Numeric Codes	For PIN or security code validations, the control can convert the entered code into an integer and verify it against stored values.	Retrieve the code using GetCodeAsInt and check if the conversion was successful before using the integer value for authentication.
Providing Real-Time Input Feedback	During the data entry process, display both the entered digits and placeholders for missing digits to guide the user toward completing the input.	Bind the CodeWithPlaceholders property to a UI element (e.g., a label) to show a dynamic, visual representation of the input state.
Type-Safe Data Extraction	When different parts of an application require the code in various data types (e.g., string, int), use the TryGetCodeAs method to extract it safely.	Use TryGetCodeAs(out int codeValue) to safely extract a numeric representation and handle potential conversion errors.

---

Code Examples

Example 1: Extracting the Raw and Formatted Code

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Set a sample value (for demonstration purposes)
otpControl.SetValue("123456");

// Extract the complete code as a string
string rawCode = otpControl.GetCodeAsString;
Console.WriteLine($"Raw Code: {rawCode}");

// Extract and display the formatted code with a custom separator
string formattedCode = otpControl.FormattedCode; // Uses default separator defined by CodeSeparator
Console.WriteLine($"Formatted Code: {formattedCode}");

// Extract the formatted filled code (only non-empty digits)
string formattedFilledCode = otpControl.FormattedFilledCode;
Console.WriteLine($"Formatted Filled Code: {formattedFilledCode}");

Example 2: Safely Converting the Code to an Integer

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Set a sample value that represents a numeric code
otpControl.SetValue("987654");

// Verify that the input is complete before processing
if (otpControl.IsComplete)
{
    // Retrieve the code as an integer
    int numericCode = otpControl.GetCodeAsInt;
    
    // Alternatively, using type-safe conversion
    if (otpControl.TryGetCodeAs<int>(out int safeCode))
    {
        Console.WriteLine($"Numeric Code: {safeCode}");
    }
    else
    {
        Console.WriteLine("Failed to convert the code to an integer.");
    }
}
else
{
    Console.WriteLine("The code is incomplete.");
}

Example 3: Displaying the Code with Placeholders for Missing Digits

// Create an instance of the control
SiticoneOtp otpControl = new SiticoneOtp();

// Set a partially complete value (e.g., only the first three digits are entered)
otpControl.SetValue("12");

// Retrieve the code with placeholders for the missing digits
string codeWithPlaceholders = otpControl.CodeWithPlaceholders;
// For example, if the control expects 6 digits, this might output: "12____"
Console.WriteLine($"Code with Placeholders: {codeWithPlaceholders}");

---

Review

Aspect	Evaluation
Flexibility	The control provides multiple ways to extract and present data, including raw strings, formatted outputs with custom separators, and safe type conversions, allowing developers to choose the best method for their needs.
Ease of Integration	With intuitive properties and methods for data extraction, developers can easily bind or process the entered code as needed, with events supporting dynamic updates and validation.
Comprehensive Data Access	By exposing both individual digit access and aggregated views (such as the complete code and formatted versions), the control covers all common data extraction scenarios.

---

Summary

Data Extraction & Presentation in the SiticoneOtp control enables developers to access, format, and process the input code efficiently. With support for both raw and formatted data retrieval, along with safe type conversions and real-time visual representation of incomplete entries, this feature streamlines the integration of user input into application logic.

---

Additional Recommendations

Recommendation	Explanation
Validate Completeness Before Extraction	Always check the IsComplete property to ensure that the code is fully entered before processing to prevent errors or unintended behavior.
Customize Formatting for User Clarity	Use custom separators and placeholders to enhance the visual presentation of the code, making it easier for users to verify their input.
Leverage Event Subscriptions for Dynamic Updates	Subscribe to events such as ValueChanged and InputCompleted to update UI elements or trigger additional processing in real time as the code is entered or modified.
Maintain Consistency Across Conversions	Use TryGetCodeAs consistently for safe type conversions and ensure that fallback mechanisms are in place to handle conversion failures gracefully.