inc-formulaire_forum.php3 is quite complicated and probably not the best one to start with.
I am not an expert in this, but I can explain the one I have already done : http://trac.rezo.net/trac/spip-zone...
It is used to put keywords (tags) on a forum post. (it is the one on the left of this page)
The global array declared at the begining :
specifies which variables you want to retrieve from the context (the higher level loops and the url). Here, we get the id_forum.
The form tag is a bit special as it cannot be put in cache (it might have to be different for each visitor). It is therefore separated in two functions :
function balise_FORMULAIRE_TAG_FORUM_stat($args, $filtres) is the "static" function. It is the one that returns what will be put in the cache.
It receives in the array $args the variables collected from the context — In our case, $args[0] will contain the id_forum — and the filters applied to the tag — you could want to get some parameters from there, etc...
If it returns a string — in our example, if the $args[0] does not exist, we return an error in that way —, the string will be directly written into the cache and that’s it.
If you want the tag to be "dynamic" and different for each user, you have to return an array. This will tell SPIP to put some PHP in the cache that will be interpreted at each hit on the page.
This PHP code will call the "dynamic" function : function balise_FORMULAIRE_TAG_FORUM_dyn($id_forum) with the parameters specified by the array returned previously — in our example, only the id_forum —
The _dyn function is called at every hit on the page. So you have access to the user cookies and can do security check from that (the global array $auteur_session is filled by spip with the informations extracted from the login cookie if the user is logged for example).
It should either return a static string (but this is not really useful) or an array. This array will specify which template to use for the tag. It should contains :
- the “fond”, the file name (without html) of the template (like for normal templates),
- the “delais”, which specify, like for normal templates, the period before refreshing the cache,
- the variable to be passed in the included context (like the parameters to the INCLUDE tag in SPIP).
In our example, we return :
so the template used will be formulaire_tag_forum.html, and we will provide two variable for the initial context :
- self (the url of the current page)
- id (the id of the forum)
This function is also the place where you will update the database with the posted data from the form. In our example, we call another file to do the insertion, this is not important.
The posted data can be accessed with the _request function. For example, we use _request('id_groupe') to get the id_groupe sent by the form.
Lets now look what the template looks like http://trac.rezo.net/trac/spip-zone...
Except all the javascript in the middle, it is quite simple. As you can see, it looks exactly like a normal template. You can put loops, and use tags.
For example, we use a loop : <BOUCLE_mots(MOTS) {id_forum = #ENV{id}} {id_groupe}>[(#TITRE|echaper_mot{#TYPE,#_groupes:TITRE}) ]</BOUCLE_mots> to show the keywords already attached to the actual forum.
The variable inserted in the context by the _dyn function can be accessed in two ways. You can :
- directly use a criterion
{id_something} if the variable has the same name. As you usually do in template to get the id_rubrique for a rubrique loop etc... - use the #ENV tag to get the variable.
[(#ENV{id})] returns in our case the id of the forum as sent by the _dyn function.
(I think that this is documented in the official documentation)
We use #ENV{self} as action for the form, so we will stay on the same page when we send the data.
Remark that we also use [(#ENV{id})] to have a unique id per form. Therefore, we can include more than one #FORMULAIRE_TAG_FORUM on the same page.
