La version 2.1 d'IPB se veut tres modulaire. Les premiers pas de cette modularité date de la 1.2 avec les "automodule", avec la 2.0 nous avons eu le droit à l'HTML logik et au début de Converge. La 2.1 rajoute les "Composants" qui sont des automodule à la puissance 1000 ! et les API que je vais vous detailler!
API ?? c'est quoi ??
Avant tout une explication sur kesako d'une API
Definition
QUOTE(Def)
A-P-I/ sg. f. Application Programming Interface. Interface de programmation d'applications, contenant un ensemble de fonctions courantes de bas niveau, bien documentées, permettant de programmer des applications de « Haut Niveau » (:-§). On obtient ainsi des bibliothèques de routines, stockées par exemple dans des DLL ou des NLM
Source
Source
Dans notre cas, les API d'IPB permet de rajouter un fichier lang, un "Composant" et la plus interresant des fonctions ! rajouter des topics et posts
Cette API permet donc par exemple dans un automodule/composant de rajouter automatiquement (et sans bidouiller le code n'importe comment) une reponse à un topic ou dans un script externe (Gestionnaire de news par exemple) de creer automatiquement un topic pour pouvoir commenter la news...
La definition n'est pas parfaite dans le cas d'IPB car API est assez mal documenté.. (Merci Matt...)
Je vais donc essayer de vous expliquez comment faire marcher cette API !
Utilisation
Comment dit précedent, vous avez la possibilitée d'utiliser l'API directement dans IPB (via les automodule/composants) ou directement dans votre propre script (indépendant d'IPB)
pour utiliser API directement dans le code IPB :
SQL
require_once( ROOT_PATH."sources/api/api_core.php" );
require_once( ROOT_PATH."sources/api/api_topics_and_posts.php" );
$api = new api_topics_and_posts();
$api->ipsclass =& $this->ipsclass;
require_once( ROOT_PATH."sources/api/api_topics_and_posts.php" );
$api = new api_topics_and_posts();
$api->ipsclass =& $this->ipsclass;
Si vous utilisez API dans votre code à vous
SQL
require_once( "/votrepathavous/sources/api/api_core.php" );
require_once( "/votrepathavous/sources/api/api_topics_and_posts.php" );
$api = new api_topics_and_posts();
$api->path_to_ipb="/votrepathavous/";
$api->api_init();
require_once( "/votrepathavous/sources/api/api_topics_and_posts.php" );
$api = new api_topics_and_posts();
$api->path_to_ipb="/votrepathavous/";
$api->api_init();
Bien sur apres il faut remplacer /votrepathavous/ par votre vrai PATH (chemin)
Ajout d'un nouveau message
cette opération se realise en 4phases
- Selection du topic ou on rajoute le message (au topic numero 10 dans notre cas)SQL$api->set_topic_id( 10 );
- Selection du "posteur" du message par son pseudoSQL$api->set_author_by_name('Prolag');
- Ajout du messageSQL$api->set_post_content("<b>Bonjour tout le monde!</b>
"); - on fini par l'ajout du post !SQL$api->create_new_reply();
Ajout d'un nouveau topic
Ca ressemble beaucoup à l'ajout de nouveau post sauf qu'on selectionne un forum au lieu d'un topic et on rentre un titre au topic
- Selection du topic ou on rajoute le message (au forum numero 10 dans notre cas)SQL$api->set_forum_id( 1 );
- Selection du "posteur" du message par son pseudoSQL$api->set_author_by_name('Prolag');
- Ajout du messageSQL$api->set_post_content("<b>Bonjour tout le monde!</b>");
- Ajout du titre du topicSQL$api->set_topic_title("Le titre de mon topic");
- on fini par l'ajout du topic !SQL$api->create_new_topic();
Vous savez donc maintenant facilement rajouter un topic ou un message
Mais cette API permet de modifier quelques options de topics et messages, sujet que nous allons aborder dans le prochain chapitre
Options avancés...
Options "Auteur"
Il y a 3 facons differents de rajouter l'auteur
- par son ID / numero uniqueSQL$api->set_author_by_id('44);
- par son pseudo principale (utilisé à l'authentification)SQL$api->set_author_by_name('Prolag');
- par son pseudo personnalisableSQL$api->set_author_by_display_name('GuT');
On a la possibilité de modifer la configuration du topic quand on le cree
On peut rajouter une description au topic
SQL
$api->set_topic_description("Ma description du topic");
Modifier son état (Sujet ouvert ou fermé)
SQL
$api->set_topic_state('closed') // on ferme le sujet
par défaut le sujet est ouvert ('open')
on peut epingler le topic
SQL
$api->set_topic_pinned(1); // on eplinge le sujet
ou le rentre invisible (en attente de validation)
SQL
$api->set_topic_invisible(1); //on rends le topic invisible
On peut trouve encore 2 autres options plus manuel par contre.
On peut specifier un post_id (le icone devant les topics ) par exemple si on veut le panneau d'avertissement /!\
on rentre
SQL
$api->topic_settings['post_icon_id'] = '13'
13 étant son numero...
Vous pouvez aussi modifier la date du topic
SQL
$api->topic_settings['topic_date'] = '112033242';
Il faut rentrer la date au format timeslamp Unix qu'on obtient via time()
Options Posts
Comme avec les topics, on peut modifier les options du post
On peut afficher ou non la signature du membre
SQL
$api->post_settings['show_signature'] = '0'; // on désactive l'affichage le signature du membre dans le post
par défaut la signature est affichée
on peut afficher ou non les smileys
SQL
$api->post_settings['show_emoticons'] = '0'; //On désactive l'affichage des smileys
par défaut les smileys sont affichés
On peut rentre le post invisible (attente de validation)
SQL
$api->post_settings['is_invisible'] = '1'; // on rends le post invisible
par défaut le post est visible
On peut specifier une adresse IP (qui par défaut est l'adresse IP du posteur..)
SQL
$api->post_settings['ip_address'] = "192.168.0.2";
On peut specifier aussi si il faut parser ou non le HTML
SQL
$api->post_settings['parse_html'] = '1' // on parse le HTMl
par défaut le HTML n'est pas parsé
et pour finir comme pour le topic, on peux specifier un date et une icone
pour la date
SQL
$api->post_settings['post_date'] ='112033242';
pour l'icone
SQL
$api->post_settings['post_icon_id'] = '12' //Affiche le coeur !
Options avancées....
Comme avec les API officielles, vous avez la possibilité d'avoir accès à plusieurs tableaux qui contiennent :
le topic :
SQL
$api->topic
le forum :
SQL
$api->forum
l'auteur de la modification (si vous utilisez set_author....)
SQL
$api->author
Erreurs
API peut generer des erreurs dans le cas, ou il ne trouve pas le topic / forum...
Les erreurs sont stockés dans un tableau api_error
on peut facilement avoir un acces
SQL
var_dump($api->api_error); // on affiche le tableau d'erreur
Aussi create_new_topic et create_new_reply retourne TRUE si l'opération a été réalise avec succès et FALSE en cas de probleme (en le rajoutant au tableau api_error)
Voila une liste rapide des erreurs que vous pouvez avoir :
not_all_data_ready => Il manque des parametres (post , forum /topic ID..)
no_post_content => Il manque le post
no_user_found => l'utilisateur n'existe pas !
no_topic_found => le topic n'existe pas !
no_forum_found => le forum n'exite pas !
Conclusion
J'espere que ce guide vous aura permis de mieux comprendre comment utiliser les API d'IPB. Un des défaut des API d'IPB est qu'elle manque de fonctionnalité ! on a pas la possibilité d'editer ou deplacer / supprimer un post par les API officielles...
