MAJ doc widgets JS (108cb6a9) · Commits · lib / unicaen / app

doc/Widgets.md

+3 −489

Original line number	Diff line number	Diff line
		@@ -94,494 +94,8 @@ Exemple de vue contenant le lien à ouvrir :
		</script>
		```

		AjaxPopover : Utilisation de base
		=================================

		\<WRAP center round alert 60%\> Ce widget est déprécié et ne sera
		bientôt plus maintenu! Un nouveau widget, plus complet, le remplace :
		[PopAjax](/develop/unicaen2/moduleunicaenunicaenapp/viewhelpers/PopAjax)
		\</WRAP\>

		Le Popover de Bootstrap (<http://getbootstrap.com/javascript/#popovers>)
		permet d\'afficher des informations sur un élément donné.

		Le rôle de l\'AjaxPopover est de transformer un lien de type ancre
		(élément a) en popover. Concrètement, lorsqu\'on clique sur ce lien, le
		popover s\'affiche avec, en contenu, la page ciblée par l\'attribut href
		du lien. Ce mécanisme s\'apppuie sur Ajax.

		Si le code retourné comporte un formulaire, alors ce dernier est
		également géré par l\'AjaxPopover.

		Pour signaler qu\'un lien doit aboutir à l\'ouverture d\'un Popover, il
		suffit de lui affecter la classe \"ajax-popover\".

		Voici un exemple de popover :

		``` {.html}
		<a href="/application/lien/vers/formulaire" class="ajax-popover event_save-popover-form">TEST</a>
		```

		Usage avancé
		============

		Un événement est émis par l\'AjaxPopover lorsqu\'un formulaire est
		soumis et que son résultat ne retourne aucune erreur. Il est donc
		possible de capturer cet événement pour effectuer diverses actions, par
		exemple fermer le popover.

		Voici, en Javascript, un exemple de capture d\'événement :

		``` {.javascript}
		$(document).ready(function() {

		$("body").on('save-popover-form', function(event,data){
		/*

		event comporte deux propriétés :
		- event.a : objet Jquery du lien.
		Il permet d'accéder au lien source du popover pour y récupérer, par exemple,
		des données ou pour accéder au popover pour le fermer, par exemple.

		- event.div : élément conteneur du popover. Utile pour modifier le contenu par exemple.

		data contient les données du formulaire posté

		*/

		event.a.popover('hide'); // on ferme le popover
		});

		});
		```

		\<WRAP center round tip 60%\> L\'événement \"save-popover-form\" sera
		généré sur le ou les liens disposant de la classe
		\"event\_save-popover-form\". Après \"event\_\", vous êtes libre de
		nommer l\'événement comme bon vous semble. \</WRAP\>

		TabAjax
		=======

		Cette aide de ue sert à dessiner des listes d\'onglets avec contenu
		chargé statiquement et/ou dynamiquement. Il est possible de mélanger des
		onglets dynamiques et d\'autres statiques.

		Usage simple (dans une vue phtml):

		``` {.php}

		echo $this->tabajax([
		[
		'id' => 'fiche',
		'label' => 'Fiche',
		'content' => 'Ceci est le contenu de la fiche descriptive',
		],
		[
		'id' => 'détails',
		'label' => 'Détails',
		'url' => $this->url('fiche/details', ['fiche' => 1245]),
		],
		]);

		```

		Ici, le premier onglet (Fiche) a un contenu statique. Le deuxième onglet
		reçoit une URL, qui sera exploitée le moment venu pour charger son
		contenu en AJAX. Les ID permettent de nommer les onglets pour les
		exploiter ensuite en JS si besoin.\
		`label`{.php} est le nom affiché sur l\'onglet.\
		`content`{.php} le contenu de l\'onglet (si pré-chargé).

		Événement \"loaded\"
		--------------------

		Il est déclenché lorsqu\'un onglet AJAX a terminé son chargement :

		``` {.javascript}
		$(function(){
		$('#zozo').tabAjax({
		'loaded': function( event, tab ){
		//console.log(event);
		console.log(tab);
		}
		});

		});
		```

		Chargement d\'un onglet à la demande
		------------------------------------

		``` {.javascript}
		$(function(){
		$('#zozo').tabAjax('select', 'onglet-general');
		});
		```

		PopAjax
		=======

		PopAjax est un \"popover\" reprenant le popover de Bootstrap et
		compatible Ajax. C\'est un Widget conçu avec le Widget Factory de
		JQueryUI (inclus dans UnicaenApp).

		Il propose :

		- de charger éventuellement son contenu en Ajax à partir d\'une URL
		- de créer simplement une DIV et de le paramétrer en lui passant des
		attributs data\*.
		- de pouvoir l\'instancier en Javascript comme n\'importe quel widget
		JQuery
		- un système d\'événements permettant de fermer le popover, de
		recharger la page ou de lancer l\'événement de votre choix si le
		formulaire inclus
		- de personnaliser plein de paramètres (où il s\'affiche, quel message
		d\'attente, etc.
		- si besoin, un popajax peut être appelé depuis un autre popajax et
		ainsi de suite sans limites.
		- quand on clique hors du popover, il se ferme tout seul.
		- un système de boite de dialogue de confirmation (avec possibilité
		d\'ajouter des éléments de formulaire au besoin)

		Voici ce que ça donne :
		![](/develop/unicaen2/moduleunicaenunicaenapp/viewhelpers/popajax.png)

		Exemples :
		----------

		``` {.html}
		<!-- Le fait de préciser que le lien est de classe popajax suffit!!! data-submit-close fermera le popAjax dès qu'un formulaire sera posté -->
		<a href="<?php echo $url ?>" class="pop-ajax" data-submit-close="true">Lien 1</a>

		<!-- Ca marche aussi avec un bouton mais il faut lui préciser l'URL de chargement en passant par un attribut du dataset-->
		<button type="button" class="pop-ajax" data-url="http://www.google.com">Mon bouton</button>

		<!-- Exemple avec un événement -->
		<a href="<?php echo $url ?>" class="pop-ajax" data-submit-event="mon-formulaire-enregistre">Lien 1</a>
		<script>

		$("body").on("mon-formulaire-enregistre", function (event, popAjax)
		{
		console.log(popAjax); // affiche en console votre objet popajax
		});

		</script>
		```

		En bref
		-------

		### Gestion des titres

		Le titre du popajax peut être adapté au contenu retourné par la requête
		AJAX : Si le code HTMl contient :

		- un titre h1
		- ou un élément de classe .popover-title
		- ou un élément de classe .page-header

		alors cet élément sera supprimé du contenu du popover et son contenu
		sera injecté dans la partie titre du popover.

		Si aucun titre n\'est disponible alors la zone de titre disparaît.

		### Boites de dialogue de confirmation

		PopAjax vous permet de réaliser simplement des boites de dialogue de
		confirmation.

		Exemple :

		``` {.html}
		<a
		class="pop-ajax"
		href="<?php echo $url ?>"
		data-content="Voulez-vous vraiement faire cela <input name='t1' value='t1' /> ?"
		data-confirm="true"
		>Confirm</a>
		```

		Dans ce cas, le texte est posé au départ et l\'URL ne sera appelée que
		lorsque le bouton de confirmation sera cliqué. J\'ai même ajouté un
		input dont la valeur sera récupérable dans les données POST de l\'action
		pour montrer que c\'est possible.

		Il est même possible de ne pas fournir de contenu de de le charger en
		AJAX si besoin. Attention dans votre action de contrôleur de bien
		distinguer dans ce cas la demande (méthode GET) de l\'action (méthode
		POST).

		Si vous ne souhaitez rien renvoyer de spécial hormis des messages
		informatifs, le modèle de vue
		`UnicaenApp\View\Model\MessengerViewModel`{.php} vous aidera à ne
		renvoyer que les messages collectés dans votre action sans avoir à créer
		de vue spécifique pour cela.

		Exemple côté PHP (dans une action de contrôleur):

		``` {.php}

		if ($this->getRequest()->isPost()){
		try{
		$this->getVotreService()->faireVotretravail();
		$this->flashMessenger()->addSuccessMessage("Tout est OK.");
		}catch(\Exception $e){
		$this->flashMessenger()->addErrorMessage($e->getMessage());
		}
		}else{
		$this->flashMessenger()->addErrorMessage('Vous devez d\'abord confirmer.');
		}

		return new \UnicaenApp\View\Model\MessengerViewModel();

		```

		### Bouton de fermeture

		Le clic sur tout élément ayant pour classe \"pop-ajax-hide\" engendrera
		la fermeture du popAjax.

		Options
		-------

		Nom (dataset) Nom (Json) Type Valeur par défaut Description
		----------------- ---------------- --------- ---------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
		url url string undefined ou href (si présent) URL de chargement de la page AJAX
		content content string undefined contenu (en HTML). si défini alors le chargement ne se fait plus à partir de l\'URL (plus d\'AJAX à l\'affichage)\...
		animation animation boolean true Détermine si une animation doit se faire quand le popover apparaît ou disparait
		delay delay integer 200 Délai de l\'animation
		placement placement string auto Placement. Valeurs possibles (par ordre de priorité) : auto, bottom, top, left, right. Si auto est déterminé alors le placement le plus judicieux sera calculé automatiquement
		submit-event submitEvent string undefined nom d\'un événement à transmettre. L\'événement sera lancé si un formulaire est posté à l\'intérieur du popover ET que le résultat ne contient aucune erreur
		submit-close submitClose boolean false Détermine on doit fermer le popover après le post d\'un formulaire sans retour d\'erreur
		submit-reload submitReload boolean false Détermine on doit recharger toute la page après le post d\'un formulaire sans retour d\'erreur
		min-width minWidth string 100px largeur minimale du popover
		max-width maxWidth string 600px largeur maximale du popover
		min-height minHeight string 50px hauteur minimale du popover
		max-height maxHeight string none hauteur maximale du popover (si le contenu dépasse alors un ascenseur apparaîtra)
		loading-title loadingTitle string Chargement\... Titre lorsque le popover est en cours de chargement
		loading-content loadingContent string <div class="loading"></div> Contenu lorsque le popover est en cours de chargement
		title title string undefined Titre à afficher si le contenu issu de la requête ne contient aucun titre à afficher
		confirm confirm boolean false transforme le popajax en boite de dialogue de confirmation
		confirm-button confirmButton string <span class="glyphicon glyphicon-ok"></span> OK Texte du bouton de confirmation (si vous fournissez un texte volontairement vide alors le bouton n\'apparaitra pas)
		cancel-button cancelButton string <span class="glyphicon glyphicon-remove"></span> Annuler Texte du bouton d\'annulation (si vous fournissez un texte volontairement vide alors le bouton n\'apparaitra pas)
		auto-show autoShow boolean false Affichage du popover dès son initialisation (sans attendre le click). utile si le popover est instancié en JS directement

		Événements
		----------

		Les événements permettent de réagir à des changements d\'état. Les
		closures ou les fonctions qui seront appelées se verront transmettre
		deux arguments :

		1. l\'événement en lui-même
		2. l\'objet popajax (ce qui permet de le manipuler ou de récupérer son
		contenu (méthode getContent), etc.

		Exemple d\'utilisation d\'événement :

		``` {.html}
		<!-- Ici, le widget est associé à l'élément a directement en Javascript et pas en passant par la classe popajax. Le titre est également transmis par le tableau JSON des options, de même que la closure pour l'événement show -->
		<a id="popajax_1" href="<?php echo $url ?>">TEST</a>
		<script>

		$(function(){

		$('#popajax_1').popAjax({title: 'Mon Titre', show: function(event, popAjax){
		console.log('show');
		console.log(event);
		console.log(popAjax);
		}});

		});

		</script>

		```

		### Liste des événements

		Événement Description
		----------- ------------------------------------------------------------------------------
		show se déclenche à l\'affichage du popajax
		hide se déclenche à la fermeture du popajax
		change lorsqu\'un changement de contenu est détecté
		submit lorsqu\'un formulaire a été posté et que le retour ne comporte aucune erreur

		Méthodes
		--------

		Popajax comporte un certain nombre de méthodes :

		Nom Arguments Valeur de retour Description
		----------------- ----------- ----------------------------- -----------------------------------------------------------------------------------------------------------
		showHide Aucun this Permet d\'afficher le popover s\'il n\'est pas affiché ou de le masquer s\'il est affiché.
		shown Aucun boolean Retourne true s\'il est affiché, false sinon
		show Aucun this Affiche le popover
		hide Aucun this Masque le popover
		errorsInContent Aucun boolean Retourne true si un ou plusieurs messages d\'alerte de danger ou d\'erreur sont affichés dans son contenu
		posPop Aucun this Repositionne le popover
		getContent Aucun element Jquery ou undefined Retourne l\'élément qui contient le texte du popover
		setContent string this Permet de peupler le contenu du popover

		Instadia
		========

		Instadia est un système de messagerie instantanée persistant contextuel.
		Cela signifie que :

		- Les messages sont stockés en base de données
		- Chaque fil de messagerie peut être lié à un contexte particulier.
		- Il est possible de dialoguer en temps réel avec des interlocuteurs.
		- Les messages restent visibles sans pouvoir être effecés

		Instadia peut être intégré très simplement au coeur d\'une application
		pour, par exemple, suivre un dossier ou commenter tel ou tel item.

		L\'intérêt est que :

		- les informations de suivi sont visibles dans leur contexte. Il n\'y
		a pas besoin d\'aller chercher l\'historique d\'une conversation
		dans sa boite mail.
		- les informations sont PARTAGÉES. Un nouvel utilisateur peut voir ce
		qui c\'est dit précédemment

		\<WRAP center round important 60%\> Dans Instadia, chaque fil de
		conversation correspond à une rubrique et éventuellement à une
		sous-rubrique. Par exemple dans Uniform nous avons une rubrique
		formation pour signaler qu\'on parle de formation, et une sous-rubrique
		par code de formation. Ainsi nous avons bien un fil de discussion par
		formation. \</WRAP\>

		Instadia est intégré à UnicaenApp. Les préresuis pour l\'utiliser sont
		les suivants :

		- votre application doit reposer sur une base de données
		- vous devez utiliser UnicaenAuth (uniquement si vous voulez
		authentifier vos utilisateurs)
		- une table, nommée instadia, doit être créée. Vous en trouverez la
		structure ci-dessous (code pour Oracle):

		``` {.sql}
		CREATE
		TABLE INSTADIA
		(
		ID NUMBER (*,0) NOT NULL ,
		USER_ID NUMBER (*,0) ,
		RUBRIQUE VARCHAR2 (80 CHAR) NOT NULL ,
		SOUS_RUBRIQUE VARCHAR2 (80 CHAR) ,
		HORODATAGE DATE NOT NULL ,
		CONTENU VARCHAR2 (3000 CHAR) NOT NULL
		)
		LOGGING ;
		ALTER TABLE INSTADIA ADD CONSTRAINT INSTADIA_PK PRIMARY KEY ( id ) ;

		ALTER TABLE INSTADIA ADD CONSTRAINT INSTADIA_USER_FK FOREIGN KEY ( USER_ID )
		REFERENCES "USER" ( ID ) ON DELETE SET NULL NOT DEFERRABLE ;

		CREATE SEQUENCE INSTADIA_ID_SEQ;
		```

		Une aide de vue `UnicaenApp\View\Helper\InstadiaViewHelper`{.php} a été
		créée pour simplifier l\'intégration. En voici un exemple d\'utilisation
		:

		``` {.php}
		/* Dans une vue */

		<?php echo $this->instadia()->setRubrique('essai')->setTitle('Mon test'); ?>

		```

		Voici le résultat (un clic sur le lien ouvre la fenêtre de CHAT) :
		![](/develop/unicaen2/moduleunicaenunicaenapp/viewhelpers/instadia.png){.align-center}

		Et voici maintenant ce qu\'on peut faire avec le Widget :

		Options
		-------

		Nom (dataset) Nom (Json) Type Valeur par défaut Description
		--------------- --------------- --------- ------------------------ --------------------------------------------------------------------------------------------------------------
		user-id userId integer undefined ID de l\'utilisateur courant (facultatif)
		user-label userLabel string \'Anonyme\' Nom de l\'utilisateur (ou undefined)
		user-hash userHash string undefined Hash permettant de récupérer le Gravatar de l\'utilisateur courant (formule : md5(strtolower(trim(\$email)))
		refresh-delay refreshDelay integer 2000 Délai de rafraichissement de la fenêtre des messages (en millisecondes)
		title title string Messagerie instantanée Titre de la fenêtre de Chat et nom du lien
		rubrique rubrique string undefined Rubrique
		sousRubrique sous-rubrique string undefined Sous-rubrique
		url url string undefined URL de communication avec le serveur
		information information string undefined Message d\'information sur la fenêtre de Chat
		width width integer 500 Largeur de la fenêtre de Chat
		height height integer 700 Hauteur de la fenêtre de Chat
		readOnly read-only boolean false Fenêtre de Chat en simple visualisation
		# Widgets Javascript

		Événements
		----------

		Les événements permettent de réagir à des changements d\'état. Les
		closures ou les fonctions qui seront appelées se verront transmettre
		deux arguments :

		1. l\'événement en lui-même
		2. l\'objet instadia (ce qui permet de le manipuler).

		### Liste des événements

		Événement Description
		------------ -------------------------------
		afficher affiche la fenêtre de Chat
		cacher ferme la fenêtre de Chat
		envoyer Lorsqu\'un message est envoyé
		addMessage Lorsqu\'un message est ajouté

		Méthodes
		--------

		Popajax comporte un certain nombre de méthodes :

		Nom Arguments Valeur de retour Description
		---------------- --------------------------- ------------------ ----------------------------------------------------------------------------------------------------------
		afficherCacher Aucun this Permet d\'afficher la fenêtre de Chat si elle n\'est pas affichée ou de la masquer si elle est affichée.
		estAffiche Aucun boolean Retourne true si elle est affichée, false sinon
		afficher Aucun this Affiche le Chat
		cacher Aucun this Masque le Chat
		envoyer Aucun this Envoie le message saisi
		addMessage user, horodatage, content this Poste un nouveau message user = id,label,hash
		getMessage Aucun string Retourne le texte en cours de saisie
		setMessage string this Change le texte en cours de saisie
		getUser Aucun id,label,hash retourne l\'utilisateur courant

		Avancé
		======

		Un service Instadia (` $sl->get('instadia');`{.php}) permet de :

		- lister les messages :
		`getMessages($rubrique = null, $sousRubrique = null)`{.php}
		- Sauvegarder un message :
		`save(UnicaenApp\Entity\Db\Instadia $instadia)`{.php}
		- Créer un Hash pour un utilisateur donné :
		`makeHash(UnicaenAuth\Entity\Db\AbstractUser $user)`{.php}
		- Réagir au post d\'un nouveau message selon la rubrique :
		`onSend( $rubrique, $sousRubrique, $callback)`{.php}

		Système de callback pour générer une action suite à un post de message
		----------------------------------------------------------------------

		Ceci est une portion de code à placer dans la méthode onBootstrap de la
		classe Module de votre application.

		``` {.php}

		$sm = $e->getApplication()->getServiceManager();
		/** @var \UnicaenApp\Service\InstadiaService $instadia */
		$instadia = $sm->get('instadia');
		$instadia->onSend('maRubrique', null, function( \UnicaenApp\Entity\Db\Instadia $instadia){
		/* DO WHAT YOU WANT */
		});

		```

		[Bootstrap DatetimePicker](./widgets/bootstrap-datetimepicker.md)
		[PopAjax](./widgets/pop-ajax.md)
		[TabAjax](./widgets/tab-ajax.md)
		[Instadia](./widgets/instadia.md)
		No newline at end of file

doc/widgets/instadia.md

0 → 100644

+160 −0

File added.

Preview size limit exceeded, changes collapsed.

doc/widgets/pop-ajax.md

0 → 100644

+204 −0

File added.

Preview size limit exceeded, changes collapsed.

doc/widgets/popajax.png

0 → 100644

+28.4 KiB

Loading image diff...

doc/widgets/tab-ajax.md

0 → 100644

+57 −0

Original line number	Diff line number	Diff line
		# TabAjax

		Cette aide de ue sert à dessiner des listes d'onglets avec contenu
		chargé statiquement et/ou dynamiquement. Il est possible de mélanger des
		onglets dynamiques et d'autres statiques.

		Usage simple (dans une vue phtml):

		```php

		echo $this->tabajax([
		[
		'id' => 'fiche',
		'label' => 'Fiche',
		'content' => 'Ceci est le contenu de la fiche descriptive',
		],
		[
		'id' => 'détails',
		'label' => 'Détails',
		'url' => $this->url('fiche/details', ['fiche' => 1245]),
		],
		]);

		```

		Ici, le premier onglet (Fiche) a un contenu statique. Le deuxième onglet
		reçoit une URL, qui sera exploitée le moment venu pour charger son
		contenu en AJAX. Les ID permettent de nommer les onglets pour les
		exploiter ensuite en JS si besoin.\
		`label`{.php} est le nom affiché sur l'onglet.\
		`content`{.php} le contenu de l'onglet (si pré-chargé).

		Événement "loaded"
		--------------------

		Il est déclenché lorsqu'un onglet AJAX a terminé son chargement :

		```javascript
		$(function(){
		$('#zozo').tabAjax({
		'loaded': function( event, tab ){
		//console.log(event);
		console.log(tab);
		}
		});

		});
		```

		Chargement d'un onglet à la demande
		------------------------------------

		```javascript
		$(function(){
		$('#zozo').tabAjax('select', 'onglet-general');
		});
		```
		No newline at end of file