Documentation de KeetagCaller version 2

KeetagCaller est la librairie qui vous permet d'intégrer rapidement le convertisseur à votre site. En savoir plus...

Sommaire

Par rapport à la version 1 de la librairie, l'apport principal de la version 2 est l'ajout de la méthode get_languages(), qui permet d'appeler l'API des langages. Cet ajout a conduit à modifier certaines méthodes déjà présentes dans la version 1.

Les méthodes publiques :

convert_text()
get_languages() [nouveauté de la V2 de la librairie]
set_option()
set_root_url() [remplace la méthode set_keetag_api_url() de la V1]
set_output_format()

Les méthodes privées :

set_urls() [nouveauté de la V2 de la librairie]
get_api_output() [remplace la méthode get_keetag_api_output() de la V1]
get_raw_api_output() [nouveauté de la V2 de la librairie]
change_json_format()
emergency_output_on_failure()

convert_text()

La méthode convert_text() est la plus importante car c'est elle qui vous permet de convertir votre texte. Elle peut prendre 3 paramètres :

$keetag->convert_text($text_to_convert, $orig_language_id, $destin_language_id);

$text_to_convert = le texte que vous voulez convertir.
$orig_language_id = le numéro d'identifiant du langage dans le lequel est balisé votre texte. Vous trouverez cet identifiant dans la liste des langages pris en charge.
$destin_language_id = le numéro d'identifiant du langage vers lequel vous voulez convertir votre texte.

Par exemple, pour convertir en HTML (ID #1 d'après la liste des langages pris en charge) ce texte qui contient des balises BBcode (ID #2 d'après la liste) :

$keetag->convert_text("Du [b]gras[/b].", 2, 1);

Mais vous pouvez également passer uniquement le texte à convertir en paramètre, si vous avez défini les langages de départ et d'arrivée avec set_option(). Cela est pratique pour ne pas répéter les paramètres si vous appelez convert_text() plusieurs fois dans votre script :

$keetag->set_option('orig_language_id',   2);
$keetag->set_option('destin_language_id', 1);
// Pas besoin de préciser les ID des langages en paramètre ici
$keetag->convert_text("Un texte à [b]convertir[/b].");
$keetag->convert_text("Un [i]autre[/i] texte.");
$keetag->convert_text("Et un [u]troisième[/u].");

La méthode peut ne prendre aucun paramètre si vous définissez également le texte à convertir avec set_option() :

$keetag->set_option('orig_language_id',   1);
$keetag->set_option('destin_language_id', 2);
$keetag->set_option('text_to_convert',    $text_to_convert);
// La méthode ne prend ici aucun paramètre
$keetag->convert_text();

Si le langage de destination est toujours le même mais que celui de départ change, vous pouvez définir ce dernier avec set_option() et passer le langage de destination en paramètre dans convert_text() :

// Indique que tous les textes seront convertis en HTML (ID #1)
$keetag->set_option('destin_language_id', 1);

// Ce texte balisé en BBCode (ID #2) sera converti en HTML
$keetag->convert_text("Un texte en [b]BBcode[/b]", 2);
// Ce texte balisé en Textile (ID #18) sera converti en HTML
$keetag->convert_text("Un texte en **Textile**", 18);

Si, à l'inverse, c'est le langage de départ qui est invariable et celui de destination qui change :

// Indique que le langage d'origine sera toujours le HTML (ID #1)
$keetag->set_option('orig_language_id', 1);

// Ce texte balisé en HTML sera converti en BBcode (ID #2).
// Notez que le 2e paramètre ($orig_language_id) vaut NULL car il est déjà défini.
$keetag->convert_text("Un texte en <strong>HTML</strong>.", NULL, 2);
// Ce texte balisé en HTML sera converti en Textile (ID #18)
$keetag->convert_text("Un <em>autre</em> texte en HTML.",   NULL, 18);

get_languages()

[Rédaction en cours]

set_option()

La méthode set_option() vous permet de définir les paramètres de conversion. Par exemple :

// Indique que les balises non reconnues devront être supprimées
$keetag->set_option('remove_unknown_tags', TRUE);
// Indique que les liens relatifs devront être transformés en liens absolus
$keetag->set_option('repair_relative_links', TRUE);

// Convertit le texte en appliquant tous les paramètres définis par set_option()
$keetag->convert_text('This is <strong>bold</strong> text.', 1, 3);

Pour connaître tous les paramètres disponibles, consultez la liste des paramètres d'appel à l'API de conversion.

Comme dans la version 1 de la librairie, le langage de départ, celui d'arrivée et le texte à convertir peuvent toujours être définis avec set_option(), au lieu d'être passés directement en paramètres de convert_text() comme dans cet exemple. Voir la documentation de la méthode convert_text() V2.

set_root_url()

[Rédaction en cours]

set_output_format()

Même fonctionnement que dans la version 1 de la librairie. Voir set_output_format() V1.