\documentclass[11pt,a4paper]{report} 
\usepackage[latin1]{inputenc} 
\usepackage[american]{babel}
\usepackage{verbatim}
\usepackage{url}
% %pour créer des lien vers des pages web
\usepackage[pdftex,colorlinks=true, urlcolor=cyan,pdfstartview=FitH]{hyperref}
%%pour inserer du code
\usepackage{listings}
\usepackage{ulem}

\setcounter{secnumdepth}{2}
\setcounter{tocdepth}{3}

%\lstset{%
%basicstyle=\ttfamily
%}
\lstdefinelanguage{Mobyle}%
{
alsoletter={:,\-},%
}

\lstset{ %
         language=Mobyle,
         showspaces=false,
         showstringspaces=false,
         showtabs=false,
         basicstyle=\footnotesize
         }


%% pour afficher des images avec pdflatex utiliser le package pdftex
\usepackage{graphicx}

% % MARGES
\oddsidemargin -1cm
\marginparwidth 0cm \textwidth 18cm
\topmargin -0.5cm
\headheight -0.8cm \headsep 0cm
% %\footskip 0cm
\textheight 26.8cm
\pagestyle{plain}

\renewcommand{\abstractname}{Overview}

\date{ Mobyle 1.0 }

\title{Mobyle Service Description Guide}

\begin{document}

\maketitle

\tableofcontents

\chapter{Introduction}
Mobyle is a system which provides an access to different software elements, in order to allow
users to perform bioinformatics analyses. Such software elements are called \textbf{services},
and belong to four distinct categories:
\begin{itemize}
 \item \textbf{programs} describe software that are executed on the server side ``command line'' tools,
 and return results in the form of files,
 \item \textbf{workflows} describe compositions of successive and/or parallel calls to other 
 server-side services (programs and/or subworkflows), and also return results as files,
 \item \textbf{viewers} describe browser-embedded visualization components, such as applets, that allow
 users to visualize data (results or bookmarks) stored in the Mobyle server.
 \item \textbf{tutorials} describe custom pages which are categorized and accessible in left part of portal. 
 These pages are displayed in the "tutorials" tab of the central part of the portal.
\end{itemize}

To publish such services on a Mobyle server, you need to install and describe them so that 
Mobyle offers the adequate user interface and executes them when required. Mobyle stores 
the description of each service in an XML document, a \textbf{service description}.

The formal description of the format of these XML files is stored in \texttt{relax-ng}
and \texttt{schematron} formats, in the \texttt{*.rnc}, \texttt{*.rng}, and \texttt{*.sch}
files, located in the \texttt{Schema} folder. The goal of this document is to describe the
elements of this format so that you can add new tools or modify existing ones. Even if you do 
not intend to use them, it is strongly recommended to download the service descriptions 
maintained and distributed by the Institut Pasteur, which are used to illustrate the most 
complex elements of the service description format.
\\
\\
\definecolor{lightyellow}{rgb}{1,1,0.7}
\colorbox{lightyellow}{
\begin{minipage}{\textwidth}
The releases of service descriptions are available on the public ftp server of the Institut Pasteur:\\
\href{ftp://ftp.pasteur.fr/pub/gensoft/projects/mobyle/}{ftp://ftp.pasteur.fr/pub/gensoft/projects/mobyle/}.
 \begin{itemize}
  \item Programs-2.0.tar.gz or higher.
  \item Workflows-??.tar.gz or higher.
  \item Viewers-??.tar.gz or higher.
  \item Tutorials-??.tar.gz
 \end{itemize}

The service descriptions are maintained in 3 subprojects of the Mobyle forge:
 \begin{itemize}
  \item \href{pasteur-programs}{https://projets.pasteur.fr/projects/show/pasteur-programs}
  \item \href{pasteur-workflows}{https://projets.pasteur.fr/projects/show/pasteur-workflows} 
  \item \href{pasteur-viewers}{https://projets.pasteur.fr/projects/show/pasteur-viewers}
  \item \href{pasteur-viewers}{https://projets.pasteur.fr/projects/show/pasteur-viewers}
 \end{itemize}

The development versions of the service descriptions are accessible from the
 public SVN Mobyle repository. With a command-line subversion client, type these
 lines:
\begin{itemize}
 \item \texttt{svn co https://projets.pasteur.fr/svn/pasteur-programs/}
 \item \texttt{svn co https://projets.pasteur.fr/svn/pasteur-workflows/}
 \item \texttt{svn co https://projets.pasteur.fr/svn/pasteur-viewers/}
 \item \texttt{svn co https://projets.pasteur.fr/svn/pasteur-tutorials/}
\end{itemize}
\end{minipage}}

\chapter{Writing a program description}\label{programs}

A program is a software: 
\begin{itemize}
 \item running on the server side,
 \item callable in a shell command line,
 \item returning some results.
\end{itemize}
XML files describe these softwares and make them usable by Mobyle. Hereinafter, ``program description''
stands for ``XML description of such a software''.\\

\noindent A program description aims at capturing different kinds of information:
\begin{itemize}
  \item how to invoke the program (a program wrapper),
  \item how to display options in submission forms or job results (a UI description),
  \item how to control values or parameters compatibilities (a ``semantic'' description).
\end{itemize}

\noindent The root element of a program description is the \textbf{program} tag. 
A program description is divided into two parts:
\begin{itemize}
 \item the \textbf{head} element, described in section~\ref{programs_head}, contains general information about the program,
 \item the \textbf{parameters} element, described in section \ref{programs_parameters}, contains the different input data, options and results of the program.
\end{itemize}
\newpage

\section{head \label{programs_head}}

\begin{itemize}
  \item \textbf{name} (\textit{required}): name of the interface you are describing.
  \begin{itemize}
    \item does not have to be identical to the actual invoked program name (but highly recommended).  
    \item has to be identical to the XML file name (minus its extension). E.g.: for the file 
    \texttt{blast2.xml}, the \textbf{name} tag has to be \texttt{<name>blast2</name>}. 
  \end{itemize} 
  \item \textbf{version}: version of the program you are interfacing, not of the XML description itself.
  \item \textbf{package} (\textit{new in 1.0}): description of the package the program belongs to. 
  Can contain all the elements defined in \textbf{head} (\texttt{name}, \texttt{version}, 
  \texttt{doc}\ldots ).

  \begin{lstlisting}[title= how to include package information (excerpt from
  \texttt{dnadist} description), breaklines=true, breakatwhitespace=true, float=p]
<program>
  <head>
    <name>dnadist</name>
    <package>
      <name>phylip</name>
      <version>3.67</version>
      <doc>
        <title>phylip</title>
	<description>
	  <text lang="en">PHYLIP is a package of programs for inferring phylogenies.</text>
	</description>
	<homepagelink>http://evolution.gs.washington.edu/phylip.html</homepagelink>
	<sourcelink>http://evolution.gs.washington.edu/phylip/getme.html</sourcelink>
        <authors>Felsenstein Joe</authors>
	<reference>Felsenstein, J. 1993. PHYLIP (Phylogeny Inference Package) 
        version 3.5c. 
	Distributed by the author. Department of Genetics, 
	University of Washington, Seattle.</reference>
	<reference>Felsenstein, J. 1989. PHYLIP -- Phylogeny Inference Package 
        (Version 3.2).
	Cladistics 5: 164-166.</reference>
	<doclink>http://bioweb2.pasteur.fr/docs/phylip/phylip.html</doclink>  
      </doc>
    </package>
    <doc>
      <title>dnadist</title>
      <description>
        <text lang="en">Compute distance matrix from nucleotide sequences</text>
      </description>
      <doclink>http://bioweb2.pasteur.fr/docs/phylip/doc/dnadist.html</doclink>
      <comment>
        <text lang="en">This program uses nucleotide sequences to compute 
        a distance matrix, under four different models of nucleotide substitution. 
        It can also compute a table of similarity between the nucleotide
        sequences. The distance for each pair of species estimates the total 
        branch length between the two species, and can be used in the distance 
        matrix programs FITCH, KITSCH or NEIGHBOR.
        </text> 
      </comment>
    </doc>
    <category>phylogeny:distance</category>
  </head>
  [...]
  \end{lstlisting}
  
  \item \textbf{doc}: documentation of the program split among the following elements:
  \begin{itemize}
    \item \textbf{description}: brief description of the software, in text or XHTML.
    This description appears at the top of the submission form.
    
    \item \textbf{reference}: scientific reference officially used to cite the program, 
    in text or XHTML. In addition, you can provide a hyperlink to the users by specifying 
    a DOI or a direct URL, respectively in the \texttt{doi} and \texttt{url} attributes.
    
    \item \textbf{authors}: program authors who must be cited.
    
    \item \textbf{doclink}: any URL pointing to useful documentation regarding the program.
    If a \textbf{doclink} is specified, a button ``Help Pages'' is displayed at the top of
    the web form:
    \begin{itemize}
      \item with only one \textbf{doclink} element, the documentation is be available both
      as the ``Help Pages'' button and as a link at the bottom of the web form,
      \item with several \textbf{doclink} elements, the ``Help Pages'' button sets the focus 
      to the bottom of web form where he can choose among the different links.
    \end{itemize}
    
    \item \textbf{sourcelink}: (\textit{new in 1.0}) any URL where the program can be found. 
    Essentially used as documentation by server administrators.
    
    \item \textbf{homepagelink}: (\textit{new in 1.0}) the URL to the homepage of the 
    software project.
    
    \item \textbf{comment}: text describing the program with more details.
    This comment is shown by clicking on the red question mark beside the title.
  \end{itemize}
  
  \item \textbf{category}: path within the classification of the programs which determines 
  where the program name will be displayed in the program tree on the left panel. Thus, the 
  \textbf{category} must be chosen carefully. The colon is used as separator between nodes 
  of the classification.
  \begin{itemize}
    \item if multiple \textbf{category} elements are specified for a service, the program 
    will appear in each branch of the tree, 
    \item if none is provided, it will appear at the ``top level''.
  \end{itemize}
  
  \item \textbf{env}: used to specify an environment variable that will be defined prior to launching any job 
  for the program. Usually implemented with entities or \texttt{XInclude}. Examples:
  \begin{itemize}
    \item to specify the location of blast databases: \texttt{<env name=``BLASTDB''>/usr/local/ncbi/db</env>}
    \item to give the path of a binary different from  the usual path: \\ \texttt{<env name=``PATH''>/path/to/my/binary</env>}
  \end{itemize}

  \item \textbf{progressReport}: used to specify a file provided by the execution of the program, which will provide information
  about the execution status of the program. This can be useful if you have a program running for a long time and executing multiple
  steps internally. In such cases the user will access progress information as the contents of this file in the job status tab of
  the portal. The \texttt{prompt} attribute lets you define a program-specific prompt for this file, otherwise the default prompt is 
  "job progress report". Ex: \texttt{<progressReport prompt="This is your progress report">progress.log</progressReport>}.

\end{itemize}

\newpage

\subsection{XInclude to include external or common information}

It is possible to include site-dependent information (such as the
above-mentioned \textbf{env} tag) by including external pieces of XML code.
Although XML entities can achieve the same goal, the recommended way is to use 
\texttt{XInclude} as it provides error-handling mechanisms not available with 
XML entities. XInclude can be used to: 
\begin{itemize} 
 \item refactor some parts of a set of descriptions,
 \item specify site-dependent variables.
\end{itemize}
 
For example, if you have a set of interfaces which wrap different programs from the same package, 
you can include common package information in an entity that you 
include in the different XML files. Just make sure that:
\begin{enumerate}
 \item the \texttt{XInclude} elements are correctly formatted
 \item the \texttt{XInclude} namespace is declared somewhere.
\end{enumerate}
 

\begin{lstlisting}[title= Example: how to include databank (excerpt from \texttt{golden} description), breaklines=true, breakatwhitespace=true,
float=h, morekeywords={xi:include, XMLns:xi, href},keywordstyle=\color{red}\textbf]
  <parameters XMLns:xi="http://www.w3.org/2001/XInclude">
    <parameter ismandatory="1" issimple="1" ismaininput="1">
      <name>db</name>
      <prompt lang="en">Database</prompt>
      <type>
        <datatype>
          <class>Choice</class>
        </datatype>
      </type>
      <vdef>
        <value>null</value>
      </vdef>
      <xi:include href="../../Local/Services/Programs/Entities/goldendb.xml">
        <xi:fallback>
          <vlist>
            <velem undef="1">
              <value>null</value>
              <label>Choose a database</label>
            </velem>
          </vlist>
        </xi:fallback>
      </xi:include>
      <format>
        <code proglang="perl">" $db:"</code>
        <code proglang="python">" " + db + ":"</code>
      </format>
      <argpos>2</argpos>
    </parameter>
\end{lstlisting}

\newpage

\label{package_information}
This mechanism is also used to share package information with other program
descriptions belonging to the same package. In the following example, the \texttt{Entities} directory 
(same level as \texttt{Programs}) contains the \texttt{phylip\_package.xml} file shared by all phylip programs 
(\texttt{dnadist}, \texttt{dnapars}, \texttt{protdist}, \texttt{protpars}\dots )

\begin{lstlisting}[title= Example: how to share package information (excerpt from \texttt{dnadist}
\underline{program} description), breaklines=true, breakatwhitespace=true, 
morekeywords={xi:include, XMLns:xi, href},keywordstyle=\color{red}\textbf]
  <head>
    <name>dnadist</name>
    <xi:include XMLns:xi="http://www.w3.org/2001/XInclude" href="Entities/phylip_package.xml"/>
    <doc>
      <title>dnadist</title>
      <description>
        <text lang="en">Compute distance matrix from nucleotide sequences</text>
      </description>
      <doclink>http://bioweb2.pasteur.fr/docs/phylip/doc/dnadist.html</doclink>
      <comment>
        <text lang="en">This program uses nucleotide sequences to compute a distance matrix,
         under four different models of nucleotide substitution. It can also
         compute a table of similarity between the nucleotide sequences. 
         The distance for each pair of species estimates the total branch length
         between the two species, and can be used in the distance matrix programs 
         FITCH, KITSCH or NEIGHBOR.</text> 
      </comment>
    </doc>
    <category>phylogeny:distance</category>
  </head>
\end{lstlisting}

\begin{lstlisting}[title= Example: how to share package information (excerpt from phylip \underline{package} description),
 breaklines=true, breakatwhitespace=true ]
<package>
  <name>phylip</name>
  <version>3.67</version>
  <doc>
    <title>phylip</title>
    <description>
      <text lang="en">PHYLIP is a package of programs for inferring phylogenies.</text>
    </description>
    <homepagelink>http://evolution.gs.washington.edu/phylip.html</homepagelink>
    <sourcelink>http://evolution.gs.washington.edu/phylip/getme.html</sourcelink>
    <authors>Felsenstein Joe</authors>
    <reference>Felsenstein, J. 1993. PHYLIP (Phylogeny Inference Package) version 3.5c. 
    Distributed by the author. 
    Department of Genetics, University of Washington, Seattle.</reference>
    <reference>Felsenstein, J. 1989. PHYLIP -- Phylogeny Inference Package (Version 3.2). 
    Cladistics 5: 164-166.</reference>
    <doclink>http://bioweb2.pasteur.fr/docs/phylip/phylip.html</doclink>  
  </doc>
</package>
\end{lstlisting}

\section{Parameters \label{programs_parameters}}

The \textbf{parameters} element is a direct child of:
\begin{itemize}
 \item either the \textbf{program} element: it includes all the defined \textbf{parameter}s for the program,
 \item or the \textbf{paragraph} element: it defines the \textbf{parameter}s of a given \textbf{paragraph}.
\end{itemize}
It can include:
\begin{itemize}
 \item \textbf{parameter} elements,
 \item nested \textbf{paragraph} elements.
\end{itemize}


\section{Paragraph}

The \textbf{paragraph} element has two functions: 
\begin{enumerate}
 \item it can group the evaluation of different \textbf{parameter}s, with respect to a set of \textbf{precond}itions for instance,
 \item it also groups visually these \textbf{parameter}s in the form. 
\end{enumerate}
\noindent Thus, a \textbf{paragraph} is both a set of \textbf{parameter}s -- visually speaking -- in the submission form and a way to share some properties such as:
\begin{itemize}
  \item \textbf{argpos} elements (see \ref{argpos}) and \textbf{precond} elements (see \ref{precond}).
  \item \textbf{layout} which allows to override the default display of the
  \textbf{parameter}s belonging to a \textbf{paragraph}. The default disposition of the \textbf{parameter}s is a vertical succession, where form \textbf{parameter}s and job results are laid out in the same order as in the program description. 
  The \textbf{layout} tag allows to define horizontal groups (with the \textbf{hbox} tag) and 
  vertical groups (\textbf{vbox} tag) in a recursive structure. Each group had a \textbf{box} element that 
  refers to the corresponding \textbf{parameter} using its \textbf{name}. See the JME description below.
\end{itemize}

\begin{lstlisting}[title=excerpt from JME XML description, breaklines=true, breakatwhitespace=true, float=p,
emph={jme_applet, smiles_input, mol_input}, emphstyle=\color{blue}\texttt,
morekeywords={layout, vbox, hbox}, keywordstyle=\color{red}\textbf]
<paragraph>
  <name>inputs</name>
  <prompt>SMILES/MOL data</prompt>
  <parameters>
    <parameter>
      <name>jme_applet</name>
      <prompt lang="en">Use this applet to edit your SMILES/MOL data</prompt>
      <type>
        <datatype>
          <class>String</class>
        </datatype>
      </type>
      <interface>
         <!-- To improve the readability of the example, 
              a part of the code has been removed.
         -->
      </interface>
    </parameter>
    <parameter>
      <name>smiles_input</name>
      <prompt lang="en">SMILES data</prompt>
      <type>
        <datatype>
          <class>Smiles_structure</class>
          <superclass>AbstractText</superclass>
        </datatype>
      </type>
   </parameter>
   <parameter>
     <name>mol_input</name>
     <prompt lang="en">MOL data</prompt>
     <type>
       <datatype>
         <class>MOL_structure</class>
         <superclass>AbstractText</superclass>
       </datatype>
     </type>
   </parameter>
 </parameters>
 <layout>
   <hbox>
     <box>jme_applet</box>
     <layout>
       <vbox>
         <box>smiles_input</box>
         <box>mol_input</box>
       </vbox>
     </layout>
   </hbox>
 </layout>
</paragraph>
\end{lstlisting}

%\clearpage

\begin{figure}[h]
\includegraphics[width=17cm]{jme_interface.jpeg}
\caption{JME interface}
\end{figure}

\clearpage

\section{Parameter}

The \textbf{parameter} element is an essential piece of the program description. It describes and stores: 
\begin{itemize}
 \item the options,
 \item the inputs,
 \item and the outputs
\end{itemize}
of a program, used to build the command line and retrieve the results.

\subsection{Parameter attributes}

The attributes of the \textbf{parameter} element are:
\begin{itemize}
  \item \textbf{ismandatory}: the \textbf{parameter} must be specified by the user, pointed out by
  a {\color{red}*} next to its prompt in the interface. \underline{Special case}: if the \textbf{parameter} is mandatory and
  if a \textbf{precond} is defined (see below), the \textbf{parameter} becomes mandatory \underline{only if} the result of the
  \textbf{precond}ition is true. These parameters are indicated by a {\color{blue}*}.
  \item \textbf{issimple}: the input parameter is displayed in the \textit{simple} version of the submission form. If there are 
  one or more \textit{simple} parameters in a form, and the Mobyle portal is configured to allow simple forms (see the configuration
  guide), then the form in the portal will only display these parameters by default, and the other parameters will be accessible only
  when clicking on the ``advanced form'' button. Please note that mandatory parameters which have no default value and no precondition
  attached should be set as \textit{simple}, otherwise the service description will not validate. 
  \item \textbf{isout}: the \textbf{parameter} is produced by the program. It is used to retrieve the results. Mobyle
  systematically generates 2 files:
  \begin{itemize}
   \item \texttt{[program name].out}, corresponding to the standard output stream,
   \item \texttt{[program name].err}, corresponding to the standard error stream
  \end{itemize} 
  These two implicit results are automatically shown to the user in the result page if they are not empty
  and are typed as ``Text''.
  \item \textbf{isstdout}: to provide a more explicit or detailed description of the standard output, 
  instead of using the \textbf{isout} attribute, define a \textbf{parameter} element 
  with the desired type and pass it as the value of the attribute \textbf{isstdout}. \textbf{isstdout}
  and \textbf{isout} are mutually \underline{exclusive}. See \textbf{parameter} golden\_out in \texttt{golden.xml} below. Please also note
  that if you specify an \textbf{isstdout} parameter with a precondition, you will need to also specify the standard output parameter for 
  all the cases where this precondition is not met (otherwise the corresponding standard output may not be displayed in the job results).
  \begin{lstlisting}[title=standard output \textbf{parameter} from \texttt{golden.xml}, breaklines=true, breakatwhitespace=true,
 morekeywords={isstdout}, keywordstyle=\color{red}\textbf ]
    <parameter isstdout="1">
      <name>golden_out</name>
      <prompt lang="en">Sequence</prompt>
      <type>
        <biotype>Protein</biotype>
        <biotype>Nucleic</biotype>
        <datatype>
          <class>Sequence</class>
        </datatype>
      </type>
      <filenames>
        <code proglang="perl">"golden.out"</code>
        <code proglang="python">"golden.out"</code>
      </filenames>
    </parameter>
  \end{lstlisting}
  \item \textbf{ishidden}: hides the \textbf{parameter} from the user, as opposed to the input parameters shown to the user in the submission form,
  or to the results captured by the output parameters shown in the job results. 
  When adding a \textbf{parameter} just to control another one, conceal it from the user by setting the attribute \textbf{ishidden} to 1. 
  The value of hidden parameters can't be set by the user. See \textbf{parameter} rateAll in \texttt{seqgen.xml} below.
\newpage
  \begin{lstlisting}[title=hidden \textbf{parameter}, breaklines=true, breakatwhitespace=true, 
morekeywords={ishidden}, keywordstyle=\color{red}\textbf]
<parameter ishidden="1">
  <name>rateAll</name>
  <prompt lang="en">Rates</prompt>
  <type>
    <datatype>
      <class>Float</class>
    </datatype>
  </type>
  <precond>
    <code proglang="perl">$rate1  and $rate2 and $rate</code>
    <code proglang="python">rate1 is not None and rate2 is not None and rate3 is not None</code>
  </precond>
  <format>
    <code proglang="perl">" -c $rate1 $rate2 $rate3"</code>
    <code proglang="python">" -c %f %f %f " %(rate1,rate2,rate3)</code>
  </format>
</parameter>
\end{lstlisting}
\end{itemize}

\subsection{Parameter subelements}

\begin{itemize}

 \item \textbf{name} (\textit{required}): mainly used inside Mobyle to refer to this parameter but not seen by the user in the interface.
  The \textbf{name}:
  \begin{itemize}
   \item has to be \underline{unique among all parameters and paragraphs},
   \item must be a valid python variable name (cannot begin by a number \ldots),
   \item cannot be the name of a javascript property of the HTMLFormElement object, to avoid unexpected behaviors in the portal. Such names
   include \textbf{name}, \textbf{nodeName}, \textbf{length}, etc. For a complete listing of the forbidden values, please refer to the \texttt{Mobyle.sch} file, located 
   in the \texttt{Schema} folder.
  \end{itemize}

 \item \textbf{prompt}: the human-readable label of the parameter that the user can see in the form

 \item \textbf{argpos}\label{argpos} that specifies the position of the parameter in the command line. 
 \begin{itemize}
   \item by convention the \textbf{command} has its \textbf{argpos} set to 0,
   \item if \textbf{argpos} is not specified at the \textbf{parameter} level, takes the \textbf{argpos} of the immediate upper level (\textbf{paragraph}),
   \item \underline{required only if} the order of parameters matters.
 \end{itemize}

 \item a \textbf{precond}\label{precond} which allows to specify under which conditions the \textbf{parameter} must be evaluated. All \textbf{precond}itions are evaluated starting with the \textbf{precond} of the outermost \textbf{paragraph} up to the \textbf{precond} of the innermost nested \textbf{paragraph}, 
 and finally ending with the \textbf{precond} of the \textbf{parameter}. This mechanism allows to refactor \textbf{precond}ition code.

 \item \textbf{format}: the inside code is evaluated to generate the command line. Mobyle uses python code but
 playMoby (\url{http://lipm-bioinfo.toulouse.inra.fr/biomoby/playmoby/}) uses perl code. By default, the result 
 of the code evaluation is used as part of the command line. To write it in a file, in particular
 to simulate the interactive behavior of some programs such as some from the Phylip suite,
 use the element \textbf{paramfile}. See \texttt{pars.xml}, \texttt{protdist.xml}, \texttt{fitch.xml}, \ldots

 \item \textbf{ctrl}: used to specify additional constraints on values provided by the user such as being an integer,
 being odd, not excessing a maximum \ldots. Upon execution, the \textbf{code} is evaluated and the corresponding error \textbf{message}
 is displayed to the user if the result is False. See parameter identity in \texttt{cons.xml} below.

 \item \textbf{vdef}: the default value for the \textbf{parameter}, mandatory for \textbf{vlist} and \textbf{flist} (see \ref{choice_paragraph}).

\end{itemize}

\begin{lstlisting}[title=control a parameter value, breaklines=true, breakatwhitespace=true, float=p,
classoffset=0, morekeywords={ctrl, format}, keywordstyle=\color{red}\textbf,
classoffset=1, morekeywords={code, message}, keywordstyle=\color{blue}\textbf]
<parameter>
  <name>identity</name>
  <prompt lang="en">Required number of identities at a position (value greater than or equal to 0)</prompt>
  <type>
    <datatype>
      <class>Integer</class>
    </datatype>
  </type>
  <vdef>
    <value>0</value>
  </vdef>
  <format>
    <code proglang="python">("", " -identity=" + str(value))[value is not None and value!=vdef]</code>
  </format>
  <ctrl>
    <message>
      <text lang="en">Value greater than or equal to 0 is required</text>
    </message>
    <code proglang="python">value &gt;= 0</code>
  </ctrl>
  <argpos>4</argpos>
  <comment>
    <text lang="en">Provides the facility of setting the required number of identities at a site...</text>
  </comment>
</parameter>
\end{lstlisting}

\subsection{Retrieving results}

A result from a program is a parameter with:
\begin{itemize}
 \item the \textbf{isout}/\textbf{isstdout} attribute set to 1,
 \item a \textbf{filenames} element.
\end{itemize}

Unix masks \label{masks} are defined in the \textbf{filenames} element to create the mapping 
between one or more file names and the parameter. Use them to represent
filenames that cannot be known statically or when the parameter must be mapped 
with several files.

For example, the toppred program can take a file with several 
FASTA protein sequences. In this case, toppred will produce one hydrophobicity 
file per sequence appearing in the input file. The name of each file will be the name of 
the corresponding sequence, suffixed with the \texttt{.hydro} extension.
To retrieve these files, the Unix mask is : ``*.hydro" (e.g. parameter
hydrophobicity\_files in \texttt{toppred.xml}). 

\clearpage
Unix mask are used as follow:
\begin{itemize}
 \item a Unix mask is defined in a \textbf{code} element,
 \item only 1 mask can be defined per \textbf{code} element,
 \item \textbf{filenames} element may have several children \textbf{code} elements 
\end{itemize}
The code is evaluated before being used as Unix mask. 

\begin{lstlisting}[title=how to retrieve results, breaklines=true, breakatwhitespace=true, 
%float=t, 
classoffset=0,morekeywords={filenames, isout}, keywordstyle=\color{red}\textbf,
classoffset=1,morekeywords={code}, keywordstyle=\color{blue}\textbf]
<parameter isout="1"> 
 <name>graphicfiles</name> 
 <prompt lang="en">Graphic output files</prompt>
 <type>
    <datatype> 
      <class>Picture</class>
      <superclass>Binary</superclass>
    </datatype>
    <card>0,n</card>
  </type>
  <precond>
    <code proglang="perl">$graph_output</code>
    <code proglang="python">graph_output == 1</code>
  </precond>
    <filenames>
      <code proglang="perl">*.$profile_format</code>
      <code proglang="python">'*.' + profile_format</code>
    </filenames>
</parameter>
\end{lstlisting}
\noindent The \textbf{comment} and \textbf{example} elements allow to generate in line help and example data for the parameter or paragraph,
very useful as pieces of documentation to the user.
\begin{itemize}
 \item When an help \textbf{comment} is available, a clickable ``{\color{red}?}'' appears beside the prompt.
 \item When an \textbf{example} is available, a ``use example data'' link appears beside the 
parameter. By clicking on it, the user fills automatically the corresponding databox
with this value.
\end{itemize}


\section{Typing \label{typing}}

Choosing the right type for a parameter is an essential point in program
description authoring, as a lot of features are based on types. The typing
influences: 
\begin{itemize}
 \item the interface display,
 \item the controls on user values assigned to the input parameters,
 \item the chaining possibilities between programs and data reusability.
\end{itemize}
In Mobyle, typing is ``multidimensional'', meaning that it's based on several fields:
\begin{itemize}
  \item the \textbf{card} represents the cardinality, \textit{i.e.} the number of distinct
  values that can be set for the parameter.
  \item the \textbf{biotype} \label{biotype} describes the biological object (Nucleic , Protein,
  Drug \ldots). It is not required as some parameters do not represent any
  biological object. The \textbf{biotype} values are free text labels, but to chain the
  data appropriately, they must be recognized so take special care on the spelling and case.
  \item the \textbf{datatype} describes the computing object.
  \item the \textbf{dataFormat} (\textit{new in 1.0}) specifies the format of the data for
  this parameter. If the parameter is an input parameter, it lists the formats
  accepted by the program, hence the formats into which Mobyle must convert (if possible)
  an input parameter value. For instance, the data formats accepted by a Sequence 
  datatype can be FASTA, EMBL, \ldots Several \textbf{dataFormat} elements can be 
  specified. If the parameter is an output one (\textbf{isout}=``1'' or \textbf{isstdout}=``1'') then the
  \textbf{dataFormat} element specifies the format for the result. This information can be
  very useful in order to suggest chaining possibilities, so it's an important 
  information. Sometimes the data format of a result cannot be predetermined but
  can be computed at runtime based on the values of other input parameters set by the user. 
  There are two ways to express this: 
  \begin{enumerate}
   \item to test the value of another parameter,
   \item to reference directly a parameter in \textbf{dataFormat},
  \end{enumerate}
  The two following examples illustrate these possibilities:
  \begin{enumerate}   
  \item  \label{muscle-flist} \begin{lstlisting}[title=\textbf{dataFormat} by testing the value of another parameter (excerpt from \texttt{muscle.xml}), 
breaklines=true, breakatwhitespace=true, emph={outformat, $outformat}, emphstyle=\color{blue}\texttt,
morekeywords={dataFormat, isstdout}, keywordstyle=\color{red}\textbf]
   <parameter>
     <name>outformat</name>
     <prompt lang="en">output format</prompt>
     <type>
       <datatype>
         <class>Choice</class>
       </datatype>
     </type>
     <vdef>
       <value>fasta</value>
     </vdef>
     <flist>
       <felem>
         <value>fasta</value>
         <label>fasta</label>
         <code proglang="perl">""</code>
         <code proglang="python">""</code>
       </felem>
       <felem>
         <value>html</value>
         <label>html</label>
         <code proglang="perl">" -html "</code>
         <code proglang="python">" -html "</code>
       </felem>
       <felem>
         <value>msf</value>
         <label>msf</label>
         <code proglang="perl">" -msf "</code>
         <code proglang="python">" -msf "</code>
       </felem>
       <felem>
         <value>phyi</value>
         <label>phylip</label>
         <code proglang="perl">" -phyi "</code>
         <code proglang="python">" -phyi "</code>
       </felem>
       <!-- it's a clustalw with a muscle header which is not supported by squizz -->
       <felem>
         <value>clw</value>
         <label>muscle format</label>
         <code proglang="perl">" -clw "</code>
         <code proglang="python">" -clw "</code>
       </felem>
       <felem>
         <value>clwstrict</value>
         <label>clustalw 1.81</label>
         <code proglang="perl">" -clwstrict "</code>
         <code proglang="python">" -clwstrict "</code>
       </felem>
     </flist>
     <comment>
       <text lang="en">fasta : Write output in Fasta format</text>
       <text lang="en">html  : Write output in HTML format</text>
       <text lang="en">msf   : Write output in GCG MSF format</text>
       <text lang="en">phylip   : Write output in Phylip (interleaved) format</text>
       <text lang="en">muscle   : Write output in CLUSTALW format with muscle header</text>
       <text lang="en">clustalw : Write output in CLUSTALW format with CLUSTALW 1.81</text>
     </comment>
   </parameter>
        
   <parameter isstdout="1">
     <name>alignmentout</name>
     <prompt lang="en">Alignment</prompt>
     <type>
       <datatype>
         <class>Alignment</class>
       </datatype>
       <dataFormat>
         <test param="outformat" eq="fasta">FASTA</test>
         <test param="outformat" eq="msf">MSF</test>
         <test param="outformat" eq="phyi">PHYLIPI</test>
         <test param="outformat" eq="clwstrict">CLUSTAL</test>
         <test param="outformat" eq="clw">MUSCLE</test>
       </dataFormat>
     </type>
     <precond>
       <code proglang="perl">$outformat =~ /^(fasta|msf|phyi|clwstrict|clw)$/ </code>
       <code proglang="python">outformat in [ 'fasta' , 'msf' , 'phyi' , 'clwstrict' , 'clw'] and outfile is None</code> 
     </precond>
     <filenames>
       <code proglang="perl">"muscle.out"</code>
       <code proglang="python">"muscle.out"</code>
     </filenames>
   </parameter>
   \end{lstlisting} 
   The user specifies the format \texttt{muscle} must use to output the alignment result with
   the first parameter ``outformat''. The second parameter ``alignmentout''
   captures the alignment result. The \textbf{dataFormat} of ``alignmentout'' is set by testing the value of
   the parameter ``outformat". To test a value we have a set of operators:
   \begin{itemize}
     \item \textbf{eq}: equal.
     \item \textbf{ne}: not equal.
     \item \textbf{lt}: less than.
     \item \textbf{gt}: greater than.
     \item \textbf{le}: less or equal than.
     \item \textbf{ge}: greater or equal than.
   \end{itemize}

   \item \label{clustalw-multialign-vlist} \begin{lstlisting}[title=\textbf{dataFormat} by referencing another parameter (excerpt from \texttt{clustalw-multialign.xml}), 
emph={outputformat, $outputformat},emphstyle=\color{blue}\texttt,
breaklines=true, breakatwhitespace=true, morekeywords={dataFormat, isout}, keywordstyle=\color{red}\textbf]
   <parameter>
     <name>outputformat</name>
     <prompt lang="en">Output format (-output)</prompt>
     <type>
       <datatype>
         <class>Choice</class>
       </datatype>
     </type>
     <vdef>
       <value>null</value>
     </vdef>
     <vlist>
       <velem undef="1">
         <value>null</value>
         <label>CLUSTAL</label>
       </velem>
       <velem>
         <value>FASTA</value>
         <label>FASTA</label>
       </velem>
       <velem>
         <value>GCG</value>
         <label>GCG</label>
       </velem>
       <velem>
         <value>GDE</value>
         <label>GDE</label>
       </velem>
       <velem>
         <value>PHYLIP</value>
         <label>PHYLIP</label>
       </velem>
       <velem>
         <value>PIR</value>
         <label>PIR</label>
       </velem>
       <velem>
         <value>NEXUS</value>
         <label>NEXUS</label>
       </velem>
     </vlist>
     <format>
       <code proglang="perl">(defined $value ) ? " -output=$value" : ""</code>
       <code proglang="python">( "" , " -output=" + str( value) )[ value is not None ]</code>
     </format>
   </parameter>
        
   <parameter isout="1">
     <name>aligfile</name>
     <prompt>Alignment file</prompt>
     <type>
       <datatype>
         <class>Alignment</class>
       </datatype>
       <dataFormat>
         <ref param="outputformat"/>
       </dataFormat>
     </type>
     <precond>
       <code proglang="perl">$outputformat =~ /^(NEXUS|GCG|PHYLIP|FASTA)$/</code>
       <code proglang="python">outputformat in [ "FASTA", "NEXUS", "GCG", "PHYLIP"]</code>
     </precond>
     <filenames>
       <code proglang="perl">(defined $outfile)? ( $outputformat eq 'GCG' )? ( $outputformat eq 'PHYLIP' )?"$outfile":"*.msf" : "*.phy" : "*.nxs"</code>
       <code proglang="python">{ "FASTA":"*.fasta", "NEXUS": "*.nxs", "PHYLIP": "*.phy" , 'GCG': '*.msf' }[ outputformat ]</code>
     </filenames>
   </parameter>     
   \end{lstlisting}
   The user specifies the format in which \texttt{clustalw} will produce the result
   with the first parameter ``outputformat''. The value of this parameter also becomes
   the \textbf{dataFormat} of the second parameter ``aligfile'' which is the parameter
   to capture the alignment.
   \end{enumerate}
\end{itemize}


\subsection{Mobyle DataTypes Tour}

\paragraph{Simple datatypes}

Simple datatypes characterize the parameters which are used to configure the jobs, and are used to generate the command line (or the paramfiles). They do not represent \textit{per se} scientifically meaningful data, and cannot be bookmarked and reused. Parameters which have a ``simple`` datatype are displayed as ``simple`` form controls (text input, select box, radio button, etc...).

\subparagraph{Boolean}
Represents boolean values. \underline{None value special case}: 
for boolean, a None value means False whereas for all other types it means undefined.

\subparagraph{Integer}
Represents integer values.

\subparagraph{Float}
Represents float values.

\subparagraph{String}
Represents string values. Since these strings will be on the command line, for
security reasons some values are not allowed. The acceptable characters are
alphanumerical words, spaces, quotes, plus and minus, single dots. 2 or more 
dots in a row are forbidden. 

This restriction could be problematic for some programs e.g: \texttt{fuzznuc}, \texttt{fuzzpro},
\texttt{fuzztran}, \ldots Indeed, these programs, from the EMBOSS suite, allow to search
patterns in sequences using a grammar using characters 
such as \texttt{[}, \texttt{]} or \texttt{*} forbidden in Mobyle.
If the parameter used to specify the pattern is typed as string, many
patterns won't be accepted. One possibility, when available, is to specify this
kind of value in a file. The special characters will not appear on the command
line and are thus allowed in Text parameter.

\subparagraph{Choice}\label{choice_paragraph}
Appears as a select list in the interface. The list can be:
\begin{itemize}
 \item a \textbf{vlist} containing predefined entries,
 \item a \textbf{flist} containing entries computed on the fly.
\end{itemize}

A \emph{\textbf{vlist}} element contains 2 or more \textbf{velem} elements. Each of them allows 
to define a new entry consisting of: 
\begin{enumerate}
 \item a \textbf{value} that will be assigned to the variable \texttt{\$value}, unless \textbf{undef}='1',
 \item a \textbf{label} meaningful to the user.
\end{enumerate}
The  \textbf{undef} attribute is used to indicate
that the \textbf{value} of the \textbf{velem} element must be considered as undefined.
In the description of \texttt{clustalw-multialign} (see \ref{clustalw-multialign-vlist}), the block
\begin{lstlisting}
  <velem undef="1">
    <value>null</value>
    <label>CLUSTAL</label>
  </velem>
\end{lstlisting}
means that if ``CLUSTAL'' is chosen, the variable \texttt{\$value} is not defined.
In that case, given the \textbf{code} element:
\begin{lstlisting}
<code proglang="python">( "" , " -output=" + str( value) )[ value is not None ]</code>
\end{lstlisting}
the \texttt{-output=} won't appear in the command line.

To force the user to consciously choose an entry:
\begin{enumerate}
 \item set the \textbf{ismandatory} attribute to 1 for the \textbf{parameter},
 \item set the \textbf{vdef} to ``null'',
 \item put as first \textbf{velem} of the \textbf{vlist} something like:
\begin{lstlisting}
  <velem undef="1">
    <value>null</value>
    <label>Choose a value</label>
  </velem>
\end{lstlisting}
\end{enumerate}

An \emph{\textbf{flist}} element contains \textbf{felem} subelements instead of \textbf{velem} elements. It obeys the same mechanisms as the \textbf{vlist}, but instead of specifying the command line (or \textbf{paramfile}) code in a \textbf{format} element, the evaluated code is specified for each corresponding felem item in a \textbf{code} element. Its main purpose is to facilitate the construction of the command line, as the choice between the different codes requires nested \textit{if} conditions if the more than two values are possible. Hence, the \textbf{flist} and \textbf{format} elements are mutually exclusive in a \textbf{parameter} element.

\begin{lstlisting}[title=flist evaluates three different python expressions to generate the command line depending on the chosen value (excerpt from
targetp.xml), emph={outputformat, $outputformat},emphstyle=\color{blue}\texttt,
breaklines=true, breakatwhitespace=true, morekeywords={dataFormat, isout}, keywordstyle=\color{red}\textbf]
          <flist>
            <felem undef="1">
              <value>null</value>
              <label>no cutoffs; winner-takes-all (default)</label>
              <code proglang="perl">''</code>
              <code proglang="python">''</code>
            </felem>
            <felem>
              <value>cutoff_95</value>
              <label>specificity &gt;0.95</label>
              <code proglang="perl">( $type eq 'p')? " -p 0.73 -t 0.86 -s 0.43 -o 0.84 " : " -t 0.78 -s 0.00 -o 0.73 "</code>
              <code proglang="python">( " -t 0.78 -s 0.00 -o 0.73 " , " -p 0.73 -t 0.86 -s 0.43 -o 0.84 " )[ type == 'p' ]</code>
            </felem>
            <felem>
              <value>cutoff_90</value>
              <label>specificity &gt;0.90</label>
              <code proglang="perl">( $type eq 'p')? " -p 0.62 -t 0.76 -s 0.00 -o 0.53 " : " -t 0.65 -s 0.00 -o 0.52 "</code>
              <code proglang="python">( " -t 0.65 -s 0.00 -o 0.52 " , " -p 0.62 -t 0.76 -s 0.00 -o 0.53 " )[ type == 'p' ]</code>
            </felem>
          </flist>
\end{lstlisting}

\subparagraph{MultipleChoice}
Similar to the Choice datatype but represented as a select box
where several values can be selected at once by holding the appropriate key. 
The selected values appear on the command line separated by the value of the \textbf{separator} element.

\subparagraph{Filename}
Generally used to specify a result file name when the program 
offers the corresponding option. For security reasons, the
user values \texttt{\# " ' $<$ $>$ \& * ; \$ ` $|$ ( ) [ ] \{ \} ?}  are not allowed.

\paragraph{File-based datatypes}

File-based datatypes characterize all the parameters and user data that are stored as files. Such data are very diverse, spanning from simple analysis reports to sequence data. They are displayed in the job submission forms using a specific component, the databox, which facilitates the load and reuse of data across analyses.

\subparagraph{AbstractText}
Should not be used directly as a datatype class in Mobyle, it only represents any text file that should not be included in chaining options that are associated with .Created to avoid unwanted inheritances. Should only appear as the value of the \textbf{superclass} element of an actual type.

\subparagraph{Text}
Handles ``generic`` text files. Before writing the data, the content is cleaned up, \textit{i.e.} the windows end-of-line
$\backslash n\backslash r$ are replaced by Unix $\backslash n$.
Moreover, some characters of the file name ( \texttt{\# " ' $<$ $>$ \& * ; \$ ` $|$ ( ) [ ] \{ \} ?} ) 
are replaced by \texttt{\_} for security reasons. If an input parameter is typed as
\textbf{Text} a lot of outputs will be potentially chained to this parameter.
Please use a more specific type if possible.

\subparagraph{Binary}
Handles ''binary'' data files. A good example of the use of binary files as input data is in the \textbf{abiview} description: the input of EMBOSS abiview is an ABI trace. Of course the content is not ``cleaned''.

\subparagraph{Sequence}
Handles any text-based sequence format, such as FASTA, Uniprot, \ldots A sequence converter based on \texttt{squizz} is already provided as a plug-in (but of course requires that you install squizz). Unlike in some previous Mobyle versions, the \texttt{readseq} support is no longer provided. 
In case you wish to use \texttt{readseq} or any other format conversion tool instead of \texttt{squizz}, you can write a python wrapper to handle it. For more information about format converters, please refer to the ``Data converter management`` section of the Mobyle configuration guide.
Usually, the parameter of ``Sequence'' datatype also defines several \textbf{dataFormat} corresponding to the formats handled natively by the program.
If the format of the provided data is detected and does not match any of the formats handled by the program, Mobyle will try to convert the data into one of them, by sequentially testing the capabilities of the converters to convert the data.

\subparagraph{Alignment}
Handles its data almost identically to the ``Sequence'' type, but represents an sequence alignment and has its own formats.

\subparagraph{Tree}
Represents a phylogenetic tree. Does not implement any specific processing for now.

\subparagraph{Report}
Designed to handle generic programs text results, if those are not handled by a more specific type.

\subsection{XML DataTypes}
The Mobyle DataTypes are based on python classes (in \texttt{Src/Mobyle/Classes)}. This
system offers some powerful features such as inheritance, but has some
limitations. Indeed, given that the chaining between two parameters is based on the
type, a python class should be written for each type of data to avoid irrelevant
chaining. In the bioinformatics field, the number of datatypes is too large to
manage such a list. That's why a mechanism to define a new datatype on the fly, 
called ``XML typing'', is also available. When ``XML typing'', a \textbf{class} element 
and a \texttt{superclass} element must be added in the program description. Beware: 
\begin{itemize}
 \item the \textbf{class} element is the new desired datatype,
 \item the \textbf{superclass} element refers to a Mobyle python DataType class
\end{itemize}
The desired datatype is thus considered as a subtype, for features such as programs chaining
(appearing as a new datatype), but it is handled like its parent Mobyle python class
for conversion and validation steps. For consistency reasons, when a same ``XML data
type'' is defined in different parameters, it can't refer to different Mobyle python classes. 
In  other words, if the \textbf{class} element is identical among 2 parameters, 
the \texttt{superclass} element must be identical too.

\subsection{Chaining}

The Mobyle system provides a suggestion mechanism allowing users to use data in a defined set of programs:
\begin{itemize}
 \item either by proposing in the form the data from the user's workspace that are compatible with the parameter,
 \item or by letting the user interactively chains the result of a job to another program form.
\end{itemize}
In the following, ``source'' stands for a result or any bookmarked data, and the ``target'' is the parameter of 
the service in which this data is about to be used. The selection of the programs and input parameters
that can accept a source is based on type compatibility: 
\begin{itemize}
 \item the datatype of the input of the target parameter has to be the same as the one of the source or a superclass of it,
 \item besides, if biotypes (see \ref{biotype}) have been defined in the output and input parameters, one of the 
 source's biotypes has to be included in the biotypes of the target parameter,
 \item finally, the ``dataFormat'' of the source and target have to be either directly or indirectly compatible:
 if the source and the target have specified data formats, the source data format must be in the list of target
 data formats or be convertible to one of the target's accepted data formats using one of the data converters configured
 on the portal.
\end{itemize}

\subsection{Extending Mobyle DataTypes}

The Mobyle python DataType can be extended by coding new classes. Any new class must :
\begin{enumerate}
 \item inherit from the DataType class or from another class which inherits from DataType,
 \item implement at least 2 public methods, \textbf{``convert''} and \textbf{``validate''}, following
the API defined in DataTypeTemplate (see \texttt{Core.py}).
\end{enumerate}
To be able to use the new datatypes in program descriptions
the same way as those provided in \texttt{Src/Mobyle/Classes}, don't forget:
\begin{enumerate}
 \item to put the new modules in \texttt{Local/CustomClasses} to prevent them from being erased during further updates,
 \item to add the new classes in the \texttt{\_\_init\_\_.py}.
\end{enumerate}

\section{Output}
Mobyle can handle results only if they are stored as files. Once a job is
completed, the different output \textbf{parameter}s are evaluated by applying the
\textbf{filename} masks (see \ref{masks}) on the job directory to list the corresponding
result files. Given that the output \textbf{parameter}s have a \textbf{datatype}, the mapping 
between output \textbf{parameter}s and result files is a way to type the results.
As said in \ref{typing}, typing is essential for chaining and data reusability.

\section{Parameter display customization}

The default display of a parameter is, \textit{by default}, automatically generated based on its characteristics (type, value
range \ldots). However, this default display can be overridden to specify custom HTML code which will be used to layout specific 
\textbf{parameter}s, \textbf{paragraphs}, or even all of them. It is advised to use this possibility with extreme caution, and 
carefully test the resulting interfaces, to avoid potential problems raised by the interference between the custom HTML code and 
the Mobyle portal client code (HTML, javascript, etc.).

The interface can customize for each input parameter its layout in the form or in the job summary page (where parameters which 
have been filled by the user will be displayed), and for each result its layout in the job summary page. Each of these possibilities
can be specified by adding an \textbf{interface} tag with a \textbf{type} attribute set to:
\begin{itemize}
 \item \textbf{form} for input parameters control display in service forms,
 \item \textbf{job\_input} for input parameters value display in job summaries,
 \item \textbf{job\_output} for result value display in job summaries.
\end{itemize}

The contents of the interface tag must be one or more xhtml elements, and the xhtml namespace must be declared accordingly in each
 of them, using the \textbf{xmlns="http://www.w3.org/1999/xhtml"} namespace declaration. Otherwise, your service description file 
will not be valid.

To specify where data values and URLs should be placed in job summaries (either inputs or outputs), the following keywords can be used 
in the interface tag:
\begin{itemize}
 \item \textbf{data-value} which specifies the value of the parameter (a string for XML-stored ``simple'' types, the file name for file-stored data),
 \item \textbf{data-url} which specifies the complete URL of the result for file stored data, i.e. \texttt{the job id + '/' + the file name}.
\end{itemize}
These keywords can be placed in any text or attribute value. To handle multiple values (e.g., multiple outputs), the father element of the attribute or
text node where the keyword is placed is repeated for each parameter value.

Here are a few examples:
\begin{lstlisting}[title=program input string control display override in the service form, 
breaklines=true, breakatwhitespace=true,  emph={name="toto"}, emphstyle=\color{blue}\texttt,
classoffset=0, morekeywords={interface}, keywordstyle=\color{red}\textbf]
<interface type="form">
<div xmlns="http://www.w3.org/1999/xhtml">
<b>use this parameter to tweak something somewhere</b>
<input name="toto" value="default value of the toto parameter"/>
</div>
</interface>
\end{lstlisting}

\begin{lstlisting}[title=program input string value display override in the job summary, 
breaklines=true, breakatwhitespace=true,  emph={data-value}, emphstyle=\color{blue}\texttt,
classoffset=0, morekeywords={interface}, keywordstyle=\color{red}\textbf]
<interface type="job_input">
  <h1 xmlns="http://www.w3.org/1999/xhtml">This is the value of this input: data-value</h1>
</interface>
\end{lstlisting}

\begin{lstlisting}[title=job output value (file) display override in the job summary, 
breaklines=true, breakatwhitespace=true,  emph={data-url}, emphstyle=\color{blue}\texttt,
classoffset=0, morekeywords={interface}, keywordstyle=\color{red}\textbf]
<interface type="job_output">
  <div xmlns="http://www.w3.org/1999/xhtml">
    <img src="data-url" alt="preview" width="500px" height="500px"/>
  </div>
</interface>
\end{lstlisting}

\newpage

\chapter{Writing a workflow description (\textit{new in 1.0}) }

A workflow is an ordered sequence of connected \textbf{task}s. Each \textbf{task} can be a
program or a workflow. The root element of a workflow is the \textbf{workflow} tag. 
A workflow description is divided into 3 parts:
\begin{itemize}
  \item \textbf{head} describes some generalities about the workflow.
  \item \textbf{flow} describes the different tasks and how to connect them.
  \item \textbf{parameters} describes the parameters of the workflow, 
  that is to say the parameters that the user can/must specify as inputs of the
  workflow and the results of the workflow.
\end{itemize}

The following phylogeny workflow:\label{phylogeny_wf}
\begin{enumerate}
 \item performs a multiple alignment,
 \item used to compute a distance matrix,
 \item to finally build a tree using the neighbor joining method.
\end{enumerate}
It is used as an example to illustrate this section.

\section{Head} 
Contains the same information as programs \textbf{head} (see \ref{programs_head}), minus all the command-line
execution-specific elements (\textbf{command} and \textbf{env}).

\section{Parameters \label{wf_parameters}}

This section describes the input parameters that the user must/can specify, and
the results of a workflow. Of course each \textbf{task} remains accessible and all
intermediate results are easily accessible. The ``results`` of the workflow
indicates which outputs are presented to the user as final results. Workflow
\textbf{parameter} elements contain the same information as program \textbf{parameter} elements
(see \ref{programs_parameters}). However, some elements are irrelevant in 
a workflow context, i.e, all the command-line execution-specific elements: 
\textbf{format}, \textbf{flist}, \textbf{argpos}, \textbf{paramfile}. 
Nevertheless, \textbf{datatype} and \textbf{dataFormat} specification remains very important 
to be able to reuse a result or visualize it with a viewer (see \ref{viewers}) in Mobyle.
For instance, if the \texttt{archeopteryx} viewer has been deployed, it can be used
to visualize the result of the phylogeny workflow defined above since the \textbf{parameter} 2 
is typed as ``Tree''.

\begin{lstlisting}[title= parameters part of a phylogeny workflow, 
breaklines=true, breakatwhitespace=true, 
classoffset=0, morekeywords={parameter, id, isout}, keywordstyle=\color{red}\textbf]
  <parameters>
    <parameter id="1">
      <name>sequences</name>
      <prompt>Input sequences</prompt>
      <type>
        <datatype>
          <class>Sequence</class>
        </datatype>
        <biotype>Protein</biotype>
      </type>
    </parameter>
    <parameter id="2" isout="1">
      <name>tree</name>
      <prompt>Phylogenetic Tree</prompt>
      <type>
        <datatype>
          <class>Tree</class>
        </datatype>
        <biotype>Protein</biotype>
      </type>
    </parameter>
  </parameters>
\end{lstlisting}
The parameter with \textbf{id}=``1'' is the input of the workflow, whereas the parameter
with \textbf{id}=``2'' with its attribute \textbf{isout}=``1'' represents the result of the workflow.

\section{Flow}
Is divided in two parts:  
\begin{itemize}
 \item \textbf{task},
 \item \textbf{link}.
\end{itemize}

\subsection{Task} 
A \textbf{task} element has the following attributes:
\begin{itemize}
\item \textbf{id} (\textit{required}): a unique label allowing to identify
each \textbf{task} in the workflow
\item \textbf{service} (\textit{required}): the name of a program or workflow
\item \textbf{suspend}: an attribute with 2 allowed values ``true'' and ``false''. If \textbf{suspend} is true,
the workflow will be suspended at the end of the task and will wait for an action from
the user to resume. This allows the user to check intermediate results and
decide if he wants to resume or cancel the workflow.
\item \textbf{description}: a one-sentence-description of the task.
\item \textbf{inputValue}: allows to specify some values for some \textbf{parameter}s of the \textbf{task} (program or
workflow). This tag is used to specify a value:
\begin{itemize}
 \item because the \textbf{parameter}'s attribute \textbf{ismandatory}=``1''
 \item to replace the default value \textbf{vdef} of the \textbf{parameter}.
\end{itemize}
The \textbf{name} attribute is used to refer to the \textbf{parameter}. Thus 
use a new \textbf{inputValue} element for each \textbf{parameter} to set.
\begin{lstlisting}[title= tasks section of phylogeny workflow, breaklines=true, breakatwhitespace=true, 
classoffset=0, morekeywords={task, id, service, suspend}, keywordstyle=\color{red}\textbf,
classoffset=1, morekeywords={inputValue, name}, keywordstyle=\color{blue}\textbf] 
    <task id="1" service="clustalw-multialign" suspend="false">
      <description>Align the sequences using Clustal-W</description>
      <inputValue name="outputformat">PHYLIP</inputValue>
    </task>
    <task id="2" service="protdist" suspend="true">
      <description>Compute my distance matrix</description>
    </task>
    <task id="3" service="neighbor" suspend="false">
      <description>Perform neighbor-joining</description>
    </task>
\end{lstlisting}
The \textbf{task} with \textbf{id} ``1'' refers to the \texttt{clustalw-multialign} program 
which \textbf{parameter} ``outputformat'' has ``PHYLIP'' as value. 
Of course, all files produced by the \texttt{clustalw-multialign}, \texttt{protdist} and
\texttt{neighbor-joining} \textbf{task}s remain accessible.
\end{itemize}

\subsection{Link}
This is an important part of the workflow design. It describes how to connect 
the different \textbf{task}s. All connections must be explicit. Each \textbf{link} is 
directional and joins two points, a source and a destination. \\

The source must be:
\begin{description}
 \item[\textit{case 1}] an input \textbf{parameter} of the workflow (see \ref{wf_parameters})
 \item[\textit{case 2}] a \textbf{parameter} of a \textbf{task}.
\end{description}

The source is unambiguously pointed out: 
\begin{description}
 \item[\textit{in case 1}] by a workflow's input \textbf{parameter}'s \textbf{id}
assigned to the \textcolor{blue}{\textbf{fromParameter}} attribute,
 \item[\textit{in case 2}] by the combination of:
  \begin{enumerate} 
   \item a \textbf{parameter}'s \textbf{name} assigned to the \textcolor{blue}{\textbf{fromParameter}} attribute,
   \item a \textbf{task}'s \textbf{id} assigned to the \textcolor{blue}{\textbf{fromTask}} attribute.
  \end{enumerate}
\end{description}

The destination must be:
\begin{description}
 \item[\textit{case 1}] an output \textbf{parameter} of the workflow (see \ref{wf_parameters}) 
 \item[\textit{case 2}] a parameter of a \textbf{task}.
\end{description}

The destination is unambiguously pointed out: 
\begin{description}
 \item[\textit{in case 1}] by a workflow's output \textbf{parameter}'s \textbf{id} assigned to the \textcolor{red}{\textbf{toParameter}} 
attribute, 
 \item[\textit{in case 2}] by the combination of:
\begin{enumerate}
 \item a \textbf{parameter}'s \textbf{name} assigned to the \textcolor{red}{\textbf{toParameter}} attribute
 \item a \textbf{task}'s \textbf{id} assigned to the \textcolor{red}{\textbf{toTask}} attribute.
\end{enumerate}
\end{description}
 
\begin{lstlisting}[title= Example of workflow connections, breaklines=true, breakatwhitespace=true, 
classoffset=0, morekeywords={fromTask, fromParameter}, keywordstyle=\color{blue}\textbf,
classoffset=1, morekeywords={toTask, toParameter}, keywordstyle=\color{red}\textbf]
  <link toTask="1" fromParameter="1" toParameter="infile"/>
  <link fromTask="1" toTask="2" fromParameter="aligfile" toParameter="infile"/>
  <link fromTask="2" toTask="3" fromParameter="outfile" toParameter="infile"/>
  <link fromTask="3" fromParameter="treefile" toParameter="2"/>
\end{lstlisting}
\begin{itemize}
  \item The first  \textbf{link} element indicates that the  \textbf{parameter} with  \textbf{id}=``1'' from
 the workflow will be sent into the  \textbf{parameter} named ``infile'' from the \textbf{task} with  \textbf{id}
=``1''.
  \item The second \textbf{link} element indicates that the \textbf{parameter} named ``aligfile''
 from the \textbf{task} with \textbf{id}=``1'' will be sent into the \textbf{parameter} named ``infile'' of the \textbf{task}
with \textbf{id}=``2''.
  \item The last \textbf{link} element indicates that the \textbf{parameter} named ``treefile'' of
  the \textbf{task} with \textbf{id}=``3'' will be sent into the \textbf{parameter} with \textbf{id}=``2'' of the
workflow. This means that it's a result of the workflow.
\end{itemize}


\newpage

\chapter{Writing a viewer/widget description (\textit{important updates in version 1.0.5}) \label{viewers} }


Viewers are a way to embed type-dependent visualization components for the data
displayed in the Mobyle portal. Viewers easily overcome the limitations of the basic 
text-based data previews offered by Mobyle. These XML
files provide a way to incorporate custom interface code to display data of a
given type in the browser. Such custom interfaces can incorporate HTML-embeddable 
components such as Java applets, Flash applets or Javascript code. For instance, using 
viewers, the Jalview component can automatically be included wherever it is relevant,
so that the user can immediately visualize the results of multiple alignment programs 
such as ClustalW or Muscle in the portal. 

\textbf{As of version 1.0.5,} these widgets now also offer the possibility 
to bookmark the edited data back to the portal.

A viewer is composed of two elements:
\begin{enumerate}
 \item an XML description in many points similar to program descriptions
 \item a set of dependencies, which are client-required files stored in a directory
 (e.g., jar files for a Java applet).
\end{enumerate}

The root element of a viewer description is the \textbf{viewer} tag (instead of the previously-cited 
\textbf{program} or \textbf{workflow} tags). It is divided in two parts: 
\begin{itemize}
  \item the \textbf{head} (\textit{required}) which describes some generalities
  about the viewer and how to display it.
  \item the \textbf{parameters} (\textit{required}) which describes (1) the kind
  of data Mobyle can apply the viewer to, and (2) the data that can be extracted back (if possible)
  from the viewer.
\end{itemize}
 
\section{Head}
Contains the same information as a program, 
minus invocation-specific elements such as \textbf{command}, \textbf{env}, etc\ldots In addition to this, 
the author can provide the viewer XHTML template, although it is now possible and recommended to specify each part
of it at the parameter level since version 1.0.5.

\section{Parameters}
The \textbf{parameters} section contains all the input and output parameters that will be used by the component to,
generate the visualization and handle bookmarking. It's very similar to the \textbf{program parameters}, minus the 
server-side invocation details.

\subsection{Input parameters: displaying/loading the data}
Input parameters represent the data that are displayed in the viewer/widget, and may provide, in addition to the common elements of input parameters, 
the viewer XHTML template. Please note that as an alternative to providing the XHTML template for parts of the viewer at each parameter's level, 
it is also possible to provide a global template in the viewer head element (this is the only way which was supported up to version 1.0.4). More details
describing how to write this template are given in the Jalview example section (\ref{jalview}).

\subsection{Output parameters: bookmarking and chaining the edited data}
Output parameters represent the data edited in the viewer/widget that can be bookmarked in the user's Mobyle workspace (or directly chained to another service).
They include all the common elements of an output (isout) parameter, with the addition of a javascript code chunk that specifies how to communicate with the embedded
component to retrieve the edited data. 

\section{Example: Jalview}\label{jalview}
Jalview is a component allowing to graphically display, explore and analyze multiple sequence alignments.
The aim of this viewer is to enable users to visualize any compatible multiple alignment data. 
``Compatible'' means that the file format of the output alignment is compatible with those accepted by the \texttt{Jalview} applet.
The \texttt{jalview.xml} file is provided in the \texttt{pasteur-viewers} descriptions package.

\begin{lstlisting}[title={ \texttt{jalview.xml} file}, breaklines=true, breakatwhitespace=true,
classoffset=0, morekeywords={data-parametername}, keywordstyle=\color{red}\textbf,
emph={aligfile, data-url}, emphstyle=\color{blue}\texttt]
<viewer>
  <head>
    <name>jalview</name>
    <version>2.7</version>
[...]
  </head>
[...]
  <parameters>
    <parameter>
    <!-- this is the description of the input alignment file -->
      <name>aligfile</name>
      <prompt>Alignment file</prompt>
      <type>
	<datatype>
	  <class>Alignment</class>
	</datatype>
	<!-- below the list of the alignment formats accepted by Jalview -->
	<dataFormat>FASTA</dataFormat>
	<dataFormat>GCG</dataFormat>
	<dataFormat>CLUSTAL</dataFormat>
	<dataFormat>PIR</dataFormat>
	<dataFormat>STOCKHOLM</dataFormat>
      </type>
      <!-- below the XHTML template that allows to embed Jalview -->
      <interface type="viewer">
	<!-- template keyword viewer-codebase is automatically translated to the URL of the viewer/widget's dependencies, that here contains the jalviewApplet.jar file -->
	<applet xmlns="http://www.w3.org/1999/xhtml" codebase="viewer-codebase" name="Jalview" code="jalview.bin.JalviewLite" archive="jalviewApplet.jar" width="100%" height="100%" id="jalview_applet">
	  <!-- template keyword data-parametername specifies which parameter this element is processing, here aligfile -->
	  <!-- template keyword data-url is automatically replaced by the url of the parameter data that have to be loaded -->
	  <param data-parametername="aligfile" name="file" value="data-url"/>
	  <param name="embedded" value="true"/>
	  <param name="linkUrl_1" value=""/>
	  <param name="srsServer" value=""/>
	</applet>
      </interface>
    </parameter>
    <parameter isout="1">
    <!-- this is the description of the edited alignment retrievable in the FASTA format -->
      <name>edited_fasta_alignment</name>
      <prompt>Edited FASTA alignment</prompt>
      <type>
	<datatype>
	  <class>Alignment</class>
	</datatype>
	<dataFormat>FASTA</dataFormat>
      </type>
      <format base64encoded="false">
	<!-- this is the code which will be used by the portal to retrieve the data -->
        <!-- the base64encoded attribute above is used to specify wether the retrieved -->
	<!-- data is text-based or binary and base64encoded -->
	<code proglang="javascript">$('jalview_applet').getAlignment('fasta')</code>
      </format>
    </parameter>
[...]
  </parameters>
</viewer>
\end{lstlisting}

\subsection{Chaining in}
Given that in this example:
\begin{itemize} 
 \item the \textbf{datatype} of the input \textbf{parameter} ``aligfile'' is ``Alignment''
 \item the \textbf{dataFormat} of the input \textbf{parameter} ``aligfile'' is ``FASTA''
\end{itemize}
the portal offers to visualize any FASTA alignment file with Jalview by providing 
an additional ``Jalview'' button in the web interface. Clicking on that button triggers
 the display of the Jalview alignment in a modal dialog box.

\subsection{Chaining out}
The edited\_fasta\_alignment output parameter is translated in the portal as a ``bookmark/pipe'' component. Clicking
it, as for other services, bookmarks or pipes the edited alignment in the FASTA format.

\chapter{Writing a tutorial description (\textit{new in version 1.5}) \label{tutorials} }
 
These XML files provide a way to incorporate custom web pages in the tutorials section of Mobyle portal that provide additional help or information on the usage of the portal and the available services.

A tutorial is composed of one or two elements:
\begin{enumerate}
 \item an XML description in many points similar to program descriptions.
 \item a set of dependencies, which may be required to display the tutorial and stored locally. these files (e.g., pictures, movies, \ldots) are stored in a directory.
\end{enumerate}

The root element of a tutorial description is the \textbf{tutorial} tag (instead of the previously-cited 
\textbf{program}, \textbf{workflow} or \textbf{viewers} tags). It only contains a head part.

\section{Head}

Contains the same information as a program, minus invocation-specific elements such as \textbf{command}, \textbf{env},\ldots. But the element \textbf{interface} with a \textbf{type} attribute set to ``tutorials'' is required.
The contents of the interface tag must be one or more xhtml elements, and the xhtml namespace must be declared accordingly in each of them, using the \textbf{xmlns="http://www.w3.org/1999/xhtml"} namespace declaration. Otherwise, your service description file will not be valid.

Here are a few examples:
\begin{lstlisting}[title=tutorial based on simple xhtml page, 
breaklines=true, breakatwhitespace=true, emphstyle=\color{blue}\texttt,
classoffset=0, morekeywords={interface}, keywordstyle=\color{red}\textbf]
<tutorial>
   <head>
      <name>seqfmt</name>
      <version>1.0</version>
      <doc>
         <title>Sequences formats</title>
         <description>
            <text lang="en">common used formats for sequences</text>
         </description>
         <authors>N. Joly</authors>
      </doc>
      <interface type="tutorial">
         <div xmlns="http://www.w3.org/1999/xhtml">
            <p>This document illustrates some common formats used for sequences representation.</p>
            <dl>
               <dt>
                  <strong>
                     <a name="embl" class="item">
                        <strong>EMBL</strong>
                     </a>
                  </strong>
               </dt>

               <dd>
                  <pre>ID MMVASPHOS standard; RNA; EST; 140 BP.
                     AC X97897;
                     DE M.musculus mRNA for protein homologous to
                     DE vasodilator-stimulated phosphoprotein
                     SQ Sequence 140 BP; 25 A; 58 C; 39 G; 17 T; 1 other;
                     ttctcccaga agctgactct atggngaccc cgagagagac tgagcagaac 60
                     ccccgcaccc ctgcacttcc aatcaggggc gccccgggag cactccccgt 120
                     ccgccctccg cgcagccatg 140
                     //
                  </pre>
               </dd>
             </dl>
           </div>
       </interface>
    </head>
</tutorial>       
\end{lstlisting}

The tutorial can use extra materials as pictures or movies. These dependencies, if stored locally, must be placed in a directory with the same name as the xml description
(minus the extension). In the xml to refer to these extra-materials you must use "tutorial-codebase'' as root for the src path.
The following example displays a picture in a tutorial:
\begin{lstlisting}[title=tutorial based on simple xhtml page, 
breaklines=true, breakatwhitespace=true, emph={name="tutorial-codebase"}, emphstyle=\color{blue}\texttt,
classoffset=0, morekeywords={interface}, keywordstyle=\color{red}\textbf]
<tutorial>
   <head>
      <name>test_picture</name>
      <version>1.0-alpha</version>
      <doc>
         <title>My beautiful picture</title>
         <description>
            <text lang="en">how to display a picture in tutorial</text>
         </description>
         <authors>Me</authors>
      </doc>
      <category>test:display</category>
      <interface type="tutorial">
         <div xmlns="http://www.w3.org/1999/xhtml">
             <h1>how to display a picture in a tutorial</h1>
             <img src="tutorial-codebase/my_picture.png">my beautiful picture</img>
         </div>
      </interface>
    </head>
<tutorial>      
\end{lstlisting}
In the example above the description file must be named test\_picture (as the name tag content plus the ``.xml'' extension) and a file ``my\_picture.png'' must be placed in a directory called test\_picture.


\chapter{Validation}

When creating or modifying a service description, validating the XML code is highly recommended 
to detect mistakes which can cause problems, in particular at display or job execution time. 
To validate a service description, use the \texttt{mobvalid} script located in the \texttt{\$MOBYLEHOME/Tools} directory\footnote{This
tool will simply automate the validation of the XML file, according to its grammar based in the \texttt{*.rnc}/\texttt{rng} files
and a set of additional schematron rules. However, it should not be necessary to be familiar with these files to be able
to write a service description.}.

As the typing system is central to the chaining process, the consistency between the types is crucial.
A same ``XML data type'' appearing in different service descriptions must always refer to the same python superclass.
Some typographical mistakes in the XML class or in a \textbf{biotype} can prevent the desired chaining 
or lead to an unexpected chaining.  The \texttt{mobtypes} script located in \texttt{\$MOBYLEHOME/Tools} 
scans service descriptions and python classes to create a repository of all types used in your portal. 
This tool helps the Mobyle administrator to maintain the consistency of his portal or the service description author to choose the right types.
The usage of \texttt{mobtypes} script is explained in the associated \texttt{README} file.

When the \texttt{Tools/mobtypes} script analyzes a service description, it generates a report with 3 sections:
\begin{itemize}
\item the Mobyle \textbf{datatype} based on python class,
\item the DataTypes defined by ``XML typing'',
\item the \textbf{biotypes} (see \ref{biotype}) used.
\end{itemize}
By default this script analyzes all installed service descriptions. It helps the Mobyle administrator to keep
a consistent set of types for the portal.

To be used in the portal, the services must be deployed and debugged if necessary.
Those operations are described in \texttt{how\_to\_configure\_Mobyle.pdf}.

\chapter{Upgrade from version 0.97}

Upgrading service definitions from previous versions to v1.0 should be reasonably straightforward. The only two incompatibilities are:

\begin{itemize}

 \item in the \textbf{dataFormat} element: whereas in versions 0.9x \textbf{dataFormat} elements are sometimes placed in a container \textbf{acceptedDataFormats} element, this container has now been removed and dataFormat elements should be direct children of the \textbf{type} element.

 \item the \textbf{interface} element has to have a \textbf{type} attribute: the details of this mechanism which extends the customization possibilities are described in the detailed documentation, but legacy 0.97 XML \textbf{interface} elements should be updated with a \textbf{type="form"} attribute for inputs and a \textbf{type="job\_output"} attribute for results.

\end{itemize}

The other evolutions of the grammar are additions are annotated with the ``\textit{new in 1.0}`` label.



\end{document}