Documentation K-Sup

Modifier le fichier

Architecture générale du panel des préférences

Le panel des préférences est un composant de l'interface utilisateur permettant aux utilisateurs de personnaliser divers aspects de l'application. Ce panel est organisé sous forme d'onglets, chaque onglet représentant une catégorie différente de paramètres.

Le panel des préférences est ajouté dans la page par le préparer SettingsViewPreparer lié à la JSP settings/settings.jsp Le panel est un receptacle sans contenu qui sera peuplé à chaque ouverture du panel et vidé à chaque fermeture.

Affichage du panel des préférences

Le panel des préférences est de type popover. Il est déclenché par un bouton contenant un attribut popovertarget="settings-panel"

Pour sélectionner un onglet particulier à l'ouverture, il faut positionner un attribut data-url-params. Par exemple l'attribut data-url-params="tab=user-settings-profile" permet de pré-sélectionner l'onglet user-settings-profile à l'ouverture.

Le panel écoute les évènements toggle pour gérer le chargement de son contenu et son nettoyage.

A l'ouverture du panel un appel fetch est réalisé sur le controller UserSettingsController. Ce controller a pour fonction d'appeler le preparer UserSettingsViewPreparer. Ce préparer est configuré pour préparer un ensemble d'expectedViews

    <bean id="userSettingsViewPreparer" class="com.kosmos.user.settings.UserSettingsViewPreparer">
        <property name="type" value="#{T(com.kosmos.user.settings.UserSettingsViewPreparer).TYPE}"/>
        <property name="view" value="/WEB-INF/jsp/settings/settings-panel.jsp"/>
        <property name="expectedViewTypes">
            <list>
                <value>#{T(com.kosmos.user.settings.profile.ProfileSettingsTabViewPreparer).TYPE}</value>
                <value>onglet2TabSettings</value>
                <value>onglet3TabSettings</value>
            </list>
        </property>
    </bean>

Rendu du panel

Le fichier settings-panel.jsp est responsable du rendu de base du panel des préférences.

<kuik:tabs id="settings-tabs" size="md">
    <c:forEach var="settingsTab" items="${userSettingsViewModel.tabs}">
        <kore:include viewModel="${settingsTab}"/>
    </c:forEach>
</kuik:tabs>

Gestion des onglets côté client

Le fichier user-settings.js contient la fonction handleTabChange() qui attache des écouteurs d'événements aux boutons d'onglets pour gérer les changements d'onglets.

Par défaut, si un attribut data-url est disponible sur l'onglet cliqué, l'url est appeléer et le contenu (html) est inséré dans l'élément ciblé par l'attribut data-body de l'onglet cliqué.

Un groupe de ressource nommé settings dans le bundle.json permet d'ajouter des fichiers javascript nécessaires au fonctionnement des onglets. Par exemple,

    ...
    "settings": {
      "files": [
        "META-INF/resources/static/js/user-settings-profile.js"
      ],
      "type": "module"
    }
    ...

Ajout d'un nouvel onglet

Pour ajouter un nouvel onglet au panel des préférences, suivez ces étapes:

Étape 1: Créer un nouveau ViewModel pour l'onglet

Créez une classe qui étend UserSettingsTabViewModel:

package com.kosmos.user.settings.mononglet;

import com.kosmos.user.settings.UserSettingsTabViewModel;

public class MonNouvelOngletViewModel extends UserSettingsTabViewModel {
    // Ajoutez des propriétés spécifiques à votre onglet si nécessaire
}

Étape 2: Créer un nouveau Controller pour l'onglet

Créez un contrôleur qui gérera les requêtes spécifiques à votre onglet:

package com.kosmos.user.settings.mononglet;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.servlet.ModelAndView;

import com.kosmos.user.settings.AbstractSettingsController;

@Controller
public class MonNouvelOngletController extends AbstractSettingsController {

    public static final String URL_MON_ONGLET = "mon_nouvel_onglet.mapping";

    /**
     * Point d'entrée pour l'affichage de l'onglet.
     */
    @GetMapping(value = "${" + URL_MON_ONGLET + "}")
    public ModelAndView getMonNouvelOnglet() {
        // Logique spécifique
        
        final SettingsContext context = initContext();
        return prepareView(context, MonNouvelOngletViewPreparer.TYPE, request, response);
    }
}

Étape 3: Créer un ViewPreparer pour l'onglet

Créez un préparateur qui définira l'ordre, l'icône et d'autres propriétés de l'onglet:

package com.kosmos.user.settings.mononglet;

import java.util.List;
import java.util.Map;

import com.kosmos.context.front.FrontContext;
import com.kosmos.preparer.IViewPreparer;
import com.kosmos.user.settings.SettingsContext;
import com.kosmos.user.settings.UserSettingsTabViewModel;
import com.kosmos.user.settings.UserSettingsTabViewPreparer;

public class MonNouvelOngletTabViewPreparer<V extends UserSettingsTabViewModel> extends UserSettingsTabViewPreparer<V> {

    public static final String TYPE = "mon-nouvel-onglet-settings-tab";
    protected static final String TAB_IDENTIFIER = "user-settings-mon-onglet";

    @Override
    public V prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
        final V viewModel = super.prepare(context, preparers);
        viewModel.setUrl(MonNouvelOngletController.buildUrl());
        final SettingsContext settingsContext = SettingsContext.of(context);
        if (settingsContext.getSelectedTab() != null) {
            viewModel.setActive(TAB_IDENTIFIER.equals(settingsContext.getSelectedTab()));
        }
        return viewModel;
    }
}

Étape 4: Créer le JSP pour l'onglet

Créez un fichier JSP pour le contenu de votre onglet, par exemple mon-nouvel-onglet.jsp dans le répertoire settings:

<%@ page trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="kuik" uri="kuik" %>

<div class="mon-nouvel-onglet-container">
    <!-- Contenu de l'onglet -->
    <h2>Mon nouvel onglet</h2>
    <p>Contenu de mon nouvel onglet...</p>
</div>

Étape 5: Configurer l'onglet dans le fichier de configuration Spring

Ajoutez la configuration de votre onglet dans un fichier XML de configuration Spring:

<bean id="monNouvelOngletTabViewPreparer" class="com.kosmos.user.settings.mononglet.MonNouvelOngletTabViewPreparer">
    <property name="type" value="#{T(com.kosmos.user.settings.mononglet.MonNouvelOngletTabViewPreparer).TYPE}"/>
    <property name="view" value="/WEB-INF/jsp/settings/mononglet/tab.jsp"/>
    <property name="tabIcon" value="${user-setting.tab.mononglet.icon:icon://ui/user}"/>
    <property name="displayOrder" value="42"/>
</bean>

<bean id="monNouvelOngletViewPreparer" class="com.kosmos.user.settings.profile.MonNouvelOngletViewPreparer">
    <property name="type" value="#{T(com.kosmos.user.settings.profile.MonNouvelOngletViewPreparer).TYPE}"/>
    <property name="view" value="/WEB-INF/jsp/settings/mononglet/tab-body.jsp"/>
    <!-- Ajoutez d'autres propriétés si nécessaire -->
</bean>

<bean class="com.kportal.core.context.ListToAddBean">
    <property name="idBeanToMerge" value="userSettingsViewPreparer"/>
    <property name="listToMerge" value="expectedViewTypes"/>
    <property name="add">
        <list>
            <value>#{T(com.kosmos.user.settings.mononglet.MonNouvelOngletTabViewPreparer).TYPE}</value> <!-- Ajoutez votre nouvelle entrée ici -->
        </list>
    </property>
</bean>

Paramètres importants

• displayOrder : L'ordre d'affichage dans les onglets (les valeurs plus petites s'affichent en premier)

Étape 6: Déclarer l'URL du contrôleur

Ajoutez la propriété d'URL dans votre fichier de propriétés de l'application:

mon_nouvel_onglet.mapping=/settings/mon-nouvel-onglet