Introduction

CUBA Platform est un framework open source destiné à rationaliser le processus de développement d'applications métier. Il combine une architecture éprouvée, des composants de qualité professionnelle prêts à l'emploi et des outils productifs, afin que vous puissiez fournir des applications Web modernes plus rapidement que jamais.

Dans ce tutoriel de démarrage rapide, nous allons gratter la surface de CUBA et développer une application de planification de conférence très simple mais entièrement fonctionnelle. Il montrera trois choses principales pour créer une application Web: comment concevoir un modèle de données, comment manipuler les données, comment créer la logique métier et, enfin, comment créer une interface utilisateur. À titre d'exemple, nous allons créer une version simple mais fonctionnelle d'une application qui vous aidera à planifier une session pour une conférence. En fait, ce tutoriel sera suffisant pour que vous démarriez votre propre application CUBA, alors commençons. Dans ce tutoriel, nous utiliserons CUBA Studio, veuillez donc l'installer avant de commencer et accepter un abonnement d'essai pour avoir accès aux concepteurs visuels.

Code source: https://github.com/cuba-platform/sample-session-planner.

Créer un projet vide

Créons un projet CUBA vide à l’aide du menu IntelliJ IDEA correspondant. Nommez-le SessionPlanner avec l'espace de noms du projet - planificateur. Nous utiliserons Java 11 comme JDK par défaut.

1

Nous utiliserons une base de données en mémoire - HSQLDB.

2

Après le premier lancement, CUBA Studio vous propose d'appliquer un abonnement d'essai à CUBA Studio Premium.

3

Appliquons un abonnement d'essai. Il est gratuit pendant 28 jours et nous donne quelques concepteurs optionnels utiles.

Création de modèles de données

La première tâche consiste à créer des entités. Le modèle de domaine métier ne comprend que deux classes: Speaker et Session. La relation est de type un-à-plusieurs. Un orateur peut diriger plusieurs sessions.

4

Pour commencer, l’entité Speaker. Pour ce faire, nous pouvons utiliser un lien sur la page d'accueil du projet:

5

Ou faites simplement un clic droit sur le nœud Data Model dans l'arborescence du projet CUBA sur le côté gauche de l'écran et sélectionnez New -> Entity.

6

Entrez le nom de l’entité – Speaker et ajoutez les attributs selon la spécification:

NomTypeObligatoireAutres contraintes
firstNameString (255)Oui
lastNameString (255)
emailString (1024)Oui“Email” validator

Dans CUBA, nous utilisons des entités JPA standard, vous pouvez donc les créer à l'aide d'un éditeur de code ou d'un concepteur visuel. Cliquez simplement sur l'icône «+» et ajoutez des attributs à l'entité, CUBA Studio générera des membres de classe pour vous.

7

Dans CUBA, vous pouvez définir un format approprié pour l’affichage d'une entité sous forme de chaîne de caractères dans l'interface utilisateur appelée Instance Name. Pour l'orateur, nous sélectionnons le prénom et le nom de famille.

8

Si nous jetons un œil à l'onglet Text en bas du concepteur d'entités, nous pouvons voir une classe java annotée par JPA. Le code généré peut être mis à jour si nécessaire, le concepteur sera mis à jour en conséquence lorsque vous basculerez vers l'onglet Designer.

En outre, vous pouvez voir l’aperçu DDL et créer des indexes si nécessaire. Par exemple, nous nous attendons à beaucoup de recherches par nom de famille. Pour rendre cette recherche plus efficace, nous pouvons créer un index pour le champ du nom.

9

Allons plus loin et associons l’entité Session à notre classe Speaker. Le tableau de spécification des attributs est ci-dessous. L'heure de fin de session sera une valeur calculée, correspondant à la date de début plus la durée.


NomTypeObligatoire
topicString (255)Oui
startDateLocalDateTimeOui
endDateLocalDateTime
speakerAssociation avec l’entité “Speaker”, cardinalité « many-to-one »Oui
durationIntegerOui
descriptionString (2000)

Regardez l'ajout d'une référence obligatoire à l'orateur. La relation est « many-to-one », nous allons donc définir un champ d'association appelé « speaker » qui fait référence à la classe Speaker. Enfin, la définition du champ devrait ressembler à ceci:

10

Création d’un attribut calculé

À présent, nous devons créer un attribut calculé automatiquement pour la date et l'heure de fin de la session. Ajoutez d'abord la méthode getter et nommez-la getEndDate. Marquez la méthode avec l'annotation @MetaProperty. Pour l'attribut calculé, nous devons spécifier les champs à charger. Dans notre cas, ce sont startDate et duration. Ensuite, ajoutez simplement une logique de calcul.

@Transient
@MetaProperty(related = {"startDate", "duration"})
public LocalDateTime getEndDate() {
   return (startDate != null && duration != null) ? startDate.plusHours(duration) : null;
}

Notez que Studio met en évidence la méthode car nous devons spécifier une étiquette de texte pour l'attribut. Appuyez sur Alt + Entrée et ajoutez un label texte à l'ensemble des messages.

11+

C'est tout. Notre modèle de domaine a été créé.

Screens Génération d'écrans CRUD

CUBA Studio contient un assistant de génération d'écran d'interface utilisateur qui nous aide à créer des écrans d'interface utilisateur basiques mais fonctionnels:

  • Browser (Navigateur) - pour afficher la liste des entités dans une grille
  • Editor (Éditeur) - pour modifier une instance d'entité à l'aide d'une interface utilisateur de type formulaire

Tout d'abord, nous allons créer des écrans pour travailler avec des Speaker. Puisque cette entité est assez simple, nous utiliserons les paramètres par défaut pour la création de l'écran. Démarrez un assistant en cliquant sur l'élément de menu Create Screen dans le menu Screen en haut du concepteur d'entités.

11

Vous pouvez également lancer l'assistant de génération d'écran en cliquant avec le bouton droit sur une entité dans l'arborescence du projet CUBA et en sélectionnant New -> Screen dans le menu contextuel.

12

Pour l'entité Speaker, nous créerons un navigateur et un éditeur par défaut. Sélectionnez Entity browser and editor screens dans l'onglet Screen Templates de l'assistant et cliquez sur Suivant. Puisque cette entité est assez simple, nous pouvons accepter les paramètres par défaut pour la création de l'écran.

13

Comme vous pouvez le voir, chaque écran se compose de deux parties: un contrôleur, écrit en java, qui est responsable de la logique interne de l'écran et de la gestion des événements et une mise en page XML qui définit l'apparence de l'écran. Dans notre cas, le navigateur comprendra les fichiers speaker-Browse.xml et SpeakerBrowse.java et pour l’éditeur - speaker-edit.xml et SpeakerEdit.java. Les fichiers sources se trouvent sous Generic UI -> Screens dans l'arborescence du projet CUBA.

14

Veuillez noter la section des données dans les descripteurs d'écran XML - elle définit la manière dont les données sont extraites de la base de données.

<data readOnly="true">
   <collection id="speakersDc"
               class="com.company.planner.entity.Speaker"
               view="_local">
       <loader id="speakersDl">
           <query>
               <![CDATA[select e from planner_Speaker e]]>
           </query>
       </loader>
   </collection>
</data>

Vous pouvez facilement naviguer entre le contrôleur d'écran, le descripteur et les entités liées avec CUBA Studio à l'aide des boutons situés en haut de la fenêtre:

15

16

17

Créer un navigateur et un éditeur pour les sessions

Exécutez l'assistant de génération d'écran, sélectionnez Entity browser and editor screens et arrêtez-vous à l'étape d'affichage du Entity Browser.

Dans la plate-forme CUBA, Entity View spécifie les champs qui seront extraits de la base de données. Vous pouvez définir des vues dans un fichier séparé pour les utiliser dans les différents modules de votre application, ou créer des vues en ligne lors de la création des écrans.

Créons une vue en ligne. Sélectionnez simplement les données nécessaires: date de fin et référence de l'orateur.

18

À l'étape suivante, les champs nécessaires sont déjà sélectionnés.

19

Vous pouvez voir que les champs correspondants sont ajoutés aux écrans.

20

En outre, définissez la durée par défaut de la nouvelle session sur une heure. Pour ce faire, accédez à la fenêtre Component inspector et abonnez-vous à l'événement InitEntity dans l'onglet Gestionnaires.

21

Définissez ensuite cette valeur dans le code.

@Subscribe
public void onInitEntity(InitEntityEvent<Session> event) {
   event.getEntity().setDuration(1);
}

Création de la base de données

Sélectionnez le menu CUBA -> Generate database scripts pour créer du SQL pour la création de la base de données. Vous pouvez consulter les scripts générés dans la fenêtre contextuelle avant de les enregistrer en tant que fichiers de projet. Veuillez noter que ces scripts font partie du projet, vous pouvez les trouver sous le nœud Main Data Store dans l'arborescence du projet.

22

Vous pouvez modifier les scripts si vous souhaitez ajouter des éléments spécifiques comme des index supplémentaires ou insérer des instructions pour les données initiales.

23

Cliquez sur le bouton Create database pour appliquer ces scripts et créer la base de données. Outre les tables d'application, CUBA crée des tables système dans lesquelles nous stockons des informations sur les utilisateurs, les rôles, les tâches, etc.

C'est tout. La base de données a été créée.

Exécution de l'application en mode développement

Pour exécuter l'application CUBA, vous pouvez utiliser l'une ou l'autre configuration d'exécution en haut de la fenêtre IDE.

24

Ou sélectionnez CUBA -> Start application server dans le menu principal.

25

Après un certain temps, vous pouvez accéder à l'application à l'aide du navigateur. L'URL sera affichée dans la boîte à outils Exécuter dans IDEA. Dans notre cas, ce sera http://localhost: 8080/app. Ouvrez l'URL dans votre navigateur Web et connectez-vous à l'application en utilisant «admin» comme nom d'utilisateur. Le mot de passe est «admin» par défaut. Vous pouvez trouver des écrans de manipulation d'entités dans le menu Application. Ajoutons ensuite quelques données à la base de données: deux orateurs et deux sessions pour eux prévues pour le reste de la semaine.

Vous pouvez essayer de saisir un e-mail non valide pour un orateur et voir que le validateur d'e-mail fonctionne comme prévu.

26

27

Les écrans générés conviennent aux opérations de base, mais dans le monde réel, l'interface utilisateur est généralement plus complexe.

Personnalisation de l'interface utilisateur

Ajoutons une vue de calendrier pour parcourir les sessions en plus de la vue en grille. Pour l'écran du navigateur, nous ajouterons un contrôle d'onglet, y placerons un calendrier et fournirons une fonctionnalité permettant de modifier et de replanifier les sessions à l'aide de ce calendrier, comme dans l'image ci-dessous:

28

Ouvrez le fichier session-Browse.xml dans le concepteur et encapsulez la table des sessions dans une feuille d'onglets dans la fenêtre Hiérarchie des composants.

29

Ajoutez une autre page à onglet sous TabSheet.

30

Mettez un contrôle de calendrier dessus.

31

Sélectionnez l'élément TabSheet dans la fenêtre Component hierarchy et sélectionnez développé dans le Component inspector. Studio demande un identifiant. Dans CUBA, nous avons besoin d'identifiants pour référencer un élément d'écran dans le code.

32

Attribuez les identifiants calendarTab et tableTab pour les onglets. Définissez ensuite respectivement les légendes du calendrier des sessions et du tableau des sessions pour ces onglets.

33

Mettez à jour le calendrier - attribuez un conteneur de données et développez-le.

34

Enfin, développez le tableau des sessions.

35

Dans CUBA, les composants de l'interface utilisateur peuvent être liés à des entités et à leurs propriétés.

Lions l'agenda à la collection de données récupérée à l'écran. Utilisez le champ de recherche pour trouver des propriétés et lier:

  • startDateProperty à la date de début d'une session
  • endDateProperty à la date de fin d'une session
  • captionProperty du sujet d'une session
  • Et descriptionProperty de la description d'une session

36

Faisons en sorte que l'agenda affiche uniquement les heures de travail.

37

En plus du concepteur visuel, vous pouvez utiliser l'éditeur XML. Ajoutons des boutons de navigation.

37_1

Pour voir les modifications dans l'interface utilisateur, vous n'avez pas besoin de redémarrer l'application, il vous suffit de rouvrir l'écran dans l'application. Le framework CUBA prend en charge le déploiement à chaud pour les écrans. Vous pouvez maintenant voir les sessions affichées sur le calendrier.

Utilisation de l'API Screen (écrans)

Lorsque nous interagissons avec l'interface utilisateur, des événements sont générés. CUBA vous propose une API que vous pouvez utiliser pour vous abonner à ces événements afin de les gérer. Traitons un clic sur l'entrée d'un calendrier et appelons l'éditeur de session. Pour les manipulations d'écran, CUBA fournit une API de création d'écran que nous utiliserons.

Dans le fichier session-Browse.xml, sélectionnez sessionsCalendar et accédez à l'onglet Handlers de la fenêtre Component Inspector. Sélectionnez CalendarEventClickEvent et cliquez sur la flèche pour accéder au contrôleur.

38

La méthode vide sera générée pour vous.

@Subscribe("sessionsCalendar")
public void onSessionsCalendarCalendarEventClick(Calendar.CalendarEventClickEvent<LocalDateTime> event) {
  
}

Nous devons ouvrir l’écran de l’éditeur pour modifier les propriétés de la session. Utilisons EditorScreenFacet. C'est un composant qui permet de préconfigurer un écran d'éditeur.

Accédez au fichier session-Browse.xml et recherchez l'éditeur dans la palette de composants et déplacez-le sous l'élément de fenêtre dans la fenêtre Hiérarchie des composants.

39

Définissez les paramètres suivants:

  • ID - sessionEditDialog;
  • conteneur de données - sessionsDc;
  • mode d'édition - EDIT;
  • classe d'entité - Session;
  • mode ouverture - DIALOG;
  • classe d'écran - SessionEdit.

40

Revenez au gestionnaire d'événements. Cliquez sur le bouton Injecter en haut de la fenêtre et sélectionnez la section API de l'écran du formulaire de service sessionEditDialog dans la fenêtre contextuelle.

Une autre façon pour l'injection (et l'abonnement) - appuyez sur Alt + Insérer la combinaison de touches dans l'éditeur et sélectionnez Injecter dans le menu contextuel:

40_1

Pour rechercher le service, commencez simplement à taper son nom, puis utilisez les touches Haut et Bas pour naviguer entre les services disponibles pour l'injection.

40_2

Transmettez l'entité de session reçue dans l'objet événement pour modification. Après cela, nous devrions montrer l'éditeur.

Dans le code du gestionnaire, cela ressemblera à ceci:

@Subscribe("sessionsCalendar")
public void onSessionsCalendarCalendarEventClick(Calendar.CalendarEventClickEvent<LocalDateTime> event) {
   sessionEditDialog.setEntityProvider(() -> (Session) event.getEntity());
   sessionEditDialog.show();
}

C'est tout. Vous pouvez rouvrir l'écran du navigateur de sessions dans l'application en cours d'exécution et appeler l'éditeur en cliquant sur la session dans le calendrier.

41

Le dialogue de l’éditeur n’est pas correctement dimensionné, nous devons donc ajuster sa largeur et sa hauteur. Dans l'EDI, ouvrez le descripteur XML de l'écran, sélectionnez la propriété dialogMode et définissez les propriétés de largeur et de hauteur sur auto.

42

Allez dans l'application et rouvrez l'éditeur en le fermant et en cliquant à nouveau sur la session dans le calendrier. La fenêtre est maintenant correctement dimensionnée.

43

Ajouter la logique métier

Nous allons maintenant utiliser CUBA Studio pour créer un service qui implémente la logique métier et utiliser ce service dans un écran. Ce sera un service de reprogrammation de session qui garantira qu’un orateur n’aura pas plus de deux sessions en une journée.

Cliquez avec le bouton droit sur le nœud de service dans l'arborescence du projet CUBA et sélectionnez New -> Service. Cela ouvrira une boîte de dialogue de création de service. Entrez SessionService comme nom d'interface, SessionServiceBean comme nom d'implémentation sera généré automatiquement.

44

Créez une méthode rescheduleSession dans l'interface comme dans l'extrait de code ci-dessous:

public interface SessionService {
   String NAME = "planner_SessionService";

   Session rescheduleSession(Session session, LocalDateTime newStartDate);
}

La méthode acceptera une session et une nouvelle date et heure de session. Le service renverra l'instance de session mise à jour.

Pour implémenter la méthode, ouvrez l'éditeur de code pour la classe SessionServiceBean, vous pouvez le trouver sous Middleware - Services dans l'arborescence du projet CUBA:

45

Vous verrez que la classe est vide et invalide:

461

Appuyez sur Alt + Insérer dans le corps de la classe et sélectionnez Implémenter les méthodes dans le menu contextuel:

46

Sélectionnez la méthode rescheduleSession, le stub de code sera généré:

@Service(SessionService.NAME)
public class SessionServiceBean implements SessionService {

   @Override
public Session rescheduleSession(Session session, LocalDateTime newStartDate) {
       return null;
   }
}

Tout d'abord, calculez l'heure de début et de fin de la journée où la session est prévue.

@Override
public Session rescheduleSession(Session session, LocalDateTime newStartDate) {
   LocalDateTime dayStart = newStartDate.truncatedTo(ChronoUnit.DAYS).withHour(8);
   LocalDateTime dayEnd = newStartDate.truncatedTo(ChronoUnit.DAYS).withHour(19);
return null;   
}

Pour le service, nous utiliserons l'API CUBA pour l'accès aux données – la classe DataManager. Avec cette classe, nous créons une requête JPQL pour vérifier s'il y a des sessions programmées pour le locuteur dans un laps de temps défini et y ajouter des valeurs de paramètres. Ensuite, nous vérifions le résultat de la requête et, en fonction du résultat, nous mettons à jour la session avec une nouvelle date de début ou nous renvoyons simplement l'instance de session d'origine.

Injectez le DataManager dans le service en appuyant sur Alt + Insérer dans le corps de la classe et sélectionnez Injecter dans le menu contextuel:

481

Sélectionnez DataManager dans la fenêtre contextuelle:

48

L'implémentation de la méthode se trouve sur l'extrait ci-dessous:

@Override
public Session rescheduleSession(Session session, LocalDateTime newStartDate) {
   LocalDateTime dayStart = newStartDate.truncatedTo(ChronoUnit.DAYS).withHour(8);
   LocalDateTime dayEnd = newStartDate.truncatedTo(ChronoUnit.DAYS).withHour(19);
   Long sessionsSameTime = dataManager.loadValue("select count(s) from planner_Session s where " +
           "(s.startDate between :dayStart and :dayEnd) " +
           "and s.speaker = :speaker " +
           "and s.id <> :sessionId", Long.class)
           .parameter("dayStart", dayStart)
           .parameter("dayEnd", dayEnd)
           .parameter("speaker", session.getSpeaker())
           .parameter("sessionId", session.getId())
           .one();
   if (sessionsSameTime >= 2) {
       return session;
   }
   session.setStartDate(newStartDate);
   return dataManager.commit(session);
}

Le service est prêt, ajoutons-le maintenant à l'écran du navigateur de session. Il sera appelé pour l'événement glisser-déposer dans le calendrier.

Dans le fichier session-Browse.xml, sélectionnez sessionsCalendar et accédez à l'onglet Handlers de la fenêtre Component Inspector. Sélectionnez CalendarEventMoveEvent et cliquez sur la flèche pour accéder au contrôleur.

Dans la méthode qui est abonnée à l'événement de glisser-déposer, nous ajoutons du code pour extraire l'entité de session de l'événement de calendrier et la transmettons au service pour replanifier cette session. Après cela, nous mettons simplement à jour cet élément dans le conteneur de données du navigateur.

@Subscribe("sessionsCalendar")
public void onSessionsCalendarCalendarEventMove(Calendar.CalendarEventMoveEvent<LocalDateTime> event) {
   Session session = sessionService.rescheduleSession((Session) event.getEntity(), event.getNewStart());
   sessionsDc.replaceItem(session);
}

Pour redéployer le nouveau service, nous devons redémarrer l'application, nous pouvons utiliser le bouton Exécuter dans IDEA.

49

Après le redémarrage, nous pouvons ouvrir le calendrier des sessions - et le tour est joué! Nous avons une fonctionnalité de reprogrammation par glisser-déposer pour le calendrier! Testons-le en ajoutant une session supplémentaire et en essayant de la replanifier.

Définir la marque commerciale

Dans CUBA, vous pouvez mettre à jour les fichiers de ressources et remplacer le texte standard. Mettons à jour le texte en fonction du domaine d’activité de l’application - planification de conférences.

Ouvrez le fichier principal du pack de messages - messages.properties qui se trouve sous Generic UI - Main Message Pack dans l'arborescence du projet CUBA.

50

Il s'agit d'un fichier java .properties standard, vous pouvez donc le modifier librement, en ajoutant de nouvelles clés de message et en mettant à jour celles existantes. Mettez à jour les messages pour refléter l'objectif de l'application. L'exemple est ci-dessous:

application.caption = Session Planner
application.logoLabel = Session Planner
application.logoImage = branding/app-icon-menu.png
application.welcomeText = Welcome to Session Planner!

loginWindow.caption = Session Planner Login
loginWindow.welcomeLabel = Welcome to Session Planner!
loginWindow.logoImage = branding/app-icon-login.png

menu-config.application-planner = Sessions and Speakers
menu-config.planner_Speaker.browse=Speakers
menu-config.planner_Session.browse=Sessions

Avec la fonctionnalité de déploiement à chaud de CUBA, tout ce que nous avons à faire est de nous reconnecter à l'application pour voir les modifications.

Marketplace

Le framework est livré avec une marketplace qui contient de nombreux composants, vous pouvez donc facilement ajouter des fonctionnalités utiles telles que la prise en charge de graphiques ou de cartes géographiques à l'application existante. Vous pouvez installer ces composants directement depuis le studio en utilisant le menu CUBA -> Marketplace.

51

Ajoutons le module complémentaire Helium. Il s'agit d'un nouveau thème visuel que vous pouvez utiliser à la place des thèmes standard. Cliquez simplement sur installer et appliquez les modifications.

Maintenant, nous devons arrêter l'application et mettre à jour la base de données pour appliquer les scripts d'initialisation du module complémentaire.

52

Exécutez l'application et accédez à l'écran des paramètres. Vous pouvez trouver le thème ajouté dans la liste déroulante. Sélectionnez-le et appliquez.

53

Connectez-vous à nouveau à l'application - le thème est appliqué.

54

Nous pouvons également ouvrir l'écran des paramètres du thème et modifier les paramètres avec un aperçu.

Conclusion

Le framework CUBA fournit de nombreuses API utiles pour vous aider à créer rapidement des applications métier. Ce guide de démarrage rapide montre uniquement les bases du framework CUBA et CUBA Studio. Vous pouvez trouver plus d'exemples et de tutoriels sur notre site Web: cuba-platform.com.

Merci de l'intérêt que vous portez à la plate-forme CUBA. Profitez du développement avec CUBA!