Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thomasgalliker/crossplatformlibrary

An extensible cross-platform toolkit which provides a basic set of functionality used in most mobile apps.
https://github.com/thomasgalliker/crossplatformlibrary

boilerplate bootstrapping cross-platform library user-controls xamarin

Last synced: 14 days ago
JSON representation

An extensible cross-platform toolkit which provides a basic set of functionality used in most mobile apps.

Host: GitHub
URL: https://github.com/thomasgalliker/crossplatformlibrary
Owner: thomasgalliker
Created: 2015-09-17T15:42:17.000Z (over 9 years ago)
Default Branch: develop
Last Pushed: 2024-03-16T10:23:44.000Z (11 months ago)
Last Synced: 2025-01-08T12:49:16.304Z (24 days ago)
Topics: boilerplate, bootstrapping, cross-platform, library, user-controls, xamarin
Language: C#
Homepage:
Size: 16.6 MB
Stars: 9
Watchers: 3
Forks: 1
Open Issues: 2
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml

Awesome Lists containing this project

README

# CrossPlatformLibrary
[![Version](https://img.shields.io/nuget/v/CrossPlatformLibrary.svg)](https://www.nuget.org/packages/CrossPlatformLibrary) [![Downloads](https://img.shields.io/nuget/dt/CrossPlatformLibrary.svg)](https://www.nuget.org/packages/CrossPlatformLibrary)

CrossPlatformLibrary is an extensible toolkit which addresses cross-cutting concern. It is a lightweight library which provides a collection of functionality used in most mobile and desktop applications such as bootstrapping, exception handling, tracing and UI dispatching.

### Supported Platforms

.Net 4.5 / WPF
.Net Standard 2.0
Xamarin.Android
Xamarin.iOS
UWP

CrossPlatformLibrary
yes
yes
yes
yes
yes

CrossPlatformLibrary.Forms
no
yes
yes
yes
not yet

### Download and Install CrossPlatformLibrary

This library is available on [NuGet](https://www.nuget.org/packages/CrossPlatformLibrary). Use the following command to install CrossPlatformLibrary using NuGet package manager console:

```PM> Install-Package CrossPlatformLibrary```

The Xamarin.Forms specific library can be installed using following command:

```PM> Install-Package CrossPlatformLibrary.Forms```

### Usage

#### User Controls
The library contains a rich set of customized user controls which extend basic implementations of existing controls. Following screenshots of the SampleApp demonstrate the usege of some of the delivered controls. The coloring is pretty random and mainly used for debugging/development purposes. Since every control uses dynamic styles, you're free to override the default styles.

SampleApp Android
SampleApp iOS

##### Getting Started
In order to use the user controls of CrossPlatformLibrary, the styles used in these controls need to be initialized properly. For this reason, add following line of code just after the line `this.InitializeComponent();` in `App.xaml.cs`:

`
CrossPlatformLibrary.Forms.CrossPlatformLibrary.Init(this, "SampleApp.Theme");
`

```TODO: to be documented```

##### Known Problems
- `System.Collections.Generic.KeyNotFoundException: The resource 'Theme.Color.TextColor' is not present in the dictionary.` This error eventually appears if user controls of CrossPlatformLibrary are used without calling the `CrossPlatformLibrary.Forms.Init(..)` method.

#### Input Validation
The base viewmodel ```BaseViewModel``` implements a pretty sophisiticated and praxisproven user input validation system which allows to run client- and server-based property validation side-by-side.
There are a few steps to follow to get input validation to work:

- Inherit your viewmodels from ```BaseViewModel``` or implement a similar logic which exposes a ```BaseViewModel.Validation``` property.
- Override the protected method ```SetupValidation```. This enables your viewmodel to use input validation. The most simple setup just returns an empty ```ViewModelValidation```.
- Setup validation rules inside ```SetupValidation```. There are basically two different approaches: Either you validate viewmodel properties locally (validation logic provided by the viewmodel) or you call a backend service which validates a given object (DTO) against some central validation logic.
- Configure the according view to react on validation errors. This is done in XAML by binding a dependency property to the string list of validation errors for a certain property. The following example binds to validation errors for property 'UserName': ```ValidationErrors="{Binding Validation.Errors[UserName]}"```
- In order to run the validation, just call ```Validation.IsValidAsync()```. Depending on the result (true/false) we proceed with further actions (e.g. saving the object).
```
var isValid = await this.Validation.IsValidAsync();
if (isValid)
{
// TODO Save...
}
```

Following snippet is an extract of a unit test. It demonstrates some setup variations.
```
protected override ViewModelValidation SetupValidation()
{
var viewModelValidation = new ViewModelValidation();

// Validation function with parameter-less custom error message
viewModelValidation.AddValidationFor(nameof(this.UserName))
.When(() => string.IsNullOrEmpty(this.UserName))
.Show(() => "Username must not be empty");

// Validation rule with parameter and custom error message
viewModelValidation.AddValidationFor(nameof(this.Email))
.When(new IsNotNullOrEmptyRule())
.Show(p => $"Email address '{p}' must not be empty.");

// Validation delegated to async service
viewModelValidation.AddDelegateValidation(nameof(this.UserName), nameof(this.Email))
.Validate(async () => (await this.validationService.ValidatePersonAsync(this.CreatePerson())).Errors);

return viewModelValidation;
}
```

#### Bootstrapping

The bootstrapping mechanism is used to startup and shutdown an application in a controlled way. The boostrapper is called at the entry point of an application and it cares about the basic initialisation tasks. The entry point of the application can differ from application type to application type.

CrossPlatformLibrary provides you with a base implementation of a bootstrapper. You may want to inherit the Bootstrapper class in order to influence the startup procedure and/or bootstrap parts of your own application. Following things can be done with a custom Bootstrapper:

* Register project-dependant dependencies in the IoC container

* Define your own IExceptionHandler to be used for unhandled exceptions

* Handle exceptions that happen during Bootstrapping (BootstrappingException)

```TODO: to be documented```

#### Exception Handling

Unhandled exceptions may occur in every application. Better we are prepared for such exceptions. IExceptionHandler instance is used to handle any System.Exception that is not handled by the application.

#### Tracing

The tracing functionality provided by CrossPlatformLibrary can be used to write application debug traces. The purpose of trace messages is to assist developers and 3rd level support locating and fixing bugs or other program flow related problems.

Tracer Name
Description

EmptyTracer
EmptyTracer doesn’t trace anything. Each call to the Write method will not execute anything.

DebugTracer
DebugTracer uses System.Diagnostics.Debug.WriteLine to write traces.

ActionTracer
ActionTracer allows you to define an Action/Delegate to which traces are written to.

Your own ITracer implementation
Write your own tracer by implementing ITracer or abstract TracerBase.

You can implement your own tracer by either implementing the ITracer and ITracerFactory interface on you own or extend the provided base implementation of the TracerBase and TracerFactoryBase.

Trace Category
Description

Debug
Information traced for debugging purposes. Usually only active in test or pre-production releases.

Information
Important trace information which is usually also traced by production software.

Warning
Some warnings which are not critical but need care.

Error
Typically handled exceptions which have to be traced in order to be analyzed and avoided.

Fatal
Software crashes, unhandled exceptions.

#### Modularity

CrossPlatformLibrary was designed in a way which promotes modular design. Modules are loosely coupled and self-contained units which serve a concrete purpose. This approach supports the separation of concerns in your application. You can easily test modules in isolation and integrate them later into your application(s) without having them too tighly coupled.

```TODO: to be documented```

#### UI Dispatching

```TODO: to be documented```

#### Dependency Management

Dependency injection containers are used to manage dependencies between components. This typically involes registration and instanciation and resolution of dependencies. CrossPlatformLibrary uses its own implementation of a dependency injection container, CrossPlatformLibrary.Ioc.SimpleIoc.

```TODO: to be documented```

### Contribution

Want to contribute to this project? Feel free to start a discussion in the issues area to see if your idea could fit in.

### License