====== Qu'est ce qu'un service portail ======

Un service portail permet de présenter des informations de manière synthétique dans le portail utilisateur. 
Il est constitué de :
  * une URL de consultation qui permet de récupérer le code HTML affiché dans le portail;
  * éventuellement une URL qui permet d'afficher un formulaire HTML <form>, ce formulaire est utilisé par l'utilisateur pour positionner ses préférences pour ce service.

====== Contrainte sur le service ======
Le service doit fournir un code **HTML autonome** qui est **inséré dans une balise HTML ''<DIV>''**.


====== Création d'un service portail ======

Un document [[freedom|Freedom]] permet de définir un service portail.

Sous Freedom, via la gestion par famille Freedom [[freedom_2.14:admin:start|(voir le manuel d'administration Freedom)]], il faut créer un nouveau document de famille Service Portail, symbolisée par l'icone {{modules:freedom-webdesk:portal_service.gif?25|Famille Service Portail}}.



==== Spécification du service ====

Les informations suivantes sont obligatoires :
  * **''Titre''** titre du service présenté aux utilisateurs et affichés dans les portails;
  * **''Consultation''** URL complète de récupération du code HTML à afficher dans le portail
  * **''Catégorie''** Permet de classifier les différents services en catégories; les catégories sont modifiables via la gestion par famille Freedom [[freedom_2.14:admin:start|(manuel d'administration Freedom)]]
  * **''Délai de raffraîchissement''**, intervalle de temps entre 2 mises à jour de l'affichage du service (ou ''Jamais'').

Les informations suivantes sont optionnelles :
  * ''Description'' description du service utilisée dans les diverses interfaces en complément au titre si elle est fournie;
  * ''Edition'', URL permettant de récupérer le code HTML du formulaire de paramétrage utilisateur;
  * ''Icone'', icone symbolisant le service portail.

Les paramètres permettent de définir certains aspects du comportement du service portail :
  * ''Disponible'' **Non** signifie que le service n'est pas proposé aux utilisateurs pour insertion dans leur portail;
  * ''Interactif'' **Oui** indique au portail que le service utilise en consultation un formulaire de saisie HTML; 
  * ''Modifiable'' //non utilisé//
  * ''Obligatoire'' //non utilisé//
  * ''Application attendue'' permet de lister les applications (au sens Freedom) nécessaire à ce service.\\ Si les applications ne sont pas présentes, le service n'est pas proposé à l'utilisation.\\ Les applications sont listés selon la syntaxe suivante : **''APPLICATION[|APPLICATION]*''**

==== Fonctionnement du service ====


L'affichage du service (automatique ou à la demande) active l'URL de ''Consultation'' en postant les éventuels paramètres utilisateur et les champs de saisie (mode ''Interactif'').

Si l'on prend l'exemple d'un service ''Interactif'' recherchant des contacts du carnet d'adresse, il se compose de :
  * l'URL de consultation http://mon.serveur.com/scontact.php
  * l'URL de paramétrage utilisateur http://mon.serveur.com/pcontact.html.

L'URL de consulation retourne le code XML suivant : \\ 
<code xml>
<?xml version="1.0" encoding="UTF-8"?><freedomsvc  title="[title]" uptime="[uptime]"><![CDATA[
<div>Rechercher : <input name="search" type="text" value=""></div>
<div>
... résultat de la recherche précédente ....
</div>
]]></freedomsvc>
</code>

Le code XML comporte 3 types d'information :
  * l'attribut ''title'' de la balise **''freedomsvc''** est le titre du service
  * l'attribut ''uptime'' de la balise **''freedomsvc''** fournie la date de mise à jour, cette date est affichée lorsque le pointeur de la souris est positionné sur le titre du service
  * le contenu de la balise **''freedomsvc''** étant le code HTML affiché dans le corps sur service.
  

Le portail gère le formulaire HTML du service et lors de l'affichage poste l'URL // http://mon.serveur.com/scontact.php // et poste le paramêtre search valorisé par la saisie de l'utilisateur.

Le code PHP //scontact.php// peut ressembler à ceci : <code php>

  // récupération de la saisie utilisateur
  $s = $HTTP_POST_VAR["search"];

  if ($s!="") {

    // ... recherche et mise en forme du résultat

  }
</code>

L'URL de paramétrage utilisateur retourne le code suivant (elle permet de demander un affichage plus ou moins long des informations conernant le(s) contact(s) trouvé(s)) :
<code html>
<select name="view">
<option value="0">résumé
<option value="1">complète
</select>
</code>

Les paramètres utilisateurs (mémorisé par le serveur) sont aussi postés lors de l'affichage du service. Le code PHP //scontact.php// peut ressembler à ceci : <code php>

  // récupération du paramètre utilisateur
  $view = $HTTP_POST_VAR["view"];

  // récupération de la saisie utilisateur
  $s = $HTTP_POST_VAR["search"];

  if ($s!="") {

    // ... recherche et mise en forme du résultat

  }
</code>

==== Services interactifs ====

Les services interactifs mettent en oeuvre des formulaires HTML.
Le formulaire et sa soumission vers le serveur sont gérés par la portail. Pour cela, certaines contraintes d'écriture du code HTML du service sont à observer.

  - le code HTML du service est inclu par le portail dans une balise ''<form>'';
  - les champs de saisie ''<input>'', ''<select>'' ... doivent posséder un attribut **''name''**;
  - le formulaire peut être soumis par l'appel à la fonction JavaScript **''submitService(event)''** sur un évènement utilisateur. Exemple <code html>
...
<input type="text" title="search ..." name="sphrase">&nbsp;
<input type="button" title="chercher" value="?" onclick="submitService(event)">
...
</code>