Documentation de Kalinka

Installer Kalinka

Désarchiver KatyushaMCD_UNIX_0.0.0_b1.tar.gz dans le dossier cible souhaiter.

Prérequis

Pour l'instant, Kalinka ne peut fonctionner qu'avec le serveur Apache HTTPD et son module rivet.

Il est aussi indispensable d'installer TCL ainsi que l'interface de communication avec les SGBD : TDBC

Fonctionnement de Kalinka

Kalinka repose sur un principe de routes.

Une route est une suite de mots ressemblant à des dossiers et sous-dossiers, comme par exemple http://mondomaine.com/produits/creation. Kalinka fera le lien entre cette suite de mots et une méthode d'action définie

Pour y parvenir, Kalinka n'utilise pas de module d'url_rewriting contrairement à la majorité des autres frameworks. Ce qui fait une dépendance logicielle en moins.

Créer une application Kalinka

Utiliser la commande suivante pour créer une application avec Kalinka :

$ chemin_vers_kalinka/Kalinka mk app Nom_de_l_application

Un dossier devrait alors être créé contenant les fichiers / sous-dossiers suivants :

$ ls
Base configs DEP Libs scripts Templates
C contenu index.tcl Routes styles

Base est le dossier dans lequel se trouvera le model de la base de donnée, les scripts SQL mais aussi la base de donnée elle-même si SQLite3 est utilisé.

Dans configs se trouve les configurations de l'application ainsi que du framework.

Le dossier DEP est dédié au déploiement de l'application.

Dans le dossiers Libs se trouve la bibliothèque du Framework Kalinka. Est aussi inclus par défault les frameworks Prototype.js et Polyushka.

script servira à placer tous les fichiers JavaScript de l'application.

Templates est l'endroit où sont stockés les templates HTML des routes

Le dossier C est là où devra se trouver toute la partie code de l'application à l'exception des routes.

contenu pour d'éventuel fichiers PDF, images, ...

index.tcl, l'index de l'application tout simplement.

Dans Routes se trouvent le code des routes de l'application. Deux routes sont créés par défaut, "index" et "404".

styles servira aux feuilles de styles CSS.

Fonctionnement d'une application Kalinka

Dans une application Kalinka, tout passe par l'index index.tcl

Les routes

Général

Les routes sont définies dans le fichier configs/Phopshore.cfg comme cela :

ROUTES:{
(/):(index)
(/index):(index)
(/404):(404)
(/articles):(articles)
(/articles/jardinage):(jardinage)
}

Éxaminons la dernière route :

(/articles/jardinage):(jardinage)

Cela signifie que losrque l'on appelle l'url http://mondomaine.com/index.tcl/articles/jardinage Kalinka va chercher les instructions pour donner une réponse dans le fichier Routes/jardinage.tcl.


Création d'une route

Pour créer une route, ce plaver dans le répertoire de l'application et exécuter la commande suivante :

$ chemin_vers_kalinka/Kalinka mk route /articles/jardinage/semis semis


Fonctionnement d'une route

Dans Kalinka, les routes fonctionnent selon le principe suivant :

Dans l'url http://mondomaine.com/index.tcl/articles/jardinage/semis la route correspondant au chemin "/articles/jardinage/semis" est "semis". Lors de l'exécution de l'application, Kalinka cherchera si des routes existent pour les chemins "/articles" "/articles/jardinage", exécutera leurs procédures principales et encapsulera les résultats les uns dans les autres :

Résultat de la route "semis", dans le résulat de la route "jardinage", lui même dans le résultat de la route "articles".

Structure d'un fichier de route

Toujours dans le cas de la route suivante :

(/articles/jardinage):(jardinage)

Le fichier de route doit ressembler à cela :

proc App_route_jardinage {get post {html "null"}} {
    set template "Templates/jardinage.html"
    set vars [dict create "FILLE" $html]
    set html [LibKalinka_TemplateHTML $template $vars]
    return $html
}
proc App_route_nom_jardinage {} {
    return "jardinage"
}
proc App_route_titre_jardinage {} {
    return "jardinage"
}
proc App_route_js_jardinage {{js "null"} {
    set js_liste [list]
    if {$js != "null"} {
        set js_liste [LibKalinka_List_concat $js_liste $js]
    }
    return $js_liste
}
proc App_route_css_jardinage {{css "null"}} {
    set css_liste [list]
    if {$css != "null"} {
        set css_liste [LibKalinka_List_concat $css_liste $css]
    }
    return $css_liste
}

La première procédure :

proc App_route_jardinage {get post {html "null"}} {
    set template "Templates/jardinage.html"
    set vars [dict create "FILLE" $html]
    set html [LibKalinka_TemplateHTML $template $vars]
    return $html
}

C'est celle qui est immédiatement exécutée lorsque le fichier de route est appelé par l'url correspondant. C'est dans cette procédure qu'on ajoutera le code nécessaire à la construction du template de la route. On pourra aussi ajouter une structure de contrôle pour savoir, dans la cas d'un formulaire, si des données POST existent et les traiter, sinon, afficher le formulaire.

On peut noter la présence de trois variables d'entrée à cette procédure. "get" et "post" sont des dictionnaires contanant les données de GET et POST. La troisième variable contient soit le rendu HTML de la route fille de la route présente, soit "null".

L'intérieur de la procédure sera expliqué dans la partie sur les templates HTML.

La deuxième procédure retourne simplement le nom de la route :

proc App_route_nom_jardinage {} {
    return "jardinage"
}

La troisième procédure retourne de titre de la page HTML qui sera contenu dans la balise title :

proc App_route_titre_jardinage {} {
    return "jardinage"
}

La quatrième procédure retourne une liste de tous les fichiers JavaScript à charger, uniquement pour cette route :

proc App_route_js_jardinage {{js "null"} {
    set js_liste [list]
    if {$js != "null"} {
        set js_liste [LibKalinka_List_concat $js_liste $js]
    }
    return $js_liste
}

La cinquième procédure retourne une liste de toutes les feuilles se styles à charger, uniquement pour cette route :

proc App_route_css_jardinage {{css "null"}} {
    set css_liste [list]
    if {$css != "null"} {
        set css_liste [LibKalinka_List_concat $css_liste $css]
    }
    return $css_liste
}

Template d'une route

Continuons avec notre exemple de route :

(/articles/jardinage):(jardinage)

Le template créé par défaut est peu garni :

<!-- Kalinka Framework TCL -->
<p>jardinage</p>
{FILLE}

Les accolades servent à placer du contenu dans le template HTML. Dans le cas présent, FILLE sera remplacé par le rendu HTML d'une potentielle route fille, par exemple : la route "semis".

Le remplacement de mots clefs par un contenu donné ne se fait pas automatiquement, dans le fichier de route, le code suivant enclenche se mécanisme :

set vars [dict create "FILLE" $html]
set html [LibKalinka_TemplateHTML $template $vars]

Si on souhaite afficher "bonjour", on ajoutera une clef au dictionnaire "vars" ayant pour valeur "bonjour" :

set vars [dict create "FILLE" $html "BJ" "bonjour"]

On ajoutera la même clef dans le template HTML :

<!-- Kalinka Framework TCL -->
<p>jardinage</p>
{BJ}
{FILLE}

Ce qui affichera "bonjour", suivi du rendu HTML de la route fille de la route actuelle.


Une route particulière : Main

Si on explore le dossier Routes, on se rend compte qu'il y a un fichier de route ne correspondant à aucune route : Main.tcl. Il s'agit de la route principale de l'application, ses procédures sont systématiquement exécutées par Kalinka, quelque soit la route appelée. Il faut donc y insérer le code général de l'application. Son template est Templates/Main.html, il est commun à l'ensemble de l'application.

Déploiement de l'application

Jusqu'ici, l'application était en mode développement. Pour la passer en mode production, il suffit de se placer dans le répertoire de l'application et d'utiliser la commande suivante :

$ chemin_vers_kalinka/Kalinka app dep

L'application prête à être déployée ainsi que toutes ses dépandances se situent dans le répertoire DEP