WebSVN – eFlore/Applications.cel – Diff – /branches/v3.01-serpe/widget/modules/saisie/Saisie.php

 <?php
-// declare(encoding='UTF-8');
 /**
- * Widget fournissant des interfaces de saisies simplifiée pour différent projets.
+ * Widget fournissant des interfaces de saisie simplifiée pour différent projets
- * Encodage en entrée : utf8
- * Encodage en sortie : utf8
+ *
  * Cas d'utilisation et documentation :
- * @link http://www.tela-botanica.org/wikini/eflore/wakka.php?wiki=AideCELWidgetSaisie
+ * @link http://www.tela-botanica.org/wikini/AideCarnetEnLigne/wakka.php?wiki=AideCELWidgetSaisie
+ *
  * Paramètres :
- * ===> projet = chaine  [par défaut : defaut] : indique le widgetde saisie à charger.
+ * - projet [par défaut : defaut] : indique le mot-clé à associer aux obs saisies; si un widget de saisie personnalisé
+ * 		portant ce nom existe, il sera chargé
- * ===> mission = chaine  [par défaut : vide] : permet de charger un "sous-widget" vis à vis du projet.
+ * - mission [par défaut : vide] : permet de charger un "sous-widget", dans le cas où un widget personnalisé
- * Indique quel projet nous voulons charger
+ * 		est associé au projet, et ce widget accepte des sous-widgets (ex: "missions-flore")
+ *
  * @author Mathias CHOUET <mathias@tela-botanica.org>
  * @author Jean-Pascal MILCENT <jpm@tela-botanica.org>
  * @author Aurelien PERONNET <aurelien@tela-botanica.org>
  * @license GPL v3 <http://www.gnu.org/licenses/gpl.txt>
  * @license CECILL v2 <http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt>
- * @copyright 1999-2014 Tela Botanica <accueil@tela-botanica.org>
+ * @copyright 1999-2015 Tela Botanica <accueil@tela-botanica.org>
  */
 class Saisie extends WidgetCommun {
 	const DS = DIRECTORY_SEPARATOR;
 	const PROJET_DEFAUT = 'defaut';
 	const WS_SAISIE = 'CelWidgetSaisie';
 	const WS_UPLOAD = 'CelWidgetUploadImageTemp';
 	const WS_OBS = 'CelObs';
 	const WS_NOM = 'noms';
+	const EFLORE_API_VERSION = '0.1';
+	const REFERENTIEL_DEFAUT = 'bdtfx';
-	const EFLORE_API_VERSION = '0.1';
+	/** référentiel utilisé pour al complétion des noms scientifiques */
+	protected $ns_referentiel;
-	private $ns_referentiel = 'bdtfx';
+	/** mot-clé associé aux saisies, et template personnalisé si appliquable */
-	private $projet = null;
+	protected $projet = null;
-	private $configProjet = null;
+	protected $configProjet = null;
-	private $configMission = null;
+	protected $configMission = null;
 	/**
-	 * Méthode appelée par défaut pour charger ce widget.
+	 * Amorçage du widget
 	 */
-	public function executer() {
-		$retour = null;
+	public function executer() {
+		// paramètres par défaut
+		$this->ns_referentiel = self::REFERENTIEL_DEFAUT;
-		extract($this->parametres);
+		$this->projet = self::PROJET_DEFAUT;
-		$this->projet = self::PROJET_DEFAUT;
+		// définition du projet / mission
-		if (isset($projet) && trim($projet) != "") {
+		if (isset($this->parametres['projet']) && trim($this->parametres['projet']) != "") {
-			$projets = explode(',', $projet);
+			$projets = explode(',', $this->parametres['projet']);
+			$this->projet = strtolower($projets[0]);
+		}
-			$this->projet = strtolower($projets[0]);
+		$this->chargerConfigProjet();
-		$this->chargerConfigProjet();
+		// exécution du service (le widget entier ou une sous-partie, par ex "Taxons")
 		$retour = null;
-		$service = isset($service) ? $service : 'widget';
+		$service = isset($this->parametres['service']) ? $this->parametres['service'] : 'widget';
 		$methode = $this->traiterNomMethodeExecuter($service);
 		if (method_exists($this, $methode)) {
+			$retour = $this->$methode();
-			$retour = $this->$methode();
+		} else {
-		} else {
+			$this->messages[] = "Le service '$methode' n'est pas disponible.";
 			$this->messages[] = "Ce type de service '$methode' n'est pas disponible.";
 		// injection des données dans le squelette
+			}
 			$contenu = $this->traiterSquelettePhp($squelette, $retour['donnees']);
 			$mime = isset($retour['mime']) ? $retour['mime'] : null;
 		} else {
 			if (count($this->messages) == 0) {
-				$this->messages[] = "La méthode du sous-service ne renvoie pas les données dans le bon format.";
+				$this->messages[] = "La méthode du sous-service ne renvoie pas les données dans le bon format";
+			}
-			$contenu = 'Un problème est survenu : '.print_r($this->messages, true);
+			$contenu = 'Un problème est survenu : ' . print_r($this->messages, true);
+		}
 		// envoi de la page
 		$this->envoyer($contenu, $mime);
+	}
+	/**
+	 * Charge le fichier de configuration associé au projet : configurations/nomduprojet.ini
+	 * Si une mission est définie, charge séparément la section de la configuration concernant
-	}
+	 * cette mission : [nommission]
 	 */
-	private function chargerConfigProjet() {
+	protected function chargerConfigProjet() {
 		$fichier_config = dirname(__FILE__).self::DS.'configurations'.self::DS.$this->projet.'.ini';
 		if (file_exists($fichier_config)) {
 			if ($this->configProjet = parse_ini_file($fichier_config, true)) {
 				if (isset($_GET['mission'])) {
 					$mission = strtolower(trim($_GET['mission']));
 					if (isset($this->configProjet[$mission])) {
 						$this->configMission = $this->configProjet[$mission];
+					}
-			}
+				}
 			} else {
-				$this->messages[] = "Le fichier ini '$fichier_config' du projet n'a pu être chargé.";
+				$this->messages[] = "Le fichier de configuration '$fichier_config' n'a pu être chargé.";
 			}
 		} else {
-			$this->debug[] = "Le fichier ini '$fichier_config' du projet n'existe pas.";
+			$this->debug[] = "Le fichier de configuration '$fichier_config' n'existe pas.";
+		}
-		}
+	}
-	}
+	/**
+	 * Retourne true si le dossier du projet courant existe, false sinon
-	private function projetASquelette() {
+	 * @return boolean
-		// fonction très simple qui ne teste que si le dossier du projet courant
+	 */
+	protected function projetASquelette() {
+		return file_exists(dirname(__FILE__).self::DS.'squelettes'.self::DS.$this->projet);
+	}
-		// existe, mais elle suffit pour le moment.
+	/**
-		return file_exists(dirname(__FILE__).self::DS.'squelettes'.self::DS.$this->projet);
+	 * Exécution du widget complet
 	 * @return Ambigous <string, unknown, multitype:string unknown >
+	 */
 	public function executerWidget() {
 		$referentiel_impose = false;
 		if (isset($_GET['referentiel']) && $_GET['referentiel'] != '' && $_GET['referentiel'] != "autre") {
-			$this->ns_referentiel = isset($_GET['referentiel']) && $_GET['referentiel'] != '' ? $_GET['referentiel'] : $this->ns_referentiel;
+			$this->ns_referentiel = $_GET['referentiel'];
 		$widget['donnees']['url_ws_autocompletion_ns_tpl'] = $urlWsNsSansRef;
 		$widget['donnees']['ns_referentiel'] = $this->ns_referentiel;
 		if ($this->especeEstImposee()) {
 			$nnEspeceImposee = $this->getNnEspeceImposee();
-			$nom = $this->executerChargementInfosTaxon($nnEspeceImposee);
+			$nom = $this->chargerInfosTaxon($nnEspeceImposee);
 			$widget['donnees']['espece_imposee'] = true;
 			$widget['donnees']['nn_espece_defaut'] = $nnEspeceImposee;
 			$widget['donnees']['nom_sci_espece_defaut'] = $nom['nom_sci'];
 			$widget['donnees']['infos_espece'] = $this->array2js($nom, true);
+		}
 		return $widget;
 	}
-	private function getTitrePage() {
+	protected function getTitrePage() {
 		$titre = 'defaut';
 		if (isset($this->configProjet['titre_page'])) {
 			$titre = $this->configProjet['titre_page'];
 			$titre = '';
+		}
 		return $titre;
+	}
+	/**
+	 * Remplit un fichier JS avec une variable contenant une liste restreinte de taxons,
+	 * pour certains projets
+	 * @return string
 	 */
 	public function executerTaxons() {
 		$widget['squelette'] = $this->projet.'_taxons';
 		$widget['squelette_ext'] = '.tpl.js';
 		$widget['donnees'] = array();
+		}
 		$widget['donnees']['taxons'] = json_encode($taxons_tries);
 		return $widget;
+	}
+	/**
+	 * Trie par nom français les taxons lus dans le fichier tsv
+	 */
-	private function recupererListeNomsSci() {
+	protected function recupererListeNomsSci() {
 		$taxons = $this->recupererListeTaxon();
 		if (is_array($taxons)) {
 			$taxons = self::trierTableauMd($taxons, array('nom_fr' => SORT_ASC));
+		}
 		return $taxons;
+	}
+	/**
+	 * @TODO documenter
-	}
+	 * @return array
 	 */
-	private function recupererListeNoms() {
+	protected function recupererListeNoms() {
 		$taxons = $this->recupererListeTaxon();
 		$nomsAAfficher = array();
 		$nomsSpeciaux = array();
 			$nomsSpeciaux = self::trierTableauMd($nomsSpeciaux, array('nom_a_afficher' => SORT_ASC));
+		}
 		return array('speciaux' => $nomsSpeciaux, 'sci-et-fr' => $nomsAAfficher);
+	}
+	/**
+	 * Lit une liste de taxons depuis un fichier tsv fourni
+	 */
-	private function recupererListeTaxon() {
+	protected function recupererListeTaxon() {
-		$taxons = null;
+		$taxons = array();
 		$fichier_tsv = dirname(__FILE__).self::DS.'configurations'.self::DS.$this->projet.'_taxons.tsv';
 		if (file_exists($fichier_tsv) && is_readable($fichier_tsv)) {
 			$taxons = $this->decomposerFichierTsv($fichier_tsv);
 		} else {
 			$this->debug[] = "Impossible d'ouvrir le fichier '$fichier_tsv'.";
+		}
 		return $taxons;
+	}
+	/**
-	}
+	 * Découpe un fihcier tsv
 	 */
-	private function decomposerFichierTsv($fichier, $delimiter = "\t"){
+	protected function decomposerFichierTsv($fichier, $delimiter = "\t"){
 		$header = null;
 		$data = array();
 		if (($handle = fopen($fichier, 'r')) !== FALSE) {
 			fclose($handle);
+		}
 		return $data;
+	}
+	/**
+	 * Récupère la liste des milieux depuis la section [milieux] de la configuration
+	 * du projet, si elle existe
+	 * @return array
+	 */
-	private function parserMilieux() {
+	protected function parserMilieux() {
 		$infosMilieux = array();
 		if (isset($this->configProjet['milieux'])) {
 			$milieux = explode('|', $this->configProjet['milieux']);
 			foreach ($milieux as $milieu) {
 			ksort($infosMilieux);
+		}
 		return $infosMilieux;
+	}
+	/**
+	 * Retourne true si le widget est restreint à une espèce, false sinon
+	 * @return boolean
+	 */
-	private function especeEstImposee() {
+	protected function especeEstImposee() {
-		return (isset($_GET['num_nom']) && $_GET['num_nom'] != ''
+		return ((isset($_GET['num_nom']) && $_GET['num_nom'] != '')
 			|| isset($this->configProjet['sp_imposee']) || isset($this->configMission['sp_imposee']));
+	}
+	/**
+	 * Retourne le numéro nomenclatural (nn) de l'espèce imposée si tel est
+	 * le cas, null sinon
-	}
+	 * @return string
 	 */
-	private function getNnEspeceImposee() {
+	protected function getNnEspeceImposee() {
 		$nn = null;
 		if (isset($_GET['num_nom']) && is_numeric($_GET['num_nom'])) {
 			$nn = $_GET['num_nom'];
 			$nn = $this->configMission['sp_imposee'];
+		}
 		return $nn;
+	}
+	/**
+	 * Consulte un webservice pour obtenir des informations sur le taxon dont le
+	 * numéro nomenclatural est $num_nom (ce sont donc plutôt des infos sur le nom
+	 * et non le taxon?)
+	 * @param string|int $num_nom
+	 * @return array
+	 */
-	private function executerChargementInfosTaxon($num_nom) {
+	protected function chargerInfosTaxon($num_nom) {
 		$url_service_infos = sprintf($this->config['chemins']['infosTaxonUrl'], $this->ns_referentiel, $num_nom);
 		$infos = json_decode(file_get_contents($url_service_infos));
-		// trop de champs injectés dans les infos espèces peut
+		// trop de champs injectés dans les infos espèces peuvent
 		// faire planter javascript
 		$champs_a_garder = array('id', 'nom_sci','nom_sci_complet',
 			'famille','nom_retenu.id', 'nom_retenu.libelle', 'num_taxonomique');
 		$resultat = array();
+			}
+		}
 		return $resultat;
+	}
+	/**
+	 * Convertit un tableau PHP en Javascript - @WTF pourquoi ne pas faire un json_encode ?
+	 * @param array $array
+	 * @param boolean $show_keys
+	 * @return une portion de JSON représentant le tableau
+	 */
-	private function array2js($array,$show_keys) {
+	protected function array2js($array,$show_keys) {
 		$tableauJs = '{}';
 		if (!empty($array)) {
 			$total = count($array) - 1;
 			$i = 0;

Subversion Repositories eFlore/Applications.cel

(root)/branches/v3.01-serpe/widget/modules/saisie/Saisie.php @ 3898 – Rev 2577 → 2688