CONTRIB.fr.md

# Contribuer au code source

## Contenu
* [Prérequis](#pr-requis)
* [Créer sa copie du projet](#cr-er-sa-copie-du-projet)
* [Contribuer au code](#contribuer-au-code)
* [Créer un nouveau skin](#cr-er-un-nouveau-skin)

## Prérequis

Les équipes de développement AFI et Biblibre utilisent le [sytème de gestion de développement](https://fr.wikipedia.org/wiki/Forge_%28informatique%29) libre [GitLab](https://www.gitlab.com) et le [système de gestion de version](https://fr.wikipedia.org/wiki/Gestion_de_versions) [Git](http://www.git-scm.com). Ce document décrit l'utilisation minimale nécessaire de ces deux outils pour pouvoir contribuer au code des projets maintenus par AFI et Biblibre. Néanmoins nous vous invitons à lire le livre [Pro Git](http://git-scm.com/book/fr).

Nous hébergeons les codes sources des projets sur une instance de GitLab accessible à l'URL https://git.afi-sa.fr. Les projets publics sont accessibles sans compte à l'URL https://git.afi-sa.fr/public.


## Créer sa copie du projet

### Créer un compte gitlab

Depuis la page [Sign Up](http://git.afi-sa.fr/users/sign_up) vous pouvez créer votre compte. Un mail sera automatiqument envoyé pour vous confirmer l'accès. 


### Cloner le projet

Une fois connecté, depuis la [page du project OPACCE](http://git.afi-sa.fr/afi/opacce), cliquez sur le bouton **Fork repository**.

Cela vous créera une copie intégrale du projet, accessible publiquement à l'adresse http://git.afi-sa.fr/mon_compte/opacce.


L'accès SSH au dépôt git est donné sur la page d'accueil de votre projet. Par exemple git@git.afi-sa.fr:mon_compte/opacce.git


### Installer l'accès SSH

Le poussage de modifications sur gitlab requiert un accès ssh.  Sur [la page de modification de votre profil](http://git.afi-sa.fr/profile), à l'onglet [SSH Keys](http://git.afi-sa.fr/profile/keys), le lien [Add SSH Key](http://git.afi-sa.fr/profile/keys/new) permet d'ajouter une clé.

#### Créer et déclarer sa clé

Si vous posséder déjà une clé sur votre poste de travail dans **~/.ssh/id_rsa.pub**, copiez le contenu.

Sinon pour [générer une clé SSH sur votre poste de travail](http://git.afi-sa.fr/help/ssh), utilisez la commande suivante:
```bash
ssh-keygen -t rsa -C "addresse_email@domaine.ext"
```

et pour afficher le contenu:
```bash
cat ~/.ssh/id_rsa.pub
```

#### Configurer l'accès SSH

L'accès SSH passe par le port **2950**. Créez ou modifiez le fichier **~/.ssh/config** pour y ajouter les lignes suivantes:
```
Host git.afi-sa.fr
  Hostname git.afi-sa.fr
  Port 2950
  User git
  IdentityFile ~/.ssh/id_rsa

```

## Contribuer au code

### Installer sa copie de l'OPAC

L'installation se déroule comme décrit [dans la procédure d'installation](INSTALL.fr.md), excepté que la commande pour cloner le projet décrite dans la section [Récupération des sources](INSTALL.md#Récupération-des-sources) utilise votre propre dépôt:
```bash
cd /var/www
git clone git@git.afi-sa.fr:mon_compte/opacce.git
```

### Faire des modifications et les pousser vers gitlab

Une fois quelques modifications effectuées, l'envoi des données se fait en deux temps.

1. Commit des modifications sur votre machine en local
```bash
git commit -a -m "Commentaires des modifications"
```

2. Pousser les modifications de votre branche master vers gitlab (origin):
```bash
git push origin master
```

Pour plus de détails, consultez [Pro Git](http://git-scm.com/book/fr)


### Proposer les modifications aux mainteneurs de la version officielle

Sur la page de votre projet GitLab, onglet **Merge Requests**, cliquez sur le lien **+ New Merge Request** et remplissez les différents champs pour décrire vos modifications. 


### Récupérer les dernières modifications de la version officielle

Tout d'abord, il faut déclarer le dépôt de la version officielle (upstream) dans votre projet local:
```bash
git remote add upstream git@git.afi-sa.fr:afi/opacce.git
```

Ceci fait, vous pouvez fusionner les modifications dans votre branche:

```bash
# Télécharge toutes les nouvelles modifications du dépôt distant
git fetch upstream master
# Fusionne les nouvelles modifications dans votre répertoire
git merge upstream/master
# Pousse la fusion sur gitlab
git push origin master
```



## Créer un nouveau skin

### Création

Se placer dans le répertoire skins à la racine de l'OPAC et recopier le skin modele

```bash
cd skins
cp -a ../public/opac/skins/modele mon_skin
```

Aller dans la configuration d'un profil de l'OPAC, le nouveau skin devrait être disponible dans le sélecteur de thème.



### Sauvegarde sur GitLab

Créer le projet sur [GitLab](https://git.afi-sa.fr) pour stocker les sources. Par exemple https://git.afi-sa.fr/mon_compte/mon_skin.

Aller dans le répertoire mon_skin et initialiser le dépôt:

```bash
cd mon_skin
git init
git remote add origin -t master git@git.afi-sa.fr:mon_compte/mon_skin.git
git add *
git commit -m "Premier commit"
git push origin master
```

Ceci fait, les nouveaux fichiers devraient être accessibles sur https://git.afi-sa.fr/mon_compte/mon_skin/files


### Description des répertoires

* **css/** contient le fichier global.css sur lequel travailler. Les autres fichiers sont destinés à devenir obsolètes.
* **images/** les icônes, dont **images/support/** pour les types de support. Les fichiers doivent être nommés comme suit: **support_id_.png**, par exemple **support_1.png** pour les livres.
* **templates/** les modèles de rendu boite de la page d'accueil. Les fichiers doivent êtres nommés en séparant les mots par des tirets bas **_**, qui seront dans la configuration des boîtes **Style de boîte**. Chaque modèle de boîte peut inclure les tags **{TITRE}**, **{RSS}**, **{CONTENU}**. Pour avoir un rendu conditionnel, le fichier peut inclure les conditions **{IF-TITRE}**, **{IF-RSS}**, **{IF-CONTENU}** suivi de la balise **{ENDIF}**

```html
<div class="right-box">
	<div class="right-box-inner">
		{IF-TITRE}
		<div class="header">
			<div><h1>{TITRE}</h1></div>
			<div class="rss">{RSS}</div>
		</div>
		{ENDIF}
		<div class="content">
			{CONTENU}
		</div>
	</div>
</div>
```


Tous les fichiers de vue du répertoire **application/modules/opac/views/scripts** peuvent être redéfinis dans un répertoire html. Les principaux sont:
* **footer.phtml** pour le pied de page
* **banniere.phtml** pour l'en-tête
* **skin_head.phtml** pour rajouter des éléments dans la balise **head** du site
* **accueil.phtml** pour la page d'accueil
* **contenu.phtml** pour les autres pages


## Créer un nouvel écran Front dans Bokeh

Toute fonctionnalité Bokeh est développée en suivant la méthodologie [Test Driven Development](https://fr.wikipedia.org/wiki/Test_driven_development).

Ce qui veut dire qu'il faut toujours commencer par écrire un test.

L'équipe Bokeh privilégie actuellement l'approche dite du scénario qui consiste à créer un répertoire sous tests/scenarios/ qui contiendra tous les tests de la nouvelle fonctionnalité.

Le premier test à écrire concernera l'accès à l'url qui affichera le nouvel écran.

Bokeh utilisant l'architecture [MVC](https://fr.wikipedia.org/wiki/Mod%C3%A8le-vue-contr%C3%B4leur) de ZendFramework (library/storm/zf/documentation/manual/core/en/index.html), il s'agira du test d'une action d'un controller.

Bokeh fourni un objet de base pour les tests de controller AbstractControllerTestCase dans tests/application/modules/AbstractControllerTestCase.php

Par exemple, partons du principe que nous souhaitons fournir la possibilité de gérer des listes de choses à faire.

Nous commençons par créer un répertoire tests/scenarios/TodoList et dans ce répertoire un fichier TodoListTest.php

```php
<?php
class TodoListTest extends AbstractControllerTestCase {
  /** @test */
  public function pageShouldContainsH1ChosesAFaire() {
  }
}
```

Remarquez que la fonction de test a la forme "contextShouldExpectation", vous trouverez cette forme très souvent dans les tests de Bokeh.

Pour lancer ce test en particulier en ligne de commande, placer vous dans le répertoire de votre Bokeh puis exécutez:
```bash
phpunit -c tests/phpunit.xml --filter pageShouldContainsH1ChosesAFaire TodoListTest tests/scenarios/TodoList/TodoListTest.php
```

Vous devriez voir:
```
OK (1 test, 0 assertions)
```

Nous pouvons simuler l'accès à une url avec la fonction AbstractControllerTestCase::dispatch($url = null, $throw_exceptions = true, $headers =  [])
```php
<?php
class TodoListTest extends AbstractControllerTestCase {
  /** @test */
  public function pageShouldContainsH1ChosesAFaire() {
    $this->dispatch('/todo');
  }
}
```

Avec ce dispatch nous venons de décider que l'url d'accès de la fonctionnalité sera /todo.

Si vous relancez les tests vous devriez voir:
```
There was 1 error:

1) TodoListTest::pageShouldContainsH1ChosesAFaire
Zend_Controller_Dispatcher_Exception: Invalid controller specified (todo)

library/storm/zf/library/Zend/Controller/Dispatcher/Standard.php:240
library/ZendAfi/Controller/Dispatcher/Standard.php:29
library/storm/zf/library/Zend/Controller/Front.php:934
tests/application/modules/AbstractControllerTestCase.php:295
tests/scenarios/TodoList/TodoListTest.php:5

ERRORS!
Tests: 1, Assertions: 0, Errors: 1.
```

ZendFramework nous informe que nous lui avons demandé un controller qui n'existe pas (todo), nous allons donc le créér.

Bokeh suit une architecture modulaire dans laquelle:

* application/modules contient des modules (opac, admin, ...)
* application/modules/[nom du module]/controllers contient des fichier XxxxxxxController.php (AbonneController.php, RechercheController.php, ...)
* chaque fichier controller contient au moins une fonction xxxxAction() (pretsAction, reservationsAction, ...)

Bokeh fournit un objet de base pour tous les controllers, ZendAfi_Controller_Action.

Créons un fichier application/modules/opac/controllers/TodoController.php:

```php
<?php
class TodoController extends ZendAfi_Controller_Action {
}
```

Si vous relancez les tests vous devriez avoir:

```
There was 1 error:

1) TodoListTest::pageShouldContainsH1ChosesAFaire
Error: Call to a member function index() on null

library/ZendAfi/Controller/Action.php:153
library/storm/zf/library/Zend/Controller/Action.php:494
library/storm/zf/library/Zend/Controller/Dispatcher/Standard.php:284
library/ZendAfi/Controller/Dispatcher/Standard.php:29
library/storm/zf/library/Zend/Controller/Front.php:934
tests/application/modules/AbstractControllerTestCase.php:295
tests/scenarios/TodoList/TodoListTest.php:5

ERRORS!
Tests: 1, Assertions: 0, Errors: 1.
```

ZendFramework nous informe que nous lui avons demandé une action qui n'existe pas (index).

Bokeh utilise la notion de routage des urls avec pour motif [module]/[controller]/[action].
Par exemple opac/recherche/simple équivaut à module opac, controller RechercheController.php, action simpleAction().
Chacune des parties de l'url est optionelle:
* lorsque l'action n'est pas donnée on considère qu'il s'agit de indexAction()
* lorsque le controller n'est pas donné on considère qu'il s'agit de IndexController.php
* lorsque le module n'est pas donné on considère qu'il s'agit d'opac

Autrement dit l'url par défaut / correspond à /opac/index/index.

Créons une action indexAction()

```php
<?php
class TodoController extends ZendAfi_Controller_Action {
  public function indexAction() {
  }
}
```

Si vous relancez les tests vous devriez avoir:

```
There was 1 error:

1) TodoListTest::pageShouldContainsH1ChosesAFaire
Zend_View_Exception: script 'todo/index.phtml' not found in path (application/modules/opac/views/scripts/)

library/storm/zf/library/Zend/View/Abstract.php:875
library/storm/zf/library/Zend/View/Abstract.php:783
library/templates/Historic/Template.php:40
library/ZendAfi/View/Helper/Layout/Opac.php:26
library/storm/zf/library/Zend/View/Abstract.php:317
application/modules/opac/views/scripts/module.phtml:2
library/storm/zf/library/Zend/View.php:107
library/storm/zf/library/Zend/View/Abstract.php:787
library/ZendAfi/Controller/Action/Helper/ViewRenderer.php:131
library/storm/zf/library/Zend/Controller/Action/Helper/ViewRenderer.php:923
library/storm/zf/library/Zend/Controller/Action/Helper/ViewRenderer.php:962
library/storm/zf/library/Zend/Controller/Action/HelperBroker.php:166
library/storm/zf/library/Zend/Controller/Action.php:504
library/storm/zf/library/Zend/Controller/Dispatcher/Standard.php:284
library/ZendAfi/Controller/Dispatcher/Standard.php:29
library/storm/zf/library/Zend/Controller/Front.php:934
tests/application/modules/AbstractControllerTestCase.php:295
tests/scenarios/TodoList/TodoListTest.php:5

ERRORS!
Tests: 1, Assertions: 0, Errors: 1.

```

ZendFramework nous informe que le rendu de cette action n'existe pas (todo/index.phtml).

Bokeh utilise une fonction du ZendFramework qui effectue automatiquement le rendu de l'action courante en cherchant un fichier dans le répertoire views/scripts/ du module courant, dans un sous-répertoire du nom du controller courant (todo) ayant comme nom de fichier le nom de l'action courante plus l'extension .phtml.

Dans notre cas, cela correspond à views/scripts/todo/index.phtml

Créons ce fichier vide.

```bash
touch application/modules/opac/views/scripts/todo/index.phtml
```

Si vous relancez les tests vous devriez avoir:

```
OK (1 test, 0 assertions)
```

L'accès à l'url s'est bien passé, l'action a été exécutée et rendue en html, mais notre test n'a rien vérifié pour l'instant (0 assertions).

Ajoutons une vérification:

```php
<?php
class TodoListTest extends AbstractControllerTestCase {
  /** @test */
  public function pageShouldContainsH1ChosesAFaire() {
    $this->dispatch('/todo');
    $this->assertContains('<h1>Choses à faire</h1>', $this->_response->getBody());
  }
}
```

Si vous relancez les tests vous devriez avoir:

```
FAILURES!
Tests: 1, Assertions: 1, Failures: 1.
```

Le test nous informe qu'il n'y a aucune balise h1 contenant "Choses à faire" dans le rendu de l'action.

Ajoutons simplement cette balise dans le fichier todo/index.phtml
```html
<h1>Choses à faire</h1>
```

Si vous relancez les tests vous devriez avoir:

```
OK (1 test, 1 assertion)
```

# Traitement des demandes et evolutions liees au Magasin de Themes

### De quelle maniere Bokeh sais que on utilise un theme?
Dans le fichier "startup.php" il y a une fonction defineUrl() qui charge le profil courant.
C'est le profil appeler qui va determiner le template qui sera charger.

La methode Class_Template::current() permet de determiner le Template en cours d'utilisation (et donc en fonction des proprietes de ce Template on devra eventuellement passer des donnees differentes)

Bokeh fournit tout le temps un profil par défaut, c'est le profil 1 qui est utilise.

Un profil te donnera toujours un thème courant : historique si la colonne template est vide dans le profil.

### Quels fichiers sont appeles lors d'une requete utilisant un theme?

Intonation est le theme "parent". Tous les autres themes apportent des petites variations,
a l'exception du theme Chili qui surcharge certaines fonctions de Intonation.

La librairie de composant graphique utilisee se trouve dans Intonation/View.

C'est un objet wrapper qui utilise une interface qui va faire la liaison entre un modele et un composant d'affichage.

Le Wrapper est l'objet qui va permettre a la vue de recuperer des proprietes d'objets, quelle que soit le type d'objet qui est affiché.

Toutes les vues attendent de la part des Wrappers des fonctions standard (interface : Intonation/Library/View/Wrapper/Abstract.php)
pour recuperer les données anisi que des actions ou des contenus enrichies.
L'objectif étant de fournir des informations avec des appels unique.


Les rendus de collections :

Ils consommennt une collection de wrapper.

Intonation/Library/Widget/Carousell/View.php

    Intonation_View_RenderWall
    Intonation_View_RenderCarousel
    Intonation_View_RenderList
    Intonation_View_RenderTruncateList
    Intonation_View_RenderHorizontalList
    Intonation_View_RenderMultipleCarousel
    Intonation_View_RenderWallGrid
    Intonation_View_RenderMap

Les rendus de wrapper Intonation/View:
    CardifyFullDescription.php
    CardifyHorizontal.php
    CardifyOnlyDescription.php
    Cardify.php
    CardifyWithOverlay.php