Installation

Il faut commencer par avoir ruby, rubygems et Ruby On Rails en version 2.3.5 sur votre machine (via votre package manager favoris). Ensuite télécharger geewee ici ou alors:

hg clone http://hg.kaworu.ch/rails-geewee

Configuration

Créer une base de donnée et éditer config/database.yml avec les bon paramètres. Hop un petit exemple pour PostgreSQL:

createuser --no-createdb --no-createrole --login --pwprompt --encrypted geewee
# createuser va demander le password pour le nouvel utilisateur
createdb --encoding=utf8 --owner=geewee geeweedb

Le fichier config/database.yml aura à peu près cette tête:

development:
    adapter: postgresql
    database: geeweedb
    username: geewee
    password: <secret>
    encoding: utf8

Ensuite il faut installer les gems dont geewee a besoin:

• haml pour les vues.
• bluecloth pour traduire de markdown vers HTML (posts, pages et commentaires).
• coderay pour le support de la coloration syntaxique des langages de programmation.
• builder pour générer les flux Atom.
• friendly_id pour des urls sexy™.
• authlogic pour l'autentification du client via l'API json.

rake gems:install

Puis on prépare les tables de la db:

rake db:migrate

Finalement il faut créer un utilisateur (auteur) pour le blog (geewee supporte d'avoir plusieurs auteurs). On lance une console rails:

./script/console

Puis

me = Author.create! :name => 'my_name', :email => 'my_email'
puts me.single_access_token

Copier le single_access_token, on va en avoir besoin. C'est la méthode utilisée pour l'authentification du client.

Utilisation

Configuration du client

geewee utilise une API json, pour faire communiquer l'application et le client. Le client geewee se trouve dans client/geewee. Il est écrit en ruby et a besoin de la gem json (le parseur yaml de ruby est 1.0 et n'est pas compatible avec json, si un jour la version 1.2 de yaml est dans ruby on aura plus besoin de cette dépendance vu que yaml >= 1.2 est un superset de json). On installe, donc:

gem install json_pure

Pour configurer le client il faut l'éditer tout en bas du fichier:

###
# Config for the geewee client in YAML, example:
=begin

---
base_url:       http://my.sexy.geewee/blog/path
editor:         ee
geewee_api_key: my_secret_single_access_token

=end


__END__
---
base_url:       http://localhost:3000
editor:         vim
geewee_api_key: PLs_gVBZwd5EudsRMObO

Modifier les valeurs après le __END__. Il y a (pour l'instant) trois champs configurables:

• base_url (requis): l'adresse de votre blog
• editor (facultatif): votre éditeur de texte favoris. Si ce champ n'est pas configuré alors $EDITOR est utilisé.
• geewee_api_key (requis): le single_access_token de votre utilisateur, c'est ce qui permet de vous authentifier.

Pour l'instant le client ne peut que gérer les catégories et les posts (les pages statiques, utilisateurs et commentaires sont supportés, mais pas encore implémenté coté client). On lance une fois sans arguments pour avoir l'aide:

% ./client/geewee

geewee: wrong # of arguments

usage: geewee operation ressource [arguments...]

CRUD operations:
===============>
    geewee create ressource
    geewee create ressource /path/to/file
    geewee show resource
    geewee show resource id
    geewee update ressource
    geewee update ressource id
    geewee update ressource id /path/to/file
    geewee destroy ressource
    geewee destroy ressource id

operations and resources:
========================>
-       show: posts, categories
-    destroy: posts, categories
-    publish: posts
-     update: posts, categories
-     create: posts, categories

On voit que les quatre opérations de bases sont disponibles pour les posts et catégories, ainsi qu'une supplémentaire (publish) pour les posts.

Opérations

show affiche les informations. Si on ne donne pas de id en paramètre, la commande show va afficher toutes les entrée de la resource demandée (par exemple toutes les catégories). Exemples:

% geewee show categories
1. blabla (6)
2. prog (5)
3. admin (3)
4. end-user (4)

% geewee show posts
 18. [unpublished] "geewee: The Geek Weblog Engine." by kAworu in blabla (Ruby On Rails, geewee, blog)
 17. "dans l'absolu, ça marche pas vraiment" by kAworu in prog (C, algo)
 16. "this is it!" by kAworu in blabla (blog)
 15. "Android FAIL" by kAworu in end-user (Google, FAIL)
 14. "nice try" by kAworu in prog (NetBSD, Knuth, C)
[...]

% geewee show posts 18
created_at: 2010-03-15T00:03:04+01:00
updated_at: 2010-03-15T00:03:05+01:00
id:       18
author:   kAworu
category: blabla
tags:     Ruby On Rails, geewee, blog
title:    geewee: The Geek Weblog Engine.

Voilà, dans mon désespoir de
[...]

Les autres commandes font ce qu'on attend d'elles, c'est à dire créer (create), modifier (update), effacer (delete) et publier (publish) (on peut aussi publier via une opération update, c'est juste moins pratique). Pour la suite on va faire un petit exemple pour faire le tour des fonctionalités.

Exemple

Catégorie

Il faut tout d'abord lancer le serveur:

./script/server

Pour créer une nouvelle catégorie on lance la commande:

geewee create categories

Là notre vim^Wéditeur favoris est lancé avec un fichier qui contient seulement:

[category]display_name:

On entre le nom que l'on veut. Si une erreur survient (vide, nom déjà pris etc) le client va afficher le chemin du fichier que l'on a édité (par exemple /tmp/geewee_126861126727982). Pour les catégories c'est pas très important car il n'y a qu'un champ, mais pour un post ça permet de pouvoir aller chercher le fichier, le modifier et recommencer l'opération avec comme argument le fichier (pour create et update). On peut aussi utiliser - comme argument de fichier, et à ce moment le client utilise l'entrée standard (ça permet de le faire à travers le réseau, ssh etc). Si on rentre un nom valide, par exemple:

[category]display_name: geewee rox!

Tout devrait bien se passer et on va voir:

===> new Category created:
  1. geewee rox! (0)

Le 1. est l'id de la catégorie, et (0) le nombre de post dans cette catégorie.

Post (ou Billet, à choix)

Maintenant que notre blog a une catégorie, on peut commencer à écrire des posts!

geewee create posts
  1. geewee rox! (0)
???> Choose a Category id (n to create a new one): 

On entre l'id de la catégorie de notre nouveau post (avec n on pourra créer une nouvelle catégorie comme on vient de le faire). On va entrer "1" et à nouveau notre éditeur est lancé:

 [post]title: 
 [post]category_id: 1
 [post]tag_list: 

 *Intro*

 %...

 *Body*

On voit que le champ category_id a été rempli avec celle que l'on a séléctionné. Les champs title et tag_list sont vides et à remplir. tag_list est une liste de mot-clés, séparée par des virgules. Il y a ensuite une ligne vide et la ligne *Intro*. On peut placer ici une courte introduction qui sera sur la page principale, le reste (*Body*) ne sera visible que sur la page du post (si on suit "lire la suite..."). l'intro et le body sont séparés par la ligne:

%...

Dans l'intro et le body on peut utiliser markdown comme markup, et des balises spéciales pour coderay:

%code lang=C
for (;;)
    fork();
%/code

Attention il faut que %code, %/code et %... soient en début de ligne!

L'argument lang= de %code est donné à coderay, il y a donc tous les langages que coderay supporte qui sont disponibles :D

On continue!

 [post]title: Mon premier post!
 [post]category_id: 1
 [post]tag_list: geewee, blog

 Mon premier post avec _geewee_ !

 %...

 %code lang=Ruby
     10.times { puts "youpie!" }
 %/code

Lorsque l'on a fini, on nous demande gentillement si il faut le publier ou pas :)

???> publish now? [y/n]:

On met non (n), car on veut avoir un aperçu du post avant de le publier.

===> new Post created: http://blog.kaworu.ch/posts/mon-premier-post

On peut maintenant aller voir ce que ça donne:

Si on est pas content, on fait un petit:

geewee update posts

Les posts sont affichés et on entre l'id de celui que l'on veut modifier (on peut donner l'id drectement en argument, et le fichier également). Une fois qu'on est content, on le publie:

geewee publish posts # on peut donner l'id aussi.
  1. [unpublished] "Mon premier post!" by kAworu in geewee rox! (blog, geewee)
???> target Post id to publish: 1
===> published.

Pour destroy je vous fait pas un dessin, il affiche les posts (ou catégories) et demande l'id si ce n'est pas donné en argument, et demande une confirmation.

Oui mais attention

geewee est tout jeune (j'ai commencé il y a une semaine seulement) et a encore pas mal de limitations.

• les messages d'erreurs du client ne sont pas encore toujours ultra claires.
• les fichiers dans /tmp du client ne sont pour l'instant jamais effacés.
• le client ne peut pas encore gérer les pages statiques, ni les commentaires, ni les utilisateurs, ni les fichiers statiques.
• le blog n'est pas encore configurable (nom et url du blog par exemple), même si c'est faisable en deux coups de vim.
• pour tout le reste il y a eurocard mastercard™.

Il y a la todo liste (devtodo) est dans le projet, si vous avez un vim et un peu de temps, patches & tests sont les bienvenus :D