====== Installation manuelle d'un mod (au format .xml) =====

===== Avant de commencer... =====
D'abord, une petite note pour dire qu'un fichier ''.xml'' peut être ouvert avec n'importe quel éditeur de texte simple, comme le Bloc-Notes de Windows.  Mais il est peut-être préférable de se tourner vers un autre outil comme [[http://www.context.cx|ConText]], [[http://bluefish.openoffice.nl|Bluefish]], gEdit, [[http://www.macromedia.com|Macromedia Dreamweaver]], [[http://www.mpsoftware.dk|MPSoftware PHP Designer 2005]] ou autre, car ils proposent la colorisation syntaxique de ce type de fichiers.

Pour saisir comment installer manuellement un mod dont le fichier d'installation est au format ''.xml'', nous prendrons un mod existant à titre d'exemple.  Nous étudierons la première étape de l'installation du mod [[http://mods.simplemachines.org/index.php?mod=163|Board Notes]], par Akabugeyes.

La première étape décrite dans le fichier d'installation ''install.xml'' de ce mod est celle-ci:
<code xml>
				<file name="$themedir/ManageBoards.template.php">
	<operation>
			<!-- Search for this text before the code we add.  You can also search for after, and the end of the file. -->
			<search position="before"><![CDATA[
								<td>
									<b>', $txt['mboards_description'], '</b><br />
									', $txt['mboards_description_desc'], '<br /><br />
								</td>
								<td valign="top" align="right">
									<textarea name="desc" rows="2" cols="29">', $context['board']['description'], '</textarea>
								</td>
]]></search>
			<!-- Add this text when we find it.  Note that it's on it's own line on purpose, and the CDATA keeps things clean. -->
			<add><![CDATA[
								<tr>
								<td>
									<b>', $txt['topblock_title'], '</b><br />
									', $txt['topblock'], '<br /><br />
								</td>
								<td valign="top" align="right">
									<textarea name="topblock" rows="2" cols="29">', $context['board']['topblock'], '</textarea>
								</td></tr>
]]></add>
		</operation>
	</file>
</code>

Décortiquons cette étape.

===== Désignation du fichier à modifier =====

<code xml>
				<file name="$themedir/ManageBoards.template.php">
</code>
Cette ligne contient le chemin et le nom du fichier à modifier.  Certaines variables peuvent être utilisées pour exprimer un chemin:
  * **$themedir** désigne ''/Themes/default''
  * **$languagedir** désigne ''/Themes/default/languages''
  * **$sourcedir** désigne ''/Sources''


===== Opération =====
<code xml>
	<operation>
</code>
Une opération consiste en une recherche et une action à prendre.

==== Commentaire =====
<code xml>
			<!-- Search for this text before the code we add.  You can also search for after, and the end of the file. -->
</code>

Comme en HTML, le texte contenu entre **''<!--''** et **''-->''** est un commentaire.  Il est possible que certains installateurs incluent des commentaires pour mieux guider les utilisateurs désirant installer un mod manuellement ; d'autres mods n'inclueront aucun commentaires.


==== Recherche ====
<code xml>
			<search position="before"><![CDATA[
								<td>
									<b>', $txt['mboards_description'], '</b><br />
									', $txt['mboards_description_desc'], '<br /><br />
								</td>
								<td valign="top" align="right">
									<textarea name="desc" rows="2" cols="29">', $context['board']['description'], '</textarea>
								</td>
]]></search>
</code>

Ici se trouve notre recherche.  Le gestionnaire de paquet tentera de trouver le texte *exact* (donc: espaces, tabulations, etc. doivent être respectées) situé entre **''<![CDATA[''** et **'']]>''** ; cela a pour effet de conserver les règles de formatage du texte.  L'attribut **''position''**, dans la balise **''<search>''**, peut prendre 3 valeurs: **''replace''** (remplacer), **''before''** (avant) ou **''after''** (après).

  * Dans le premier cas, le texte recherché sera remplacé par le texte à ajouter.
  * Dans les second et troisième cas, l'attribut **''position''** renseigne quant à la position de ce texte à rechercher **//par rapport au texte à ajouter//**.


<code xml>
			<!-- Add this text when we find it.  Note that it's on it's own line on purpose, and the CDATA keeps things clean. -->
</code>
Encore un commentaire.

==== Ajout ====
<code xml>
			<add><![CDATA[
								<tr>
								<td>
									<b>', $txt['topblock_title'], '</b><br />
									', $txt['topblock'], '<br /><br />
								</td>
								<td valign="top" align="right">
									<textarea name="topblock" rows="2" cols="29">', $context['board']['topblock'], '</textarea>
								</td></tr>
]]></add>
</code>

La balise **''<add>''** contient le texte à ajouter.  Ce texte est encore une fois situé entre **''<![CDATA[''** et **'']]>''** afin de préserver les règles de formatage (espaces, tabulations, etc.) ; il sera donc ajouté au fichier tel qu'il apparaît.


==== Fin de l'opération ====
<code xml>
		</operation>
</code>

L'opération étant terminée, on ferme la balise **''<operation>''**.


===== Fin de la modification dans le fichier =====
<code xml>
	</file>
</code>

S'il n'y a plus de modification à apporter dans le fichier que nous éditions, on ferme la balise **''<file>''**

=====

Dans un langage plus compréhensible pour les humains, nous pourrions lire les instructions de cette façon:

Dans le fichier ''/Themes/default/ManageBoards.php'' //(''<file name="$themedir/ManageBoards.template.php">'')//, nous recherchons le texte suivant //(''<search position="before"><![CDATA[ ... ]]></search>'')// ; ce texte se trouvera avant //(''position="before"'')// le texte que nous ajoutons //(''<add><![CDATA[ ... ]]></add>'')//.