Documentation G4EX (Graphs for EXperiments)

Transcription

1 Documentation G4EX (Graphs for EXperiments) G4EX version mai 2013 Auteurs : Emile GENNARI, Vincent NEGRE, Anne TIREAU INRA Centre de Montpellier Note : Ce logiciel fait partie du meta-projet SILEX ( Toute distribution sans l autorisation des auteurs est interdite. Contacts : anne.tireau@supagro.inra.fr et pascal.neveu@supagro.inra.fr Autres participants : Mathias CHOUET, Virginie ROSSARD, Jonathan MINEAU CESARI, Nicolas BRICHET, Alexandre MAIRIN et Pascal NEVEU.

2 G4EX version /05/ Table des matières Introduction... 3 Arborescence du module... 3 Pré-requis... 3 Installation... 3 Utilisation... 4 Préambule... 4 Description de l'api... 4 Initialisation du graphique... 4 Options disponibles pour setchart... 4 Options disponibles pour setlegend... 4 Options disponibles pour settitle et setsubtitle... 5 Ajout de l'axe X... 5 Options disponibles pour setxaxis... 5 Ajout d'axes Y... 5 Options disponibles pour addyaxis... 5 Ajout d'une courbe... 6 Cas des «scatters»... 6 Cas des «flags»... 7 Mise à jour dynamique d une série : monitoring... 7 Exportation CSV des données du graphique... 7 Affichage HighStock / HighChart... 7

3 G4EX version /05/ Introduction Le module G4EX s'appuie sur les librairies Javascript HighCharts et HighStock ( Son objectif est de fournir une API PHP qui permette d'utiliser directement ces librairies sans écrire de Javascript. Les fonctionnalités interfacées ne couvrent pas la totalité des possibilités offertes par HighCharts/HighStock. Elles couvrent les besoins des Systèmes d Information développés dans le cadre d expérimentation de l INRA (SPO, Pech-Rouge, LBE et LEPSE). Ce module est compatible avec les versions HighCharts-2.14 et HighStock Arborescence du module répertoire classes : contient les différentes classes du modules. répertoire config : contient le fichier de configuration qui définit les chemins vers les librairies javascript. répertoire doc : contient la doc utilisateur, un jeu de données mysql. répertoire examples : contient différents exemples d'utilisation du module. répertoires js et libs : contient les librairies nécessaires. Pré-requis serveur Apache, PHP, une machine virtuelle Java (pour le module d exportation), Mysql (pour exemple avec connexion à une base de données mysql). Installation Décompresser l'archive G4EX dans le répertoire web de votre machine (en général /var/www). Vérifier que l'utilisateur Apache, généralement www-data possède les droits de lecture sur l'arborescence sudo chown -R user.www-data /var/www/g4ex Remplacer user par le propriétaire des fichiers. Pour faire fonctionner l'exemple database.php vous devez créer une base de données : mysql -ulogin pmotdepasse < /var/www/g4ex/doc/mesuremeteo.sql Remplacer login et motdepasse par les identifiants de l'utilisateur qui a les droits de connexion à la base de données. Vous devez également modifier les paramètres de connexion dans database.php, monitoring.php et updating.php. Remplacer login et motdepasse par vos identifiants de connexions. Éventuellement localhost par l'adresse de votre machine.

4 G4EX version /05/ Utilisation Pour tester le module ouvrez votre navigateur à l'adresse et essayer les différents exemples. Préambule Dans G4EX, une courbe, ou ensemble de points, est désignée par le terme série. Avant d utiliser G4EX, pour les types de courbe line, spline, scatter, column, il faut récupérer et préparer les données à afficher sous la forme de tableaux associatifs, de la forme tableau[x] = y, où x l abscisse et y l'ordonnée. La plupart des fonctions prennent en paramètre un tableau associatif de différentes options. Description de l'api Initialisation du graphique $graph = new G4EX_Graphic(); Le constructeur initialise un graphique et paramètre des éléments de bases comme un titre, un soustitre, une légende, etc. Il est possible de configurer à posteriori ces éléments avec les fonctions suivantes : setchart() setlegend() settitle() setsubtitle() setplotoptions() Options disponibles pour setchart renderto :String Identifiant de la balise HTML dans lequel sera affiché le graphique. Par défaut c'est une div «container» marginright, marginbottom, margintop : Number Marges du graphique zoomtype : xy, x, y Type de zoom autorisé. Par défaut en 2 dimensions (xy). On peut aussi zoomer dans une seule dimension (x, y). Options disponibles pour setlegend layout : vertical, horizontal Légende horizontale ou verticale align : right, left, center Position de la légende

5 G4EX version /05/ verticalalign : top, bottom Position de la légende x : Number Marge horizontale de la légende y : Number Marge verticale de la légende BorderWidth : Number Taille de la bordure Options disponibles pour settitle et setsubtitle text : String Label du titre / sous-titre x : Number Par défaut le titre / sous-titre est centré. x permet un décalage horizontal. Ajout de l'axe X $graph->setxaxis(array("xaxislabel" => 'heure')); Options disponibles pour setxaxis xaxislabel : String Label de l'axe X type : String Type de donnée de l axe, par défaut «lineaire», existe aussi «logarithmic» or «datetime». xmin : Number La valeur min des valeurs de l'axe X (utile pour faire des zooms manuels) xmax : Number La valeur max des valeurs de l'axe X (utile pour faire des zooms manuels), remarque on laisse 5% de plus après la borne max. Ajout d'axes Y Attention : l'ordre dans lequel sont ajoutés les axes Y est important car un numéro (0, 1 ) est assigné à chaque axe et sera utilisé pour associer une courbe à un axe. $graph->addyaxis(array("yaxislabel" => "hauteur1")); $graph->addyaxis(array("yaxislabel" => "hauteur2", "opposite" => 'true')); Options disponibles pour addyaxis yaxislabel : String Le label de l'axe Y

6 G4EX version /05/ ymin : String La valeur min des valeurs de l'axe Y (utile pour faire des zooms manuels) ymax : String La valeur max des valeurs de l'axe Y (utile pour faire des zooms manuels) opposite : true/false Par défaut les axes Y sont placés à gauche. Si on veut un axe à droite il suffit de mettre cette option à true. Ajout d'une courbe $graph->addserie(new G4EX_Serie("line", "Nom de la courbe", $tableaudonnées, array("yaxis" => "0"))); Lorsqu'on ajoute une série on doit entrer le type, son nom, le tableau de données : ce sont les paramètres obligatoires. Types de courbes/séries proposées : «line» : points reliés les uns aux autres, «spline» : points reliés les uns aux autres, effet lissé, «scatter» : points non reliés sur la courbe, «column» : histogramme, «flags» : drapeau, pour annoter un point, positionné sur l axe des abscisses. Le tableau de données est un tableau associatif de la forme : $data[x]=y Le 4 e paramètre est un tableau d'options. Ici on paramètre l'option Yaxis de notre courbe pour la lier au premier axe (0) définit. Dans notre exemple «hauteur1». Les options disponibles sont : yaxis : String / identifiant de l axe à associer à la série Association d une série à un axe donné. L identifiant de l axe dépend de l ordre de déclaration de l axe. serievisible : true ou false Permet de rendre visible une courbe au premier affichage du graphique. markerserieenabled : true ou false et radiusmarkerserie Affichage ou pas des points de la courbe avec le diamètre des marques. Cas des «scatters» $graph->addserie(new G4EX_Serie("scatter", "Nom de la série", $tableaudonnées)) Un Scatter est une série où les points ne sont pas reliés et les valeurs en Y affichées au-dessus des points. Des options spécifiques sont interfacées : functiondatalabelsformatter : String et paramsdatalabelformatter : String Fonction JavaScript et paramètres implémentés par l utilisateur pour fixer le format d affichage associés aux points de la série.

7 G4EX version /05/ labelsenabled : true ou false Visibilité des labels des points, visible par défaut. Cas des «flags» On peut également ajouter des flags (drapeaux) sur une courbe. Pour cela on ajoute une série spéciale appelée «FlagsSerie». $graph->addflagsserie(new FlagsSerie("Titre", $tableaux, $tableautitles, $tableautext)); Ici, contrairement aux autres types de courbes (comme line) pour afficher un drapeau (flag) il faut au préalable avoir 3 tableaux simples : les valeurs des X pour le positionnement des drapeaux sur l axe des abscisses, les titres à inscrire dans les drapeaux, les textes qui seront visibles au survol de la souris sur le drapeau. Mise à jour dynamique d une série : monitoring L idée est de charger une fonction JavaScript utilisateur permettant ajoutant une donnée à une série. Vous trouverez des exemples : examples/monitoring.php, Exportation CSV des données du graphique $graph-> setcsvexporting(array(«filename»=>«export2013.csv»)) Cette méthode permet d exporter les données des séries du graphique. Attention : le script risque de ne pas aboutir en fonction de la puissance du navigateur et du nombre de données. Dans le cas d un grand nombre de données, nous nous conseillons de récupérer les données directement à leurs sources (base de données ou autres). Affichage HighStock / HighChart $graph->setrenderstockchart(true) Permet de passer d un mode graphique à l autre. Par défaut, le rendu est celui de HighChart. Le rendu HighStock est particulièrement bien adapté aux données temporelles.