Pour Commencer

Prérequis

NPM : Pour être capable de compiler localement la solution Simpleter.Components il est nécessaire de disposer de NPM sur votre machine.

En effet, certaines dépendances de la solution et de la bibliothèque de composants sont issues de packages fournis par le gestionnaire de package NPM :

• Bootstrap (bootstrap)
• Material Icons (@material-icons)
• PopperJS (@popperjs)
• ...

Pour installer NPM, il convient d'installer NodeJS sur votr machine depuis le site officiel. Si vous n'installez pas NPM vous ne serez pas en mesure de compiler le projet (vous obtiendrez des erreurs concernant la commande NPM i ou NPM install).

Commandes utiles

Pour générer un package nuget en local

Positionnez-vous dans le répertoire racine de la solution et exécutez le code suivant :

.\build.ps1 -VersionPrefix 2.0.0.0 -VersionSuffix beta1

• Où *1.0.1.119 est la dernière version publiée +1 par azure devops libre à vous d'incrémenter ensuite beta1 pour utiliser le package en local
• Le package sera ensuite disponible dans le répertoire ./local-nuget à la racine du repo, à vous de le copier dans votre repository locale de nugets

Vous pouvez aussi changer le répertoire de destination en ajoutant le paramètre destination :

.\build.ps1 -VersionPrefix 3.0.1.0 -VersionSuffix beta1 -Destination "./localnugets"

Guide d'Installation

Installer le Package

 dotnet add package Simpleter.Components

Ajouter dans _Imports.razor

 @using Simpleter.Components

Ajouter dans index.html (côté client) ou _Host.cshtml (côté server) dans le head

 <link href="_content/Simpleter.Components/dist/Simpleter.Components.css" rel="stylesheet" />

Ajouter dans index.html ou _Host.cshtml dans le Body

<script src="_content/Simpleter.Components/dist/Simpleter.Components.js"></script>

Ajouter dans la rubrique concernée de Program.cs

 using Simpleter.Components.Services;

 builder.Services.AddSimpleterComponents();

Nettoyage de votre projet avant utilisation

Références à Bootstrap

Dans votre projet, si vous avez déjà une dépendance à Bootstrap, supprimez la :

• Par exemple, supprimez dans index.html :

 <link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />

• (Et éventuellement) supprimez les fichiers statiques de Bootstrap, comme le dossier Boostrap dans wwwroot/css

Références à Open-Iconic

Les composants de Simpleter.Components utilisent la bibliothèque d'icônes Material Icons basée sur les icônes de Google Fonts. Aussi, sauf si vous en avez un besoin explicite, supprimez le dossier open-iconic dans wwwroot/css et toute dépendance dans votre fichier index.html ou _Host.cshtml dans le head et préférez l'utilisation des icônes de la bibliothèque Material Icons.

Par exemple, supprimez la ligne suivante dans le fichier app.css :

@import url('open-iconic/font/css/open-iconic-bootstrap.min.css');

Surcharges de styles Bootstrap par défault

Par défaut, dans le fichier de styles d'une application Blazor (fichier app.css), vous trouverez des surcharges des styles Bootstrap par défaut. Il convient d'enlever tous les styles personnalisés.

Supprimer le contenu du fichier app.css en faisant bien attention à conserver les styles liés à Blazor.

Sauf personnalisations réalisées par vos soins, le fichier ne doit contenir que ces classes :

#blazor-error-ui {}
#blazor-error-ui .dismiss {}

.blazor-error-boundary {}
.blazor-error-boundary::after {}

Première utilisation

Comment intégrer le Layout de base ?

Main Layout

Dans MainLayout.razor

• Tout supprimer sauf :

@inherits LayoutComponentBase

• et copier-coller ce contenu :

<SimpleApplicationContainer>

    <NavigationContent>
        <NavMenu />
    </NavigationContent>

    <BodyContent>
        @Body
    </BodyContent>
</SimpleApplicationContainer>

Navigation Menu

Le NavMenu.razor de base n'est pas exploitable tel quel (styles personnalisés) :

• Tout supprimer
• Remplacer par :

<nav class="flex-column">
    <SimpleNavigationSection Label="Navigation">
        <SimpleNavigationLink Href="/" Label="Index" IconName="home" />
    </SimpleNavigationSection>
</nav>

Guide de mise en place de nouvelles pages et de la navigation

Historique

Pour assurer la navigation dans l'application, il existe un menu qui, initialement était construit manuellement dans la page Shared/NavMenu.razor en utilisant :

• SimpleNavigationSection
• SimpleNavigationLink
• SimpleNavigationLinkGroup

Le titre des pages était lui directement intégré, dans chaque page via le composant SimplePageTitle

L'application ne disposait pas de fil d'ariane pour permettre l'application

Nouvelle mise en place

La gestion du menu, des titres de page et de la navigation par fil d'ariane a été repensée et une série de composants font leur apparition, nécessitant une nouvelle approche pour l'intégration des pages dans la navigation.

La page Shared/NavMenu.razor contient désormais une référence au composant SimpleDynamicNaMenu qui va être alimenté automatiquement.

Pour alimenter la navigation, il convient, dans l'application cliente, de réaliser les opérations suivantes :

1. Gestion de la hiérarchie

Créer une nouvelle classe qui implémente l'interface ISimpleterHierarchyProvider (Exemple : AppHierarchy.cs)

• Propriété ApplicationPrefix : Préfixe qui sera ajouté dans le titre de la page du navigateur
• Propriété PageWithoutTitleDefault : Titre de la page qui sera affiché dans la barre de menu, si vous n'avez pas défini de titre dans la hiérarchie
• Méthode Init : Fonction d'initialisation qui propose 3 propriétés à alimenter :
  • routes : Liste des routes pour regrouper les pages
  • pages : Liste des pages qui se trouvent à la racine
  • filters : Liste des paramètres de filtres dans les pages

Vous devez remplir, dans la méthode Init la hiérarchie des pages et renseignez les attributs correspondants :

• Au titre de la page ;
• A l'icône à afficher dans le menu ;
• A l'identifiant du lien dans le menu ;
• etc.

Exemple :

On a la hiérarchie suivante :

• Pages.Accueil : /home
• Pages.Client : /travail/client
• Pages.Contact : /travail/client/contacts
• Pages.ParametresClient : /parametres/client

Alors le code à produire sera le suivant :

public void Init(List<RouteReferenceItem> routes, List<PageReferenceItem> pages, List<FilterParameter> filters)
{
    var routeTravail = routes.AddRoute("travail");
    var routeParams = route.AddRoute("Paramètres");

    pages.AddPage(typeof(Pages.Accueil),"Accueil");

    routeParams.AddPage(typeof(Pages.ParametresClient),"Paramètres Client");
    
    var pageClient = routeTravail.AddPage(typeof(Pages.Client),"Clients");
    pageClient.AddSubPage(typeof(Pages.Contact),"Contacts");
}

Un certain nombre de paramètres sont optionnels (Icône dans le menu, Identifiant du menu, etc.). Cependant, il est conseillé de les valoriser.

Dans le menu, appaitront la hiérarchie {route}/{route}/{page} et uniquement pour les pages diposant d'une route sans paramètres.

N'apparaitront pas dans le menu :
- Les pages avec paramètre
- Les "sous-pages" (utilisées pour la navigation et le fil d'ariane).

Le titre ne doit correspondre qu'au titre de la page directement. 
Exemple, si j'ai une page "Liste des Clients" et une sous-page "Modifier un client", les titres de pages devront être : 
- Liste des clients : "Clients" (ou "Liste des Clients")
- Modifier un client : "Modifier" (pas la peine de répêter les mots clés du niveau précédent)

##### 2. Injection de la hiérarchie

Dans `Program.cs` ajouter la ligne suivante :

``` c#
builder.Services.AddScoped<ISimpleterHierarchyProvider, NomDeVotreClasse>(); // Classe : AppHierarchy

##### 3. Titre des pages et fil d'ariane

Note : 
Vous pouvez toujours utiliser le composant `SimplePageTitle` dans les pages Blazor. 
Cependant, le titre de la page ne correspondra pas à la logique métier et le fil d'ariane ne sera pas géré.

###### 3.1. Cas général

Il est nécessaire d'utiliser désormais le composant `SimpleBreadcrumbTitle` qui s'utilise comme suit :
``` blazor
<SimpleBreadcrumbTitle BasePage=@this />

###### 3.2. Sous-page avec route paramétrée 

Si la page dans laquelle vous intégrez le titre est une "sous-page" dont l'un des parents est associé à des paramètres, vous devrez les préciser.

*Exemple* : 
Je veux que le fil d'ariane s'affiche correctement sur la page "Liste des contacts d'un client" dont la route est `/clients/{IdClient}/contacts`
Il convient donc de passer au composant les paramètres de la route (ici IdClient) ET le libellé qu'on souhaitera afficher dans le fil d'ariane (Exemple : le nom du client).

Pour ce faire, il convient d'utiliser un autre attribut : `Parameters` qui s'utilise comme suit : 
Parameters = Tableau de BreadcrumbParameter(Nom du paramètre, Valeur du paramètre, Texte à afficher)

*Code à intégrer * :
``` blazor
<SimpleBreadcrumbTitle BasePage=@this 
    Parameters=@(new(new[]{new BreadcrumbParameter("IdClient",maVariableIdClient,maVariableNomDuClient})) />

###### 3.3. Personnalisation de la page de retour

Par défaut, le composant SimpleBreadcrumbTitle va automatiquement récupérer l'URL de retour dans la hiérarchie.
Cependant, si vous souhaitez absolument définir une page de retour différente, vous pouvez utiliser le paramètre suivant : `ReturnPageType`
``` c#
<SimpleBreadcrumbTitle BasePage=@this ReturnPageType=@(typeof(Pages.MaPage) />

### Vous êtes prêts !

Consulter le projet de démo `Simpleter.Components.Demo` pour voir l'utilisation des composants en situation réelle.