diff --git a/README.md b/README.md index 077372103aa..7a3004ebf21 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Les pages de documentation générale Jeedom sont directement accessibles sur ce ### Documentation du core -La documentation relative au core Jeedom *(manuels d'utilisation et de configuration)* se trouve dans le dossier `docs/fr_FR` du dépôt du core : . La branche `alpha` est à privilégier pour les contributions. +La documentation relative au core Jeedom *(manuels d'utilisation et de configuration)* se trouve dans le dossier `docs/fr_FR` du dépôt du core : . La branche `develop` est à privilégier pour les contributions. ### Documentation des plugins @@ -32,8 +32,8 @@ Comme pour le core Jeedom, la documentation des plugins officiels est automatiqu > >A lire impérativement avant toute intervention : [**Comment contribuer au développement du core Jeedom ?**](https://doc.jeedom.com/fr_FR/contribute/core) -Tout comme la documentation, le core Jeedom est open source et ouvert aux contributions. L'intégralité du code est consultable à cette adresse : . -Sauf indication contraire, **les modifications doivent impérativement être soumises sur la branche `alpha`**. +Tout comme la documentation, le core Jeedom est open source et ouvert aux contributions. L'intégralité du code est consultable à cette adresse : . +Sauf indication contraire, **les modifications doivent impérativement être soumises sur la branche `develop`**. ------------ @@ -59,7 +59,7 @@ The general Jeedom documentation pages are directly accessible on this repositor ### Core documentation -Documentation relative to the Jeedom core *(user and configuration manuals)* can be found in the folder `docs/fr_FR` from core repository : . The `alpha` branch is preferred for contributions. +Documentation relative to the Jeedom core *(user and configuration manuals)* can be found in the folder `docs/fr_FR` from core repository : . The `develop` branch is preferred for contributions. ### Plugins documentation @@ -71,8 +71,8 @@ As with the Jeedom core, officials plugins documentations are automatically gene > >Must be read before any intervention : [**How to contribute to Jeedom core development ?**](https://doc.jeedom.com/en_US/contribute/core) -Like documentation, the Jeedom core is open source and open to contributions. The complete code can be consulted at this address : . -Unless otherwise indicated, **modifications must be submitted on the `alpha` branch**. +Like documentation, the Jeedom core is open source and open to contributions. The complete code can be consulted at this address : . +Unless otherwise indicated, **modifications must be submitted on the `develop` branch**. ------------ diff --git a/fr_FR/beta/index.md b/fr_FR/beta/index.md index 7e977754b05..82ea1a81e53 100644 --- a/fr_FR/beta/index.md +++ b/fr_FR/beta/index.md @@ -1,77 +1,119 @@ -## Beta et Alpha test de Jeedom +# Bêta-test de Jeedom -### Définition +Un bêta‑testeur est un utilisateur qui teste les versions du logiciel avant qu'elles soient diffusées à l'ensemble des utilisateurs. Le bêta-testing permet de remonter des erreurs qui pourraient apparaitre lors de la phase de développement *(bug fonctionnel ou souci d'interface par exemple)*. C'est une importante source d'amélioration pour le projet, qui permet d'apporter des idées fraîches et de tester les nouveautés en conditions réelles. -Un Beta Testeur est un utilisateur qui teste les versions du logiciel avant qu'elles ne soient diffusées à tous les utilisateurs. Le beta testing permet de remonter des erreurs (bug fonctionnel ou soucis d'interface utilisateur par exemple) lors de la phase de développement. C'est donc une importante source d'amélioration pour le projet, qui peut apporter des idées fraiches et tester les nouveautés en conditions réelles. +## Mises en garde -### Précautions +Bien que les développeurs prennent un maximum de précautions, les versions en cours de développement sont susceptibles d'inclure des bugs pouvant rendre un plugin ou le core totalement inopérants. De la même manière, les fonctionnalités en cours de développement peuvent être reportées, voire abandonnées en fonction des circonstances. Il faut donc être plutôt à l'aise avec les procédures de sauvegarde/restauration de Jeedom avant de se lancer dans le bêta-testing. -Les versions **Beta** et **Alpha** du Core ou des plugins sont des versions de développement. Même si les développeurs prennent bien sûr des précautions, ces versions peuvent comprendre des bugs susceptibles de rendre un plugin ou le Core totalement inopérant. Il faut donc être familier des procédures de backup, récupération, etc. +Comme indiqué ci-dessus, le fait de basculer Jeedom ou un plugin sur une version en cours de développement comporte des risques. Par conséquent, **il est fortement recommandé de le faire sur une installation de test prévue à cet effet *([une machine virtuelle](../installation/vm) par exemple)* plutôt que sur un Jeedom en production**. -Le développement du Core se fait sur [Github](https://github.com/jeedom/core) sur la version **Alpha**. Celle-ci possède donc toutes les futures nouveautés, mais aussi le plus de bugs. De plus, les développements faits sur cette version sont susceptibles d'être annulés ou reportés. La version **Alpha** remonte ensuite en **Beta**, qui est généralement *Featured fixed* et consiste donc à s'assurer de sa stabilité, tout en permettant aux développeurs de plugins de tester leurs futures versions. +>**IMPORTANT** +> +>L'équipe Jeedom ne peut être tenue responsable de tout dysfonctionnement survenant suite à l'installation d'une version autre que stable. Dans ce cas **l'accès au support officiel est impossible**, il faut donc [faire une remontée](#Faire%20une%20remontée). -> **Important** -> Le passage en beta (ou alpha) d'un plugin ou du Core est risqué et interdit tout accès au support officiel de l'équipe Jeedom. Les développeurs sont toutefois présents sur [Community](https://community.jeedom.com/) pour aider en cas de problème, sans garantie toutefois. +## Branches -> **Important** -> Il est fortement déconseillé d'installer une beta ou alpha sur un Jeedom de production ! Il est indispensable de tester sur un Raspberry ou une VM de test et l'équipe Jeedom ne pourra être tenue pour responsable de tout dysfonctionnement. +Jeedom est un logiciel open-source dont le développement peut être suivi en temps réel sur [GitHub](https://github.com/jeedom/core){:target="_blank"}. Chaque branche correspondant à différents niveaux d'avancement dans son développement. -### Comment +### Branches principales -Le Core de Jeedom est Open-Source. Tout le monde peut décider de passer son Jeedom d'une version Stable à une version Beta ou Alpha, avec toutes les précautions nécessaires citées ci-dessus. +- **develop** : Version en cours de développement incluant des modifications régulières *(intégration continue)*. +- **release** : Prochaine version déployée quelques jours avant passage en stable. +- **master** : Version stable de Jeedom *(branche par défaut incluant le support officiel)*. -Le Core possède trois branches principales sur [Github](https://github.com/jeedom/core): +### Branches annexes -- **alpha** : Branche de la version V4 alpha. Principalement destinée aux développeurs pour la version suivante de Jeedom. -- **beta** : Branche de la version V4 beta. Principalement destinée aux beta testeurs, pour tester avant passage en Stable. -- **master** : Branche stable de la V4. +Les branches annexes correspondent à des développements indépendants et ponctuels, voués à être intégrés à une branche principale. -> **Attention** -> Encore une fois, cette manipulation est à réserver aux utilisateurs avancés en toute connaissance de cause. +- **feat/xxxxx-yyyyy** : Nouvelle fonctionnalité testable avant son déploiement dans `develop`. +- **fix/xxxxx-yyyyy** : Correctif non urgent testable quelques jours avant son déploiement dans `develop`. +- **hotfix/xxxxx-yyyyy** : Correctif urgent rapidement déployé dans `master` & `develop`. -> **Attention** -> Le *downgrade* de version est totalement déconseillé et peut rendre Jeedom totalement inopérant. Par exemple, *downgrader* de Beta v4.2 vers Stable v4.1 ne doit pas être fait ! Dans ce cas, la meilleure solution est d'attendre la future version Stable de l'actuelle Beta, puis remettre la configuration de Jeedom en version Stable, et faire une mise à jour manuelle. De même un backup d'une version ultérieure ne doit pas être restauré sur une version antérieure (par exemple backup 4.2 sur Core 4.1). +>**INFORMATION** +> +>`xxxxx-yyyyy` correspond au sujet court de la fonctionnalité ou du correctif en question. -Pour changer de version, rendez vous dans *Réglages → Système → Configuration*, onglet *Mises à jour/Market*. Laissez la Source de mise à jour à **Défaut** et choisissez la version que vous souhaitez. +### Changer de version -Ensuite, sauvegardez puis rendez vous dans *Réglages → Système → Centre de Mise à jour*. Ici lancez une mise à jour du Core. +A la lecture des [mises en garde](#Mises%20en%20garde) exposées précédemment, il est évident que **cette manipulation est à réserver aux utilisateurs avancés en toute connaissance de cause**. -### Feedbacks +Pour changer de branche, et donc de version Jeedom, rendez-vous dans le menu **Réglages → Système → Configuration**, onglet **Mises à jour/Market**. Laissez la source de mise à jour sur **Défaut** et sélectionnez la version du core *(branche)* que vous souhaitez installer. -Le but d'un beta testeur est de remonter les soucis rencontrés lors de ses tests. -Ces remontées se font sur **[Community](https://community.jeedom.com/)** dans la section **[beta-testeurs](https://community.jeedom.com/c/salon-des-beta-testeurs/6)** +Ensuite, cliquez sur le bouton **Sauvegarder** puis dirigez-vous vers le menu **Réglages → Système → Centre de Mise à jour**. Depuis cette page il ne reste qu'à effectuer une mise à jour du core pour basculer sur la nouvelle version. -C'est aussi sur cette section qu'un testeur peut créer un sujet pour proposer une amélioration. +>**IMPORTANT** +> +>En cas de changement de numérotation du core, il est vivement déconseillé de revenir sur une version inférieure *(downgrade)*. Il est plutôt recommandé d'attendre que les modifications arrivent en version stable pour rebasculer dessus.\ +>Concernant les branches annexes, une fois la fonctionnalité ou le correctif testés, il faut revenir sur la version à la base *(`develop` dans la majorité des cas)*. -> Chaque sujet sur cette section doit être identifié avec le tag de la version en cours de développement. Par exemple : tag v4_4 (un underscore est utilisé car les points sont interdits dans les tags sur Discourse. +## Mises à jour -Cette section n'est pas accessible publiquement. Pour y avoir accès, vous devez remplir un formulaire afin que l'équipe Jeedom donne [accès à votre compte](https://blog.jeedom.com/jeedom-partenaire-beta-testeur/). +En `master` *(stable)* ou `release`, chaque nouvelle version entraine un changement de numérotation *(x.y.z)*. Si la case **Vérification automatique des mises à jour** est cochée, alors un message de notification sera émis dans Jeedom accompagné d'une pastille rouge dans la barre de menu. Sinon il faut se rendre dans le menu **Réglages → Système → Centre de Mise à jour** puis cliquer sur le bouton **Vérifier les mises à jour**. -> Avant de remonter un problème, mettez à jour le Core et réessayez de reproduire. Voir ci-dessous. +À l'inverse, les autres branches n'engendrent pas de notification ni d'alerte dans le centre de mises à jour malgré des modifications régulières. Il revient donc au bêta‑testeur de mettre le core à jour manuellement et régulièrement. Avant chaque phase de tests notamment, et surtout, avant d'effectuer toute remontée afin de s'assurer que le problème n'a pas déjà été corrigé. -### Gestion des mises à jour du Core +## Changelog -En version **Stable**, chaque changement provoque un changement de version (mineure, par exemple 4.1.xx) qui, si vous avez coché **Vérification automatique des mises à jour**, provoquera un message et l’apparition de la pastille rouge dans la barre de menu. Ces mises à jour sont également affichées dans *Réglages → Système → Centre de Mise à jour* en cliquant manuellement sur *Vérifier les mises à jour*. +Le **journal des modifications** *(ou changelog)* offre un aperçu des changements apportés par chaque version de Jeedom. -En version **Beta** et **Alpha**, les changements sont beaucoup plus fréquents (plusieurs fois par jour) et ne provoquent pas de changement de version. Elles n'apparaitront donc pas dans le *Centre de Mise à jour*, c'est au testeur de mettre régulièrement le Core à jour, de préférence avant toute phase de test et avant de remonter un problème afin de s'assurer que celui-ci n'a pas déjà été corrigé plus tôt. +Seules les versions [`master` *(stable)*](../core/#VERSION#/changelog){:target="_blank"} et [`release`](https://github.com/jeedom/core/blob/release/docs/#LANG#/changelog.md){:target="_blank"} garantissent la présence d'un changelog détaillé et à jour. -> L'équipe change parfois de version en cours de développement, pour marquer certaines phases. Mais contrairement à la version Stable, beaucoup de changements sont faits entre deux versions. Chaque testeur peut suivre les commits sur les branches [Github](https://github.com/jeedom/core). +En `develop`, les intégrations étant continues, le journal des modifications n'est pas encore généré à cette étape. Pour prendre connaissance des changements apportés depuis la dernière version stable, il faut se référer aux [notes de version](https://github.com/jeedom/core/blob/develop/docs/release-notes.md){:target="_blank"} qui listent les *Pull Requests* validées sur cette branche. -### Changelog +Les branches annexes faisant quant à elles référence à un élément précis, elles ne nécessitent à première vue pas de détails pour être appréhendées. -Dès le début du développement de la version **Alpha**, l'équipe essaye de tenir à jour le futur [Changelog](/fr_FR/core/4.5/changelog). Les nouveautés pouvant évoluer fortement voir être supprimées ou reportées, celui-ci n'est donc pas forcément à jour et n'a pas valeur de référence. +## Plugins -En version **Stable**, le changelog reprend chaque version mineure (4.1.26 -> 4.1.27 etc). En version **Beta** et **Alpha** le changelog est numéroté x.0.0 et ne correspond donc pas forcément à la version mineure en cours. Par exemple, lors du développement de la v4.2, le changelog est uniquement noté 4.2.0 alors qu'une beta peut être en 4.2.7. Lors du passage en **Stable**, le changelog tiendra alors compte de chaque future version mineure. +La présente page s'attarde principalement sur les bêta-tests autour du core Jeedom mais le principe reste sensiblement le même pour les plugins. En effet, les plugins sont mis à disposition en version stable *(branche `master`)* par défaut mais ils disposent également de versions `beta` pour les développements en cours. -### Ressouces +Pour accéder aux plugins en version `beta`, il est nécessaire de cocher la case **Activer l'accès aux plugins bêta** dans [votre profil Market](https://market.jeedom.com/index.php?v=d&p=profils){:target="_blank"}. Il suffit ensuite d'installer ou de réinstaller le plugin dans cette version. - [Accès Community](https://blog.jeedom.com/jeedom-partenaire-beta-testeur/) - -Community [beta-testeurs](https://community.jeedom.com/c/salon-des-beta-testeurs/6) +>**IMPORTANT** +> +>L'installation d'un plugin en version `beta` fait perdre tout accès au support officiel. -[Doc contribuer](/fr_FR/contribute/) +## Faire une remontée -[Doc Développeurs](/fr_FR/dev/) +Les bêta‑testeurs sont en première ligne pour identifier un dysfonctionnement, tester une nouvelle fonctionnalité ou valider une correction avant publication en stable. -[Github](https://github.com/jeedom/core) +Après avoir clairement analysé la situation, plusieurs canaux sont disponibles pour effectuer des remontées les plus détaillées possibles avec tout le contexte nécessaire. Quel que soit le canal choisi, la première étape indispensable consiste à effectuer une recherche afin de s'assurer que le sujet n'est pas déjà abordé pour ne pas créer de doublons. + +>**IMPORTANT** +> +>Il est crucial de comprendre un minimum le sujet par soi-même sans se reposer intégralement sur l'analyse d'une intelligence artificielle. Celle-ci peut toutefois rester utile pour la mise en forme de la remontée ou pour ajouter du complément *(vérifié)*. + +### Forum Jeedom + +Les remontées peuvent être formulées directement dans [le salon des bêta‑testeurs du forum Jeedom](https://community.jeedom.com/c/salon-des-beta-testeurs/6){:target="_blank"}. + +Choisissez la section adaptée à la catégorie de la remontée puis ajoutez les étiquettes *(tags)* en lien avec le sujet *(`v4_5` par exemple)*. Il ne reste plus qu'à rédiger votre retour en incluant le maximum d'informations afin que toute personne extérieure soit en mesure de comprendre, de reproduire et d'analyser la situation. + +>**INFORMATION** +> +>Le salon des bêta‑testeurs intègre également [une section **Suggestions**](https://community.jeedom.com/c/salon-des-beta-testeurs/suggestion/29){:target="_blank"} pour proposer des améliorations. + +### Issue GitHub + +Si, après recherche, une *issue* ou une *pull request* est déjà ouverte sur le même sujet alors vous pouvez y ajouter votre analyse à condition qu'elle apporte des éléments pertinents dans le cadre du développement concerné. + +Sinon, vous pouvez ouvrir [une *issue* sur GitHub](https://github.com/jeedom/core/issues){:target="_blank"} détaillant de manière exhaustive le dysfonctionnement rencontré. + +>**INFORMATION** +> +>L'anglais est la norme sur GitHub pour que tout un chacun soit en mesure de comprendre le sujet mais nous acceptons les textes rédigés en français. + +## Contribuer au développement + +Que ce soit pour corriger une simple faute d'orthographe ou de syntaxe, ou même pour proposer un changement plus important, tout le monde peut participer au développement et à l'évolution de la solution Jeedom à son niveau. + +### Documentation + +Les pages de documentation que vous consultez actuellement nécessitent des mises à jour et des adaptations régulières pour rester valables et fiables. L'assistance de la communauté est grandement appréciée à ce niveau. + +Quelques spécificités sont à prendre en compte avant de proposer des changements sur la documentation. Il est donc indispensable de prendre connaissance des bonnes pratiques pour [contribuer à la documentation](../contribute/doc) en premier lieu. + +### Core et Plugins + +A l'instar de la documentation, le core Jeedom ainsi que la plupart des plugins sont également ouverts aux contributions externes. Référez-vous à la page ["Contribuer au core ou aux plugins"](../contribute/core) pour en savoir plus. diff --git a/fr_FR/contribute/core.md b/fr_FR/contribute/core.md index 515bbe827c6..b7b89c84df3 100644 --- a/fr_FR/contribute/core.md +++ b/fr_FR/contribute/core.md @@ -1,284 +1,71 @@ -# Contribuer au développement du Core +# Contribuer au core ou aux plugins -Vous souhaitez contribuer au développement du Core de Jeedom ? +Jeedom est un logiciel open-source dont le code est consultable sur [GitHub](https://github.com/jeedom/core/tree/develop){:target="_blank"} et qui est ouvert aux contributions des développeurs tiers. -- Vous pouvez faire des PRs (*Pull requests*) sur le *repository* du Core. -- Si vous avez des idées d'évolutions et souhaitez participer sur le long terme, n'hésitez pas à [contacter l'équipe du projet](mailto:contact@jeedom.com). +>**IMPORTANT** +> +>Il est crucial de comprendre le code proposé sans se reposer intégralement sur des développements réalisés par une intelligence artificielle. Celle-ci peut toutefois rester utile pour de l'optimisation ou pour effectuer des vérifications complémentaires. -Voici les notions de bases à connaître : +## Prérequis -> Avant de proposer un PR, mettez à jour votre alpha pour vérifier que le bug n'a pas déjà été corrigé. Et synchronisez votre dépôt github. +Pour contribuer au développement du core Jeedom ou d'un plugin, quelques prérequis sont à connaître et à prendre en compte : +- Tout d'abord, il est indispensable de prendre connaissance et d'appliquer [la procédure de bêta-test de Jeedom](../beta/), +- il faut également disposer d'[un compte utilisateur sur GitHub](https://github.com/){:target="_blank"}, +- Savoir faire [une *Pull Request* sur GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request){:target="_blank"}, +- Comprendre le langage concerné par les modifications *(`PHP`, `JavaScript`, `HTML`, `CSS`, `Python`, `Node.js`, etc.)*, +- Tester les changements proposés afin de s'assurer qu'ils n'engendrent pas d'autres bugs ou effets de bord, +- Enfin, des connaissances du système Linux Debian peuvent être nécessaires en fonction du code à faire évoluer. -> Vérifiez que ce que vous corrigez ne cause pas d'autres bugs. La plupart des fonctions du Core sont appellées par différentes pages du Front-End ou par d'autres fonctions du Core et par les plugins. Faites une recherche sur le Core pour voir/comprendre où les fonctions sont utilisées et, dans le doute, exposez le soucis et votre correction sur [Community](https://community.jeedom.com/). +## Développeurs tiers -## Branches Github +Que vous soyez développeur confirmé ou pas, chacun a son rôle à jouer pour participer au développement et à l'évolution de la solution Jeedom à son niveau. Différentes aides peuvent être fournies à travers la documentation et le forum Jeedom. -Pour participer au développement de Jeedom, vous devez avoir un compte [Github](https://github.com/). +>**INFORMATION** +> +>Si vous n'êtes pas à l'aise à l'idée d'intervenir directement sur les fichiers du core ou d'un plugin mais que vous souhaitez apporter votre pierre à l'édifice, vous pouvez toujours contribuer en créant un sujet sur le forum dans la section ["Utilisation du core de Jeedom"](https://community.jeedom.com/c/utilisation-du-core-de-jeedom/57){:target="_blank"} ou [celle dédiée aux plugins](https://community.jeedom.com/c/plugins/46){:target="_blank"} avec l'étiquette du plugin concerné. -Le code du Core est Open-Source est disponible [ici](https://github.com/jeedom/core). +### Documentation développeurs -- **alpha** : Branche de la version V4 alpha. Principalement destinée aux développeurs pour la version suivante de Jeedom. -- **beta** : Branche de la version V4 beta. Principalement destinée aux beta-testeurs, pour tester avant passage en Stable. -- **master** : Branche stable de V4. +Nous vous recommandons de prendre régulièrement connaissance des documentations relatives au [développement du core](../dev/core) ou au [développement d'un plugin](../dev/) afin d'appliquer les rêgles établies et d'être certain de respecter les normes de Jeedom. -Les mises à jour se font sur ces branches en fonction de la configuration de Jeedom **Réglages → Système → Configuration / Mises à jour/Market**. +### Forum développeurs -Les PRs (*Pull requests*) doivent toujours être faits sur la branche alpha. +En complément de la documentation, vous avez également accès [au salon des développeurs du forum](https://community.jeedom.com/c/developpeur-developpeurs/5){:target="_blank"} qui regorge d'informations. -De même, afin de participer aux discussions sur [Community](https://community.jeedom.com/), inscrivez-vous en tant que développeur : [Jeedom dev](https://www.jeedom.com/fr/dev.html). +>**INFORMATION** +> +>Ce salon est en lecture seule par défaut, pour pouvoir y intervenir il est indispensable d'être préalablement [inscrit en tant que développeur Jeedom](https://market.jeedom.com/index.php?v=d&p=becomeDeveloper){:target="_blank"}. -## Développement +## Contribuer au core Jeedom -Pour aider au développement du Core, vous devez maîtriser un ou plusieurs des langages suivants: +Les contributions au core Jeedom doivent être soumises sur [la branche `develop`](https://github.com/jeedom/core/tree/develop){:target="_blank"} dans la grande majorité des cas, sauf si une branche dédiée à la fonctionnalité existe déjà. En cas de doute, nous vous recommandons d'ouvrir une issue afin que les mainteneurs puissent vous orienter vers la bonne branche, voire en créer une si nécessaire. -- PHP : Développement des classes php, des appels ajax depuis le front-end. -- javascript : Développement des classes js et du front-end. -- CSS : Développement de l'interface. +>**IMPORTANT** +> +>Si vous souhaitez soumettre plusieurs changements, il faut ouvrir autant de *pull requests* que de corrections ou fonctionnalités concernées. -Des connaissances de l’environnent Linux sont également souhaitables. +## Contribuer aux plugins -## Arborescence du Core +Concernant les plugins, les demandes d'évolution doivent être soumises sur la branche `beta`. -Le code est réparti dans différents répertoires à la racine de Jeedom (par défaut : /var/www/html) : +>**INFORMATION** +> +>Certains dépôts de plugins ne sont pas accessibles publiquement. Dans ce cas, vous pouvez également contribuer en créant un sujet sur [le forum](https://community.jeedom.com/c/plugins/46){:target="_blank"} avec l'étiquette du plugin concerné. -- **3rdparty** : Dossier comprenant les bibliothèques externes utilisées par Jeedom (jQuery, CodeMirror, etc). -- **backup** : Dossier des sauvegardes de Jeedom. -- **core** : Dossier comprenant les fonctions internes du Core: - - **ajax** : Fichiers php d'interface entre les classes js et les classes php. - - **api** : Fichiers php des API. - - **class** : Fichiers des classes php (*eqLogic, cmd, jeeObject, history, cron, etc.*). - - **com** : Fichiers des classes php de communication (*http, shell*). - - **config** : Fichiers php de configuration du Core et *default.config.ini* comprenant les paramètres de configuration par défaut. Fichier version pour la version du Core. - - **css** : Icônes disponibles avec le Core et leur CSS. - - **i18n** : Fichiers json comprenant les chaînes de caractères traduites. - - **img** : Images (logos, fonds, etc.) du Core. - - **js** : Fichiers des class js, appelées notamment depuis les pages de Jeedom. - - **php** : Fichiers php nécessaires au Core (hors classes). - - **repo** : Fichiers php propres au market, samba, etc. - - **template** : Fichiers html (*Dashboard et Mobile*) pour l'affichage des eqLogics (Tuile), commandes (Widgets) et scenarios. - - **themes** : Fichiers CSS des trois thèmes du Core (Dark, Light, Legacy), pour Dashboard et Mobile. -- **data** : Dossier comprenant les données utilisateur (Rapports, Vues, css/js de Personnalisation Avancée, Design 3D, etc). -- **desktop** : Dossier comprenant toutes les pages affichées (l'interface) en desktop et leurs fonctions. - - **common** : Fichiers js/php communs à plusieurs pages. Regroupe des fonctions pouvant être appelées depuis plusieurs pages, notamment le *utils.js*, présent sur toutes les pages en Desktop. - - **css** : Fichiers css propres à l'affichage Desktop. - - **img** : Images propres à l'affichage Desktop. - - **js** : Fichiers js correspondant à chaque page (*administration, dashboard, scenario, etc.*). - - **modal** : Fichiers php des modales, comprenant le code php/html et le code js. - - **php** : Fichiers php correspondant à chaque page (*administration, dashboard, scenario, etc.*). -- **docs** : Documentation. -- **install** : Fichiers d'installation de Jeedom. -- **log** : Dossier comprenant tous les logs (http.error, update, etc) et ceux des scénarios (sous-dossier scenarioLog, nommés par id). -- **mobile** : Dossier comprenant toutes les pages affichées (l'interface webapp) en mobile et leurs fonctions. - - **css** : Fichiers css propres à l'affichage Mobile. - - **html** : Fichiers html correspondant à chaque page (*home, equipment, timeline, etc.*). - - **js** : Fichiers js correspondant à chaque page (*home, equipment, timeline, etc.*). - - **modal** : Fichiers html correspondant aux modales en Mobile. -- **plugins** : Dossier comprenant tous les plugins installés. -- **script** : Script de déploiement, certificats. -- **support** : Dossier utilisé en cas de demande de support. -- **vendor** : Dossier comprenant des bibliothèques tierces php. +## Gestion des traductions +Les traductions sont générées automatiquement dans les fichiers `i18n/*.json`. Il est inutile de modifier ces fichiers car ils sont réécrits régulièrement par un robot. -## Front-end - -L'interface de Jeedom fonctionne comme un site web, à partir de php interfacé avec SQL et de js / CSS. - -Au départ, le browser charge le fichier `/index.php` : -- Vérification de l'installation de Jeedom, renvoi vers `install/setup.php` si nécessaire. -- Vérification de la provenance Desktop ou Mobile. -- Chargement des fichiers et classes nécessaires avec `/core/php/core.inc.php`. -- Vérification de l'authentification de l'utilisateur. -- Vérification de paramètres dans l'url pour charger directement le bon contenu. -- Redirige vers la version Desktop `/desktop/php/index.php` ou Mobile `mobile/html/home.html` en fonction des paramètres de l'url. - -### Desktop - -L'interface de Jeedom fonctionne sur le principe du One-Page. Une fois chargée, les différentes pages sont affichées en changeant le contenu d'un container. - -Le fichier principal en Desktop est `/desktop/php/index.php`. - -Chaque page possède au minimum deux paramètres dans l'url. Exemple : - -`https://my.dns1.jeedom.com/index.php?v=d&p=dashboard` : -- **v** : Version de l'interface : d pour Desktop, m pour mobile. -- **p** : Page à afficher. Ici, `dashboard`. - -Dans ce cas, le fichier `/desktop/php/index.php` va charger le fichier `/desktop/php/dashboard.php` dans la div `div_pageContainer`. Celui-ci va également charger le fichier `/desktop/js/dashboard.js` comprenant les fonctions js propres à l'affichage de cette page (ici, le Dashboard). - -Le fichier `/desktop/php/index.php` se charge aussi de : -- Vérifier le mode *rescue* -- Vérifier l'authentification de l'utilisateur. -- Vérifier si nécessaire la page à charger en fonction de la configuration (page par défaut de l'utilisateur). -- Créer la structure html (*head, body, div_pageContainer, etc*). -- Charger les CSS, bibliothèques etc. -- Charger le thème de l’utilisateur. -- Créer la barre de menu. -- Renseigner certaines variables php/js globales. -- Charger le fichier js `desktop/common/js/utils.js` - -Le fichier `desktop/common/js/utils.js` est donc toujours présent, et chargé une fois. Il permet de : -- Gérer les events js du menu. -- Gérer les paramètres d'url en fonction de la page demandée. -- Charger la page demandée dans la div `div_pageContainer`. -- Gérer les ouverture/fermeture des modales (fenêtre de dialogue). -- Gérer une éventuelle bascule de thème en fonction de l'heure. -- Permettre aux différents fichiers js d'accéder à des fonctions communes. - -Ainsi, les fichiers index.php et utils.js fournissent la structure et les fonctions de base de l'interface. -Ensuite, le contenu de la page appelée est chargé depuis desktop/php/page.php et desktop/js/page.js. -Ces fichiers de contenu, purement orientés interface, peuvent accéder aux fonctions du Core (les classes `/core/class`) directement en php, ou en js grâce aux classes js (`/core/js`) en passant par des appels ajax (`/core/ajax`). - -Les fonctions internes du Core sont ainsi bien séparées, pour le fonctionnement interne (Back-end), mais sont accessibles par l'interface. De même, chaque page possède sont propre code php et js. Ceci permet de mieux faire évoluer et maintenir le code, mais aussi d'optimiser les performances en chargeant uniquement les classes et fonctions nécessaires. - -#### Core v4.2 -Depuis le Core v4.2, toutes les fonctions js du fichier `desktop/common/js/utils.js` sont isolées dans un namespace `jeedomUtils{}`. -Par exemple, la fonction précédemment dans le root window `loadPage()` devient `jeedomUtils.loadPage()`. - -Pour des raisons de rétro-compatibilité pour les plugins, les anciennes fonctions sont toujours déclarées et seront dépréciées dans une version ultérieure. [Voir la liste ici](https://github.com/jeedom/core/blob/alpha/desktop/common/js/utils.js#L1423). - -#### Core v4.3 -Dans la continuité de la version 4.2, les pages du front-end en desktop on été isolées afin d'éviter de référencer des variables et fonctions dans le root window. Ceci sécurise de possible collision de déclaration et facilite la lecture et la compréhension du code ainsi que son debuggage. - -Le fichier `core/js/jeedom.class.js`déclare deux nouveaux namespaces : -##### jeeFrontEnd[} - -Certaines variables globales sont maintenant dans ce namespace : - -```js -jeeFrontEnd = { - __description: 'Global object where each Core page register its own functions and variable in its sub-object name.', - jeedom_firstUse: '', - language: '', - userProfils: {}, - planEditOption: {state: false, snap: false, grid: false, gridSize: false, highlight: true}, - //loadPage history: - PREVIOUS_PAGE: null, - PREVIOUS_LOCATION: null, - NO_POPSTAT: false, - modifyWithoutSave: false, - //@index.php - serverDatetime: null, - clientServerDiffDatetime: null, - serverDatetime: null, - serverTZoffsetMin: null, -} -``` - -Exemple type pour desktop/js/corepage.js : - -```js -"use strict" - -if (!jeeFrontEnd.corepage) { - jeeFrontEnd.corepage = { - myVar: 'oneVar', - init: function() { - window.jeeP = this //root shortcut - }, - postInit: function() { - //Do stuff once page loaded - }, - myFunction: function(_var) { - var myFuncContextVar = this.myVar + ' -> ' + _var - console.log(myFuncContextVar) - } - } -} - -jeeFrontEnd.corepage.init() - -$(function() { - jeeFrontEnd.corepage.postInit() -}) - -$('#myButton').on('click', function() { - jeeP.myFunction('test') -}) +Pour que le système de traduction fonctionne il faut respecter un certain formalisme selon le langage utilisé : +- En `PHP`, hors dossier `desktop/php` : +```php +$myString = __('Ma phrase qui sera traduite', __FILE__); ``` - -> Le namespace de la page ne sera donc pas recréé au retour sur cette même page. De plus, la variable `jeeP` permet d'utiliser `jeeFrontEnd.corepage` avec une syntaxe courte, elle correspond à un `self` propre à la page. - -##### jeephp2js[} - -Utilisé pour passer les variables d'un script php vers le front-end js. Par exemple : - +- En `PHP`, dans le dossier `desktop/php` : ```php -sendVarToJS([ - 'jeephp2js.myjsvar1' => init('type', ''), - 'jeephp2js.myjsvar2' => config::byKey('enableCustomCss') -]); +$myString = '{{Ma phrase qui sera traduite}}'; ``` - -Puis - +- En `JavaScript`: ```js -$(function() { - if (jeephp2js.myjsvar1 == '1') { ... } -}) +var myString = '{{Ma phrase qui sera traduite}}' ``` - -> Le namespace jeephp2js{} est vidé au changement de page pour éviter toute variable résiduelle non attendue. - -### Mobile - -L'interface Desktop est responsive et s'adapte à la taille du navigateur. Toutefois, certaines choses, comme l'édition d'un scénario, seraient compliquées sur un petit écran. De plus, sur un smartphone à l’extérieur, en 3G ou même 4G, il est important d'optimiser la rapidité de l'affichage. C'est pourquoi Jeedom possède une interface Mobile, plus légère et adaptée aux petits écrans. - -La page de référence est `/mobile/html/index.html`, qui se charge de : -- Vérifier l'authentification de l'utilisateur. -- Créer la structure html (*head, body, div_pageContainer, etc*). -- Charger les CSS, bibliothèques etc. -- Charger le thème de l’utilisateur. -- Renseigner certaines variables php/js globales. -- Charger le fichier js `mobile/js/application.js` - -Le fichier `mobile/js/application.js` contient les fonctions communes à toutes les pages. - -Comme pour l'interface Desktop, la page appelée est constituée de deux fichiers : -- `/mobile/html/home.html` : le code html. -- `/mobile/js/home.js` : les fonctions js propres à cette page. - -Une différence notable en Mobile est l'absence de pages php. La génération du code repose donc sur les classes js, qui peuvent toujours appeler les fonctions du Core avec des appels ajax. - -### Fichiers CSS - -Les CSS du Core reposent principalement sur ces fichiers : -- En Desktop : - - desktop/css/boostrap.css : Version nettoyée par l'équipe du CSS Bootstrap v3.3.7. - - desktop/css/desktop.main.css : CSS principal de l'interface. - - desktop/css/coreWidgets.css : CSS propres aux widgets du Core. - -- En Mobile : - - mobiles/css/mobile.main.css : CSS principal de l'interface. - - mobiles/css/coreWidgets.css : CSS propres aux widgets du Core. - -Les thèmes contiennent des CSS propres à chaque thème, notamment les colors.css. - -Ordre de chargement des CSS en Desktop : -- 3rdParty css (CodeMirror, etc.). -- Fonts (roboto, camingocode, text-security-disc). -- coreWidgets.css -- desktop.main.css -- colors.css (variables de couleurs du thème). -- core2019_xx.css (fichier principal du thème). -- shadows.css (si activé en configuration). -- custom.css (fichier css de personnalisation avancée). - - -## Back-end - -*en cours* - -L'interface est une chose, mais bien sûr votre Jeedom est toujours actif, afin de faire tourner les scénarios, les crons, les logs, les historiques etc. - -Le Back-end s’appuie sur les mêmes classes php que le Front-end, présentes dans `/core/class/`. Chaque partie de Jeedom possède sa classe php, notamment : - -- jeeObject.class.php : Regroupe les fonctions concernant les objets de Jeedom. -- eqLogic.class.php : Regroupe les fonctions concernant les équipements de Jeedom. -- cmd.class.php : Regroupe les fonctions concernant les commandes de Jeedom. -- cron.class.php : Regroupe les fonctions concernant les tâches planifiées de Jeedom. -- config.class.php : Regroupe les fonctions concernant les paramètres de configuration de Jeedom. -- scenario.class.php : Regroupe les fonctions concernant les scénarios de Jeedom. -- DB.class.php : Regroupe toutes les fonctions d'accès à la base de données de Jeedom. Tous les accès SQL requis par les autres classes sont gérés par celle-ci. - -etc. - diff --git a/fr_FR/contribute/doc.md b/fr_FR/contribute/doc.md index 5641762f9fd..49681fe98b0 100644 --- a/fr_FR/contribute/doc.md +++ b/fr_FR/contribute/doc.md @@ -1,76 +1,66 @@ # Contribuer à la documentation -La documentation de Jeedom est centralisée sur ce site, par plusieurs mécanismes. Comme le Core de Jeedom, la documentation est accessible sur Github et est Open-Source (licence MIT). +La documentation Jeedom est centralisée sur ce site à travers plusieurs mécanismes. Comme le core de Jeedom, [la documentation est consultable sur GitHub](https://github.com/jeedom/documentations){:target="_blank"} et est Open-Source *(licence MIT)*. -Pour participer à la documentation, vous devez donc avoir un compte [Github](https://github.com/). +Celle-ci se découpe en trois grandes catégories : +- [La documentation générale](#Documentation%20générale) +- [La documentation du core Jeedom](#Documentation%20du%20core%20Jeedom) +- [La documentation des plugins](#Documentation%20des%20plugins) -Bien sûr, vous pouvez toujours faire un message sur le [forum](https://community.jeedom.com/), en mettant le tag documentation-jeedom sur votre message. +>**INFORMATION** +> +>Si vous souhaitez revoir un grand nombre de fichiers, il est préférable de le faire par étape *(par rubrique par exemple)* plutôt que soumettre de nombreuses modifications en une seule fois. -Celle-ci est différenciée en trois catégories : +## Prérequis -## La documentation générale +Pour contribuer à la documentation, quelques prérequis sont à connaître et à prendre en compte : +- Tout d'abord, il faut disposer d'[un compte utilisateur sur GitHub](https://github.com/){:target="_blank"}, +- Savoir faire [une *Pull Request* sur GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request){:target="_blank"}, +- Connaître [le langage `Markdown`](https://fr.wikipedia.org/wiki/Markdown){:target="_blank"} utilisé pour la mise en forme du texte, +- Les traductions étant générées depuis le français, les contributions doivent impérativement être soumises en français *(dossier `fr_FR`)*, +- Enfin, les traductions étant générées automatiquement, aucune modification ne doit être apportée aux fichiers `i18n/*.json`. -Les pages de documentation générale sont celles qui ne proviennent pas directement du Core. +>**INFORMATION** +> +>Si vous n'êtes pas à l'aise à l'idée d'intervenir directement sur les fichiers de documentation, vous pouvez également contribuer en créant un sujet sur [le forum](https://community.jeedom.com/){:target="_blank"} avec l'étiquette `documentation-jeedom`. -Par exemple : +## Documentation générale -- [Présentation](https://doc.jeedom.com/fr_FR/presentation/) -- [Concepts](https://doc.jeedom.com/fr_FR/concept/) -- [Contribuer à la documentation](https://doc.jeedom.com/fr_FR/contribute/doc) +Les pages de documentation générale concernent toutes les pages, hormis celles relatives aux **Manuels** *(core Jeedom)* et aux **Plugins**. Les fichiers sont accessibles sur [le dépôt de la documentation](https://github.com/jeedom/documentations/tree/master/fr_FR){:target="_blank"}. L'adresse du site de documentation correspondant à un fichier `Markdown` *(\*.md)* sur GitHub, par exemple : -Ces pages sont disponibles sur le [dépôt de la documentation](https://github.com/jeedom/documentations/tree/master/fr_FR) +- **Compatibilité** (https://doc.jeedom.com/#LANG#/compatibility/) → https://github.com/jeedom/documentations/blob/master/fr_FR/compatibility/index.md +- **Installation sur Raspberry Pi** (https://doc.jeedom.com/#LANG#/installation/rpi) → https://github.com/jeedom/documentations/blob/master/fr_FR/installation/rpi.md +- **Développement de plugin** (https://doc.jeedom.com/#LANG#/dev) → https://github.com/jeedom/documentations/blob/master/fr_FR/dev/index.md -Suivant l'url sur le site de documentation, vous pouvez retrouver le fichier md correspondant. Exemples : +>**IMPORTANT** +> +>Les documentations du core et des plugins étant gérées à part, aucune contribution ne pourra être acceptée dans les dossiers `core`, `plugins` et `plugins_contributor` *(voir paragraphes suivants)*. -- Présentation -> https://github.com/jeedom/documentations/blob/master/fr_FR/presentation/index.md -- Concepts -> https://github.com/jeedom/documentations/blob/master/fr_FR/concept/index.md -- Contribuer à la documentation -> https://github.com/jeedom/documentations/blob/master/fr_FR/contribute/doc.md +## Documentation du core Jeedom -Vous pouvez donc faire des PRs (*Pull requests*) sur ces fichiers `.md`. +La documentation du core Jeedom correspond aux rubriques **Manuel d'utilisation** et **Manuel de configuration**, accessibles en cliquant sur le bouton "❔" en haut à droite sur l'interface Jeedom. Les fichiers se situent sur [le dépôt du core](https://github.com/jeedom/core/tree/develop/docs/fr_FR){:target="_blank"}, dans le répertoire `docs/fr_FR`. -Vous pouvez voir dans ce répertoire, les répertoires core, plugins, etc. Ceux-ci sont gérés automatiquement, donc inutile de faire des PRs ici (lire la suite). +Chaque page de manuel correspond à un fichier `Markdown` *(\*.md)* sur GitHub, par exemple : +- **Manuel d'utilisation - Changelog** (https://doc.jeedom.com/#LANG#/core/#VERSION#/changelog) → https://github.com/jeedom/core/tree/develop/docs/fr_FR/changelog.md +- **Manuel d'utilisation - Scénarios** (https://doc.jeedom.com/#LANG#/core/#VERSION#/scenario) → https://github.com/jeedom/core/tree/develop/docs/fr_FR/scenario.md +- **Manuel de configuration - Personnalisation Avancée** (https://doc.jeedom.com/#LANG#/core/#VERSION#/custom) → https://github.com/jeedom/core/tree/develop/docs/fr_FR/custom.md +>**IMPORTANT** +> +>Les contributions doivent être soumises sur la branche `develop` du core. -## La documentation du Core de Jeedom +## Documentation des plugins -La documentation du Core est sur le dépôt du Core, dans le répertoire doc : [https://github.com/jeedom/core/tree/alpha/docs/fr_FR](https://github.com/jeedom/core/tree/alpha/docs/fr_FR) +La documentation des plugins correspond aux rubriques **Plugins Officiels** et **Plugins Tiers**. Comme leur nom l'indique, les plugins officiels sont développés par l'équipe Jeedom, les plugins tiers étant le travail de développeurs externes et indépendants. -Pour chaque page de Jeedom, il existe un fichier page.md correspondant. - -Ce sont les pages accessibles par le (?) en haut à droite sur l'interface de votre Jeedom, et situées dans les rubriques : - -- Manuel d'utilisation -- Manuel de configuration - -Vous pouvez donc faire des PRs (*Pull requests*) sur les fichiers .md, de préférence sur la branche alpha. - - -## La documentation des plugins - -Sur le même principe que la documentation du Core, celle des plugins est récupérée automatiquement depuis le dépôt du plugin. - -Par exemple, pour le plugin OpenZWave - -- Accès à la doc ici : https://doc.jeedom.com/fr_FR/plugins/automation%20protocol/openzwave/ -- dépôt du plugin : https://github.com/jeedom/plugin-openzwave/blob/beta/docs/fr_FR/index.md - -Là il faut trouver le dépôt du plugin en question, puis aller dans son répertoire doc/fr_FR. Tout en distinguant les [plugins officiels](https://github.com/jeedom) des plugins tiers. De plus, les plugins payants (officiels ou tiers) ne sont pas accessibles, car sur des dépôt privés. Dans ce cas, vous pouvez toujours faire un message sur le [forum](https://community.jeedom.com/), avec le tag documentation-jeedom ou du plugin. - - -## Les traductions - -Les traductions sont présentes dans les autres dossiers de langues. Le répertoire `docs/i18n/` comprend des fichiers .json par langue pour la traduction des chaînes de caractères de l'interface du Core lui-même. - -Celles-ci sont générées automatiquement par un système de traduction propre à Jeedom. Il est donc inutile de faire des modifications dessus, car elle seront écrasées par le système. Si vous souhaitez améliorer les traductions, vous pouvez le signaler sur [Community](https://community.jeedom.com/). Si vous maîtrisez une des langues de Jeedom et souhaitez aller plus loin, vous pouvez demander un accès au système de traduction, qui permet de corriger toutes les traductions de chaque langue des différentes versions du Core et des plugins officiels : [contacter l'équipe du projet](mailto:contact@jeedom.com). - -Dans le code vous pouvez spécifier des chaînes à traduire comme cela : - -En PHP : `$myString = __('Ma phrase qui sera traduite', __FILE__);` - -En JavaScript : ``{% raw %}var myString = '{{Ma phrase qui sera traduite}}'{% endraw %}`` - -Le système de traduction se chargera alors de leur traduction et de leur référencement dans les fichiers json (`docs/i18n/`) et le Core de leur remplacement dans l'interface. - -Si vous souhaitez faire un lien vers une autre page de documentation, vous pouvez ajouter `/fr_FR/contribute/doc`. A la traduction, la partie fr_FR sera automatiquement adaptée. +Comme le core Jeedom, la documentation de chaque plugin est récupérée depuis son dépôt GitHub. Prenons **le plugin ZwaveJS** par exemple : +- **Changelog** (https://doc.jeedom.com/#LANG#/plugins/automation%20protocol/zwavejs/beta/changelog) → https://github.com/jeedom/plugin-zwavejs/blob/beta/docs/fr_FR/changelog.md +- **Documentation** (https://doc.jeedom.com/#LANG#/plugins/automation%20protocol/zwavejs/beta/) → https://github.com/jeedom/plugin-zwavejs/blob/beta/docs/fr_FR/index.md +>**INFORMATION** +> +>Certains dépôts de plugins ne sont pas accessibles publiquement. Dans ce cas, vous pouvez toujours contribuer en créant un sujet sur [le forum](https://community.jeedom.com/c/plugins/46){:target="_blank"} avec l'étiquette `documentation-jeedom` et celle du plugin concerné. +>**IMPORTANT** +> +>Les contributions doivent être soumises sur la branche `beta` des plugins. diff --git a/fr_FR/dev/core.md b/fr_FR/dev/core.md new file mode 100644 index 00000000000..7e188d8749f --- /dev/null +++ b/fr_FR/dev/core.md @@ -0,0 +1,245 @@ +# Développement du core + +## Arborescence + +Le code est réparti dans différents répertoires à la racine de Jeedom *(`/var/www/html` par défaut)* : + +- **3rdparty** : Dossier comprenant les bibliothèques externes utilisées par Jeedom *(jQuery, CodeMirror, etc)*. +- **backup** : Dossier des sauvegardes de Jeedom. +- **core** : Dossier comprenant les fonctions internes du Core: + - **ajax** : Fichiers php d'interface entre les classes js et les classes php. + - **api** : Fichiers php des API. + - **class** : Fichiers des classes php *(eqLogic, cmd, jeeObject, history, cron, etc.)*. + - **com** : Fichiers des classes php de communication *(http, shell)*. + - **config** : Fichiers php de configuration du Core et *default.config.ini* comprenant les paramètres de configuration par défaut. Fichier version pour la version du Core. + - **css** : Icônes disponibles avec le Core et leur CSS. + - **i18n** : Fichiers json comprenant les chaînes de caractères traduites. + - **img** : Images (logos, fonds, etc.) du Core. + - **js** : Fichiers des class js, appelées notamment depuis les pages de Jeedom. + - **php** : Fichiers php nécessaires au Core (hors classes). + - **repo** : Fichiers php propres au market, samba, etc. + - **template** : Fichiers html *(Dashboard et Mobile)* pour l'affichage des eqLogics (Tuile), commandes (Widgets) et scenarios. + - **themes** : Fichiers CSS des trois thèmes du Core (Dark, Light, Legacy), pour Dashboard et Mobile. +- **data** : Dossier comprenant les données utilisateur (Rapports, Vues, css/js de Personnalisation Avancée, Design 3D, etc). +- **desktop** : Dossier comprenant toutes les pages affichées (l'interface) en desktop et leurs fonctions. + - **common** : Fichiers js/php communs à plusieurs pages. Regroupe des fonctions pouvant être appelées depuis plusieurs pages, notamment le *utils.js*, présent sur toutes les pages en Desktop. + - **css** : Fichiers css propres à l'affichage Desktop. + - **img** : Images propres à l'affichage Desktop. + - **js** : Fichiers js correspondant à chaque page *(administration, dashboard, scenario, etc.)*. + - **modal** : Fichiers php des modales, comprenant le code php/html et le code js. + - **php** : Fichiers php correspondant à chaque page *(administration, dashboard, scenario, etc.)*. +- **docs** : Documentation. +- **install** : Fichiers d'installation de Jeedom. +- **log** : Dossier comprenant tous les logs (http.error, update, etc) et ceux des scénarios (sous-dossier scenarioLog, nommés par id). +- **mobile** : Dossier comprenant toutes les pages affichées (l'interface webapp) en mobile et leurs fonctions. + - **css** : Fichiers css propres à l'affichage Mobile. + - **html** : Fichiers html correspondant à chaque page *(home, equipment, timeline, etc.)*. + - **js** : Fichiers js correspondant à chaque page *(home, equipment, timeline, etc.)*. + - **modal** : Fichiers html correspondant aux modales en Mobile. +- **plugins** : Dossier comprenant tous les plugins installés. +- **script** : Script de déploiement, certificats. +- **support** : Dossier utilisé en cas de demande de support. +- **vendor** : Dossier comprenant des bibliothèques tierces php. + +## Front-end + +L'interface de Jeedom fonctionne comme un site web, à partir de php interfacé avec SQL et de js / CSS. + +Au départ, le browser charge le fichier `/index.php` : +- Vérification de l'installation de Jeedom, renvoi vers `install/setup.php` si nécessaire. +- Vérification de la provenance Desktop ou Mobile. +- Chargement des fichiers et classes nécessaires avec `/core/php/core.inc.php`. +- Vérification de l'authentification de l'utilisateur. +- Vérification de paramètres dans l'url pour charger directement le bon contenu. +- Redirige vers la version Desktop `/desktop/php/index.php` ou Mobile `mobile/html/home.html` en fonction des paramètres de l'url. + +### Desktop + +L'interface de Jeedom fonctionne sur le principe du One-Page. Une fois chargée, les différentes pages sont affichées en changeant le contenu d'un container. + +Le fichier principal en Desktop est `/desktop/php/index.php`. + +Chaque page possède au minimum deux paramètres dans l'url. Exemple : + +`https://my.dns1.jeedom.com/index.php?v=d&p=dashboard` : +- **v** : Version de l'interface : `d` pour Desktop, `m` pour mobile. +- **p** : Page à afficher. Ici, `dashboard`. + +Dans ce cas, le fichier `/desktop/php/index.php` va charger le fichier `/desktop/php/dashboard.php` dans la div `div_pageContainer`. Celui-ci va également charger le fichier `/desktop/js/dashboard.js` comprenant les fonctions js propres à l'affichage de cette page (ici, le Dashboard). + +Le fichier `/desktop/php/index.php` se charge aussi de : +- Vérifier le mode *rescue* +- Vérifier l'authentification de l'utilisateur. +- Vérifier si nécessaire la page à charger en fonction de la configuration (page par défaut de l'utilisateur). +- Créer la structure html *(head, body, div_pageContainer, etc)*. +- Charger les CSS, bibliothèques etc. +- Charger le thème de l’utilisateur. +- Créer la barre de menu. +- Renseigner certaines variables php/js globales. +- Charger le fichier js `desktop/common/js/utils.js` + +Le fichier `desktop/common/js/utils.js` est donc toujours présent, et chargé une fois. Il permet de : +- Gérer les events js du menu. +- Gérer les paramètres d'url en fonction de la page demandée. +- Charger la page demandée dans la div `div_pageContainer`. +- Gérer les ouverture/fermeture des modales (fenêtre de dialogue). +- Gérer une éventuelle bascule de thème en fonction de l'heure. +- Permettre aux différents fichiers js d'accéder à des fonctions communes. + +Ainsi, les fichiers index.php et utils.js fournissent la structure et les fonctions de base de l'interface. +Ensuite, le contenu de la page appelée est chargé depuis desktop/php/page.php et desktop/js/page.js. +Ces fichiers de contenu, purement orientés interface, peuvent accéder aux fonctions du Core (les classes `/core/class`) directement en php, ou en js grâce aux classes js (`/core/js`) en passant par des appels ajax (`/core/ajax`). + +Les fonctions internes du Core sont ainsi bien séparées, pour le fonctionnement interne (Back-end), mais sont accessibles par l'interface. De même, chaque page possède sont propre code php et js. Ceci permet de mieux faire évoluer et maintenir le code, mais aussi d'optimiser les performances en chargeant uniquement les classes et fonctions nécessaires. + +#### Core v4.2 +Depuis le Core v4.2, toutes les fonctions js du fichier `desktop/common/js/utils.js` sont isolées dans un namespace `jeedomUtils{}`. +Par exemple, la fonction précédemment dans le root window `loadPage()` devient `jeedomUtils.loadPage()`. + +Pour des raisons de rétro-compatibilité pour les plugins, les anciennes fonctions sont toujours déclarées et seront dépréciées dans une version ultérieure. [Voir la liste ici](https://github.com/jeedom/core/blob/alpha/desktop/common/js/utils.js#L1423). + +#### Core v4.3 +Dans la continuité de la version 4.2, les pages du front-end en desktop on été isolées afin d'éviter de référencer des variables et fonctions dans le root window. Ceci sécurise de possible collision de déclaration et facilite la lecture et la compréhension du code ainsi que son debuggage. + +Le fichier `core/js/jeedom.class.js`déclare deux nouveaux namespaces : +##### jeeFrontEnd + +Certaines variables globales sont maintenant dans ce namespace : + +```js +jeeFrontEnd = { + __description: 'Global object where each Core page register its own functions and variable in its sub-object name.', + jeedom_firstUse: '', + language: '', + userProfils: {}, + planEditOption: {state: false, snap: false, grid: false, gridSize: false, highlight: true}, + //loadPage history: + PREVIOUS_PAGE: null, + PREVIOUS_LOCATION: null, + NO_POPSTAT: false, + modifyWithoutSave: false, + //@index.php + serverDatetime: null, + clientServerDiffDatetime: null, + serverDatetime: null, + serverTZoffsetMin: null, +} +``` + +Exemple type pour `desktop/js/corepage.js` : + +```js +"use strict" + +if (!jeeFrontEnd.corepage) { + jeeFrontEnd.corepage = { + myVar: 'oneVar', + init: function() { + window.jeeP = this //root shortcut + }, + postInit: function() { + //Do stuff once page loaded + }, + myFunction: function(_var) { + var myFuncContextVar = this.myVar + ' -> ' + _var + console.log(myFuncContextVar) + } + } +} + +jeeFrontEnd.corepage.init() + +$(function() { + jeeFrontEnd.corepage.postInit() +}) + +$('#myButton').on('click', function() { + jeeP.myFunction('test') +}) +``` + +> Le namespace de la page ne sera donc pas recréé au retour sur cette même page. De plus, la variable `jeeP` permet d'utiliser `jeeFrontEnd.corepage` avec une syntaxe courte, elle correspond à un `self` propre à la page. + +##### jeephp2js + +Utilisé pour passer les variables d'un script php vers le front-end js. Par exemple : + +```php +sendVarToJS([ + 'jeephp2js.myjsvar1' => init('type', ''), + 'jeephp2js.myjsvar2' => config::byKey('enableCustomCss') +]); +``` + +Puis + +```js +$(function() { + if (jeephp2js.myjsvar1 == '1') { ... } +}) +``` + +> Le namespace jeephp2js{} est vidé au changement de page pour éviter toute variable résiduelle non attendue. + +### Mobile + +L'interface Desktop est responsive et s'adapte à la taille du navigateur. Toutefois, certaines choses, comme l'édition d'un scénario, seraient compliquées sur un petit écran. De plus, sur un smartphone à l’extérieur, en 3G ou même 4G, il est important d'optimiser la rapidité de l'affichage. C'est pourquoi Jeedom possède une interface Mobile, plus légère et adaptée aux petits écrans. + +La page de référence est `/mobile/html/index.html`, qui se charge de : +- Vérifier l'authentification de l'utilisateur. +- Créer la structure html *(head, body, div_pageContainer, etc)*. +- Charger les CSS, bibliothèques etc. +- Charger le thème de l’utilisateur. +- Renseigner certaines variables php/js globales. +- Charger le fichier js `mobile/js/application.js` + +Le fichier `mobile/js/application.js` contient les fonctions communes à toutes les pages. + +Comme pour l'interface Desktop, la page appelée est constituée de deux fichiers : +- `/mobile/html/home.html` : le code html. +- `/mobile/js/home.js` : les fonctions js propres à cette page. + +Une différence notable en Mobile est l'absence de pages php. La génération du code repose donc sur les classes js, qui peuvent toujours appeler les fonctions du Core avec des appels ajax. + +### Fichiers CSS + +Les CSS du Core reposent principalement sur ces fichiers : +- En Desktop : + - `desktop/css/boostrap.css` : Version nettoyée par l'équipe du CSS Bootstrap v3.3.7. + - `desktop/css/desktop.main.css` : CSS principal de l'interface. + - `desktop/css/coreWidgets.css` : CSS propres aux widgets du Core. + +- En Mobile : + - `mobile/css/mobile.main.css` : CSS principal de l'interface. + - `mobile/css/coreWidgets.css` : CSS propres aux widgets du Core. + +Les thèmes contiennent des CSS propres à chaque thème, notamment les colors.css. + +Ordre de chargement des CSS en Desktop : +- 3rdParty css (CodeMirror, etc.). +- Fonts (roboto, camingocode, text-security-disc). +- coreWidgets.css +- desktop.main.css +- colors.css (variables de couleurs du thème). +- core2019_xx.css (fichier principal du thème). +- shadows.css (si activé en configuration). +- custom.css (fichier css de personnalisation avancée). + + +## Back-end + +*en cours* + +L'interface est une chose, mais bien sûr votre Jeedom est toujours actif, afin de faire tourner les scénarios, les crons, les logs, les historiques etc. + +Le Back-end s’appuie sur les mêmes classes php que le Front-end, présentes dans `/core/class/`. Chaque partie de Jeedom possède sa classe php, notamment : + +- `jeeObject.class.php` : Regroupe les fonctions concernant les objets de Jeedom. +- `eqLogic.class.php` : Regroupe les fonctions concernant les équipements de Jeedom. +- `cmd.class.php` : Regroupe les fonctions concernant les commandes de Jeedom. +- `cron.class.php` : Regroupe les fonctions concernant les tâches planifiées de Jeedom. +- `config.class.php` : Regroupe les fonctions concernant les paramètres de configuration de Jeedom. +- `scenario.class.php` : Regroupe les fonctions concernant les scénarios de Jeedom. +- `DB.class.php` : Regroupe toutes les fonctions d'accès à la base de données de Jeedom. Tous les accès SQL requis par les autres classes sont gérés par celle-ci. + +etc. diff --git a/js/init.js b/js/init.js index 8d7301a863e..9c5a17f8465 100644 --- a/js/init.js +++ b/js/init.js @@ -129,11 +129,11 @@ var docMenu = [ { link: "/#LANG#/plugins/other/", icon: "fas fa-bars", fr_FR: "Autre", en_US: "Other", es_ES: "Otros", de_DE: "Andere", pt_PT: "" }, ] }, { - fr_FR: "Plugins Contributeurs", - en_US: "Contributor Plugins", - es_ES: "Plugins Contribuidor", - de_DE: "Mitwirkende Plugins", - pt_PT: "Plugins Colaboradores", + fr_FR: "Plugins Tiers", + en_US: "Third-Party Plugins", + es_ES: "Plugins de Terceros", + de_DE: "Plugins von Drittanbietern", + pt_PT: "Plugins de Terceiros", submenu: [ { link: "/#LANG#/plugins_contributor/security/", icon: "fas fa-lock", fr_FR: "Sécurité", en_US: "Security", es_ES: "Sécurité", de_DE: "Sicherheit", pt_PT: "" }, { link: "/#LANG#/plugins_contributor/automation%20protocol/", icon: "fas fa-rss", fr_FR: "Protocole domotique", en_US: "Home protocol", es_ES: "Protocolo de domótica", de_DE: "Hausautomationsprotokoll", pt_PT: "" }, @@ -167,12 +167,16 @@ var docMenu = [ }, { divider: true }, { - fr_FR: "Beta / Alpha", - en_US: "Beta / Alpha", - es_ES: "Beta / Alpha", - de_DE: "Beta / Alpha", - pt_PT: "Beta / Alpha", - link: "/#LANG#/beta/" + fr_FR: 'Contributeurs', + en_US: 'Contributors', + es_ES: "Colaboradores", + de_DE: "Mitwirkende", + pt_PT: "Contribuidores", + submenu: [ + { link: "/#LANG#/beta/", fr_FR: "Bêta-Test", en_US: "Beta Test", es_ES: "Prueba Beta", de_DE: "Beta-Test", pt_PT: "Teste Beta" }, + { link: "/#LANG#/contribute/doc", fr_FR: "Documentation", en_US: "Documentation", es_ES: "Documentación", de_DE: "Dokumentation", pt_PT: "Documentação" }, + { link: "/#LANG#/contribute/core", fr_FR: "Core & Plugins", en_US: "Core & Plugins", es_ES: "Core & Plugins", de_DE: "Core & Plugins", pt_PT: "Core & Plugins" } + ] }, { fr_FR: 'Développeurs', en_US: 'Developers', @@ -180,8 +184,8 @@ var docMenu = [ de_DE: "Entwickler", pt_PT: "Desenvolvedores", submenu: [ - { link: "/#LANG#/contribute/", fr_FR: "Contribuer", en_US: "Contribute", es_ES: "Contribuir", de_DE: "Bijdragen", pt_PT: "Contribuir" }, { link: "/#LANG#/dev/", fr_FR: "Plugins", en_US: "Plugins", es_ES: "Complementos", de_DE: "Plugins", pt_PT: "Plugins" }, + { link: "/#LANG#/dev/core", fr_FR: "Core", en_US: "Core", es_ES: "Core", de_DE: "Core", pt_PT: "Core" }, { link: "/#LANG#/core/#VERSION#/api_http", fr_FR: "Api HTTP", en_US: "Api HTTP", es_ES: "Api HTTP", de_DE: "Api HTTP", pt_PT: "Api HTTP" }, { link: "/#LANG#/core/#VERSION#/jsonrpc_api", fr_FR: "API JsonRPC", en_US: "API JsonRPC", es_ES: "API JsonRPC", de_DE: "API JsonRPC", pt_PT: "API JsonRPC" }, { link: "/dev/phpdoc/#VERSION#", fr_FR: "PhpDoc", en_US: "PhpDoc", es_ES: "PhpDoc", de_DE: "PhpDoc", pt_PT: "PhpDoc" },