Documentation de Novius OS¶

Bienvenue sur la documentation de Novius OS. Elle est hébergée et générée par Read The Docs.

Toutes les contributions sont les bienvenues : signalement ou correction d’erreurs, propositions d’améliorations ou traductions.

Les sources sont sur Git Hub, nous attendons vos Pull Request avec impatience. Contactez-nous si vous avez besoin d’aide avec votre contribution.

Documentation d’API (en anglais uniquement)
English version

Sommaire¶

Installer Novius OS¶

Installation¶

Prérequis généraux ¶

Disposer d’un serveur avec MySQL et PHP 5.3+

Novius OS tourne aussi bien sur :

Linux, Mac OS que Windows (à partir de Vista)
Apache avec le mod_rewrite activé ou Nginx

Nous décrivons ci-après la procédure d’installation sur un serveur LAMP (Linux/Apache/MySQL/PHP), de type Debian, sur lequel vous avez les droits d’administration. À adapter à votre configuration.

Installation de AMP

sudo apt-get install apache2 php5 mysql-server libapache2-mod-php5 php5-mysql

Activer le mod_rewrite d’Apache.
sudo a2enmod rewrite

Installation rapide ¶

Pré-requis ¶

Avoir un accès ligne de commande sur le serveur et disposer des droits d’administration sudo.
Avoir Git installé.

Installation ¶

Ouvrez un terminal et saisissez :

cd /var/www
sudo wget http://raw.github.com/novius-os/ci/master/elche/tools/install.sh && sh install.sh

À la question « Enter the directory name where you want to install Novius OS (default novius-os) », indiquez le nom du répertoire dans lequel vous voulez installer votre instance de Novius OS. Laissez vide pour l’installer dans un répertoire novius-os.

Une fois l’installation terminée :

Ouvrez votre navigateur à l’URL http://votredomaine/novius-os/ (remplacez novius-os par le nom du répertoire que vous avez saisi).
Poursuivez l’installation avec l’assistant de paramétrage.

Note

Pour une installation en local, l’URL sera probablement http://localhost/novius-os/.
Si le DOCUMENT_ROOT de votre serveur n’est pas /var/www/, modifiez la première ligne en conséquence.

Installation via Zip ¶

Cette procédure est à privilégier si vous souhaitez installer Novius OS sur un hébergement mutualisé :

Téléchargez novius-os.5.0.1-elche.zip.
Dézippez le fichier.
Uploadez (ou déplacer) le répertoire novius-os dans le DOCUMENT_ROOT de votre serveur (par exemple via FTP).
Ouvrez votre navigateur à l’URL http://votredomaine/novius-os/ (remplacez novius-os par le nom du répertoire où vous avez dézippé Novius OS).
Poursuivez l’installation avec l’assistant de paramétrage.

Installation avancée ¶

Configuration d’un Virtual Host ¶

Les commandes suivantes sont données à titre d’exemple si vous voulez installer Novius OS sur Ubuntu, adaptez les en fonction de votre distribution.

sudo nano /etc/apache2/sites-available/novius-os.conf

Remplacez nano par n’importe quel autre éditeur de texte.

Remplacez novius-os.conf par le nom que vous voulez donner à votre Virtual Host.

Copiez la configuration suivante dans le fichier que vous venez d’ouvrir et sauvegardez.
Adaptez la ligne ServerName avec votre nom de domaine dans le cas d’une installation en production.
De même, remplacez /var/www/novius-os par le répertoire dans lequel vous avez installé Novius OS.

<VirtualHost *:80>
        DocumentRoot /var/www/novius-os/public
        ServerName   novius-os
        <Directory /var/www/novius-os/public>
                AllowOverride All
                Options FollowSymLinks
        </Directory>
</VirtualHost>

La configuration par défaut contient un répertoire public. C’est vers ce lui que doit pointer DocumentRoot.

Activez votre nouveau VirtualHost :

sudo a2ensite novius-os.conf

Relancez ensuite Apache pour appliquer la nouvelle configuration.

sudo service apache2 reload

Configurer le fichier hosts, dans le cas d’installation sur votre machine¶

Si vous installez Novius OS sur votre machine locale, vous devez ajouter une ligne au fichier /etc/hosts, avec la valeur du ServerName (novius-os dans l’exemple ci-desssus) .

sudo nano /etc/hosts

Ajouter la ligne suivante :

127.0.0.1   novius-os

Installation avancée avec Git ¶

Il faut cloner le dépôt disponible sur GitHub :

git clone --recursive git://github.com/novius-os/novius-os.git

Cette commande télécharge le dépôt principal, avec plusieurs submodules :

novius-os : le cœur de Novius OS, qui contient lui-même des submodules, comme fuel-core ou fuel-orm.
Différents submodules dans local/applications : les applications blog, actualités, commentaires, formulaires, diaporamas...

La branche par défaut du dépôt pointe vers la dernière version stable.

Les nouvelles versions seront disponibles dans des nouvelles branches.

Pour le moment, tous les dépôts dépendants de novius-os/novius-os partagent le même numéro de version. C’est-à-dire qu’une application disponible sur notre compte Github existe dans les mêmes versions que le cœur de Novius OS. Donc si vous utilisez novius-os/core en version 5.0.1, alors vous devriez aussi utiliser novius-os/app dans le même numéro de version 5.0.1.

Pour changer la version que vous voulez utiliser après un clone, n’oubliez pas de mettre à jour les submodules !

Exemple qui utilise la dernière nightly de la branche dev :

cd /var/www/novius-os/
git checkout dev
git submodule update --recursive

Installation sur serveur Nginx ¶

Exemple de configuration Nginx :

server {
listen 80;
server_name localhost;

root /var/www/novius-os;
index index.php index.html;

access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log notice;

location = /favicon.ico {
log_not_found off;
access_log off;
}

location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}

error_page 404 /public/htdocs/novius-os/404.php;

autoindex off;

location @rewrites {
rewrite ^/(admin(/.*)?)$ /public/htdocs/novius-os/admin.php last;
rewrite ^/.+(.html|/)$ /public/htdocs/novius-os/front.php last;
rewrite ^/([^.]*)$ /public/htdocs/novius-os/front.php last;
rewrite ^ /public/htdocs/novius-os/front.php last;
}

rewrite ^/(static|cache|media|data|htdocs)/(.*) /public/$1/$2 break;
rewrite ^/install.php /public/htdocs/install.php last;

try_files $uri @rewrites;

location ~ \.php$ {
 fastcgi_split_path_info ^(.+\.php)(/.+)$;
 fastcgi_pass unix:/var/run/php5-fpm.sock;
 fastcgi_index index.php;
 include fastcgi_params;
 }
}

Assistant de paramétrage¶

Vous avez suivi la première étape de l’installation. Les fichiers de Novius OS sont donc installés, le serveur paramétré et vous accédez à http://votredomaine/novius-os/. Le plus dur est passé, la partie simple commence :-).

Étape 1 : Vérifier les prérequis¶

Cette étape devrait être une simple formalité si vous avez installé Novius OS avec la procédure d’installation rapide. Dans les autres cas, si vous voyez beaucoup de rouge, ne vous inquiétez pas ! Le site a juste besoin de droits en écriture dans certains répertoires. Cette étape vous donne des explications et les commandes à exécuter pour corriger tous les points.

Si vous ne voulez pas vous embêter, copiez / collez le résumé des commandes disponibles en bas de la page dans un terminal : c’est fini !

Étape 2 : Configurer la base de données MySQL¶

Vous avez besoin d’une base MySQL avec un utilisateur ayant les droits nécessaires. Dans le cas d’un hébergement mutualisé, ces paramètres ont dû vous être fournis par votre hébergeur. Dans les autres cas, voici un exemple pour une base en localhost :

CREATE DATABASE `nom_de_votre_base` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON `nom_de_votre_base`.* TO 'nom_de_votre_utilisateur'@localhost IDENTIFIED BY 'mot_de_passe';
FLUSH PRIVILEGES;

Remplissez les quatre champs demandés en fonction de la configuration de votre base.

Cette étape va créer deux fichiers local/config/db.php et local/config/crypt.php et, surtout, les tables nécessaires dans votre base de données.

Étape 3 : Créer le premier compte administrateur¶

Remplissez les champs demandés pour créer le premier compte administrateur de votre Novius OS. L’email et le mot de passe vous serviront pour votre première connexion. Ces informations seront ensuite modifiables via le back-office.

Étape 4: Choix des langues¶

Choisissez (ou ajoutez) les langues disponibles dans le front-office de votre site avant de finir l’installation.

Voir aussi

Concernant le paramétrage des contextes, reportez-vous aux principes et à la documentation d’API.

Applications¶

Vous arrivez sur le gestionnaire d’applications. C’est ici que vous installez les applications dont vous avez besoin.

Se déconnecter / connecter¶

Pour vous déconnecter, cliquez sur votre prénom en haut à droite. Un menu apparait alors :

Vous être alors redirigé sur le formulaire de connexion.

Problèmes courant d’installation¶

Htaccess non autorisé avec Apache ¶

Symptômes ¶

Vous avez le message Your server does not allow .htaccess file
Vous utilisez Novius Os sur une serveur Apache
Vous avez installé Novius OS dans un sous-répertoire d’un host, généralement le host par défaut

Solution ¶

Trouvez le fichier de configuration du virtualhost, généralement dans /etc/apache2/site-enabled/.
Éditez le fichier de configuration du virtualhost avec les droits en écriture.

Dans cette exemple, nous utilisons l’éditeur nano et le nom du fichier de configuration du virtualhost est 000-default :

sudo nano /etc/apache2/site-enabled/000-default

Dans le fichier, trouvez la ligne ressemblant à (si Novius OS est installé dans le répertoire /var/www/ subdirectory) :

<Directory /var/www>
    AllowOverride None
    Options FollowSymLinks
</Directory>

Changez AllowOverride None par AllowOverride All. Sauvegardez vos changement et redémarrez Apache :

sudo service apache2 restart

Droits d’écriture sur Windows ¶

Symptômes ¶

Vous avez installé Novius OS sur Windows
Vous avez des messages commençant par Give write permission to all users

Solution ¶

Vous pouvez essayer de démarrer votre serveur WAMP avec les privilèges administrateur.

Ou vous pouvez essayez de changer les droits d’accès sur le répertoire de Novius OS, et récursivement sur ces sous-répertoires. Donner les droits d’écritures pour tout le monde (Exemple pour windows 7). Essayez en redémarrant le serveur après.

Droits d’écriture en FTP ¶

Symptômes ¶

Vous avez installé Novius Os en le transférant par FTP
Vous avez des messages disant que les répertoires must be writeable
Vous ne pouvez pas exécuter les commandes données, vous n’avez pas accès au serveur via ssh

Solution ¶

Vous pouvez donner les droits d’écriture avec votre logiciel FTP. Par exemple, ce tutoriel pour Filezilla

chmod a+w veut dire donner les droits d’écriture à tous les utilisateurs.

Installation de GD sur Ubuntu ¶

Symptômes ¶

Vous avez le message GD is required
Vous utilisez Novius OS sur Ubuntu

Solution ¶

sudo apt-get install php5-gd
sudo apt-get install libgd2-xpm-dev*

L’extension Json n’est pas installée ¶

Symptômes ¶

Vous avez un message disant Call to undefined function json_encode() ou Call to undefined function json_decode()

Certaines distributions ont enlevé l’extension standard JSON à partir de la version 5.5rc2 de PHP à cause d’un conflit de licence.

Solution ¶

sudo apt-get install php5-json

Forbidden quand vous accédez au back-office ¶

Symptômes ¶

Après l’installation, quand vous essayez d’accéder au back-office, votre navigateur retourne une page disant Forbidden

Ce problème existe notamment pour l’hébergeur Infomaniak.ch

Solution ¶

Éditez le fichier .htaccess. Changez la ligne :

Options +FollowSymLinks -Indexes

Par :

Options +FollowSymlinks -SymlinksIfOwnerMatch -Indexes

magic_quotes_gpc must be off ¶

Symptômes ¶

Vous avec le message PHP configuration directive ‘magic_quotes_gpc’ must be off
Vous êtes sur un hébergement mutualisé OVH

Solution ¶

Ajoutez cette ligne au fichier .htaccess :

SetEnv MAGIC_QUOTES 0

404 à l’installation ¶

Symptômes ¶

Vous avec un 404 après la première page d’installation
Vous êtes sur un hébergement mutualisé 1&1

Solution ¶

Ajoutez un RewriteBase dans le fichier .htaccess :

<IfModule mod_rewrite.c>
    RewriteEngine   on
    RewriteBase     /novius-os-install-dir/

La suite¶

Première page¶

Ouvrir l’application Pages web¶

Si vous voulez créer un site web, vous devez utiliser l’application Pages web :

L'application Pages web sur l'onglet d'accueil

Ajouter une page (votre première)¶

Écrire du contenu et cliquer « Ajouter »¶

Aperçu de votre travail¶

L’action Visualiser vous permet d’avoir un aperçu de la page avant qu’elle ne soit publiée.

Publier votre page¶

Une fois que vous êtes satisfait du contenu, choisissez « Sera publié » et enregistrez.

Admirez le travail remarquable que vous venez de faire :

Gabarits¶

Les pages ont besoin de gabarits qui englobent le contenu ajouté en back-office et définissent le style.

Au moment d’ajouter ou modifier une page, on précise son gabarit.

Il est aussi possible d’ajouter de nouveaux gabarits. Les gabarits sont embarqués avec les applications. Ajouter un gabarit passe donc par l’ajout d’une application (via le gestionnaire d’application).

Applications¶

Les applications permettent de rajouter des fonctionnalités à Novius OS.

Le gestionnaire d’applications¶

Permet d’installer / désinstaller des applications.

Après des changements du metadata d’une application ou de votre site web (instance de Novius OS), une mise à jour est nécessaire dans le gestionnaire d’applications. C’est également le cas quand une application native est modifiée.

Mise à jour¶

Mise à jour des fichiers¶

Git¶

Si vous avez installé Novius OS avec Git, placez-vous dans le répertoire de votre Novius OS :

git fetch origin
git checkout master/elche
git submodule update --recursive --init

Note

La mise à jour des submodules peut afficher une ligne

warning: unable to rmdir packages/log: Le dossier n'est pas vide

si c’est le cas, exécutez la commande suivante :

rm -rf novius-os/packages/log/

Zip¶

Si vous avez téléchargé Zip, la procédure est plus complexe.

Mettons que votre Novius OS est installé dans monsite/.
Faites une sauvegarde de votre répertoire (copiez le répertoire ou zippez le).
Téléchargez le nouveau zip de Novius OS et dézippez-le. Vous avez un répertoire novius-os/.
Dans monsite/, détruisez les répertoires suivant :
- monsite/novius-os/
- Tous les répertoires monsite/local/applications/noviusos_*
Copiez les répertoires et fichiers suivant de novius-os/ vers monsite/ :
- novius-os/
- Tous les répertoires local/applications/noviusos_*
- Tous les fichiers local/config/*.sample
- public/htdocs/install/, public/htdocs/install.php et public/htdocs/migrate.php.sample
- Tous les fichiers à la racine du répertoire

Vous pouvez alors continuer votre mise à jour.

Lancer la migration¶

Avant de lancer la procédure de migration automatique, sauvegarder votre base de données.

Via SSH¶

Si vous avez accès à SSH sur le serveur, placez-vous dans le répertoire de votre Novius OS :

sudo php oil refine migrate
sudo php oil refine migrate -m

Via Navigateur¶

Si vous n’avez pas accès à SSH, vous pouvez faire la migration via votre navigateur :

Au préalable vous devez renommer le fichier public/migrate.php.sample en public/migrate.php.
Appelez ensuite ce fichier via son URL, par exemple http://www.monsite.com/migrate.php.

Via l’interface back-office¶

Si vous n’avez pas accès à SSH, vous pouvez faire la migration via l’interface d’administration de votre Novius OS :

Connectez-vous à votre back-office
Ouvrez l’application “Gestion des applications”
Cliquer sur “Prendre en compte les changements” pour toutes les applications, ou sur “Actualiser toutes les metadata” dans la barre d’outils si vous êtes en mode expert.

Warning

Quand vous allez accéder à votre back-office sans avoir lancé les migrations, votre logiciel sera dans un état instable. Les sources ne correspondront pas avec l’état de la base de données. Vous aurez sans doute des messages d’erreur. Vous pouvez les ignorer.

Mettre à jour vos développement¶

Si vous avez des développements personnels, suivez la procédure le Guide de migration de la version Dubrovka à la version Elche.

Optimisations après installation¶

Configuration et activation de XSendFile¶

Pour comprendre ce qu’est XSendFile et à quoi il sert, c’est par ici : Médiathèque.

Apache¶

Dans Apache, il existe un module mod_xsendfile qui fournit la fonctionnalité. Ensuite, il faut modifier votre fichier .htaccess pour l’activer.

# Post-installation optimisation
<IfModule xsendfile_module>
    XSendFile On

    # Replace "novius-os-install-dir" by the real Novius OS installed directory
    XSendFilePath /novius-os-install-dir/local/data

</IfModule>

Novius OS détecte tout seul la présence du module et active automatiquement l’envoi de fichiers avec XSendFile.

nginx¶

Dans nginx, XSendFile est activé par défaut, mais l’entête à utiliser est X-Accel-Redirect. Dans ce cas, il faut éditer votre fichier de configuration config.php pour y renseigner cet entête :

<?php
return array(
    // ...
    'novius-os' => array(
        // ...
        'use_xsendfile' => 'X-Accel-Redirect',
    ),
);

Comprendre Novius OS¶

Fondamentaux du logiciel¶

Une architecture MVC¶

Novius OS répond aux standards de découpage Modèle-Vue-Contrôleur, qui définissent des logiques de travail :

dans la conception des applications ;
dans l’organisation d’un projet sous Novius OS.

Utilisation de frameworks¶

L’utilisation de frameworks oriente fortement la conception et l’implémentation des applications. Il convient donc de connaitre le rôle de chacun. Pour autant, cette documentation concernant Novius OS avant tout, veuillez vous référer à de la documentation ou tutoriaux externes pour plus de précisions sur ces frameworks.

FuelPHP¶

Consulter les tutoriaux FuelPHP par Novius

Le framework PHP utilisé pour Novius OS est FuelPHP.

Les éléments de FuelPHP les plus utilisés sont ceux qui permettent de valider les données, l’ORM et le mapping des différents fichiers. Au delà de ces éléments, des outils inclus dans le framework simplifient grandement l’implémentation des applications (comme la classe Arr par exemple).

ORM de FuelPHP¶

ORM pour object-relational mapping. En français mapping objet-relationnel.

L’ORM permet une gestion de la base de données par des objets PHP, des classes, et en gérant notamment les relations entre les tables.

Des exemples parlent plus qu’un long discours :

$new_monkey = Model_Monkey::forge();
$new_monkey->monk_name = 'Julian';
$new_monkey->save();

$monkeys = Model_Monkey::find('all');
foreach ($monkeys as $monkey) {
        //...
}

$monkey = Model_Monkey::find(4);
$monkey->delete();

Novius OS est basé sur l’ORM de FuelPHP. Veuillez vous référer à sa documentation.

Néanmoins, Novius OS ajoute une sur-couche notable à l’ORM : les Behaviours.

En français, Behaviour veut dire comportement. Les Behaviours permettent d’étendre des Model en y ajoutant des comportements standardisés.

Ils sont similaires aux Observers de FuelPHP mais plus puissants :

Comme les Observers, ils sont configurables par des options.
Comme les Observers, ils peuvent intercepter des événements pour agir sur le Model (par exemple l’événement before_save se déclenchant avant la sauvegarde).
En plus, ils fournissent aussi des méthodes, d’instance ou statiques, sur le Model.
Ils peuvent également fournir de nouveaux événements.

jQuery UI / Wijmo¶

Bien que les actions logiques soient effectuées en PHP côté serveur, Novius OS est en majorité écrit en Javascript. Cela s’explique par la grande importance donnée à l’interface utilisateur et à l’ergonomie (cf. Principes ergonomiques).

Pour proposer des interfaces et interactions riches, Novius OS utilise plusieurs librairies JS :

jQuery: Ce framework facilite l’écriture du code JS pour l’édition du contenu HTML. Il n’est pas directement orienté UI.

Documentation
jQuery UI: Ce complément de jQuery permet d’ajouter des éléments d’interface. Une majorité de l’UI de Novius OS est issue de cette librairie.

Documentation
Wijmo: Cette librairie est basée sur jQuery UI et fournit des éléments d’interface complémentaires, appelés widgets.

Documentation et Exemples

Il y a une hiérarchie entre ces librairies, Wijmo est la plus impactante sur l’ergonomie de Novius OS.

Organisation des répertoires¶

De Novius OS¶

Repertoires à la racine¶

~/novius-os/ : Le core de Novius OS
~/local/ : Votre site
~/public/ : Le DOCUMENT_ROOT du site
~/logs/ : Un répertoire de logs

Le répertoire `public`¶

Un fichier peut être :

Exécutable ou non exécutable
Fourni par le developpeur ou le logiciel, ou généré par le logiciel

Cela donne 4 usages possibles. Chacun d’eux a un répertoire dans ~/public/ :

~/public/static/ : Équivalent des assets. Des fichiers non exécutables fournis par le développeur ou Novius OS.
~/public/data/ : Fichiers non exécutables générés par Novius OS.
~/public/htdocs/ : Fichiers exécutables fournis par par le développeur ou Novius OS.
~/public/cache/ : Fichiers exécutables générés par Novius OS

Note

Ici, Novius OS fait référence au core, ou toute application de votre site web.

Il y a un 5ème répertoire ~/public/media/ utilisé par la Médiathèque.

Là où Novius OS peut écrire, le développeur ne le peut pas et vice et versa.

~/public/static/ et ~/public/htdocs/ ont la même structure de sous-répertoire :

~/novius-os/ : Pour les fichiers venant du logiciel
~/apps/<application_name>/ : Pour les fichiers venant des developpeurs d’applications.

Ces sous-répertoires sont des liens symboliques, créés à l’installation du logiciel ou à l’activation des applications.
Ces liens symboliques pointant respectivement vers le htdocs et le static du repertoire du logiciel ou de l’application.
Voir ci-dessous l’organisation des répertoires d’une application.

Le répertoire du `core`¶

~/novius-os/framework/ : Le framework de Novius OS
~/novius-os/fuel-core/ : Le framework FuelPHP
~/novius-os/packages/ : Les packages FuelPHP

Le répertoire `local`¶

~/local/applications/ : Les applications Novius OS.
~/local/cache/ : Contient des médias redimensionnés.
~/local/classes/ : Classes PHP de vos développements.
~/local/config/ : Vos fichiers de configuration de Novius OS
~/local/data/ : Fichiers générés par Novius OS
~/local/metadata/ : Des fichiers de metadata de votre site, générés par Novius OS.
~/local/migrations/ : Des classes de migration.
~/local/views/ : Vos fichiers PHP de Views de vos développements.

Note

Les répertoires classes et views ne devrait pas contenir beaucoup de fichiers, la plupart de vos développements devrait être des applications..

D’une application¶

Tout Novius OS reprend les principes de segmentation issus de l’architecture MVC. Ils s’appliquent aussi bien au core qu’aux applications.

On distingue 6 dossiers principaux :

classes: Ce dossier regroupe la partie logique, c’est-à-dire les classes PHP qui définissent et manipulent les données. Il s’agit a minima des contrôleurs et modèles de l’application. On y retrouve également des outils utilisés par les vues ou directement par les contrôleurs.
config: Ce dossier rassemble l’ensemble des informations permettant de représenter vos modèles. Les contrôleurs effectuent les opérations logiques sur vos données, mais auront besoin d’informations complémentaires à transmettre aux vues pour leur représentation. Ces informations sont ainsi séparées des contrôleurs, n’ayant pas de valeur logique, et des vues, car celles-ci reçoivent les données en paramètres et ne les recherchent jamais.

Le fichie de configuration du contrôleur controller/admin/monkey.ctrl.php se situe à config/controller/admin/monkey.ctrl.php Une classe et son fichier de configuration partagent une convention de nommage symétrique.
lang: Ce dossier contient les fichiers de traduction, organisés en sous-dossiers par langue.
migrations: Ce dossier contient les fichiers de migration.
static: Ce dossier contient l’ensemble des scripts (JS et CSS) et ressources publiques (comme les images) chargées en front office.
views: Ce dossier contient les fichiers responsables de l’affichage et de la représentation des données.

Numérotation des versions¶

Pour comprendre la numérotation des versions de Novius OS, regardons de plus près cette release : Dubrovka 4.1.2.

La première partie (Dubrovka 4) est la version majeure. Les versions majeures de Novius OS sont numérotées et portent aussi le nom d’une ville pour être plus facilement identifiée (par ordre alphabétique, ex : ‘D’ est la 4ème lettre de l’alphabet). Les versions majeures apportent de nouvelles fonctionnalités à l’utilisateur final comme au développeur, corrige des bugs et les ruptures de compatibilité sont courantes.
La deuxième partie (1) est la version intermédiaire. Les versions intermédiaires apportent principalement des corrections de bugs et petites améliorations ; de nouvelles fonctionnalités mineures sont parfois disponibles. Il n’y a pas de rupture de compatibilité.
La dernière partie (2) est la version mineure. Les versions mineures sont pour la sécurité et les corrections de bugs uniquement. Elles n’apportent pas de nouvelles fonctionnalités et sont ainsi transparentes pour l’utilisateur final. Les mises à jour sont simples à effectuer.

Note

Avant Novius OS Dubrovka, la numérotation ne suivait pas exactement le modèle décrit ici.

Différences avec FuelPHP¶

Chemin des constantes¶

Consultez la documentation d’API des constantes.

Autoloader¶

Deux namespaces sont ajoutés par Novius OS :

novius-os:	pointant vers NOSPATH.
local:	pointant vers APPPATH.

Bootstrap et points d’entrées¶

Dans Novius OS, le front-office et le back-office sont deux espaces bien séparés.

Au lieu d’un seul point d’entrée index.php de FuelPHP, Novius OS a deux points d’entrée :

~/novius-os/htdocs/admin.php : Point d’entrée du back-office. Traite toutes les URL commençant par /admin/.
~/novius-os/htdocs/front.php : Point d’entrée du front-office. Traite toutes les URL finissant par .html ou la racine de votre site.

Point d’entrée du back-office¶

Novius OS a une route configurée pour son back-office, dont la règle est la suivante :

<?php
'routes' => array(
        '^admin/(:segment)/(:any)' => '$1/admin/$2',
),

Concrètement une URL admin/noviusos_page/page/insert_update/113 va être transformée en noviusos_page/admin/page/insert_update/113. Ce qui correspond à exécuter la méthode action_insert_update du controller Controller_Admin_Page de l’application noviusos_page.

Voir aussi

Documentation de FuelPHP sur le routing.

Principes ergonomiques¶

L’interface de Novius OS est construite autour de grands principes ergonomiques. Deux d’entre eux sont à connaitre pour le développement d’applications : la navigation par onglets et l’App Desk.

Navigation par onglets¶

Voir le screencast consacré à la navigation par onglets

Les onglets structurent le travail de l’utilisateur du back-office. Le but est de le faire gagner en productivité, en limitant les tâches répétitives et les chargement de pages.

On distingue deux types d’onglets :

Onglet d’application : Les onglets d’application n’ont pas de titre, ils sont uniquement représentés par l’icône de l’application, en grand. Dans cet onglet, on trouve l’App Desk de l’application (voir plus bas).
Onglet d’item : depuis l’onglet d’application, on accède à l’édition ou la visualisation d’un item, dans un nouvel onglet. Les onglets d’item portent le titre de l’item et l’icône de l’application, en petit.

Les avantages de la navigation par onglets sont multiples. On retiendra :

plusieurs items d’une même application peuvent être modifiés en parallèle ;
les aller-retours entre items ou applications sont extrêmement rapides ;
l’utilisateur reprend son travail là où elle / il l’avait laissé, l’ouverture des onglets étant conservée d’une session à une autre.

Les pop-ups doivent être limitées au cas modal, c’est-à-dire quand une action doit impérativement être accomplie (ou annulée) avant que le travail ne puisse se poursuivre (ex : confirmation d’une suppression, ajout d’un lien ou image à un contenu WYSIWYG).

L’App Desk¶

Voir le screencast consacré à l’App Desk

L’App Desk est l’accueil d’une application, il permet l’accès aux différents items. Il est constitué des éléments suivants :

Tableau principal : il liste les items d’une application, une ou plusieurs vues sont proposées (vignettes, tableau, arborescence, etc.). Son contenu est filtré par les inspecteurs et / ou une recherche full-text. Il ne peut y avoir qu’un seul tableau principal par App Desk.
Inspecteurs : les inspecteurs regroupent les éléments meta d’une application (ex : auteurs pour un blog, dossiers pour la médiathèque). Les inspecteurs permettent de filtrer le contenu du tableau principal (ex : voir uniquement les billets d’un auteur précis). Certains inspecteurs permettent aussi de gérer des données (ex : supprimer un dossier).
- Inspecteur de prévisualisation : l’inspecteur de prévisualisation est un cas particulier. Contrairement aux autres inspecteurs, il n’agit pas sur le tableau principal, c’est le tableau principal qui agit sur lui : quand un item est sélectionné, ses détails sont affichés dans l’inspecteur de prévisualisation (image, propriétés, récapitulatif des actions possibles pour l’item).
Actions : dans la vaste majorité des cas, chaque App Desk doit proposer une et une seule action principale, généralement l’ajout d’un nouvel item. Des actions secondaires peuvent aussi être proposées, sous forme de liens : ajout d’un élément meta (ex : un dossier) ou action fréquente (ex : export).

L’App Desk offre de nombreuses possibilités de mise en page aux développeurs, comme à l’utilisateur final. Néanmoins, nous recommandons de proposer comme mise en page par défaut une Three-Pane Interface :

Alternativement, l’inspecteur de prévisualisation peut être placé sous le tableau principal.

Fondamentaux des applications¶

Une application se définit par ses modèles, mais aussi par les contrôleurs et vues associés. Ils dépendent de la nature de l’application. Néanmoins, certains éléments / principes sont génériques et réutilisables dans tous les cas.

Définition¶

Pour pouvoir ajouter une application au gestionnaire d’applications, il faut créer un fichier metadata.config.php pour votre application. Ce fichier doit contenir le namespace de l’application, qui doit être de la forme Provider\NomApplication. Il faut y ajouter le nom de l’application, une version et le provider (caractérisé au minimum par un nom).

Il est également possible de définir d’autres éléments dans ce fichier metadata :

Launchers: Icônes de l’onglet d’accueil permet de lancer une application. Ils sont définis par un nom et une URL
Data catchers: Composant d’une application permettant d’exploiter les données partagées par d’autres (dites sharable data)
Enhancers: Grâce aux enhancers, une application vient enrichir le contenu édité dans un WYSIWYG.
Templates: Modèles de pages pour le front-office.

Voir aussi

Infographie ‘Comprendre les applications’

L’App Desk¶

Avant tout, consulter les principes ergonomiques pour comprendre l’App Desk.

La configuration de l’App Desk¶

L’App Desk est caractérisé par plusieurs éléments configurables :

le type d’affichage des données ;
les données à afficher ;
les actions principales et secondaires.

Le tableau principal peut proposer plusieurs vues (à ne pas confondre avec le V de MVC) : liste, arborescence ou vignettes.

Ces vues sont définies via des fichiers de configuration, qui précisent les données à afficher ainsi que les actions principales et secondaires.

Les inspecteurs sont également définis via des fichiers de configuration. Ils indiquent sur quel attribut ou relation les données du tableau principal seront triées, ainsi que les actions associées aux éléments de l’inspecteur. À noter que les inspecteurs sont basés :

Soit sur le même modèle que celui du tableau principal, l’inspecteur fait alors référence à des attributs (ex : date de création pour des billets de blog) ;
Soit sur un autre modèle (ex : auteur pour des billets de blog).

Contrôleurs, formulaires et modèles¶

Depuis l’App Desk, il est possible d’appeler des contrôleurs qui réalisent des opérations sur les données concernées.

Certaines opérations s’effectuent directement (ex : la suppression, seule une confirmation est demandée). Elles sont, dans ce cas, attribuées au contrôleur de l’App Desk.

D’autres opérations appelent une vue et sont alors attribuées au contrôleur du modèle. Généralement, la vue appelée est un formulaire (ajout / édition). Ce dernier est construit grâce au fichier de configuration du modèle, qui peut être rempli grâce à une instance du modèle. Le contrôleur est de nouveau appelé lors de l’envoi du formulaire pour enregistrer les données.

Observers et behaviours¶

Les observers sont issus du framework FuelPHP.

Ce sont des procédures liées directement à un modèle. Elles sont appelées lorsque qu’un évènement identifié est déclenché. Ces procédures sont utilisées pour formatter, modifier ou valider des propriétés du modèle (ex : reformattage des données avant l’ajout en base de données).

Les behaviours, implémentées pour Novius OS, reprennent et étendent ce principe. Là où les observers effectuent une action sur une propriété du modèle, les behaviours définissent un ensemble de méthodes qui établissent un comportement particulier sur le modèle (ex : translatable, publishable). Ces méthodes sont également déclenchées via des évènements.

Ces outils ont pour intérêt de mutualiser des méthodes pour plusieurs modèles distincts.

Partage de contenu¶

Voir aussi

Infographie « Partage dans Novius OS »

Content nuggets¶

Un « content nugget », ou pépite de contenu, est un ensemble cohérent de données destiné à être partagé.

Structure des données¶

Les données d’un content nugget peuvent être de la nature suivante :

Titre
URL
Texte
Image

Pour qu’une application puisse partager son contenu, il suffit de lui assigner le Behaviour Sharable et définir quelles sont les données constituant le content nugget.

Data catchers¶

Les data catchers sont des composants d’une application qui exploitent les content nuggets (eux-mêmes générés par les modèles).

Ils sont définis dans le fichier metadata.config.php d’une application, à l’image des autres composants (gabarits, enhancers et launchers).

Data catchers inclus dans le logiciel¶

Simple Twitter
Simple Facebook
Simple Google+
Blog

Le data catcher Blog est utilisé pour créer des billets de blog à partir du contenu d’autres applications, notamment d’applications métiers spécifiques. Vous ajoutez, par exemple, un nouveau produit à votre catalogue, vous préparez facilement un billet de blog annonçant cette nouveauté.

Exemple : Simple Twitter¶

Voici comment est défini le data catcher de partage simple vers Twitter :

<?php

return array(
'data_catchers' => array(
    'noviusos_simpletwitter' => array(
        'title' => 'Twitter',
        'description'  => '',
        'iconUrl' => 'static/apps/noviusos_simpletwitter/img/twitter.png',
        'action' => array(
            'action' => 'window.open',
            'url' => 'https://twitter.com/intent/tweet?text={{urlencode:'.\Nos\DataCatcher::TYPE_TITLE.'}}&url={{urlencode:absolute_url}}',
        ),
        'onDemand' => true,
        'specified_models' => false,
        'required_data' => array(
            \Nos\DataCatcher::TYPE_TITLE,
        ),
        'optional_data' => array(
            \Nos\DataCatcher::TYPE_URL,
        ),
    ),
),
);

Le data catcher Simple Twitter exploite des content nuggets ayant au moins un titre. L’URL est optionnelle, mais est utilisée quand elle est fournie.

Multi-Contextes¶

Principes du multi-Contextes¶

Novius OS peut nativement gérer plusieurs sites, chacun de ces sites pouvant avoir plusieurs versions linguistiques.

Un contexte est un binome site / langue.

Exemple¶

Votre instance de Novius OS peut gérer votre site vitrine qui se décline en 3 langues (français, anglais et espagnol), votre site pour mobile disponible qu’en français, et un site événementiel en anglais.

Site / Langue	Français	Anglais	Espagnol
Vitrine	X	X	X
Mobile	X
Événementiel		X

Votre instance Novius OS gérera alors 5 contextes :

Vitrine / Français
Vitrine / Anglais
Vitrine / Espagnol
Mobile / Français
Événementiel / Anglais

Configuration¶

Pour configurer les différents contextes de votre instance Novius OS, veuillez vous référer à la documentation d’API.

Cas particuliers¶

Qui peut le plus peut le moins. Votre Novius OS peut gérer :

un seul site dans plusieurs langues
plusieurs sites dans une seule langue
un seul site dans une seule langue

L’interface du back-office tient compte de ses différents cas. Le terme _contexte_ s’effacera alors pour ne parler plus que de sites ou de langues.

Il disparaitra même complètement en cas d’un seul site et de une seule langue.

Ajouter des contextes¶

Vous pouvez ajouter à n’importe quel moment de nouveaux contextes, sites ou langues à votre configuration. Modifiez simplement votre fichier contexts.config.php, les nouveaux contextes sont aussitôt pris en compte.

Voir aussi

Documentation d’API du multi-contextes.

`Contextable` / `Twinnable`¶

Novius OS est nativement multi-contextes. Mais chaque application décide de la façon dont elle utilise les contextes. Trois cas de figures.

Application n’utilisant pas les contextes¶

Le cas le plus simple. Une application n’implémente pas la notion de contexte. C’est le cas par défaut, elle n’a rien à faire.

Son contenu sera alors le même quelque soit le contexte et elle pourra être utilisée (via ses enhancers) dans n’importe quel contexte.

Application `Contextable`¶

L’application utilise les contextes. Chaque item est associé à un contexte et ne peut être utilisé que dans son contexte.

Techniquement les tables de l’application auront un champ context de type varchar(25) contenant le code du contexte et les Models de l’application implémenteront le behaviour Contextable.

Application `Twinnable`¶

L’application utilise les contextes et crée des ponts entre-eux. Chaque item est associé à un contexte et peut-être lié à d’autres items de contextes différents.

Techniquement les tables de l’application auront 3 champs :

common_id_property:
context:	de type `varchar(25)` et contenant le code du context de l’item.
	de type `int` et contenant un ID commun aux items liés entre-eux.
is_main_property:
	de type `boolean`, chaque groupe d’items liés entre-eux a un seul item principal.

Les Models de l’application implémenteront le behaviour Twinnable.

Exemple¶

Struture de la table d’exemple :

item_id (clé primaire)
item_context
item_common_id_property
item_is_main_property
item_title

Créons un premier item :

item_id	item_context	item_common_id_property	item_is_main_property	item_title
1	main::fr_FR	1	1	Premier item

La colonne item_common_id_property prend le même ID que la clé primaire de l’item.

L’item est déclaré item principal, donc la colonne item_is_main_property prend la valeur 1.

Ajoutons un autre item, dans un autre contexte, et lié au premier item :

item_id	item_context	item_common_id_property	item_is_main_property	item_title
1	main::fr_FR	1	1	Premier item
2	main::en_GB	1	0	First item

La colonne item_common_id_property prend le item_common_id_property de l’item auxquel il est lié.

La colonne item_is_main_property prend la valeur 0, ce n’est pas l’item principal.

Observons la table après plusieurs ajouts :

item_id	item_context	item_common_id_property	item_is_main_property	item_title
1	main::fr_FR	1	1	Premier item
2	main::en_GB	1	0	First item
3	main::en_GB	3	1	Second item
4	main::fr_FR	3	0	Second item (fr)
5	event::fr_FR	5	1	Item du site event
6	main::es_ES	1	0	First item (es)

Les items 1, 2 et 6 sont liés entre-eux et l’item principal est 1 / main::fr_FR.

Les items 3 et 4 sont liés entre-eux et l’item principal est 3 / main::en_GB.

Supprimons l’item 1 :

item_id	item_context	item_common_id_property	item_is_main_property	item_title
2	main::en_GB	1	1	First item
3	main::en_GB	3	1	Second item
4	main::fr_FR	3	0	Second item
5	event::fr_FR	5	1	Item du site vent
6	main::es_ES	1	0	First item

L’item 2 a récupéré le rôle principal, mais l’item_common_id_property du 2 et du 6 n’a pas changé.

Médiathèque¶

Principe¶

La médiathèque est un point central qui regroupe la majorité des fichiers utilisés par les applications. Elle contient des images, des documents, des vidéos ou tout autre type de fichier.

Les fichiers sont stockés dans le répertoire privé /novius-os/local/data/media/
On y accède par l’URL http://your.website.com/media/folder/ressource.ext

Fonctionnement¶

Lors du premier accès au média, le gestionnaire 404 est appelé et un lien symbolic est alors créé dans public/media et les requêtes suivantes n’auront plus besoin de gestionnaire 404.

La raison de ce fonctionnement est pour l’ajout futur de médias privé. Pour ces derniers, sera retourné :

un code d’erreur HTTP 401 (autorisation nécessaire) ;
soit le fichier sera envoyé sur la sortie standard, mais sans création de lien symbolique (le droit d’accès est vérifié lors de chaque requête).

Dans le cas des images transformées, le processus est similaire avec une étape supplémentaire : l’enregistrement de l’image transformée dans le répertoire local/cache/media/.

Optimisation¶

Lorsque PHP envoie le fichier, le processus est bloqué jusqu’à ce que la totalité du fichier soit transféré. Il est néanmoins possible de libérer le processus instantanément en déléguant l’envoi du fichier au serveur web sous-jacent (Apache ou nginx).

Le mécanisme utilisé s’appelle XSendfile et consiste à envoyer un header spécial depuis le script PHP. Le nom de ce header varie d’un serveur à l’autre :

X-Sendfile est utilisé par Apache et d’autres ;
X-Accel-Redirect est utilisé par nginx.

Voir aussi

Optimisations après installation

Fichiers joints (hors médiathèque)¶

Vous n’avez pas forcément envie de stocker tous vos fichiers dans la médiathèque. Par exemple, si vous avez une application « Offres d’emploi » qui reçoit des candidatures, vous ne souhaitez pas que les CV des candidats soient visibles dans la médiathèque.

Pour traiter ce cas, il existe un mécanisme de fichiers indépendants Attachment. À la manière des pièces jointes dans un e-mail, il est ainsi possible de joindre un fichier CV à une candidature.

Permissions et droits d’accès¶

Rôles (ou “profils”)¶

Les permissions s’appliquent systématiquement sur un rôle. Ensuite, chaque utilisateur se voit attribuer un ou plusieurs rôles, dont il hérite les droits d’accès.

Un rôle par utilisateur¶

Pour des raisons de simplicité et de compréhension, dans une installation par défaut :

ces rôles sont cachés ;
chaque utilisateur se voit automatiquement attribuer un seul rôle ;
il n’est pas possible de partager un rôle entre plusieurs utilisateurs.

La notion de rôle s’efface complètement et les droits d’accès se configurent via un onglet dédié sur la fiche d’un utilisateur :

Plusieurs rôles par utilisateur¶

Il est cependant possible d’activer la gestion des rôles multiples dans le fichier de configuration principal : novius-os.users.enable_roles = true.

Une fois activés, il devient donc possible de partager un rôle entre plusieurs utilisateurs. Les permissions peuvent alors se configurer plus finement :

sur la fiche d’un utilisateur, l’onglet “Droits d’accès” disparait au profit d’un bloc “Rôles” ;
l’AppDesk de l’application Utilisateurs s’enrichit :
- d’un nouvel inspecteur “Rôles” ;
- une nouvelle action “Ajouter un rôle”.
les droits d’accès se configurent désormais sur la fiche d’un rôle.

Structure d’un droit d’accès¶

Il existe deux types de droits d’accès :

les simples : oui ou non ;
les multiples : applicables sur une liste de catégories.

Le droit simple a du sens en lui-même, par exemple “Est-ce que je peux ajouter une page ?” ou encore “Est-ce que je peux supprimer une page verrouillée ?”.

Les droits multiples n’ont pas de sens seuls, ils s’expriment uniquement en fonction d’une catégorie. Par exemple, “Est-ce que je peux écrire dans ce dossier ?” a besoin d’une liste de dossiers sur lesquels s’appliquer, ou bien “Est-ce que j’ai accès à cette application ?” a besoin de la liste des applications pour s’exprimer.

Un droit simple est composé d’une seule colonne perm_name, tandis qu’un droit multiple (= droit par catégorie) est composé de deux colonnes : perm_name (comme pour le droit simple) et perm_category_key.

Utilisation dans les applications¶

Fichier `permissions.config.php`¶

Grâce à ce fichier, chaque application peut définir la liste des permissions qu’elle souhaite configurer.

L’affichage se fait dans une colonne dédiée à droite du nom de l’application lors de l’édition des permissions :

Voir aussi

API associée au fichier de configuration des permissions

API pour vérifier une permission¶

<?php
// Simple : 1 seul argument, le nom de la permission
\Nos\User\Permission::check('noviusos_app::delete_locked');

// Multiple (réglable par catégories) : 2 arguments, le nom de la permission + la clé de la catégorie
\Nos\User\Permission::check('noviusos_app::create_in_folder', $folder_id);

// Gestion de niveau d'accès (avancé, utile quand combiné à des rôles multiples) : 2 arguments, le nom de la permission + le niveau (numérique)
\Nos\User\Permission::atLeast('noviusos_app::level', '2_moderator');

Voir aussi

Documentation d’API pour la classe Permission.

Warning

Le nom de la permission est un élément important. La partie avant les :: doit représenter un nom d’application valide. Pour que la permission soit validée, il faut également que l’utilisateur ait accès à cette application.

CRUD¶

Il est possible de cacher des champs en fonction des permissions. Pour cela, il faut utiliser la clé show_when qui définit une fonction de callback retournant si le champ doit être visible ou non.

 <?php
 return array(
     'fields' => array(
         'my_field' => array(
             'label' => 'My field',
             'form' => array(
                 'type' => 'text',
             ),
             'show_when' => function() {
                 // The field will only be visible when the user has the requested permission
                 return Permission::check('my_app::my_permission');
             },
         ),
     ),
 );

Actions¶

Il est possible de désactiver des actions en fonction des permissions grâce à la clé disabled.

 <?php
 return array(
     'data_mapping' => array(/*...*/),
     'actions' => array(
         'delete' => array(
             'label' => __('Delete'),
             'primary' => false,
             'icon' => 'home',
             'action' => array(/*...*/),
             'targets' => array(
                 'grid' => true,
             ),
             'disabled' => array(
                 function($item) {
                     return !Permission::check('my_app::can_delete_item') ? __('You don\'t have the permission to delete items.') : false;
                 }
             ),
         ),
     ),
 );

Front-Office et cache¶

Novius OS utilise le mod_rewrite d’Apache (ou l’équivalent sur un autre serveur) pour afficher les pages en front-office.

Toutes les URLs finissant par .html, la home et les répertoires sont redirigées vers le fichier NOSROOT/public/htdocs/novius-os/front.php.

Ce fichier charge Novius OS et délègue le traitement de l’URL au Controller_Front.

Le Controller_Front analyse l’URL et détermine le chemin du fichier de cache correspondant. À partir de là, plusieurs possibilités.

Exécution du cache¶

Le fichier de cache correspondant à l’URL existe.

Le cache des pages est enregistré dans le répertoire NOSROOT/local/cache/page/. Le premier niveau d’arborescence correspond aux domaines des URLS. Le cache recrée ensuite l’arborescence de l’URL.

Le fichier de cache en lui-même est un fichier PHP. Le début du fichier contient toujours une vérification de la validité du cache par rapport à sa durée de vie. Il contient également un mécanisme pour recréer les propriétés du Controller_Front qui étaient disponibles au moment de sa génération (page, URLs, status, headers, custom data).

Ce fichier de cache est exécuté et, s’il est toujours valide, ce qu’il affiche est renvoyé à l’internaute, avec le status et les headers enregistrés.

Génération du cache¶

Si le fichier de cache correspondant à l’URL n’existe pas ou n’est plus valide.

Le Controller_Front va déterminer la page appelée en fonction de l’URL. La page connue, il récupère le template qui lui est lié. Puis le ou les WYSIWYG de la page venant s’insérer dans le template.

Si les WYSIWYG contiennent des enhancers, ces enhancers sont exécutés et leur résultat enregistré.

Puis le template est exécuté comme une View en prenant comme paramètre le tableau des WYSIWYG ($wysiwyg), le titre de la page ($title), la page ($page) et le Controller_Front ($main_controller).

Le contenu généré est enregistré dans le fichier de cache.

Puis le fichier de cache est exécuté comme expliqué ci-dessus, et renvoie le contenu à l’internaute, avec le status et les headers potentiellement spécifiés lors du processus de génération du cache (notamment par les enhancers).

Interactions possibles¶

Au cours du processus, le Controller_Front envoie différents événements à des moments clés. En interceptant ces événements vous pouvez influencer ou modifier le traitement.

Voir aussi

Événements front-office

Vous pouvez également influencer ou modifier le traitement par les méthodes du Controller_Front en récupérant son instance, soit par NosNos::main_controller(), soit via $this->main_controller dans un enhancer.

Modifier le contenu généré¶

Dans certains cas, vous pouvez vouloir générer un contenu de sortie sans tenir compte du template, par exemple pour renvoiyer un flux RSS depuis un enhancer. Pour cela, utiliser la méthode sendContent() du Controller_Front.

Voici un exemple de code d’un enhancer :

<?php

$this->main_controller->setHeader('Content-Type', 'application/xml');
$this->main_controller->setCacheDuration(60 * 30); // La durée de cache est fixée à 30 minutes
return $this->main_controller->sendContent($rss); // La variable $rss contient le flux RSS

Le fichier de cache ne contiendra alors que le contenu du flux RSS et la réponse HTTP enverra un header pour spécifier le content-type.

Exécution hors cache¶

Dans certain cas, le système de cache peut-être trop efficace. Par exemple, si une partie du template ou d’un enhancer doit être différent en fonction de si l’utilisateur est identifié ou non. Dans ce cas il est utile d’enregistrer dans le cache le code PHP a exécuter et non pas son résultat.

Pour cela, il suffit d’utiliser les méthodes callHmvcUncached() et viewForgeUncached de la classe FrontCache.

<?php

\Nos\FrontCache::callHmvcUncached(
    'uri/controller',
    array(
        'id' => \Front_Utilisateur::get_current_user_id() // C'est un exemple, la classe \Front_Utilisateur n'existe pas.
    )
);

// ou

\Nos\FrontCache::viewForgeUncached(
    'uri/view', // Le chemin d'une vue
    array(
        'id' => \Front_Utilisateur::get_current_user_id()
    ),
    false
);

Suffix Handler¶

Si vous voulez que le chemin de cache tienne compte d’autre chose que de la simple URL. Par exemple, que le cache tienne compte d’un paramètre GET (par défaut, le même cache est utilisé que l’URL ai ou n’ai pas de paramètre GET).

Pour cela, il suffit d’utiliser la méthode addCacheSuffixHandler() du Controller_Front.

<?php

\Nos\Nos::main_controller()->addCacheSuffixHandler(array(
    array(
        'type' => 'GET',
        'keys' => array('my_param'),
    ),
));

// ou

\Nos\Nos::main_controller()->addCacheSuffixHandler(array(
    array(
        'type' => 'callable',
        'callable' => array('MyClasse', 'myMethod'),
        'args' => array(
            'argument pour exemple'
        ),
    ),
));

Dans le 1er cas, le système de cache gérera un fichier différent pour une même URL ayant un paramètre GET my_param avec une valeur différente.

Dans le second cas, le système de cache appellera la méthode MyClasse::myMethod('argument pour exemple'), charge à la méthode de renvoyer un suffixe au fichier de cache si besoin.

Gérer votre site web¶

Installer une application dans Novius OS¶

Où trouver des applications ?¶

Le compte GitHub de Novius OS est un bon point de départ.

La page des contributeurs sur le site Novius OS liste des applications de la communauté.

Vous pouvez également aller directement sur les comptes GitHub de Fumito Mizuno et de Novius Agency qui contiennent beaucoup d’applications.

Installer une nouvelle application¶

2 solutions sont possibles : utiliser Git ou via un fichier .zip.

Méthode 1 : utiliser Git¶

Sur GitHub, copiez l’URL Git du dépôt :

Cloner ensuite le dépôt dans le répertoire /local/applications/.

cd local/applications
git clone URL_DU_DEPOT

Enfin, n’oubliez pas d’aller activer l’application depuis le gestionnaire d’applications.

Méthode 2 : via un fichier .zip¶

Sur GitHub, télécharger l’application sous forme de fichier .zip.

Dézipper l’archive téléchargée dans le répertoire /local/applications/.

Renommer le répertoire créé pour supprimer le nom de la branche (rajouté automatiquement par GitHub). Par exemple, il faut renommer novius_ftplite-master-elche en novius_ftplite tout court.

Enfin, n’oubliez pas d’aller activer l’application depuis le gestionnaire d’applications.

Warning

Ne modifiez pas les fichiers présents à l’intérieur de l’application que vous venez de télécharger, sinon vous ne pourrez pas la mettre à jour. Utilisez les mécanismes d’extensions d’application pour faire une modification.

Activer une application¶

Ouvrez le gestionnaire d’applications (depuis le bureau) :

Cliquez sur « Installer » à côté du nom de votre application :

Mettre à jour une application¶

Méthode 1 : avec Git¶

Allez dans le répertoire de votre application, puis mettez le dépôt à jour dans la version souhaitée :

cd local/applications/novius_ftplite
git fetch
git checkout master/elche

Allez ensuite dans le gestionnaire d’applications pour « Prendre en compte les changements ».

Méthode 2 : depuis un fichier .zip¶

Note

Avant de mettre à jour une application, vérifiez que vos (éventuels) développements spécifiques sont compatibles.

Sur GitHub, téléchargez la nouvelle version de l’application sous forme de fichier .zip.

Remplacez ensuite le répertoire de correspondant dans local/applications (vous pouvez supprimer l’ancien répertoire pour y mettre le nouveau).

Comme pour l’installation, n’oubliez pas de renommer le répertoire créé pour supprimer le nom de la branche (rajouté automatiquement par GitHub).

Allez ensuite dans le gestionnaire d’applications pour « Prendre en compte les changements ».

Définir les langues et contextes de votre site¶

Avec Novius OS, vous pouvez gérer plusieurs sites et/ou langues dans le même back-office. Un “contexte” est un couple site / langue.

Voir aussi

Principes du multi-Contextes

Vous pouvez définir ces contextes à n’importe quel moment, même après la mise n ligne du site. Éditez simplement le fichier contexts.config.php.

Voir aussi

Documentation API sur le multi-contextes.

Formatage des URL¶

Tous les segments d’URL construient dans Novius OS sont formattés avec le mécanisme “friendly slug”.

Par défaut :

Les caractères ?, :, \, /, #, [, ], @, & et l’espace sont remplacés par un -.

Transformation en minuscules.

Suppression des - en début ou fin de chaine.

Remplacement de - consécutifs par un seul.

Mais vous pouvez utiliser d’autres règles ou définir vos propres règles. Vous pouvez également avoir des règles spéciales pour les contextes.

Quatre lots de règles sont définis :

default (comme décrit ci-dessus)
no_accent. Tous les accents sont remplacés par un caractère équivalent non accentué.
no_special. Tous les caractères qui ne sont pas des caractères de mot, le - ou le _ sont remplacés par -.
no_accent_and_special. Combinaison des lots de règles no_accent et no_special.

Un fichier de configuration d’exemple est disponible : local/config/friendly_slug.config.php.sample. Si vous voulez modifier les règles appliquées par défaut, renommez ou copiez le fichier en local/config/friendly_slug.config.php, et modifiez le selon votre cas.

Règles par défaut¶

Pour changer les règles par défaut :

créez un jeu de règle dans setups.
Définissez l’active_setup égal à ce jeu.

<?php
return array(
    'active_setup' => 'my_default',

    'setups' => array(
        'my_default' => array(
            // Utilise les règles 'no_accent'
            'no_accent',

            // Remplace l'espace en '_'
            ' ' => '_',

             // Tous les caractères qui ne sont pas des mots, un '-' ou un '_' ou un '*' sont remplacés par '-'.
            '[^\w\*\-_]' => array('replacement' => '-', 'flags' => 'i'),
        ),
    ),
);

Règles par contexte¶

Pour définir des règles spécifiques à un contexte, définir une clé avec l’ID de contexte dans le tableau setups.

<?php
return array(
    'setups' => array(
        'main::en_GB' => array(
            //... Définissez ici vos règles spécifiques au contexte main::en_GB
        ),
    ),
);

Voir aussi

Documentation API sur le “Friendly slug”.

Mise en production¶

Transfert de l’instance sur le serveur de production¶

Il y a plusieurs façons d’envoyer une instance Novius OS sur votre serveur de production :

La façon la plus simple serait de copier tous les fichiers de l’instance ainsi que la base de donnée sur le serveur. Cependant, comme les données sont généralement différentes entre ces deux instances, ce n’est pas très pratique. Et vous aurez probablement à modifier les fichiers de configuration.
Vous pouvez envoyer tous les fichiers sauf ceux des dossiers local/metadata et local/data. Vous devrez installer Novius OS sur le serveur la première fois. Ainsi, la configuration de mysql, des urls, et du compte administrateur se fera facilement.

Cependant, quelque soit la méthode que vous choisissez, vous devrez changer quelques éléments de configurations afin d’améliorer l’optimisation.

Changer l’environnement en mode production¶

La première étape est de changer l’environnement Fuel (enregistré sous Fuel::$env). Cela adaptera automatiquement quelques paramètres tels que la durée de vie du cache ou le niveau des logs. Le site de FuelPHP explique comment changer cet environnement.

Vous pouvez le faire en changeant le valeur de SetEnv dans la configuration d’Apache.

SetEnv FUEL_ENV production
// ou
SetEnv NOS_ENV production

Configuration de connection à la base de données¶

Vous devez ajouter la clé production dans le fichier de configuration local/config/db.config.php. La configuration peut être assez similaire que celle de la clé development; si vous avez installé votre instance directement sur le serveur de production, vous n’avez juste qu’à renommer la clé development en production. Le site de FuelPHP documente très bien comment configurer l’accès à votre base de données.

Modifier les durées de vie du cache¶

La durée de vie du cache est adaptée si l’environnement est en production. Vous pouvez néanmoins la changer en modifiant le fichier local/config/config.php.

return array(
    'novius-os' => array(
        'cache' => true,
         // Les durées de vie de cache sont par défaut à 3600 secondes en mode production
        'cache_duration_page' => 3600, // durée de vie du cache des pages
        'cache_duration_function' => 3600, // durée de vie du cache des autres éléments (applications...)
        'cache_model_properties' => false, // définit si Novius OS enregistrer les propriété des modèles dans le
        // cache. S'applique uniquement aux modèles dont les propriétés ne sont pas définies
    ),
);

Configuration des emails¶

Si vous avez besoin que votre instance Novius OS puisse envoyer des emails, vous devez renommer votre fichier local/config/email.config.php.sample en local/config/email.config.php. Les détails de configuration sont très bien expliqués dans le site de FuelPHP.

Les bases de FuelPHP¶

Qu’est-ce que le MVC ?¶

C’est l’acronyme de Modèle-Vue-Contrôleur.

C’est une approche pour séparer votre code en fonction du rôle qu’il joue. De manière simplifiée, une requête est traitée par un contrôleur. Ce dernier charge des données en passant par les modèles. Enfin, il décide quelle vue sera utilisée pour afficher les données qui seront visibles par vos visiteurs.

Voir aussi

MVC dans la documentation FuelPHP

Voir aussi

MVC dans Wikipedia

Où créer mes nouveaux fichiers ?¶

Toutes les classes respectent la même convention de nommage précise :

en minuscule, sauf la première lettre de chaque niveau en majuscule ;
les underscore jouent le rôle de dossier.

Par exemple le fichier classes/controller/admin/login.php correspond à la classe nommée Controller_Admin_Login.

Les classes PHP se situent dans le dossier classes.

Les classes contrôleurs trouvent leur place dans le dossier classes/controller.

Les classes modèles vont dans classes/model.

Comment écrire une vue ?¶

Les vues sont situées dans le dossier views.

Voir aussi

Documentation de FuelPHP sur les vues

Comment utiliser l’ORM ?¶

Un ORM permet 2 choses :

accéder à vos données en base sous forme d’objets PHP ;
établir des relations entre ces objets.

L’ORM de FuelPHP utilise le pattern Active Record.

Les liens suivants vers la documentation de FuelPHP vous seront utiles :

Voir aussi

Créer des modèles

Voir aussi

Faire des requêtes à partir des modèles

Voir aussi

Définir des relations et s’en servir dans les requêtes

Créer une nouvelle application¶

Assistant “Créer mon appli”¶

L’assistant “Créer mon appli” permet de générer facilement et rapidement les bases d’une nouvelle application : Modèles, champs et groupe de champs, App Desk, launchers, URL enhancers, etc.

En industrialisant la création d’une application, l’assistant vous permet d’être plus productif et de vous concentrer sur l’essentiel.

Warning

La dernière étape de l’assistant “Créer mon appli” est la création de la base données et des fichiers de votre nouvelle application. Ces fichiers seront dans un nouveau répertoire, au nom de votre application, dans local/application/. Novius OS (le user Apache si Novius OS tourne sur un serveur Apache) doit donc avoir les droits d’écriture dans ce répertoire.

Créer un enhancer¶

1. Définition dans le fichier `metadata`¶

Les metadata d’un enhancer sont décrites dans la documentation d’API.

2. [Back-office] Créer un contrôleur pour l’enhancer¶

Pour gérer la popup de configuration et la prévisualisation de l’enhancer, nous avons besoin d’un contrôleur.

Créez donc le fichier mon_appli::classes/controller/admin/enhancer.ctrl.php en étendant le Controller_Admin_Enhancer adéquat.

<?php

namespace Mon\Appli;

class Controller_Admin_Enhancer extends \Nos\Controller_Admin_Enhancer
{

}

Comme tous les contrôleurs de Novius OS, ajoutons lui un fichier de configuration mon_appli::config/controller/admin/enhancer.config.php

<?php

return array(
    // Vide pour l'instant, nous allons le remplir plus bas
);

Popup de configuration¶

L’affichage ou non d’une popup de configuration est conditionnée par la présence ou non de la clé dialog dans le fichier metadata.config.php. Ajoutons cette information :

<?php

return array(
    'enhancers' => array(
        'mon_appli' => array(
            'dialog' => array(
                'contentUrl' => 'admin/mon_appli/enhancer/popup',
                'ajax' => true,
            ),
        ),
    ),
);

Ici, la popup fera appel à la méthode action_popup() de la classe Mon\Appli\Controller_Admin_Enhancer. Ce dernier est prévu pour fonctionner en Ajax.

Comme pour toute modification du fichier metadata.config.php, il faut aller appliquer les changements depuis le gestionnaire d’applications.

Désormais, lorsqu’on ajoute notre enhancer dans un WYSIWYG, une popup s’affiche, mais il n’y a aucune option à configurer !

Le contrôleur standard que nous avons étendu prévoit d’être configuré pour ajouter les options de l’enhancer. Rendez-vous dans le fichier de configuration mon_appli::config/controller/admin/enhancer.config.php :

 <?php

 return array(
     // Configuration des options de configuration dans la popup
     'fields' => array(
         'item_per_page' => array(
             'label' => __('Item per page:'),
             'form' => array(
                 'type' => 'text',
                 'value' => 10, // This is only the default
             ),
         ),
     ),
 );

La syntaxe des fields est identique à celle du fichier de configuration du CRUD, avec possibilité de mettre des renderers.

Lorsque vous configurez uniquement les fields et que vous n’avez pas renseigné popup.layout, le contrôleur en ajoute un automatiquement pour vous avec cette configuration :

 <?php

 return array(
     // Généré automatiquement par le contrôleur lorsque les ``fields`` sont présents
     'popup' => array(
         'layout' => array(
             'fields' => array(
                 'view' => 'nos::form/fields',
                 'params' => array(
                     'fields' => array(/* Liste de tous les champs renseignés dans 'fields' */),
                     'begin' => ' ',
                     'end' => ' ',
                 ),
             ),
         ),
     ),
 );

Si vous souhaitez modifier ce layout par défaut (par exemple rajouter une 2e vue pour inclure du JavaScript), vous devez le renseigner en totalité (et remettre la vue nos::form/fields si vous en avez besoin).

À l’intérieur des vues, les variables suivantes sont disponibles :

$enhancer_args : l’ancienne configuration de l’enhancer ;
$fieldset : lorsque vous avez renseignés des fields, un Fieldset est créé dans cette variable.

Modifier la prévisualisation¶

La prévisualisation ajoutée dans le WYSIWYG est chargée en faisant appel à la valeur previewUrl configurée dans le fichier metadata.config.php.

Généralement, vous ferez appel au même contrôleur que celui de la popup, mais en appelant la méthode action_preview() au lieu de action_popup().

La vue fournie par défaut utilise une icône, un titre (les valeurs par défaut reprennent l’icône 64*64 de l’application, ainsi que le titre de l’enhancer) et un layout (fichiers de vues additionnels appelés).

mon_appli::config/controller/admin/enhancer.config.php :

 <?php

 return array(
     // Configuration de la popup
     'fields' => array(
         // Ce qu'on avait configuré plus tôt
     ),
     // Configuration de la prévisualisation
     'preview' => array(
         // (facultatif) vue à utiliser pour le rendu (valeur par défaut en exemple)
         //'view' => 'nos::admin/enhancer/preview',
         // (facultatif) fichiers de vues additionnels (inclus par la view au-dessus)
         //'layout' => array(),
         'params' => array(
             // (optionnel) reprend le titre de l'enhancer par défaut
             'title' => "Mon super enhancer",
             // 'icon' (optionnel) reprend celui de l'application en taille 64*64 par défaut
         ),
     ),
 );

À noter qu’il est possible de spécifier une fonction de callback à la fois pour le titre ou pour l’icône. Elle recoit alors un paramètre : la configuration de l’enhancer $enhancer_args.

Par exemple, pour l’enhancer « Formulaire », le titre du formulaire sélectionné s’affiche.

3. [Front-office] Afficher votre contenu sur le site¶

Une fois la page enregistrée et publiée, l’enhancer va s’exprimer sur le site.

Le contenu sera généré par le contrôleur configuré dans une des clés enhancer ou urlEnhancer du fichier metadata.config.php (selon si on voulait un enhancer simple ou un URL enhancer). N’oubliez pas de prendre en compte les changements dans le gestionnaires d’applications si vous faites des modification sur ce fichier.

Par exemple, l’application « Formulaires » a pour configuration noviusos_form/front/main ce qui fera appel à la méthode action_main() du Controller_Front de l’application noviusos_form (qui correspond en fait au contrôleur Nos\Form\Controller_Front).

Cette action prend en paramètre le tableau de configuration qui a été défini dans la popup de configuration $enhancer_args.

Créons le contrôleur mon_appli::controller/front.ctrl.php

<?php

namespace Mon\Appli;

class Controller_Front extends \Nos\Controller_Front_Application
{
    public function action_main($enhancer_args = array())
    {
        // Pour tester
        return print_r($enhancer_args, true);
    }
}

4. URL enhancers¶

Dans le cas d’un URL enhancer, ce dernier sera capable de gérer des URL.

Lorsqu’on parle du billet de blog toto ou de la catégorie ski, on fait en réalité référence au billet de blog dont le nom virtuel est toto et à la catégorie dont le nom virtuel est ski.

Prenons un exemple : si votre URL enhancer a été ajouté sur la page mon/blog.html, alors il sera en mesure de gérer des URL qui commencent par mon/blog/**.html, comme :

mon/blog.html (liste de tous les billets) ;
mon/blog/toto.html (billet de blog toto) ;
mon/blog/page/2.html (2^e page de la liste des billets) ;
ou encore mon/blog/category/ski.html (liste des billets de la catégorie ski).

Comme précédemment, le contenu est généré par l’action main, mais il est possible de récupérer l’URL étendue avec $this->main_controller->getEnhancerUrl();.

Ensuite, le contrôleur peut générer du contenu différent en fonction de l’URL demandée. Voici un exemple (simplifié) tiré de l’application « Blog » :

<?php

namespace Nos\Blog;

class Controller_Front extends \Nos\Controller_Front_Application
{
    public function action_main($enhancer_args = array())
    {
        // URL complète de la page == 'mon/blog/category/ski.html'
        // => $enhancer_url == 'category/ski' (sans .html)
        $enhancer_url = $this->main_controller->getEnhancerUrl();
        $segments = explode('/', $enhancer_url);

        if (empty($enhancer_url))
        {
            // URL 'mon/blog.html' (URL de la page sur laquelle a été ajouté l'enhancer)
            // Affichage de la liste des billets (page 1)
        }
        else if (count($segments) == 1)
        {
            // URL 'mon/blog/toto.html'
            // Affichage du billet de blog 'toto'
        }
        else if (count($segments) == 2)
        {
            if ($segments[0] == 'page')
            {
                // URL 'mon/blog/page/2.html'
                $page = $segments[1];
                // Affichage de la page 2 de la liste des billets
            }
            else if ($segments[0] == 'category')
            {
                // URL 'mon/blog/category/ski.html'
                $category = $segments[1];
                // Affichage de la liste des billets de la catégorie 'ski'
            }
        }

        // L'URL demandé n'est pas gérée par cet enhancer (erreur 404 pour cet enhancer)
        throw new \Nos\NotFoundException();
    }
}

Lorsque l’enhancer gère des URL pour certains modèles (ORM), c’est lui qui connait la procédure de génération des ces dernières. Pour ce faire, il faut alors implémenter une méthode statique getUrlEnhanced() qui va s’en occuper :

<?php

namespace Nos\Blog;

class Controller_Front extends \Nos\Controller_Front_Application
{
    public static function getUrlEnhanced($params = array())
    {
        $item = \Arr::get($params, 'item', false);
        if ($item) {
        $model = get_class($item);
        $page = isset($params['page']) ? $params['page'] : 1;

        switch ($model)
        {
            // URL pour un billet de blog particulier
            case 'Nos\Blog\Model_Post' :
                return urlencode($item->virtual_name()).'.html';
                break;

            // URL pour la liste des billets d'une catégorie (avec optionnellement une page)
            case 'Nos\Blog\Model_Category' :
                return 'category/'.urlencode($item->virtual_name()).($page > 1 ? '/'.$page : '').'.html';
                break;
            }
        }

        return false;
    }
}

Cette fonction est liée à la Behaviour_Urlenhancer et aux méthodes url() et urls() des modèles. Pour voir comment les configurer, il faut se référer à la documentation d’API associée.

Exemple :

<?php

// Sélection de la catégorie ayant pour ID 1
$category = Nos\Blog\Model_Category::find(1);

$url = $category->url(array('page' => 2));

$url aura pour valeur mon/blog/category/ski/2.html. Si on décompose :

mon/blog : URL de la page sur laquelle est présent l’enhancer ;
ski : URL virtuelle de la catégorie ayant pour ID 1 ;
2 : numéro de page demandée dans les paramètes.

Créer un gabarit¶

1. Définition dans le fichier `metadata`¶

Les metadata d’un template sont décrites dans la documentation d’API.

2. Configuration de déclinaison de gabarit¶

Vous pouvez optionnellement définir une configuration de déclinaison de gabarit si votre gabarit est paramétrable par contexte.

3. Création du fichier de vue¶

L’emplacement du fichier dépend de la clé file configurée dans le fichier metadata.config.php.

À l’intérieur du gabarit, vous avez accès à plusieurs variables intéressantes :

$main_controller:
$wysiwyg:	Un tableau contenant en clé le nom du WYSIWYG configuré dans le fichier `metadata.config.php` et en valeur le contenu saisi dans le back-office.
$page:	L’instance du `Nos\model_Page` courant.
$title:	Le titre à mettre dans un tag `h1`
	L’instance du contrôleur s’occupant du front-office.

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="shortcut icon" href="static/favicon.ico" />
    <link rel="stylesheet" type="text/css" href="static/apps/noviusos_templates_basic/css/base.css" media="all">
</head>

<body>

    <header>Cette zone d'entête sera affichée sur toutes les pages configurées avec ce gabarit.</header>

    <div id="menu">
        Mon joli menu
    </div>

    <div id="content">
        <?= $wysiwyg['content']; ?>
    </div>

</body>
</html>

Rajouter des champs¶

Voir aussi

Ajouter un champ

La majorité des champs qui sont ajoutés ont besoin d’une colonne dans la table MySQL correspondant à votre modèle.

Les champs sont ensuite ajoutés au formulaire du CRUD en passant par la clé fields du fichier de configuration.

La syntaxe se base sur une fonctionnalité existante de FuelPHP, qui définit comment une colonne s’affiche.

Voir aussi

Documentation de FuelPHP sur les propriétés d’un modèle

En plus des champs de formulaires standards, Novius OS possède des renderers, qui sont un peu plus poussés. Ils permettent par exemple de sélectionner un média, une page, une date...

Exemple de configuration :

<?php
return array(
        'name' => array(
                'label' => 'Texte affiché à côté du champ',
                'form' => array(
                        'type' => 'text',
                        'value' => 'Valeur par défaut',
                ),
                'validation' => array(),
);

Champs standards¶

Le texte en gras est la valeur de la propriété type.

<input type=”text“>
<input type=”password“>
<textarea>
<select>
<input type=”radio“>
<input type=”checkbox“>
<input type=”submit“>
<input type=”button“>
<input type=”file“>

Champ <select>¶

<?php
return array(
        'gender' => array(
                'label' => 'Genre',
                'form' => array(
                        'type' => 'select',
                        'options' => array(
                                'm' => 'Masculin',
                                'f' => 'Féminin',
                        ),
                ),
                'validation' => array('required'),
        ),
);

<button type=”submit”>¶

type = submit génère <input type="submit">
type = button génère <input type="button">

La propriété tag peut être utilisé pour forcer un tab HTML précis, pour gérer le cas bouton de type submit.

FuelPHP utilisera automatiquement la value comme texte du bouton.

<?php
return array(
        'save' => array(
                'form' => array(
                        'type' => 'submit',
                        'tag' => 'button',
                        'value' => 'Save',
                ),
        ),
);

Introduit dans la version Chiba2.1.

La clé save n’est plus obliigatoire dans la configuration des champs d’un CRUD.

Renderers (champs améliorés)¶

La liste des renderers est disponible dans la documentation d’API.

Ajouter des vignettes dans l’App Desk¶

C’est en réalité très simple. Il faut définit deux clés spéciales dans votre data_mapping :

thumbnail : chemin vers la vignette de l’item ;
thumbnailAlternate : chemin vers une image de remplacement lorsqu’il n’y a pas de vignette.

Pour ce faire, rendez-vous dans le fichier config/common/item.config.php :

<?php

return array(
    'data_mapping' => array(
        'thumbnail' => array(
            'value' => function ($item) {
                foreach ($item->medias as $media) {
                    return $media->get_public_path_resized(64, 64);
                }
                return false;
            },
        ),
        'thumbnailAlternate' => array(
            'value' => function ($item) {
                return 'static/apps/mon_appli/icons/64.png';
            }
        ),
    ),
);

Il faut ensuite activer la vue vignette dans la configuration de l’App Desk mon_appli::config/controller/admin/appdesk.config.php :

 <?php

 return array(
     'model' => '',
     'query' => array(),
     'inspectors' => array(),
     'i18n' => array(),
     'thumbnails' => true,
 );

Facultativement, il est possible de mettre la vue vignette par défaut (au lieu de la vue liste) :

 <?php

 return array(
     'model' => '',
     'query' => array(),
     'inspectors' => array(),
     'i18n' => array(),
     'thumbnails' => true,
     'appdesk' => array(
         'appdesk' => array(
             'defaultView' => 'thumbnails',
         ),
     ),
 );

Afficher mes vignettes dans différents formats¶

Vous avez ajouté des vignettes à votre mode modèle. Maintenant vous voulez les afficher en front-office.

En mode liste, vous voulez les afficher couper avec une taille fixe de 150x150 pixels et en noir et blanc.

Dans votre vue de liste :

 <?php

 foreach ($items as $item) {
     echo $item->thumbnail->getToolkitImage()->crop_resize(150, 150)->grayscale()->html(array(
         'style' => 'float:right;'
     ));
     echo '<h2><a href="', $item->url(), '">', e($item->title), '</a></h2>';
 }

En mode fiche, vous voulez affiche la vignette de l’item avec un largeur maximale de 300 pixels et une hauteur maximale de 200 pixels, et une légère rotation de 15 degrés.

Dans votre vue de liste :

 <?php

 echo $item->thumbnail->getToolkitImage()->shrink(300, 200)->rotate(15)->html();
 echo '<h1>', e($item->title), '</h1>';
 echo '<p>', e($item->description), '</p>';

Voir aussi

La classe Toolkit_Image pour plus de possibilités.

Avoir des champs commun à tous les contextes¶

Si votre application est Twinnable, vous voulez peut-être rendre certains champs d’un modèle commun à tous les contextes. Par exemple, dans l’application Monkey l’année de naissance, l’espèce et la photo d’un singe ne sont pas dépendantes du contexte. Un singe en version française aura la même année de naissance, la même espèce et la même photo que dans sa version anglaise.

Voir aussi

Multi-Contextes

Champ commun¶

Pour définir un champ commun à tous les contextes pour un model, il suffit de le déclarer dans la clé common_fields du comportement Twinnable.

Exemple¶

<?php
class Model_Page extends \Nos\Orm\Model
{
    protected static $_behaviours = array(
        'Nos\Orm_Behaviour_Twinnable' => array(
            'context_property'      => 'monk_context',
            'common_id_property' => 'monk_context_common_id',
            'is_main_property' => 'monk_context_is_main',
            'common_fields'   => array('monk_species_common_id', 'monk_birth_year'),
        ),
    );
}

Média et WYSIWYG commun¶

Pour définir un média ou un WYSIWYG commun à tous les contextes pour un model, il suffit d’utiliser les providers shared_wysiwygs_context et shared_medias_context ajoutés par le comportement Twinnable.

Ajouter un fichier associé¶

Principes¶

Novius OS fournit la classe Attachment pour gérer les fichiers associés.

Les fichiers associés sont stockés dans le répertoire local/data/files/.

Généralement les fichiers sont associés à un Model mais il est possible de les gérer comme bon vous semble. Pour définir un Attachment il suffit de fournir une configuration.

<?php

$attachment = \Nos\Attachment::forge('my_id', array(
        'dir' => 'apps'.DS.'myapps',
));

Dans l’exemple ci-dessus, notre fichier associé sera enregistré dans le répertoire local/data/files/apps/myapps/my_id/.

Pour enregistrer un fichier, il suffira de faire :

$attachment->set($_FILES['file']['tmp_name'], $_FILES['file']['name']);
$attachment->save();

Dans cet exemple, nous enregistrons un fichier uploadé comme fichier associé. Le chemin du fichier sera alors local/data/files/apps/myapps/my_id/nom_original.ext où nom_original.ext est le nom original du fichier uploadé, récupéré via $_FILES['file']['name'].

Attaché à un model¶

Dans le cas d’un fichier attaché à un Model, c’est encore plus simple. Dans la définition de votre classe, il suffit de déclarer :

class Model_Example extends \Nos\Orm\Model
{

        protected static $_attachment = array(
                'avatar' => array(),
                'cv' => array(),
        );

De cette façon, chaque item de Model_Example aura 2 fichiers associés : avatar et cv.

$item = Model_Example::find('first');
$item->avatar->set($_FILES['file']['tmp_name'], $_FILES['file']['name']);
$item->avatar->save();

Utilisation avancée¶

Pour plus de détails, consultez la documentation d’API d’Attachment.

Extensions¶

A la création de votre Attachment, vous pouvez spécifier une liste d’extensions de fichier autorisées en ajoutant la clé extensions au tableau de configuration et en lui donnant un tableau d’extensions acceptées en valeur.

Si votre fichier doit être une image, une clé image à true suffira.

Alias pour l’URL¶

Par défaut, votre fichier attaché sera disponible à l’URL du type :

http://www.mondomaine.com/data/files/dir/id/file_name.extension

Si dir est égal, comme souvent, à apps/mon-apps/mon-type-de-fichier/, celà peut faire une URL assez longue.

Définissez une clé alias dans le tableau de configuration de votre Attachment. La valeur de alias, remplacera celle de dir dans l’URL.

Fichier attaché sécurisé¶

Si votre fichier attaché ne doit pas être accessible à n’importe qui, vous pouvez le sécuriser. Il suffit de définir, toujours dans le tableau de configuration, une clé check de type fonction de callback. A chaque fois que le fichier sera demandé, via son URL, le système exécutera cette fonction, en lui passant l’objet Attachment en paramètre, pour vérifier si la personne connectée a le droit d’y accéder.

Exemple :

class Verification
{
        public static function check($attachment)
        {
                return isset($_SESSION['user_connected']) && $_SESSION['user_connected'];
        }
}

$attachment = \Nos\Attachment::forge('my_id', array(
        'dir' => 'apps'.DS.'myapps',
        'check' => array('Verification', 'check'),
));

De cette façon, si l’internaute est connecté, donc dans notre cas la variable de session user_connected est à true, il recevra le fichier. S’il ne l’est pas, il recevra une erreur 404.

Traduire l’application¶

Chaque application possède un répertoire lang dans lequel sont placés les fichiers de traductions, qu’on appellera dictionnaires.

Ce répertoire contient autant de sous-répertoires que de langues dans lesquelles on veut traduire notre application, et qui contiennent eux-même les dictionnaires.

Ces répertoires de langues portent des noms de locales, comme par exemple fr (Français), ou en (Anglais).

Les dictionnaires sont des fichiers PHP qui retournent un tableau PHP, un peu comme les fichiers de configuration.

Voir aussi

API de la classe I18n

Fichier `metadata.config.php`¶

Les metadata étant un peu spéciales, elles nécessitent un fichier de traduction à part. La première étape est d’indiquer dans quel dictionnaire se trouvent les traductions du fichier metadata.config.php.

 <?php

 return array(
     'name' => 'My app',
     'namespace' => 'My\App',
     'i18n_file' => 'my_app::metadata',
     // ... autres clés
 );

Comme toute modification sur les metadata, ne pas oublier d’appliquer les changements dans le gestionnaire d’applications.

Ensuite, il faut créer le dictionnaire my_app::lang/fr/metadata.lang.php :

<?php

return array(
    'My app' => 'Mon appli',
);

Novius OS sait automatiquement quelles clés peuvent / ont besoin d’être traduites dans le fichier metadata et ira chercher les traductions correspondantes.

Autres fichiers¶

Partout ailleurs, vous pouvez utiliser la fonction __() qui ira chercher (par défaut) les traductions dans le dictionnaire my_app::default.

Par exemple :

<?php

// La traduction sera récupérée depuis my_app::lang/<lang>/default.lang.php
__('Translate this');

Mode avancé : configurez vos dictionnaires¶

Si vous ne souhaitez pas mettre vos traductions dans le fichier default.lang.php, vous pouvez configurer dans quel dictionnaire sont situées les traductions, fichier par fichier.

C’est assez simple pour les vues et la configuration :

<?php

// Configure la fonction __() pour le reste du fichier
Nos\I18n::current_dictionary('my_app::common');

__('Translate this'); // La traduction sera récupérée depuis my_app::lang/<lang>/common.lang.php

C’est plus pointu pour les contrôleurs, car la langue dépend de l’utilisateur et n’est connue qu’après la phase d’authentification, qui a lieu dans le before().

C’est pourquoi un point d’entrée prepare_i18n() a été créé :

 <?php

 namespace Nos\Form;

 class Controller_Admin_Form extends \Nos\Controller_Admin_Crud
 {
     public function prepare_i18n()
     {
         // Configure la langue des fichiers de traductions en fonction de l'utilisateur connecté
         parent::prepare_i18n();
         // Configure la fonction __() pour le reste du contrôleur
         \Nos\I18n::current_dictionary('noviusos_form::common');
     }

     // Autres méthodes qui font usage de __()
 }

Il est possible de spécifier plusieurs dictionnaires pour un fichier en utilisant un tableau. Les traductions seront alors récupérés dans le premier fichier qui contient la traduction.

 <?php

 Nos\I18n::current_dictionary(array('my_app::dictionary', 'my_app::common'));

 // La traduction sera récupérée depuis my_app::lang/<lang>/dictionary.lang.php si elle existe
 // Ou dans my_app::lang/<lang>/common.lang.php sinon
 __('Translate this');

Fichiers de migrations¶

Chaque application ainsi que le dossier local peut avoir un dossier migrations. Ce dossier contient des fichiers de migration qui sont un moyen pratique de mettre à jour la base de données ou les fichiers locaux. Le système de migration FuelPHP est utilisé. Néanmoins il y a deux choses que vous devriez savoir pour Novius OS:

Les fichiers de migration des applications doivent être sous le namespace {{NAMESPACE_DE_LAPPLICATION}}\Migrations
Quand c’est possible, les mises à jour des fichiers migrations doivent se trouver dans un fichier sql séparé (pour faciliter les mises à jour manuelles). Comme la plupart du temps il n’y a que des requêtes sql à exécuter, la classe Nos\Migration a été implémentée dans l’optique de faciliter ces migrations. Vous pouvez y jeter un coup d’œil dans la documentation d’API.

Lorsqu’une application est installée ou mise à jour, les fichiers de migration qui s’y trouvent sont exécutés (s’ils ne l’ont pas déjà été) via l’interface de l’application manager.

Créer votre Behaviour¶

À quoi ça sert ?¶

Créer un behaviour permet d’appliquer un même comportement sur plusieurs modèles différents, en partageant la même base de code réutilisable.

Les behaviours sont une extension du mécanisme d’observers présents dans FuelPHP. Ils permettent notamment (comme pour les observers), d’écouter les notifications before_* et after_* déclenchées par FuelPHP.

Les behaviours permettent deux fonctionnalités supplémentaires :

d’écouter des évènements déclenchés par Novius OS (notamment par le CRUD et l’AppDesk) ;
d’ajouter dynamiquement des méthodes supplémentaires sur vos modèles (et de manière réutilisable).

Voici quelques exemples pour illustrer ces propos :

ajout d’une action dans l’App Desk ou le CRUD ;
ajout d’une colonne dans le dataset (data_mapping) d’un modèle ;
ajout d’un champ dans le formulaire d’ajout / d’édition d’un item ;
ajout d’une méthode ‘myBehaviourMethod()’ pour tous les modèles utilisant ce behaviour.

On citera :

Le behaviour Publishable, qui rajoute un champ dans la configuration du CRUD et qui l’affiche en utilisant le Renderer_Publishable.
Les behaviours Urlenhancer, Twinnable et Sharable qui rajoutent respectivement les actions visualiser, traduire et partager.

Étendre la classe Orm_Behaviour¶

Pour créer un behaviour, il faut créer une classe qui étend Nos\Orm_Behaviour, puis implémenter :

les méthodes d’évènements déclenchés par FuelPHP (before_* et after_*), de la même manière que pour les Observer ;
les méthodes d’évènements déclenchés par Novius OS (notamment par le CRUD et l’AppDesk) ;
les méthodes que vous voulez rendre disponibles sur les modèles qui utilise votre behaviour.

Vous pouvez ajouter n’importe quelle classe en tant que Behaviour en ajoutant son nom de classe complet dans la propriété $_behaviours de votre modèle.

Properties¶

Comme avec un observer FuelPHP, les modèles peuvent spécifier un tableau de configuration dans leur définition des behaviours. Cette configuration sera disponible dans la variable $this->_properties à l’intérieur du behaviour.

<?php

class Model_Monkey extends Nos\Orm\Model
{
    protected static $_behaviours = array(
        'My_Behaviour' => array(
            'my_key' => 'my_value',
        ),
    );
}

<?php

class My_Behaviour extends Nos\Behaviour
{
    /*
     * Dans n'importe quelle méthode, $this->_properties aura la valeur :
     * array(
     *     'my_key' => 'my_value',
     * )
     */
}

Écouter un évènement déclenché par FuelPHP (Observer)¶

Ce sont les évènements de type before_* et after_*.

Par exemple, Behaviour_Author stocke l’ID des utilisateurs ayant créé / modifié un item dans une colonne du modèle grâce (respectivement) aux évènements before_insert et before_save fournis par l’ORM de FuelPHP.

<?php

class Orm_Behaviour_Author extends Orm_Behaviour
{
    public function before_insert(\Nos\Orm\Model $item)
    {
        $created_by_property = \Arr::get($this->_properties, 'created_by_property', null);
        if ($created_by_property === null) {
            return;
        }

        $user = \Session::user();
        if (!empty($user)) {
            $item->{$created_by_property} = $user->user_id;
        }
    }
}

Écouter un évènement déclenché par Novius OS¶

De la même manière que pour les observers, il faut implémenter une méthode qui porte le même nom de l’évènement déclenché.

Par exemple, pour écouter l’évènement form_processing, on implémentera la méthode form_processing().

La différence avec les évènements déclenchés par FuelPHP réside dans les paramètres envoyées à ces méthodes :

Là où les méthodes d’Observer (before_* et after_*) prennent un unique paramètre $item (instance du modèle), les évènements déclenchés par Novius OS peuvent en prendre plusieurs, et dépendent du type d’évènement.

Il existe deux types d’évènements :

les évènements d’instance, qui prennent systématiquement l’$item en premier paramètre, plus éventuellement d’autres paramètres spécifiques à l’évènement ;
les évènements statiques, qui reçoivent uniquement les paramètres spécifiques à l’évènement.

La liste des évènements (d’instance et statiques) est disponible dans la documentation d’API.

Un évènement est appelé sur tous les Behaviour qui ont implémenté la méthode correspondante. La valeur de retour de ces méthodes n’a pas d’importance : les évènements utilisent les arguments passés par référence pour agir.

Exemple avec l’évènement d’instance form_processing (déclenché lors de la sauvegarde d’un item via le CRUD).

<?php

class My_Behaviour extends Nos\Behaviour
{
    public function form_processing(Nos\Orm\Model $item, $data, &$json_repsonse)
    {
        // Exemples :
        // On remplit des valeurs à sauvegarder dans l'item
        // On rajoute une clé dans le tableau JSON
    }
}

// Pour information : en interne, Novius OS fait appel à cet évènement via ce code suivant :
$item->event('form_processing', array($data, &$json_response));

Exemple avec l’évènement statique crudConfig

<?php

class My_Behaviour extends Nos\Behaviour
{
    public function crudConfig(&$config, $controller)
    {
        // Exemples :
        // On rajoute un champ en modifiant $config['fields']
    }
}

// Pour information : en interne, Novius OS fait appel à cet évènement via ce code suivant :
Model_Class::eventStatic('crudConfig', $config, $controller);

Rajouter dynamiquement une méthode d’instance sur un modèle¶

De la même manière que les évènements déclenchés par FuelPHP et les évènements d’instance, les méthodes dynamiques portent le même nom que la méthode à rajouter sur le modèle et prennent en premier paramètre $item, l’instance du modèle.

Contrairement aux évènements, une méthode retourne généralement une valeur.

Par exemple, le Behaviour_Contextable dans Novius OS rajoute la méthode get_context() sur les modèles qui l’utilisent :

<?php

// Model file
class Model_Monkey extends Nos\Orm\Model
{
    protected static $_behaviours = array(
        'Orm_Behaviour_Contextable' => array(
            'context_property' => 'monk_context',
        ),
    );
}


// Behaviour file
class Orm_Behaviour_Contextable extends Nos\Behaviour
{
    public function get_context(Orm\Model $item)
    {
        return $item->get($this->_properties['context_property']);
    }
}

// Use case
$monkey = Model_Monkey::find('first');

// Cette méthode est disponible parce que Model_Monkey utilise Behaviour_Contextable, qui la rajoute
$context = $monkey->get_context();

Rajouter dynamiquement une méthode statique sur un modèle¶

De la même façon que pour une méthode d’instance mais plus besoin du premier paramètre $item.

<?php

// Model file
class Model_Monkey extends Nos\Orm\Model
{
    protected static $_behaviours = array(
        'Orm_Behaviour_Twinnable' => array(
            'context_property'      => 'monk_context',
            'common_id_property' => 'monk_context_common_id',
            'is_main_property' => 'monk_context_is_main',
            'common_fields'   => array('monk_species_common_id', 'monk_birth_year'),
        ),
    );
}


// Behaviour file
class Orm_Behaviour_Twinnable extends Nos\Behaviour
{
    public function hasCommonFields()
    {
        $class = $this->_class;
        return count($this->_properties['common_fields']) > 0 ||
            static::sharedWysiwygsContext($class) > 0 ||
            static::sharedMediaContext($class) > 0;
    }
}

// Use case
Model_Monkey::hasCommonFields();

Étendre une application¶

Mécanismes d’extensions¶

Créer un fichier dans `local`¶

On peut modifier n’importe quel fichier de vue, de configuration ou de langue via le dossier local.

Ceci est possible grâce au comportement des fichiers chargés « en cascade » existant dans FuelPHP et adapté dans Novius OS. C’est très simple à faire, car il suffit de copier un fichier existant et de le modifier à notre guise !

Dans le cas d’une application, il faut copier le fichier dans local/config/apps/{application}/ ou local/views/apps/{application}/.

Pour étendre un fichier du moteur de Novius OS, on utilisera local/config/apps/novius-os/ et local/views/novius-os/.

La syntaxe « générique » est donc local/{section}/{application}/ avec :

{section}` est égal à config ou views ;
{application}` correspond à apps + un nom d’application ou novius-os pour le moteur.

Configuration¶

L’application noviusos_page possède un fichier de configuration controller/admin/appdesk.config.php (le fichier se situe donc dans noviusos_page::config/controller/admin/appdesk.config.php).

Si on le copie dans local/config/apps/noviusos_page/controller/admin/appdesk.config.php alors ce dernier sera fusionné automatiquement avec celui de l’application qui le demande.

Vues¶

Lorsqu’on créé le fichier local/views/apps/noviusos_help/admin/help.view.php ce dernier est utilisé en remplacement de noviusos_help::admin/help.view.php !

Pour étendre un fichier du moteur, on utilisera le nom d’application novius-os. Par exemple, on créera le fichier local/views/novius-os/admin/login.view.php.

Utiliser les évènements pour modifier une configuration¶

N’importe quel fichier de configuration peut être modifié grâce à l’évènement config|<path>.

Remplacer une vue par une autre¶

Il est possible de faire appel à la méthode View::redirect() pour remplacer un fichier de vue par un autre.

<?php

// Remplace la vue 'admin/help' de l'application 'noviusos_help' par la vue 'help' du dossier 'local'
View::redirect('noviusos_help::admin/help', 'local::help');

Créer une application dédiée d’extension¶

Pour étendre une application, on créé une autre application qui va modifier la première.

L’application 2 définit qu’elle étend mon_application via son fichier metadata.config.php :

 <?php

 return array(
     'name' => 'Application 2',
     // On définit que c'est une application d'extension
     'extends' => array(
         'my_application',
     );
 );

Une fois application_2 installée, elle sera chargée en même temps que mon_application.

Lorsqu’une application étend une autre, certains comportements deviennent automatiques.

Voir aussi

Mécanisme d’extension dans le Metadata.

Exemple :

application_2 étend mon_application.

Configuration¶

Les fichiers de configurations des Controller et des Model de mon_application peuvent être automatiquement étendus par application_2.

Exemple, mon_application définit le fichier de configuration suivant pour Controller_Test : applications/mon_application/config/controller/test.config.php

Si dans application_2, le fichier correspondant applications/application_2/config/apps/mon_application/controller/test.config.php existe, alors il sera fusionné.

C’est-à-dire que dans Mon\Application\Controller_Test, la variable $config contiendra la fusion 2 fichiers (celui de l’application étendue mon_application, et aussi celui de application_2 qui étend la première).

Vues¶

Les fichiers de vues de mon_application peuvent être remplacés par application_2.

Exemple, mon_application a une vue views/admin/help.view.php

Si dans application_2, le fichier correspondant applications/application_2/views/apps/mon_application/admin/help.view.php existe, il sera utilisé à la place de celui de mon_application.

Le bootstrap¶

Le fichier bootstrap permet d’exécuter du code php lors du chargement d’un site / d’une application. Il est possible d’en créer à deux emplacements :

local/bootstrap.php : s’éxecutera lors du chargement du site.
local/applications/APPLICATION/bootstrap.php : s’éxecutera lors du chargement de l’application APPLICATION.

L’intérêt d’un tel fichier est qu’il permet de facilement étendre une application. C’est dans ces fichiers que l’on pourra utiliser les événements et les redirections de vue.

Ajouter un champ¶

Nous allons partir d’un exemple pour l’explication.

Ajoutons un champ Source pour un billet de blog, qui permettra de renseigner une URL externe ayant produit le contenu original.

Dans la BDD¶

ALTER TABLE `nos_blog_post` ADD `post_source` VARCHAR(255);

Dans le Model¶

Deux possibilités :

Déclarer la nouvelle colonne dans les properties du model.
Activer le système de cache des properties des models.

Déclarer la colonne¶

Pour déclarer votre nouvelle colonne nous allons écouter l’événement qui charge le fichier de configuration du model.

<?php

Event::register_function('config|noviusos_blog::model/post', function(&$config) {
    $config['properties']['post_source'] = array(
        'default' => null,
        'data_type' => 'varchar',
        'null' => false,
    );
});

Voir aussi

Définition des properties dans la documentation de FuelPHP

Activer le cache des `properties`¶

Créez le fichier local/config/config.php à partir du fichier local/config/config.php.sample si ce n’est pas encore fait.

Décommentez la ligne (ou créez la) ayant la clé cache_model_properties et lui assigner true :

<?php

return array(
    //...

    'novius-os' => array(
        //...
        'cache_model_properties' => true,

        //...
    ),
);

Une fois activé, le système va mettre toutes les properties des models en cache dans le répertoire local/cache/fuelphp/model_properties/. Quand une colonne est ajoutée et non déclarée, au premier appel à get() ou à set() pour cette colonne, les properties seront mise à jour avec une requête en base pour lister les colonnes du model.

Warning

Ce mécanisme n’est possible qu’avec les drivers MySQL et MySQLi.

Voir aussi

La documentation sur la configuration de Novius OS.

Dans le formulaire¶

Le formulaire d’ajout / édition d’un billet de blog est définit dans sa configuration CRUD. Pour l’étendre, nous allons utiliser un évènement !

Dans le fichier local/bootstrap.php (créez-le si nécessaire) :

<?php

Event::register_function('config|noviusos_blog::controller/admin/post', function(&$config) {

    // Ajout du champ 'post_source' de type 'text'
    $config['fields']['post_source'] = array(
        'label' => 'Source originale :',
        'form' => array(
            'type' => 'text',
            'placeholder' => 'http://',
        ),
    );

    // Affichage du champ dans le formulaire
    // Nous créons une entrée intitulée 'Source' dans le menu de droite
    $config['layout']['menu']['Source'] = array('post_source');
});

Le formulaire possède désormais un champ éditable supplémentaire, comme vous pouvez le voir ci-dessous :

Champ 'source' dans le formulaire d'un billet de blog

Dans la visualisation¶

Pour la vue, nous créer le fichier local/views/apps/noviusos_blognews/front/post/content.view.php

<?php

// On inclut le fichier d'origine (qui affiche le contenu)
include APPPATH.'/applications/noviusos_blognews/views/front/post/content.view.php';

// On rajoute la source à la fin
if (!empty($item->post_source)) {
    ?>
    <p class="blognews_source">
        <?= __('Source:') ?>
        <a href="<?= htmlspecialchars($item->post_source) ?>">
            <?= htmlspecialchars($item->post_source) ?>
        </a>
    </p>
    <?php
}

Modifier l’affichage sur le site¶

Nous allons partir d’un exemple pour l’explication.

Sur le site Novius OS nous avons personnalisé l’affichage des billets de blog. Voyons-voir comment cela fonctionne.

Apparence par défaut de l’application blog :

Vue liste par défaut de l'application 'Blog'

Apparence sur le site Novius OS.org (notre objectif) :

Vue liste modifiée de l'application 'Blog'

Modification de la vue¶

1^ère technique : étendre la vue¶

Grâce à la cascade du système de fichiers, on peut copier le fichier original noviusos_blognews::views/front/post/item.view.php dans notre dossier local : local::views/apps/noviusos_blognews/front/post/item.view.php

<div class="blognews_post blognews_post_item">
    <div class="blognews_primary_information">
        <?= \View::forge('noviusos_blognews::front/post/title', array('item' => $item)) ?>
        <?= \View::forge('noviusos_blognews::front/post/summary', array('item' => $item)) ?>
    </div>
    <div class="blognews_secondary_information">
        <?= \View::forge('noviusos_blognews::front/post/publication_date', array('item' => $item)) ?>
        <?= \View::forge('noviusos_blognews::front/post/tags', array('item' => $item)) ?>
    </div>
</div>

Nous avons supprimé l’affichage de la vignette, de l’auteur, des catégories et du nombre de commentaires.

2^e technique : étendre la configuration¶

L’application blog permet dans sa configuration de désactiver l’affichage de certains éléments. En ce qui nous concerne, c’est possible pour tous ceux qu’on souhaite ne pas afficher, sauf pour la vignette.

Lorsqu’on utilise le fichier de configuration de l’application blog, cette dernière modifie l’affichage à la fois dans la liste des billets, mais également sur la fiche, ce qui ne nous convient pas dans notre cas (cette technique est donc montrée ici à titre d’exemple).

Grâce à la cascade du système de fichiers, on peut copier le fichier original noviusos_blognews::config/config.php dans notre dossier local : local::config/apps/noviusos_blognews/config.php :

<?php

// On laisse uniquement les clés que l'on souhaite modifier
return array(
    'categories' => array(
        'show' => false,
    ),
    'authors' => array(
        'show' => false,
    ),
    'comments' => array(
        'show' => false,
    ),
);

Ajout du CSS¶

1^ère technique : étendre la vue¶

Nous créer le fichier local::views/apps/noviusos_blognews/front/post/list.view.php

<?php

// On ajoute notre fichier CSS spécifique
\Nos\Nos::main_controller::addCss('static/css/blog_custom.css');

// On inclut le fichier d'origine (qui affiche la liste des billets)
include APPPATH.'applications/noviusos_blognews/views/front/post/list.view.php';

Notre vue modifiée inclut d’abord un fichier CSS (à créer dans public/static/css/blog_custom.css), puis appelle la vue d’origine.

2^e technique : agir directement sur le gabarit¶

Il est également possible d’inclure le fichier CSS via l’évènement front.start, mais dans ce cas, il le sera sur toutes les pages de votre site, et pas seulement sur la page blog.

Dans le fichier local/bootstrap.php (créez-le si nécessaire) :

<?php

// Événement qui se déclenche lorsqu'on charge une page du site
Event::register('front.start', function() {
    \Nos\Nos::main_controller::addCss('css/blog_custom.css');
});

Dans le cas du site Novius OS, nous avons créés nos gabarits spécialement pour le site, ils incluent directement le CSS nécessaire à la personnalisation de l’affichage du blog.

Ajouter une action en back-office¶

Les actions sont définies dans le fichier config/common/{model}.config.php.

Le meilleur moyen est de s’inspirer des actions par défaut qui existent dans Novius OS.

Placeholders¶

La configuration des actions contient des {{placeholders}}.

Sont remplacés en PHP :
- {{model_label}} : le nom du modèle
- {{controller_base_url}} : l’URL du contrôleur associé au modèle
Sont remplacé par l’App Desk (en JavaScript) :
- {{context}} : contexte actuellement affiché (ou premier contexte lorsque plusieurs sont affichés)

Tous les autes placeholders sont remplacés par les données de l’item : {{_id}} et {{_title}} dans ce cas, mais égalements n’importe quel champ définit dans le data_mapping.

Cibles des actions¶

Il y a 3 cibles possibles pour les actions :

toolbar-grid : barre d’outils de l’appdesk
grid : ligne d’item dans la grille principale de l’appdesk
toolbar-edit : barre d’outils sur le formulaire d’ajout / édition

Add / Edit / Delete¶

L’action add :

ouvre un nouvel onglet ;
fait appel à la méthode action_insert_update() du contrôleur Nos\Media\Controller_Admin_Media ;
avec un paramètre $_GET['context'] qui permet de pré-sélectionner le contexte actif ;
s’affiche uniquement dans la barre d’outils de l’App Desk.

L’action edit :

ouvre l’onglet d’édition (la méthode n’étant pas précisée pour nosTabs, la valeur par défaut open sera utilisée : elle donnera le focus à l’onglet existant s’il est déjà ouvert, ou en créera un nouveau le cas échéant) ;
fait appel à la méthode action_insert_update( $id ) du contrôleur Nos\Media\Controller_Admin_Media ;
avec un paramètre id passé à la méthode ;
s’affiche uniquement dans la grille principale.

L’action delete :

fait appel à la méthode action_delete( $id ) du contrôleur Nos\Media\Controller_Admin_Media ;
avec un paramètre id passé à la méthode ;
s’affiche à la fois dans la grille principale et sur le formulaire d’édition, mais uniquement pour les items existants (pas lors de l’ajout).

 <?php

 return array(

     // Acion par défaut ADD
     'add' => array(
         'label' => __('Add {{model_label}}'),
         'primary' => true,
         // Le clic ouvrira un nouvel onglet
         'action' => array(
             'action' => 'nosTabs',
             'method' => 'add',
             'tab' => array(
                 'url' => '{{controller_base_url}}insert_update?context={{context}}',
             ),
         ),
         // L'action sera affichée uniquement dans la barre d'outils de l'App Desk
         'targets' => array(
             'toolbar-grid' => true,
         ),
     ),

     // Action par défaut EDIT
     'edit' => array(
         'label' => __('Edit'),
         'primary' => true,
         'icon' => 'pencil',
         // Le clic ouvrira (ou rendra le focus) l'item
         'action' => array(
             'action' => 'nosTabs',
             'tab' => array(
                 'url' => "{{controller_base_url}}insert_update/{{_id}}",
                 'label' => '{{_title}}',
             ),
         ),
         // L'action s'affiche uniquement dans la grille principale
         'targets' => array(
             'grid' => true,
         ),
     ),

     // Action par défaut DELETE
     'delete' => array(
         'label' => __('Delete'),
         'primary' => true,
         'icon' => 'trash',
         'red' => true,
         // Le clic ouvrira une popup de confirmation
         'action' => array(
             'action' => 'confirmationDialog',
             'dialog' => array(
                 'contentUrl' => '{{controller_base_url}}delete/{{_id}}',
                 'title' => strtr($config['i18n']['deleting item title'], array(
                     '{{title}}' => '{{_title}}',
                 )),
             ),
         ),
         // L'action s'affiche à la fois dans la grille principale et sur le formulaire d'édition...
         'targets' => array(
             'grid' => true,
             'toolbar-edit' => true,
         ),
         // ...mais pas pour les nouveaux items !
         'visible' => function($params) {
             return !isset($params['item']) || !$params['item']->is_new();
         },
     ),
 );

Modifier un comportement en front-office¶

Novius OS fournit un mécanisme d’évènements destiné à interagir avec le moteur.

Il existe 2 types d’évènements :

Ceux qui servent à modifier une / des valeur(s) ;
Ceux qui notifient qu’une action s’est produite.

<?php

// Exemple d'évènement qui écoute une action
Event::register('event_name', function($value)
{
    // L'action 'event_name' s'est produite
});

<?php

// Exemple d'évènement qui modifie une valeur
Event::register_function('event_name', function(&$value)
{
    // $value peut être modifiée
});

Pour une liste des évènements, il faut se référer la documenation API associée.

Voir aussi

Events

Faire une redirection 301 en fonction de l’URL¶

Il est possible de créer une page en back-office avec comme type Lien externe pour faire une redirection 301.

Il est également possible de les configurer via un fichier ./htaccess.

Enfin, on peut aussi le faire directement via le code, comme présenté ci-dessous.

<?php

Event::register_function('front.start', function($params)
{
    // Utilisation de la classe Str de FuelPHP
    if (Str::starts_with($params['url'], 'an-old-url'))
    {
        // Note : 10 == strlen('an-old-url')
        $new_url = 'my-new-url'.substr($params['url'], 10);

        // Utilisation de la classe Response de FuelPHP
        Response::redirect($new_url, 'location', 301);
    }
});

Envoyer un mail remerciement dans un formulaire de contact¶

<?php

Event::register_function('noviusos_form::after_submission', function(&$answer, $enhancer_args)
{
    foreach ($answer->fields as $field)
    {
        if ($field->anfi_field_type == 'email' && !empty($field->anfi_value)
        {
            $email = Email::forge();
        $email->from('mon@email.me', 'Mon Nom');
        $email->to($field->anfi_value);
        $email->subject('Votre demande de contact');

        // Email au format texte (use html_body() instead if you want to send HTML email)
        $email->body('Merci pour votre demande de contact, elle a bien été reçue. Nous allons y répondre prochainement.');

        try
        {
            $email->send();
        }
        catch(\Exception $e)
        {
            // Could not send the email
        }
        }
    }
});

Notes de versions¶

Notes de la version Elche¶

Nouveautés¶

Nouvelle application Menu pour gérer les menus de son site web.
Nouvelle application Déclinaison de gabarit pour gérer des déclinaisons de gabarit par contexte.
Nouvelle application Gabarit Bootstrap personnalisable qui utilise les déclinaisons de gabarit. Vous pouvez personnaliser les elements, la mise en page, le thème, les menus.
UI: L’image de fond est sur le body et ses bords sont visibles en permanence
UI: Nouvelle barre système avec une nouvelle fonctionnalité plein écran
UI: La barre d’outils des Appdesks et CRUDs est en bas
UI: Sur le bureau, les applications sont maintenant organisable sur une grille, et non plus juste triable
Renderer: Nouveau renderer Renderer_Item_Picker basé sur l’appdesk natif de modèle
Renderer: Nouveau renderer Renderer_Select_Model pour sélectionner un item d’un modèle. Gère les comportement contexable et twinnable.

Développeur¶

ORM: Ajout d’un système de Providers. Possibilité d’ajouter des providers à un modèle. Les providers sont des assecceurs par clé d’items liés par relation.
ORM: Les Wysiwygs et Medias deviennent des providers natifs.
ORM: Nouveau providers shared_wysiwygs_context et shared_medias_context.
Enhancer: La configuration de popup gère la validation de formulaire si des champs ont des contraintes.
Grid: Les cellFormatters sur les colonnes fonctionnent sur tous les widgets noslistgrid, plus seulement sur le tableau principal de l’appdesk

Ruptures de compatibilité¶

Média et WYSIWYG commun aux contextes

Mise à jour des librairies tierces¶

jQuery 1.11.1
jQuery UI 1.10.4
Wijmo 2014v1.34
require.js 2.1.11
pNotify 2.0
JQuery.cookie 1.4.1
JQuery.form 3.50.0-2014.0.2.05
JQuery.mousewheel 3.1.11
JQuery.datetimepicker 1.4.4
Webshims 1.13, in Form application,

Dépréciés¶

Nos:parse_wysiwyg(), Nos:parse_enhancers() et Nos:get_enhancer_content()

Introduit dans la version 5.0.1.

Nouveautés¶

Traduction japonnaise.
ORM: Les relations twinnable permettent maintenant de définir un contexte au lieu d’utiliser celui du model courant. Cela permet d’utiliser le contexte courant du front office à la place pour récupérer le plus de model traduit possible.

Guide de migration de la version Dubrovka à la version Elche¶

Mettre à jour son Novius OS et ses applications¶

Reportez-vous à la page Mise à jour si vous ne l’avez pas encore fait.

Modification de vos développements¶

Ruptures de compatibilité¶

Média et WYSIWYG commun aux contextes¶

Tous les Wysiwygs et Medias communs doivent être appellés avec les providers shared_wysiwygs_context et shared_medias_context
Enlever les déclaration des variables shared_wysiwygs_context et shared_medias_context des modèles.

Dépréciés¶

Une mise en conformité n’est pas obligatoire mais souhaitable pour pouvoir migrer sans soucis lors de prochaine version.

Nos:parse_wysiwyg(), Nos:parse_enhancers() et Nos:get_enhancer_content()¶

Ces méthodes sont dépréciées, utilisez :

Tools_Wysiwyg::parse() à la place de Nos:parse_wysiwyg()
Tools_Wysiwyg::parseEnhancers() à la place de Nos:parse_enhancers()
Tools_Enhancer::content() à la place de Nos:get_enhancer_content()

Contribuer à Novius OS¶

Normes de codage¶

Ces normes pour le formatage du code doivent être suivies par toute personne contribuant à Novius OS.

Vous pouvez utiliser le ruleset.xml for PHP_CodeSniffer fait pour Novius OS.

Case¶

Tous les mots clés sont en minuscule (class, interface, extends, implements, abstract, final, var, const, function, public, private, protected, static, if, else, elseif, foreach, for, do, switch, while, try, catch, true, false et null).

Toutes les constantes sont majuscules (constante globale ou de classe).

Signature des structures de contrôle¶

try {
    ...
} catch (...) {
    ...
}

do {
    ...
} while (...);

while (...) {
    ...
}

// Un seul espace entre chaque condition des boucles 'for'.
for ($i = 0; $i < 10; $i++) {
    ...
}

// Un seul espace entre chaque condition des boucles 'foreach'.
foreach ($array as $key => $item) {
    ...
}

if (...) {
    ...
} else if (...) {
    ...
} else {
    ...
}

// Un seul espace après un cast.
$variable = (array) $variable;

Déclaration de fonction¶

/*
L'accolade d'ouverture d'une fonction est sur la ligne suivant la déclaration de la fonction.
Pas d'espace avant les virgules.
Un seul espace après les virgules.
Un seul espace entre le type et l'argument.
Un seul espace avant le signe '=' de la valeur par défaut.
Un seul espace après le signe '=' de la valeur par défaut.
Les paramètres avec une valeur par défaut doivent être à la fin de la signature de la fonction.
*/
function myfunction(array $first, $second, $third = array())
{
        ...
}

Appel de fonction¶

/*
Pas d'espace avant les virgules.
Un seul espace après les virgules.
*/
$value = myfunction($first, $second, $third);

Classe¶

/*
L'accolade d'ouverture d'une classe est sur la ligne suivant la déclaration de la classe.
Il doit y avoir une ligne vide après la déclaration du namespace.
Toutes les propriétés de la classe doivent avoir une portée (variables, functions and methods).
A single space after scope keywords (private, public, protected, static).
*/
namespace Name\Space;

class MyClass
{
        private $variable1 = null;

        protected static $variable1 = true;

        const MY_CONSTANT = false;

        public static function myfunction()
        {
                ...
        }
}

Fichier¶

Les caractères de fin de ligne doivent être un n. Les fichiers ne doivent pas se finir par un tag de fermeture PHP.

Seulement une instruction par ligne.

Le code PHP doit utilisé les tags longs <?php ?> ou les tags courts d’affichage <?= ?>; aucune autre forme de tag ne doit être utilisée.

Les accolades de fermeture de même portée doivent être alignées. Les structures de contrôles sont correctement indentées (4 espaces, pas de tabulation).

Pas d’espace en début et fin de fichier.

Charte rédactionnelle (Français)¶

Introduction¶

Cette charte est destinée à toute personne écrivant des textes d’interface pour Novius OS : développeurs et designers d’applications, contributeurs au cœur, traducteurs. Elle établit des règles communes à l’ensemble des applications et langues afin d’offrir aux utilisateurs des textes cohérents et agréables.

Cette charte est basée sur les design personas d’Aaron Walter. Le guide Voice and Tone de MailChimp, créé par l’équipe de Walter, a également été une source d’inspiration.

À propos de la traduction¶

La traduction n’est pas du mot-à-mot. Il s’agit de rester fidèle au design original tout en l’adaptant à un nouveau public, à une autre culture. Une traduction littérale des textes de Novius OS n’aurait pas de sens. La traduction doit donner la sensation que le texte traduit est le texte original. Le premier document à traduire sont ces règles afin qu’une charte localisée soit disponible.

Personnalité, ton à adopter¶

Novius OS est conçu pour des professionnels. Ils ne l’utilisent pas pour le plaisir, ils ont un travail à faire. Novius OS doit montrer à ses utilisateurs qu’il partage le même objectif : réaliser le travail demandé le plus efficacement possible. Novius OS adopte ainsi un ton professionnel et qui va à l’essentiel. Novius OS vouvoie l’utilisateur.

Ceci étant dit, utiliser Novius OS n’a pas à être ennuyeux pour autant. Le discours habituel et insipide des logiciels (ex Veuillez entrer une valeur correcte) est à éviter. Nous ne voulons pas que Novius OS soit perçu comme un logiciel de plus.

Novius OS peut faire sourire ses utilisateurs (tout particulièrement s’ils viennent de réaliser une tâche), mais pas rire. Le logiciel n’est pas leur copain. Il s’agit plutôt d’un collègue de confiance et bien informé avec qui ils ont plaisir à travailler. Ou plutôt une équipe de collègues, car Novius OS dit « Nous » et pas « Je ».

Enfin, même si une partie du public de Novius OS sont des développeurs, les textes ne doivent pas comprendre de jargon. De même, un ton trop familier (ex : Désolé mec, ça a planté !) n’est pas bienvenu.

Caractéristiques de la personnalité¶

Professionnel mais pas ennuyeux.
Efficace, direct mais pas autoritaire.
Cohérent mais pas répétitif.
Sympathique mais pas familier.
Bien informé mais pas donneur de leçon.

Exemples de textes¶

Actions :

Ajouter un nouvel item:
Se connecter:	Allez, au travail
Se déconnecter:	Se déconnecter (à bientôt !)
	Ajouter une page [1]
Sauvegarder un item:
	Enregistrer [1]

Confirmation :

Nouvel item ajouté:
	Parfait ! Le billet de blog a été ajouté. [2]
Item mis à jour:
	C’est bon, les modifications ont été enregistrées. [2]

Erreurs :

Erreur de l’utilisateur:
	Vous devez ajouter un titre pour que le produit puisse être sauvegardé. Désolé. [3]
Erreur du système:
	Il y a eu un problème. Merci de ré-essayer et de contacter votre développeur ou Novius OS si le problème persiste. Veuillez accepter nos excuses pour la gêne occasionnée. [4]
Prévention des erreurs (message):
	Des réponses à ce formulaire ont déjà été reçues. Le modifier pourrait supprimer des données collectées. [5]
Prévention des erreurs (bouton de confirmation):
	Ne vous inquiétez pas, je sais ce que je fais. [5]

[1]	(1, 2) Pas besoin d’en dire plus. Être efficace, c’est offrir des actions principales clairement libellées.

[2]	(1, 2) Un peu de diversité ne fait pas de mal tant que le style reste cohérent. Ex : « Ça y est est », « Et voilà ! » ou « C’est tout bon ! » pour commencer un message de confirmation.

[3]	Ne prenez pas pour acquis que c’est la faute de l’utilisateur. Peut-être que ce n’était pas évident que le champ était obligatoire.

[4]	Pas de « Oups ! ». C’est sérieux, l’utilisateur a probablement perdu du temps ou des données.

[5]	(1, 2) Quand vous avez besoin de l’attention de l’utilisateur, adressez-vous directement à elle / lui et faites des textes d’interface une conversation.

Documentation de Novius OS¶

Sommaire¶

Installer Novius OS¶

Installation¶

Assistant de paramétrage¶

Étape 1 : Vérifier les prérequis¶

Étape 2 : Configurer la base de données MySQL¶

Étape 3 : Créer le premier compte administrateur¶

Étape 4: Choix des langues¶

Applications¶

Se déconnecter / connecter¶

Problèmes courant d’installation¶

La suite¶

Première page¶

Ouvrir l’application Pages web¶

Ajouter une page (votre première)¶

Écrire du contenu et cliquer « Ajouter »¶

Aperçu de votre travail¶

Publier votre page¶

Gabarits¶

Applications¶

Le gestionnaire d’applications¶

Mise à jour¶

Mise à jour des fichiers¶

Git¶

Zip¶

Lancer la migration¶

Via SSH¶

Via Navigateur¶

Via l’interface back-office¶

Mettre à jour vos développement¶

Optimisations après installation¶

Configuration et activation de XSendFile¶

Apache¶

nginx¶

Comprendre Novius OS¶

Fondamentaux du logiciel¶

Une architecture MVC¶

Utilisation de frameworks¶

FuelPHP¶

ORM de FuelPHP¶

jQuery UI / Wijmo¶

Organisation des répertoires¶

De Novius OS¶

Repertoires à la racine¶

Le répertoire public¶

Le répertoire du core¶

Le répertoire local¶

D’une application¶

Numérotation des versions¶

Différences avec FuelPHP¶

Chemin des constantes¶

Autoloader¶

Bootstrap et points d’entrées¶

Point d’entrée du back-office¶

Principes ergonomiques¶

Navigation par onglets¶

L’App Desk¶

Fondamentaux des applications¶

Définition¶

L’App Desk¶

La configuration de l’App Desk¶

Contrôleurs, formulaires et modèles¶

Observers et behaviours¶

Partage de contenu¶

Content nuggets¶

Structure des données¶

Data catchers¶

Data catchers inclus dans le logiciel¶

Exemple : Simple Twitter¶

Multi-Contextes¶

Principes du multi-Contextes¶

Exemple¶

Configuration¶

Cas particuliers¶

Ajouter des contextes¶

Contextable / Twinnable¶

Application n’utilisant pas les contextes¶

Application Contextable¶

Application Twinnable¶

Le répertoire `public`¶

Le répertoire du `core`¶

Le répertoire `local`¶

`Contextable` / `Twinnable`¶

Application `Contextable`¶

Application `Twinnable`¶

Fichier `permissions.config.php`¶