HapplyNotif Client

Client javascript pour consommer l'API de HapplyNotif

⚠️ Attention ⚠️ La documentation est écrite pour une utilisation avec Symfony mais est compatible avec n'importe quel projet.

Utilisation

Installation

L'utilisation de la librairie se veux le plus simple possible. Installez la avec

npm install @alpeshabitat/happlynotif-client

Utilisation

Importez le client dans votre fichier JavaScript ainsi que le css qui l'accompagne

import '@alpeshabitat/happlynotif-client/dist/style.css'

import HapplyNotifClient from '@alpeshabitat/happlynotif-client'

Il faut ensuite l'activer

const happlyNotif = new HapplyNotifClient()

On peut également passer un objet de configuration pour modifier certains paramètres si besoin. Voici les valeurs par défaut et leur utilité.

const happlyNotif = new HapplyNotifClient({
    debug: false, // Active le mode debug qui affiche les erreurs et des informations de coinfiguration supplémentaires
    apiUrl: undefined, // Base url de l'API
    applicationName: undefined, // slug de l'application (pour contruire l'url de l'API)
    notificationsIcon: undefined // Icone à utiliser pour les notification. Prévu pour être utilisé avec des balises <svg> ou <i>. ex: '<i class="fas fa-bullhorn"></i>'
})

On va ensuite pouvoir activer les fonctionnalités de notifications et de changelogs séparément.

const happlyNotif = new HapplyNotifClient()

happynotif.initNotifications()
happynotif.initChangelogs()

Par défaut, le client s'attend a trouver des conteneurs avec les id happly-notif-notifications-container et happly-notif-changelogs-container pour afficher les notifications et les changelogs. Si vous souhaitez changer ces id, vous pouvez passer des selecteurs css en paramètre des fonctions d'initialisation.

happynotif.initNotifications('#my-notifications-container') // par défaut : #happly-notif-notifications-container
happynotif.initChangelogs('#my-changelogs-container') // par défaut : #happly-notif-changelogs-container

Configuration

Il faut ensuite configurer le client pour qu'il puisse communiquer avec l'API. Pour cela, On va passer par des 'data attributes' sur un élément html de la page.

Il est également possible de les configurer sur le conteneur de notif/de changelogs, plus d'informations dans la section Autre méthode de configuration

```html
<div id="happly-notif-params" data-api-url="https://myurl.fr/api" data-application-name="my-application" data-api-key="my-api-key"></div>

Dans le cas d'une utilisation avecc symfony, on va passer par des variables d'environnements pour configurer le client.

Il faut d'abord ajouter les variables d'environnement dans votre fichier .env

###> HapplyNotif ###
HAPPLYNOTIF_API_KEY="my-api-key"
HAPPLYNOTIF_API_URL="http://myapi.com/api"
HAPPLYNOTIF_APPLICATION="my-app"
###< HapplyNotif ###

Puis, dans votre fichier de config twig.yaml, il faut ajouter les données utilisées ci-dessus.

twig:
    globals:
        happly_notif_api_key: '%env(HAPPLYNOTIF_API_KEY)%'
        happly_notif_api_url: '%env(HAPPLYNOTIF_API_URL)%'
        happly_notif_application: '%env(HAPPLYNOTIF_APPLICATION)%'

Enfin, dans votre fichier twig de base, il faut ajouter les data attributes sur l'élément html qui contient les variables d'environnement.

<span 
    id="happly-notif-params" 
    data-api-url="{{happly_notif_api_url}}" 
    data-application-name="{{happly_notif_application}}" 
    data-api-key="{{happly_notif_api_key}}"
>
</span>

Les données sont récupérées depuis ce span et sont utilisées pour l'initialisation de la librairie.

Affichage

Pour afficher les notifications, il faut ajouter un conteneur html avec l'id happly-notif-notifications-container dans votre page.

<div id="happly-notif-notifications-container"></div>

Même chose pour les changelogs.

<div id="happly-notif-changelogs-container"></div>

Autre méthode de configuration

Il est également possible de configurer les parametres du client directement sur le conteneur, pratique si vous n'utilisez que les changelogs ou que les notifications.

<div id="happly-notif-notifications-container" data-api-url="{{happly_notif_api_key}}" data-application-name="{{happly_notif_application}}" data-api-key="{{happly_notif_api_key}}"></div>

Si vous utilisez cette méthode avec les changelogs et les notifications en même temps, il est nécessaire que la première initialisation concerne le conteneur qui porte ces atrtibuts. On aurait par exemple:

happynotif.initNotifications() // premiere initialisation sur les *notifications*
happynotif.initChangelogs()

<!-- conteneur des *notifications* portant les attributs de config -->
<div 
    id="happly-notif-notifications-container" 
    data-api-url="{{happly_notif_api_key}}" 
    data-application-name="{{happly_notif_application}}" 
    data-api-key="{{happly_notif_api_key}}">
</div> 

<div id="happly-notif-changelogs-container"></div>

Et c'est tout, le client va se charger de récupérer les notifications et les changelogs et de les afficher dans les conteneurs.

👾 Environnement de développement

🏁 Pré-requis

• NPM/Nodejs

🤝 Contribuer au projet

Dans le dossier du projet Lancer la commande

npm install

Il est possible de tester facilement le paquet en l'installant dans un autre projet avec la commande

npm install /chemin/complet/vers/le/dossier

Les changements s'appliqueront en temps réel (après avoir fait un npm run build)

📃 Règles de codage

• Le projet utilise une configuration prettier disponible dans le fichier prettierrc, il faut donc installer l'extension Prettier sur VsCode
• Indentation = 4 espaces

🔍 Merge Request

Les "Merges Requests" sont les bienvenues.

Pour les changements majeurs, veuillez en discuter avec le reste de l'équipe.

Merci de ne jamais travailler directement dans la branche main.

🏛 Code de Conduite

Dans l'intérêt de favoriser un environnement ouvert et accueillant, nous nous engageons à faire de la participation à ce projet une expérience exempte de harcèlement pour tout le monde, quel que soit le niveau d'expérience, le sexe, l'identité ou l'expression de genre, l'orientation sexuelle, le handicap, l'apparence personnelle, la taille physique, l'origine ethnique, l'âge, la religion ou la nationalité.