MauiPersianToolkit

Maui Persian Toolkit

NuGet License Build Tests .NET 8

MauiPersianToolkit is a comprehensive library for .NET MAUI that provides a variety of Persian language UI controls and components with full support for multiple calendar systems. This library is designed to help developers create modern, cross-platform applications with support for Persian language and right-to-left (RTL) layouts.

✨ Key Features

📅 Advanced Calendar System

🎨 UI Controls

💬 Dialog System

🛠️ Developer Tools

📋 Project Statistics

🚀 Installation

You can install the MauiPersianToolkit package via NuGet Package Manager or .NET CLI:

NuGet Package Manager

Install-Package MauiPersianToolkit

.NET CLI

dotnet add package MauiPersianToolkit

🎯 Getting Started

1. Startup Configuration

Add the Persian Toolkit to your MauiApp in MauiProgram.cs:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                fonts.AddFont("IranianSans.ttf", "IranianSans");
            })
            .UseMauiCommunityToolkit()
            .UsePersianUIControls();  // Add this line
        
        return builder.Build();
    }
}

2. Basic XAML Usage

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:persian="clr-namespace:MauiPersianToolkit.Controls;assembly=MauiPersianToolkit"
             x:Class="YourApp.MainPage"
             Title="Persian Toolkit Demo">

    <ScrollView>
        <StackLayout Padding="20" Spacing="15">
            
            <!-- Persian DatePicker - Single Selection -->
            <Label Text="Persian DatePicker (Single)" FontSize="16" FontAttributes="Bold"/>
            <persian:DatePicker 
                PlaceHolder="Select Date" 
                SelectedPersianDate="{Binding SelectedDate}"
                CalendarType="Persian"
                DisplayFormat="yyyy/MM/dd" />
            
            <!-- Gregorian DatePicker -->
            <Label Text="Gregorian DatePicker" FontSize="16" FontAttributes="Bold"/>
            <persian:DatePicker 
                PlaceHolder="Select Date" 
                SelectedPersianDate="{Binding SelectedGregorianDate}"
                CalendarType="Gregorian"
                DisplayFormat="yyyy/MM/dd" />
            
            <!-- Islamic (Hijri) DatePicker -->
            <Label Text="Islamic DatePicker" FontSize="16" FontAttributes="Bold"/>
            <persian:DatePicker 
                PlaceHolder="Select Date" 
                SelectedPersianDate="{Binding SelectedHijriDate}"
                CalendarType="Hijri"
                DisplayFormat="yyyy/MM/dd" />

            <!-- Entry Control -->
            <Label Text="Entry Field" FontSize="16" FontAttributes="Bold"/>
            <persian:EntryView 
                PlaceHolder="Enter your name" 
                Text="{Binding UserName}" />

            <!-- Expander Control -->
            <Label Text="Expandable Section" FontSize="16" FontAttributes="Bold"/>
            <persian:Expander IsExpanded="False" Header="Click to expand">
                <Label Text="This content is hidden until expanded" Padding="10"/>
            </persian:Expander>

        </StackLayout>
    </ScrollView>
</ContentPage>

3. Calendar System Usage

Using Calendar Services Directly

using MauiPersianToolkit.Services.Calendar;
using MauiPersianToolkit.Enums;

// Get calendar service
var persianService = CalendarServiceFactory.GetService(CalendarType.Persian);
var gregorianService = CalendarServiceFactory.GetService(CalendarType.Gregorian);
var hijriService = CalendarServiceFactory.GetService(CalendarType.Hijri);

// Convert dates
var today = DateTime.Now;
string persianDate = persianService.ToCalendarDate(today);      // "1403/05/25"
string gregorianDate = gregorianService.ToCalendarDate(today);  // "2024/08/16"
string hijriDate = hijriService.ToCalendarDate(today);          // "1446/02/21"

// Parse dates back
var parsed = persianService.ToGregorianDate("1403/05/25");

// Get calendar information
int year = persianService.GetYear(today);
int month = persianService.GetMonth(today);
string monthName = persianService.GetMonthName(month);
bool isLeap = persianService.IsLeapYear(year);
DayOfWeek holiday = persianService.GetLastDayOfWeek();  // Friday for Persian

Using Extension Methods (Backward Compatible)

using MauiPersianToolkit;

DateTime today = DateTime.Now;

// Convert to Persian (default)
string persianDate = today.ToPersianDate();  // "1403/05/25"

// Convert to other calendars
string gregorianDate = today.ToCalendarDate(CalendarType.Gregorian);
string hijriDate = today.ToCalendarDate(CalendarType.Hijri);

// Parse back
var parsed = "1403/05/25".ToDateTime();
var gregorianParsed = "2024/08/16".ToDateTime(CalendarType.Gregorian);

4. Dialog Usage

using MauiPersianToolkit.Services.Dialog;
using MauiPersianToolkit.Models;

public partial class MainPage : ContentPage
{
    private readonly IDialogService _dialogService;
    
    public MainPage(IDialogService dialogService)
    {
        InitializeComponent();
        _dialogService = dialogService;
    }

    // Alert Dialog
    private async void ShowAlert()
    {
        await _dialogService.Alert("This is an alert message");
    }

    // Confirm Dialog
    private async void ShowConfirm()
    {
        var config = new ConfirmConfig
        {
            Title = "Confirm Action",
            Message = "Are you sure?",
            AcceptText = "Yes",
            CancelText = "No",
            OnAction = (result) =>
            {
                if (result)
                    Debug.WriteLine("User confirmed");
                else
                    Debug.WriteLine("User cancelled");
            }
        };
        
        await _dialogService.Confirm(config);
    }

    // Prompt Dialog
    private async void ShowPrompt()
    {
        var config = new PromptConfig
        {
            Title = "Enter Name",
            Message = "Please enter your name:",
            Placeholder = "Name",
            AcceptText = "OK",
            CancelText = "Cancel",
            OnAction = (result) =>
            {
                if (result.IsOk)
                    Debug.WriteLine($"User entered: {result.Input}");
            }
        };
        
        await _dialogService.Prompt(config);
    }

    // Custom Dialog
    private async void ShowCustomDialog()
    {
        var customContent = new StackLayout
        {
            Children =
            {
                new EntryView { PlaceHolder = "Name" },
                new EntryView { PlaceHolder = "Email" },
                new persian:DatePicker { PlaceHolder = "Birth Date" }
            }
        };

        var config = new CustomDialogConfig
        {
            Title = "Register",
            Message = "Enter your information",
            Content = customContent,
            AcceptText = "Register",
            CancelText = "Cancel",
            OnAction = (result) =>
            {
                Debug.WriteLine($"Dialog result: {result}");
            }
        };
        
        await _dialogService.CustomDialog(config);
    }
}

📚 Examples and Documentation

Calendar Service Examples

See MauiPersianToolkit/Examples/CalendarServiceExamples.cs for:

Calendar Tests

The project includes comprehensive unit tests:

CalendarServiceTests - 7 tests covering:

CalendarWeekLayoutTests - 13+ tests covering:

Run tests:

dotnet test ./MauiPersianToolkit.Test/MauiPersianToolkit.Test.csproj

🔧 Customization

All controls are designed to be easily customizable:

Custom Calendar Type

Implement ICalendarService for custom calendar support:

public class MyCustomCalendarService : ICalendarService
{
    // Implement interface methods
    public string ToCalendarDate(DateTime gregorianDate) { /* ... */ }
    public DateTime ToGregorianDate(string calendarDate) { /* ... */ }
    // ... other methods
}

// Register with factory
CalendarServiceFactory.RegisterService(
    CalendarType.Custom, 
    new MyCustomCalendarService()
);

Style Customization

Customize colors, fonts, and behaviors:

<persian:DatePicker
    PlaceHolder="Select Date"
    SelectDayColor="Blue"
    CanSelectHolidays="False"
    DisplayFormat="yyyy/MM/dd" />

🧪 Testing

The project includes a comprehensive test suite:

MauiPersianToolkit.Test/
├── CalendarServiceTests.cs (7 tests)
├── CalendarWeekLayoutTests.cs (13+ tests)
└── CalendarWeekLayoutTests.README.md (documentation)

GitHub Actions CI/CD

Automated testing on every commit:

See .github/workflows/ for CI/CD configuration.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/YourFeature)
  3. Commit your changes (git commit -m 'Add YourFeature')
  4. Push to the branch (git push origin feature/YourFeature)
  5. Open a Pull Request

Contribution Guidelines

🙏 Acknowledgments

📞 Support

🔗 Quick Links

📊 Project Status

Component Status Coverage
Core Library ✅ Stable Mature
Calendar System ✅ Stable 3 calendars
UI Controls ✅ Stable 10+ controls
Dialog System ✅ Stable 4 types
Unit Tests ✅ Complete 20+ tests
Documentation ✅ Complete Full

Happy Coding! 🚀

Start building beautiful Persian-enabled applications with MauiPersianToolkit today!

This site is open source. Improve this page.