SPIP

Estructura general d'SPIP

merce — 2010-08-31T21:31:38Z

SPIP és un CMS únic en el seu gènere.

Més enllà del seu funcionament que es pot qualificar de « data driven », és a dir « pilotat per les dades » (els famosos BUCLES), ha proporcionat sempre en primera línia els mitjans de « personalitzar », adaptar ell seu funcionament i la seva presentació al gust i a les necessitats pròpies del lloc.

Primerament era la possibilitat de proporcionar els seus propis esquelets (plantilles), d'adjuntar-hi fragments de PHP específics i sobrecarregar les funcions de base del « core » (les function xxx_dist() que veurem més endavant).

La versió 1.9 introdueix un mecanisme complementari, els connectors o plugins. Han sorgit de la voluntat d'obrir SPIP a funcionalitats suplementàries sense fer que el seu nucli (el « core » sigui més feixuc). La tendència actual és tanmateix la d'alleugerir aquest core transferint les funcionalitats opcionals als connectors.
SPIP 2.0 s'hauria d'haver reduït i lliurar amb una col·lecció de connectors de base que l'usuari activarà segons els utilitzi realment o no. Per exemple, és tracta que les breus no estiguin més a dins del core sinó que estiguin en un connector opcional. En efecte, només una part de les instal·lacions les utilitza i és preferible no alentir el sistema de base per aquells que no en tenen necessitat.

Però ja, SPIP 1,9 ha renovat completament els directoris que el constitueixen per tal de separar els elements en funció de la seva vida, del fet que siguin modificables i de la seva pertinença al que és propi o específic al lloc o al codi de base. Un dels altres objectius apuntats aquí és la possibilitat de compartir el nucli : que diversos llocs puguin compartir una base de codi comú.

Estudiem primer aquesta nova organització de directoris, d'allò que pertany a SPIP del que és propi del lloc, d'allò que queda constant del que es mou.

Distribució

arrel del lloc

L'arrel, que ha estat completament buidada i no conté pràcticament més que index.php que redirigeix cap a spip.php, és actualment l'únic punt d'entrada de la part pública del lloc.

inc-public.php3 és un fitxer fantasma per assegurar la compatibilitat ascendent.

.htaccess opcional per l'url rewriting essencialment.

win_png.htc [1] i rien.gif per assegurar la transparència png amb MSIE

ecrire/

Aquesta carpeta conté actualment el conjunt de fitxers interpretables pel cantó del servidor (PHP i MySQL) i aquest, tant per la visualització pública (subcarpeta public/) com per la visualització privada.

El nom d'aquesta carpeta és històric, és allà on antigament s'hi trobava el codi que permetia modificar el contingut del lloc. Paradoxalment, actualment és una carpeta no modificable i mai hi escriurem a dins. En una instal·lació normal, conté només els scripts lliurats per la distribució i és gairebé imperatiu no fer-hi cap tipus de modificació.

El seu script index.php és el punt d'entrada d'ecrire/, la part privada del lloc.

dist/ [2]

Conté tots els arxius lliurats als client (HTML, Javascript, fulls d'estil, imatges de diferents formats) i també els patrons de disseny anomenats esquelets. Aquests esquelets són interpretats al cantó del servidor per tal d'enviar al client un text purament MIME (la majoria de les vegades HTML, però també RSS, SVG... veure JS).

Són els models estàndard lliurats amb SPIP, i tampoc aquest s'han de modificar però si que es poden substituir copiant-los a dins de squelettes/

oo/ [3]

Aquesta carpeta proporciona el mode « accessibilitat » d'SPIP (en mode text). Conté, essencialment, un índex que envia de nou al sistema estàndard.

Adaptació

config/

Aquesta carpeta, creada en el moment de la instal·lació, conté l'script de connexió a la base de dades : connect.php i l'script que fixa el tipus dels arxius creats pel servidor : chmod.php.

És també aquí on es posarem les opcions universals del lloc, en un fitxer (a crear) : mes_options.php [4]

IMG/

Conté tots els documents originals (mida real) del lloc. Està subdividit en subcarpetes per tipus de documents.
En el moment de la instal·lació, conté només document de prova per la fabricació d'imatges.

squelettes/

És aquí on posarem tots els arxius : scripts, imatges, formularis..., propis del lloc, seguint la mateixa estructura que ecrire/ o dist/. Per exemple, per tornar a definir el resum del lloc, copiem/adaptem l'arxiu sommaire.html del directori dist/.

Posem aquí, sobretot, l'script mes_fonctions.php (a crear) que es carregada cada cop que es torna a calcular la pàgina. Fixem-nos que és possible fer un xxx_fonctions.php que serà carregat només quan serà demanada la pàgina xxx (per exemple : sommaire_fonctions.php).

En el moment de la instal·lació, aquesta carpeta no existeix, l'hem de crear.

plugins/

Aquesta carpeta (que també s'ha de crear) rep les subcarpetes de cada connector (plugin). Per exemple, el connector crayons es troba situat a plugins/crayons/.

Temporal

local/

Conté tots els fitxers (re-)calculables a partir dels documents i dades del lloc.

Es tracta bàsicament de caches d'imatges reduïdes. Hi trobem també les caches calculades per certs plugins com « coloration_code ».

Aquesta carpeta es pot buidar, no tindrà cap més cost que el seu nou càlcul.

tmp/

Aquí hi ha emmagatzemats tots els arxius temporals com les "caches" d'esquelets, les sessions, els logotips etc.

Conté també el subdirectori dump/ on hi ha arxivades les còpies de seguretat de les dades.

Aquesta carpeta pot estar sempre buida.

[1] suprimit a partir de la versió SPIP 2.0

[2] A partir de la versió d'SPIP 2.0, aquesta carpeta ha estat reanomenada com a squelettes-dist/.
Llegiu : Actualització de la versió 1 .9 .x a la 2 .0 .x.

[3] suprimit a partir de la versió SPIP 2.0

[4] Llegiu : El fitxer mes_options.php

Vegeu també : Ampliar SPIP

|singulier_ou_pluriel{ xxx:chaîne_un, xxx:chaîne_plusieurs}

merce — 2010-08-31T20:35:01Z

El filtre |singulier_ou_pluriel permet fer variar una visualització en funció del valor numèric retornat per l'etiqueta a la que s'ha aplicat.

El filtre |singulier_ou_pluriel s'utilitza la majoria de les vegades per concordar (singular o plural) les cadenes de llengua en funció del retorn d'una etiqueta.

Exemple

En el nostre fitxer local_xx.php, declarem:

'nombre_truc_un' => 'hi ha 1 retorn en aquest bucle.',
 'nombre_truc_plus' => 'hi ha @nb@ retorns en aquest bucle.'

Després escrivim en el nostre bucle:


 ...
 
 [(#TOTAL_BOUCLE|singulier_ou_pluriel{local:nombre_truc_un, local:nombre_truc_plus, nb})]

- Si el bucle només retorna un enregistrament, mostrarà:

hi ha 1 retorn en aquest bucle.

- Si el bucle retourna 36 enregistraments (per exemple), mostrarà:

hi ha 36 retorns en aquest bucle.

Fixeu-vos que es pot passar un 3r. argument a aquest filtre: nb que permet integrar a la cadena el valor numèric retornat per l'etiqueta.

Atenció:
Aquest filtre espera explícitament ítems de llengua com arguments. Caldrà, per tant, que no li passem etiquetes de llengua:
|singulier_ou_pluriel{module:item_un, module:item_plus}
és l'escriptura correcta;
|singulier_ou_pluriel{<:module:item_un:>, <:module:item_plus:>}
és una escriptura dolenta.

{fusion champ_sql}

merce — 2010-08-29T14:24:31Z

El criteri fusion permet reagrupar els resultats d'un bucle SPIP segons els diferents valors d'un camp.

Si el bucle sense el criteri {fusion champ_sql} porta diversos registres que tenen el mateix valor de champ_sql, llavors, el bucle amb el criteri {fusion champ_sql} només en presentarà un d'aquests.

Per això, la petició SQL generada integra una instrucció GROUP BY.

Exemple 'pedagògic'

El següent bucle mostrarà els títols de tots els articles del lloc:

El bucle següent, amb un criteri fusion que porti a la secció, partirà igualment de tots els articles, però els reagruparà per id_rubrique idèntica, i presentarà al final només un únic article per secció.

Exemple 'aplicat'

El següent bucle mostra els 10 missatges més recents del fòrum, escollits per data i procedents d'una IP diferent:

Atenció

Un criteri de classificació {par xxx} combinat amb el criteri {fusion champ_sql} no ens retornarà necessàriament els resultats esperats.

- torna els articles classificats per id_article (de l'1 al 10000 per exemple).

- torna els articles, classificats per id_article després d'agrupar-los per id_rubrique, però aquests reagrupaments estan fets desordenadament i, a priori, sense cap classificació especial!

Vegeu també

- el criteri {doublons}
- el filtre |unique

Add your own style!

Mark — 2010-08-23T16:00:10Z

You are able to modify the style rules supplied with SPIP and add in your own by creating your own style sheet. Details below...

If you already know the CSS language (otherwise first read this article: "Introduction to style sheets"), you can very easily modify the appearance of your site without even having to know anything about SPIP's internal language of loops and tags.

Creating your own stylesheet

When you first install SPIP, the squelette templates are distributed with several "external stylesheets" which combine together the rules used to generate the graphical mark-up of your site. You can modify these files and add your own rules to them, but it's generally a better idea to do these modifications and additions in your own CSS stylesheet so that your creativity is not obliterated when you next install an update to the SPIP core software.

Important: never work directly in the files supplied by default, otherwise you will run the very serious risk of losing all your customisations when you update SPIP itself! To avoid losing the changes, almost make copies of any "core" files that you do decide to change anyway.

1. Create a file named my_styles.css (or whatever it is you have decided to call it) and store it in your "squelettes" folder. You will copy into this file all the style rule definitions that you would like to use and modify; but for the purposes of this tutorial, we're going to assume that you're starting off with a completely empty stylesheet.

2. Call this stylesheet in the header section of your squelette templates, i.e. between the tags in the HTML file (right after the title and other similar meta tag fields). This call should look something like this:

Often enough, you only need a single stylesheet for all of the graphical mark-up rules for a site, but you still create as many such stylesheets in the same manner as this as you so choose. It's often the case that some webmasters separate style rules depending on the medium and/or the targeted browser, simply to keep things clear and simple.

History: Since SPIP 1.8.2, we have been using:

<link rel="stylesheet" type="text/css" href="#DOSSIER_SQUELETTE/mes_styles.css" />

Since SPIP 1.9, the #CHEMIN tag has replaced and imrpoved on the #DOSSIER_SQUELETTE tag.

Respecting the "cascade"

It is important to keep in mind how the cascade component of CSS: when several style definitions are applicable to a single given element, the closest style for the element is the one that takes priority. What is close is affected by the order in which the style rules are "read", so this is therefore a very important matter.

- External stylesheets

If you use several stylesheets, note that the order in which they are referenced in the page header is important. If you first call my_styles.css and then spip_style.css, then the rules in the latter file will take priority, because they are closer to the elements to which they apply, which means that they will override your rules. Remember, then, to call your stylesheets in the opposite order:

- Styles defined in the HTML code

If you do not want to touch the CSS files, you can still continue to insert, in all the necessary spots, the graphical instructions directly into the HTML code of your squelette templates: either by defining some style rules in the head section, and/or by attaching the style rules directly onto the HTML tags inside the page.

The style attached directly to the tags, being the closest to the elements in question, will take priority over those defined in the head, which themselves will take priority over any external stylesheets.

Styles that have "class"

So how can we change, for example, the appearance of all of the sub-headings generated by SPIP? This is actually very easy. Open up your my_styles.css file in a text editor and add the following line:

h3.spip { color: red; font-size: 18px; }

Now reload the page: all of the sub-headings now magically appear in red; note that if you have any other h3 content on your page, then they will not be displayed in red.

A brief explanation of the syntax of this page formatting rule is in order:

- h3.spip just before the braces means that the rule only applies to the

tags that have been assigned a `class` attribute equal to "`spip`". Note: none of the
tags without that attribute, and no other tags that do have that attribute but are not actually
tags, will be affected by this rule.

If you add in your own style rules, note that the value assigned to the `class` attribute is completely arbitrary. The only thing that matters, is that you use the same name in the HTML code (`class="toto"`) and in your CSS stylesheet (`.toto { ... }`).
Remember, though, that you can not actually rename the `class` attributes associated with the code generated by SPIP (which have style definitions all combined in `spip_style.css`).

- The braces contain the list of graphical properties associated with the style rule as defined. In our example we note the the colour is set to be read and that the font in question will be displayed with a size of 18 pixels.

Note that all of the properties that are not defined in this list retain their normal values for the tag in question: in our example, the `h3` will always still generate a text displayed in bold, because nothing in your style definition has instructed that "standard" rule to be overwritten.

Managing the cache

The fact that the style rules are defined in a separate file has an important consequence. In fact this file, as opposed to your squelette templates, is not managed by SPIP (it doesn't need it at all!). This means that if you modify a stylesheet, you do not need to empty the SPIP cache: just reload the page from your browser (although some browsers may require you to specifically reload a new stylesheet with a special command - after time, the browser will do this automatically, but at least Firefox will probably require a CTRL-F5 instead of the normal F5 for the refresh). So having external stylesheets actually makes graphically reformatting your pages an easier task.

Remember still that your stylesheet must be declared in your HTML files, and that they must be recalculated any time that you change them for their contents to be reflected on the browser screen.

Several logos for a single article

Mark — 2010-08-20T18:03:27Z

In order to give some graphical "life" to a site, it's a common desire to use different logos (and in particular, logos of different sizes) for the same article depending on where that article is referenced or used.

For example, you might want to use a "big" logo on the home page in order to draw attention to the "article of the day", and then use a "small" logo where that article is included in the site's general navigation mechanism.

Recalling that since SPIP 1.7, SPIP 1.7.2 , SPIP webmasters have been able to use the image_reduire function to create various versions (in size) of a single same logo assigned to an article. But we will need to employ a different method if we have several different logos for any single given article.

Some webmasters have created individual methods based on the differentiated usage of the "normal" logo and the "mouseover" or "hover" logo. For example: the "normal" logo might be used as a "small logo" for the article in a navigational context (called using the #LOGO_ARTICLE_NORMAL tag), and then use the "mouseover" logo (called using the #LOGO_ARTICLE_SURVOL tag) to access the "big logo" when linking to the article from the home page. Although it works, this sort of approach complicates the squelette templates and means that you can't use the "mouseover" logo for its intended purpose which SPIP would automatically provision itself in the "normally" appropriate circumstances. In addition, it doesn't really leave a lot of room for flexibility.

Since version SPIP 1.4 , it has been possible to attach documents to articles (and later also to sections/rubriques). We're going to explain here below how you can use these attached documents to create several logos for a given article.

The general principle

- We will continue to use the article's two logos to display just the "normal" logos (those that will appear in the most commonly accessed navigation links, as is the case for a section that lists its constituent articles), which means we can enjoy using the standard simple mechanisms for logos in SPIP with automatic handling of the "mouseover" logo (and simultaneously re-enabling the ordinary usage of the #LOGO_ARTICLE and #LOGO_ARTICLE_RUBRIQUE tags).

- We will choose to attach to each article concerned an additional document (generally an image in either GIF, JPEG or PNG format), which we will then systematically assign the same title name. This is all we need to be able to display this document (by referencing with this assigned standard name) instead of the "normal" article logo whenever we have a need to do so.

- This method then clearly makes it possible for us to assign as many different logos as we want for a given article (not just one big logo and one small logo, but why not a thumbnail logo as well to brighten up a title zone for the article as well, etc.).

- We will then see that thanks to SPIP's loops, it becomes very easy to determine within our templates if such a "big" logo exists (the one bearing the name that we so chose), and to take appropriate action (displaying it instead of the "normal" logo) for any specific piece of text in our database - or to use a completely different kind of graphical component instead.

- With the continuing innovation of modern technology, proprietary formats and broadband access, these specific versions of the logos, being as they are simply attached documents, can be in various other formats instead of just standard image "stills". We could just as easily display Flash or Shockwave animations, video clips, whatever you have at hand, instead of the "big" logos that we illustrate in this article.

Installing the documents and the choice of their names

- We have decided (quite arbitrarily, and you should follow or modify as suits your needs) that the attached documents that will be used as the "big" logos will all be named as "spip_logo": it is this "spip_logo" document that will be displayed on the home page of our site instead of the "normal" article logo entered in the "normal" fashion in the editor's private zone.

We will soon other names later in this exercise to create more delicate effects: but right now, we will decide that all such names will be prefixed with "spip_". (This will allow us, in the normal display of documents attached to an article, to exclude all the ones that have names starting with "spip_". This will mean that our using attached documents as alternative logos will not interfere with the display of other images, a portfolio of photos, for example.)

- For an article published online (so that we can play around with our squelette templates when testing them), we simply attach:

one normal logo; we could, if we wanted, also add a "mouseover" logo which would be automatically displayed when the site visitor moved their mouse over the normal logo;


The "normal" logo: The logo uploaded using the standard method for article logos. Normally this will be an image of modest proportions.

one "attached document" (using the "ATTACH A DOCUMENT" panel); to make things simple, we attach just an ordinary image (JPEG, GIF, PNG); once this document is installed ("uploaded"), we will assign it a name of "spip_logo". There - that's all you need to do in the private zone... SPIP will automatically display this document at the bottom of the page for the article in the private zone, displaying the name of the file as it's stored in the server directory, its title that you just assigned ("spip_logo") and the image's dimensions measured in pixels.


The "spip_logo" document: The only requirement is to assign this document a title of "spip_logo". There is no need to install a preview thumbnail. If this were a multimedia document (Flash, Shockwave...), you will need to manually specify its dimensions in pixels.

- We choose what we will do with this document entitled "spip_logo": it will be displayed on the home page of the site instead of the normal logo for the most recently published article. Doing this will mean that the home page can display a "BIG" image to highlight the "article of the day".

Displaying the "spip_logo" on the site's home page

- We start by inserting a very simple loop to display the most recently published article on the site and its "normal" logo. (In all of the examples which follow, the HTML code has been reduced to its strict minimum for the sake of clarity: you will still need to "wrap it up" nicely in the correct position and framing that suits your graphical charter.)

This very simple loop will display the first article ({0,1}) amongst all ARTICLES in the database, selected in order of publication date ({par date}) from most recent to earliest published ({inverse}). This means that we will definitively be displaying the article most recently published on the site. Inside that loop, we display the logo of the article followed by the title of the article.

- We said before, that we would like to display the document attached to the article that has a name of "spip_logo" instead of the normal logo. In that case then, the code becomes:

The BOUCLE_logo_article_of_the_day loop selects from the documents attached to that article ({id_article}) the one that is named "spip_logo" ({titre=spip_logo}). Inside that loop, we request the display of that attached document using (#EMBED_DOCUMENT).

The usage of #EMBED_DOCUMENT inside squelette templates makes it possible to directly insert the document into the page using the standard loop mechanism. SPIP takes care of creating the corresponding code for the images or other multimedia files (depending on the type of the file that has been attached and embedded).

- Once inconvenience: if the article does not have an attached document titled "spip_logo", then the code above will only display the title. So we will then make another modification, which will allows the display of the "normal" logo for the article if in fact that article does not have a specific attached document nominated for this purpose. Attention: once you've understood this concept, there aren't any other subtleties to learn to achieve all of the effects detailed further below...

We have simply added the call to the "normal" logo (#LOGO_ARTICLE) as the alternative text (the code located just before the closing of a loop, that will be displayed if the loop does not return any results itself - in this case, that will be when there isn't any document attached to the article that bears the title of "spip_logo").

So we have obtained the result we were looking for:
- if there is an attached document linked to the article to which we have assigned the title "spip_logo", then it will be directly displayed;
- otherwise, it will be the "normal" logo that will be displayed.

Excluding these specific documents form the normal display of attached documents

In the articles template, we display the attached articles using the BOUCLE_documents_joints, which is constructed with the following criteria applied to it:

This calls the DOCUMENTS linked to this article ({id_article}), which are definitely attached documents and not just images ({mode=document}) and which have not already been displayed inside the text of the article by using the shortcut ({doublons}).

We modify this code to prevent the display, inside of this loop (which is a kind of document "portfolio"), of any documents that have a title starting with "spip_" (we do not want to display here the "BIG" logo that is used on the site's homepage):

The {titre!==^spip\_} criteria is a regular expression, the syntax of which has been very strictly formalised. It selects the documents that have a title which does not match the regular expression (the !== means "not matching the regular expression"): the first characters (the ^ symbol is used to denote the start of the text string) are "spip" followed by "_" (in regular expressions, we are required to use an "escape" character in order to specify the literal "_" by using the carat just beforehand, this "\_", since the "_" character plays a special role in regular expression syntax).

This criteria then selects attached documents with a title that does not start with "spip_".

The demonstration of the general principle is now finished, and you've now got the key ingredients necessary for you to work with on your own site. The examples that follow are simply some additional variants on the theme.

Always display a big logo at the top of the page

I have decided, once again quite arbitrarily, that there should always be a big image displayed at the top of the page for my articles. This is a graphical layout choice all of my own: in order to ensure some graphical consistency to my site, I'm going to display a large format version of an image linked to the article up at the top of the page (a variation on the "big" logo principle above), and if the article doesn't have one of its own assigned, then I will use a "default" image that I have stored elsewhere on my site.

- Still using the same principle: I attach a document to my article and assign it the title of "spip_top". (To make sure that the document does not display in the "portfolio" generated by the preceding BOUCLE_documents_joints loop, I have selected a different title that starts with "spip_".)

In my articles template, I simply display this document at the top of the page with this:

As in the previous example, I display the document linked to the article for this page which has a title of "spip_top". Too easy.

- As with the earlier example, I would like to display the article logo instead of that document doesn't exist for this article:

- But this still isn't quite the desired result. I insist, for reasons of graphical consistency, to make sure that I always have a big image in the predetermined image dimensions.

So I'm going to create some substitution images (still quite arbitrary on my part), for use in the event that an article doesn't have any image of its own at all. These images that I create meet the graphical demands that I have stipulated (e.g. they have the same dimensions as the documents that I normally use for the "spip_top" image).

So somewhere on my site, I've create a section to host such substitution documents "in bulk". I need to activate the use of documents linked to sections/rubriques. (I could also create an article which hosts all these documents, and then not need to activate the availability of attaching documents to sections. But in the end, the code wouldn't really be much different.) Assuming that this section was number 18 (a number which SPIP automatically assigns when the section is created). I then install all of my substitution (or default) documents into this section number 18. In this case, there's no use giving each of these "bulk" documents any title.

In order to randomly call a document stored in this section, all I need to do use the criteria shown below:

(Attention: the {par hasard} criteria does not mean that the image selected will necessarily be a different one each time that the page is visited, only that it will be selected at random each time that the page is actually recalculated.)

We need to take care that the site navigation does not include section 19, which does not need to shown to site visitors at all. The criteria {id_rubrique!=18} will take care of that for us.

- To complete the installation of our mechanism, we need to insert this loop displaying the randomly selected section 18 substitution document as the alternative text in our BOUCLE_doc_top loop (instead of the #LOGO_ARTICLE):

<BOUCLE_doc_top(DOCUMENTS){id_article}{titre=spip_top}> #EMBED_DOCUMENT </BOUCLE_doc_top> <BOUCLE_doc_substitution(DOCUMENTS){id_rubrique=18}{0,1}{par hasard}> #EMBED_DOCUMENT </BOUCLE_doc_substitution> <//B_doc_top>

Displaying a graphical title

Still using the same principle, we are now going to display a graphical version of the article's title. This involves an image that has been created using a graphical design programme, which uses the article's title shown with a particularly carefully selected typographical layout (shadow effects, colour gradients, fancy fonts...).

- We will state that this will be a attached document linked to the article that we will always name "spip_title".

- To call this document, at the location where the #TITRE of the article would normally be displayed, we will include a now familiar looking loop instead:

<BOUCLE_doc_title(DOCUMENTS){id_article}{titre=spip_title}> #EMBED_DOCUMENT </BOUCLE_doc_title>

Note again that this method not only allows us to use an image to display the title, but we could also use a Flash animation or a video clip... In such cases, you will need to specify manually what the pixel dimensions of your article are supposed to be.

- So let's finish of the mechanism: if there is no attached document bearing the title of "spip_title", then we need to display the necessary information as standard ordinary HTML text:

<BOUCLE_doc_title(DOCUMENTS){id_article}{titre=spip_title}> #EMBED_DOCUMENT </BOUCLE_doc_title> [<div>(#SURTITRE|majuscules)</div>] <div><font size=6>#TITRE</font></div> [<div>(#SOUSTITRE|majuscules)</div>] <br>[(#DATE|nom_jour)] [(#DATE|affdate)]</p> <//B_doc_title>

* * *

We'd like to mention here one last advantage to this kind of method...

It makes it possible to radically alter the graphical interface of your site again later at any time you choose. You won't need to manually delete all these documents named as "spip_top", "spip_title"..., all you need to do is create new squelette templates that just simply don't call them at all.

For example, if the "spip_top" documents have been previously all created with a width of 450 pixels, and the new graphical interface requires images with a width of 600 pixels instead, then you don't need to modify all of your "spip_top" images one by one - you can just assign a new name for the replacement images, and install the new versions of the replacement documents at your own pace and name them "spip_large" instead. During the transition, there won't be any glaring graphical inconsistencies from one article page to another.

The more adventurous readers might even imagine all sorts of tests for the document type ({extension=...}) or their size ({largeur=...}, {hauteur=...}) (no PHP necessary) to compile interfaces that respond to these tests (e.g. a certain graphical interface to use if "spip_top" has a 450 pixel width, and another if it has a 600 pixel width...).

SPIP 1.6

merce — 2010-08-19T14:49:36Z

La nova versió «oficial» d'SPIP és la 1.6.

Podeu descarregar SPIP-1.6 a l'adreça habitual http://rezo.net/spip-dev/DISTRIB/

ACTUALITZACIÓ

L'actualització es pot fer a partir de qualsevol versió anterior d'SPIP.

Si utilitzeu habitualment la instal·lació automàtica, en tindreu prou llençant el fitxer spip_loader.php3 des del vostre navegador i seguir les instruccions que s'hi mostren.

Si feu servir la instal·lació manual a partir d'un arxiu descarregat des de l'URL de més amunt, haureu de:

Escollir un arxiu: el format només depèn de vosaltres, els fitxers, en el seu interior, són idèntics; fixeu-vos que si teniu una connexió lenta, podeu escollir una versió monolingüe (l'arxiu porta llavors el sufixe del codi de la llengua: per exemple "-fr" pel francès).

Descomprimir l'arxiu que heu escollit.

Enviar els fitxer per FTP al vostre lloc Web (esborrant eventualment els fitxers anteriors: abans, però, penseu a fer una còpia de seguretat dels vostres esquelets, per si falla o dóna errors la manipulació errònia).

Atenció: estigueu atents a no esborrar involuntàriament el contingut del directori IMG/ ja que aquest conté totes les imatges i els documents adjunts del vostre lloc!

Aneu, amb el vostre navegador, a ecrire/ i seguiu les instruccions (haureu de crear un fitxer o directori particular a dins d'ecrire/data/ i després deixeu que SPIP faci l'actualització de la vostra base de dades).

I... això és tot!

Remarques importants (i habituals):

- Abans podeu fer una còpia de seguretat de la vostra base de dades; sapigueu no obstant que normalment no tindreu necessitat de fer-la servir ja que SPIP s'encarrega ell sol de l'actualització de la vostra base de dades. Per altra banda, aquesta salvaguarda no es podrà restaurar sense danys sobre una versió més recent que la vostra versió actual; per tant, només es pot utilitzar com a últim recurs!

- Sobretot, NO BUIDEU LA VOSTRA BASE DE DADES ABANS DE FER L'ACTUALITZACIÓ. (L'error és clàssic, alguns imaginen, erròniament, que fa falta buidar la base de dades i, a continuació, restaurar la còpia de seguretat).

DOCUMENTACIÓ

La documentació s'ha actualitzat; suposa dos articles nous:
- La gestió de les dates
- Les llengües d'SPIP

ESPAI PRIVAT MULTILINGÜE

És el canvi més gros a SPIP després de la versió 1.5: l'espai privat, l'ajuda en línia i una petita part de l'espai públic (és a dir, els formularis gestionats per SPIP) a partir d'ara estan disponibles en diverses llengües.

Durant la instal·lació d'SPIP, podreu escollir una llengua per la visualització de la interfície. Aquesta llengua també serà adoptada com a "llengua per defecte" del vostre lloc. És aquest reglatge el que determinarà:

la llengua amb la que es mostraran els formularis de l'espai públic (formularis de cerca, de comentaris als fòrums, d'identificació per l'espai privat, etc.)
les regles aplicades pel motor tipogràfic (només el francès i l'esperanto suporten la correcció tipogràfica francesa completa)

No us preocupeu, podeu canviar aquesta configuració més endavant en qualsevol moment, a la configuració del lloc i dins de la categoria "opcions avançades". A més, cada redactor o administrador pot, independentment de la resta, modificar la llengua utilitzada per la interfície quan visita l'espai privat. També podeu acollir comunitats de redactors / administradors de llengües diverses.

PARTICIPAR

Hi ha altres llengües en preparació, i si voleu participar en l'esforç de la traducció, podeu posar-vos en contacte amb la llista spip-trad@rezo.net

Si voleu parlar d'SPIP en una de les llengües ja integrades, hem posat en funcionament llistes específiques, així com llocs de referència: la seva adreça és spip-xx@rezo.net i http://www.uzine.net/spip-xx (on xx s'ha de substituir pel codi de la llengua en qüestió). A vegades el "lloc de referència" només proposa la llista: això vol dir que tot està encara construint-se.

COMENTARI IMPORTANT: probablement és preferible començar, durant una nova instal·lació, per anar a la configuració avançada per tal d'escollir el joc de caràcters 'utf-8' més que el tradicional i antiquat 'iso-8859-1'.

Són suportats diversos jocs de caràcters corrents, sobretot utf-8, iso-8859-1, iso-8859-15, windows-1251 (ciríl·lic); la sindicació també és totalment compatible d'un lloc a un altre independentment dels jocs de caràcters escollits.

MOTOR DE CERCA

- Funcions de transcripció multilingüe: en la mesura del possible els caràcters accentuats o no occidentals són traduïts en els seus "equivalents" (no accentuats, fonètics...) ; la precisió de la transcripció depèn en part de la configuració de PHP, pels jocs de caràcters no integrats a SPIP.

D'aquesta manera una paraula en ciríl·lic s'indexarà en la seva forma de transcripció en ASCII, (per exemple : "teoreticheskaya"). La cerca donarà resultats tan de la forma original de la paraula com de la forma transcrita. De fet és una generalització del mecanisme que permetia ja fer cerques en francès, alemany, (etc.) sense haver d'escriure els accents.

- Quan la llengua del lloc és 'vi' (vietnamita), la transcripció és més complexa: els accents són codificats per xifres, i la cerca també es pot fer tant a partir de paraules escrites amb tots els accents com a partir de la transcripció clàssica (a^.) o spip (a65)...

- El guió baix (underscore) ja no és considerat com un separador de paraules, sinó com un caràcter alfabètic (documentació informàtica).

- A partir d'ara es poden indexar les sigles de dues lletres i més, incloent-hi també aquelles que contenen xifres (G8, CNT...). Una sigla és una paraula que no té cap lletra minúscula.

- Per raó d'aquestes millores, l'actualització d'SPIP activa excepcionalment que es torni a indexar completament tot el vostre lloc (si el motor de cerca està activat).

UNA CORRECCIÓ IMPORTANT

- Modificació del funcionament del $dossier_squelettes, per tornar-lo més àgil i compatible amb : a partir d'ara SPIP cerca, en ordre, dossier_squelettes/fond=10.html, després dossier_squelettes/fond-8.html (remuntant la jerarquia de les seccions10, 8, etc. cap a l'arrel), després dossier_squelettes/fond.html, després ./fond.html a l'arrel del lloc, després ./fond-dist.html

Pels , SPIP mira si el fitxer dossier_squelette/fichier.php3 existeix (i l'inclou si és el cas); i sinó inclou ./fichier.php3 (sense verificar necessàriament la seva existènica).

MINIATURES AUTOMÀTIQUES

- La generació automàtica de miniatures (es pot activar des de la configuració del lloc, a dins la categoria "opcions avançades") a partir d'ara és compatible amb més sistemes, i les miniatures generades tenen més qualitat (és aconsellable utilitzar PHP 4.3 o superior si volem tenir uns resultats més òptims).

SINDICACIÓ

- La sindicació dels llocs referenciats accepta un nombre més gran de formats de «backends», i reconeix més informacions a l'interior d'aquests (compatibilitat amb els formats RSS 0.91, 1.0, 2.0, i recuperació de dates i autors segons els diversos formats)

- Els fitxers de sindicació generats per SPIP (backend.php3 pels articles, backend-breves.php3 per les breus) són més complerts, contenen sobretot la data exacta de publicació dels "ítems" sindicats.

GESTIÓ DE DATES

- L'etiqueta #DATE_NOUVEAUTES permet publicar la data del darrer enviament de correu electrònic presentant les novetats.

- correcció de l'error dels criteris {age} i {age_relatif}; aquests permeten a partir d'ara distingir dos articles publicats el mateix dia (noció de «precedent» de «següent»)

- introducció de criteris {jour_relatif}, {mois_relatif} i {annee_relatif}, com extensió de l'{age_relatif}, però arrodonit al dia, al mes i a l'any (cosa que permet fer a partir d'ara un bucle per «tots els articles del mes de març del 2003» [especialment dedicat als amants dels weblogs])

- neteja de la data passada a dins de l'URL: 2003, 2003/01, però també a partir de PHP3.0.12 (utilització de la funció strtotime), date=-1year, date=1march1970, etc.

- #DATE es pot utilitzar a fora dels bucles (context o URL)

En resum, i utilitzant hàbilment les etiquetes , actualment estan permeses totes les manipulacions sobre les dates. A partir d'ara, tots els criteris de data permeten comparar les date_redac entre elles o amb la data passada en URL (afegir _redac al final)

ACCESSIBILITAT DE L'ESPAI PRIVAT

Hem afegit una colla de dreceres de teclat a l'espai privat, per tal de facilitar la navegació pels sistemes no gràfics. Totes aquestes tecles són generades pel navegador i el sistema d'explotació: és a dir, que les heu d'utilitzar, si el vostre sistema ho permet, combinant-les amb «Alt», «Ctrl» o «Pomme»... Us toca a vosaltres provar-ho.

Resum de les dreceres:

- Les tecles 1, 2, ... 9, 0 activen les diferents entrades dels menús de navegació (les dues rengleres d'icones al capdamunt de la pantalla). Com a conseqüència del número limitat de xifres disponibles, només les primeres icones de la segona filera són accessibles d'aquesta manera;)
(NB : si esteu en un teclat azerty, no oblideu utilitzar a més la tecla shift, o passar a través del teclat numèric)
- La tecla S salta directament a la columna «de la dreta», qui presenta el contingut útil de la pàgina en curs (útil amb els sistemes amb la parla per no enumerar totes les tries de navegació de la columna de l'esquerre i dels menús d'icones)
- La tecla R salta directament a la casella de cerca (nota: no oblideu que aquesta casella només està disponible si s'utilitza la interfície completa), cosa que us permet cercar ràpidament un contingut (teclegeu Ctrl R, i després el text a cercar, i premeu la tecla Enter)
- Les tecles A, B, C, etc. permeten saltar a cadascun dels «blocs de visualització» presents a la pàgina (un «bloc» és, per exemple, una llista d'articles, un formulari...). El número de tecles disponibles d'aquesta manera depèn del número de blocs.

PETITS AFEGITS I CORRECCIONS

- propre() és una mica més compatible amb les normes HTML modernes

- Una nova variable $ligne_horizontale permet personalitzar la línia

- Atenció, els subtítols canvien en referència a l'històric: per trobar l'estil antic, cal que personalitzeu $debut_intertitre i $fin_intertitre

- Nou filtre «|sinon»: [(#TEXTE|sinon{"pas de texte"})] mostra el text; si està buit, mostra «pas de texte».

- Noves etiquetes #LOGO_AUTEUR_NORMAL i #LOGO_AUTEUR_SURVOL

- Al menú «afegir un document des del directori upload», els noms dels arxius es mostren per odre alfabètic; a més, els subdirectoris instal·lats eventualment a upload/ es tenen en compte.

- el fitxer engines-list.ini s'ha desplaçat a dins de ecrire/ i anomenat de nou com engines-list.txt: si l'heu modificat, alerta a posar les vostres correccions al nou fitxer: l'antic es suprimirà.

- el fitxer inc_meta_cache.php3 passa a ecrire/data/ (permet eventualment assegurar un funcionament normal d'SPIP mentre s'està treballant en el directori ecrire/)

- El criteri {branche} està suportat oficialment

- Afegit de nous tipus de documents autoritzats

- Canvi d'estratègia en ?var_recherche=toto: només s'afegeixen a dins dels URLs en el sí dels bucles {recherche} (i no a dins de tota la pàgina). Per tant, ja no cal definir-los a dins dels inc-urls... (si teniu un inc-urls... personalitzat [diferent del 'standard' o 'html'], és aconsellable revisar-lo tot suprimint la part que s'ocupa de var_recherche).

- Error: a partir d'ara es pot utilitzar #POINTS pels llocs referenciats

- Error: supressió dels fòrums adjunts quan s'elimina un lloc referenciat

- Error: no acceptar canvis de nom o correu electrònic en els fòrums amb subscripció

- Error: miniatures no suprimides a la supressió d'un document

- Error: les peticions amb correu electrònic únic no funcionen

- Pedaç allotjament-discount

* * *

Per consultar la llista de novetats a partir de les versions anteriors, mireu la secció Evolució i actualitzacions.

Extending SPIP

Mark — 2010-08-19T14:07:27Z

If you're thinking about extending SPIP and specifically intend to contribute to the kernel, there are a few salient points to consider:: SPIP is a tool already used by thousands of people, it has a history and a planned road map, and is a widely collaborative project with a global audience. Certain choices have been made, not always easily, but which have led to an overall consistency in the code, which makes moving forward a much simpler task. Whenever an earlier choice reveals itself to be clearly incompatible with a new technology that would be useful to integrate, a refactoring of the code is commenced but which may take several months to complete, entailing a prolonged inconsistency until it's done. It's obvious why such decisions should be avoided where possible, and accept that occasionally a new rule will be violated, with the refactoring of that section still not having been completed. It's also true that even if programming styles vary a little from one place to another, an overall internally coherent system is in constant evolution, and a useful and widely used software is not derived from religious application of some sainted procedures, but results from organic growth from a lively and open community.

Organisation of the code sources

Since version 1.9 was released, it has been made possible to modify SPIP's behaviour without altering its kernel code, principally due to the use of the access paths defined by the SPIP_PATH global constant. All SPIP extensions should use this mechanism so that integration testing can be detachable from the system as a whole by simply redefining that access path, with the SPIP core distribution essentially being read only. If you are convinced that a certain desired behaviour can not be achieved using this mechanism, please discuss your requirements and thoughts before proceeding through the spip-dev discussion list.

Contributions to SPIP should always be described with an article on Spip-Contrib, and their constituent contents made available as documents attached to that article, or (and even better) stored in the spip-zone which provides a Subversion code server provisioned by Trac.

In order to extend SPIP in this way, it is necessary to fully understand how the various directories nominated in the SPIP path are organised and the roles played by the files assigned to each of these directories. This is the purpose of this article, but you might well also benefit from reading the "release notes" article describing the SPIP path system that was issued when SPIP 1.9 was initially released.

The root directory of the SPIP distribution essentially contains:

- a file called spip.php, aliased as index.php, to handle backwards compatibility with prior versions, and which loads up the ecrire/inc_version.php initialisation file, and then immediately passing control on to the main script: ecrire/public.php;

- a directory called ecrire which contains only files that can be interpreted on the server side (PHP and SQL);

- one or more (depending on the version) directories containing files that can be interpreted on the client side (HTML, JavaScript, style sheets, images in various formats) as well as the formatting templates known as squelettes. These squelettes/templates are interpreted on both server and client sides: these are files compiled in a MIME format, and supplemented with SPIP directives which are processed on the server side in order to send the client a text file that is purely MIME (normally HTML, but also RSS, SVG, ICS, etc).

- four directories which are empty upon installation, which will contain the temporary and permanent data necessary for maintaining the web site.

The roles of the prive and squelettes-dist directories and their sub-directories

These folders contain the files that determine the presentation of SPIP's output, for the private and public zones respectively. Prior to SPIP 2.0, these two directories were one and the same, and were then named as dist. They contain a large number of sub-directories, summaries of which are detailed here below:

directory role

/ contains the squelette templates. The template files are suffixed with .html for historical reasons but this does not imply anything about their contents. You can supply any file without that extension as the page parameter for the URL of a SPIP site and it will be used just like a squelette template that did have the extension.
This directory also contains the stylesheets (with the .css extension) defining the default styling for the pages

formulaires/ contains the html section of the dynamic tags, form templates which use PHP code stored in the ecrire/balise directory

icones_barre/ contains the images used to illustrate the typographic toolbar in the private zone

images/ images used in the private zone

javascript/ JavaScript libraries (jQuery, typographical toolbar, ...)

modeles/ squelette templates that can be called using the #MODELE tag or with shortcuts in the form of

polices/ the fonts that can be used with typographical (textual) images

vignettes/ standard thumbnails for the types of document that can be associated with an article

The roles of the ecrire directory and its sub-directories

The ecrire directory contains several sub-directories which contain the PHP files defining the functions and sometimes, but quite rarely, triggering certain initialisation tasks when they are loaded (these exceptions will soon be eliminated). The files located in the main directory which are the most important ones to understand as regards making your own contributions to SPIP are: inc_version.php, public.php and index.php.

The ecrire/inc_version.php file initialises the global constants and variables necessary for SPIP's normal operations, specifically those that ensure its portability over the various supporting platforms. Fairly early on when it is loaded, it includes the inc/utils.php file where all of the essential SPIP files are defined, and then another file not part of the standard SPIP distribution called mes_options.php, which is used to modify the initialisation task without needing to modify the inc_version.php file. In particular, it is possible in this customised file to call the spip_initialisation function in order to define the data directories and thereby enable you to run several distinct SPIP web sites using a single distribution kernel (the standard call to this function, further down in the inc_version.php file, will automatically be neutralised so that it does not run twice). Another essential SPIP function is find_in_path, which uses the access paths as well as include_spip which relies on find_in_path, and charger_fonction which relies on include_spip. All of SPIP's files are loaded by one of these two functions.

The ecrire/public.php file, called by spip.php, has the critical role of provisioning the public web pages required whenever an HTTP request contains the page parameter (with URL rewriting possibly intervening beforehand). This script then applies the squelette template which bears the same name as that parameter. It returns the HTTP headers and calculated contents, handles any possible errors that may occur, and runs the background tasks using the internal SPIP cron function. Contributing to the SPIP public zone therefore consists of supplying new templates, and also possibly additional stylesheet rules and images that they may reference.

The other role of the ecrire/public.php directory concerns cases where the HTTP requests includes the action argument. It then applies the charger_fonction function with the v value of that action parameter. This application will cause the loading of the file with the same name in the action directory, which has a principal function named action_v_dist which is thereby invoked. These scripts principally perform write operations (to the database or to an external file) and generally do not return any results, thereby escaping any issues with page formatting.

The index.php file is the central access file to the forms in the private zone. It authenticates the site visitor, initialise that user's personal data, and applied the charger_fonction function to the v value of the exec parameter. This application will cause the loading of the file with the same name from the execdirectory, which will have a principal function called exec_v_dist which is then invoked. That function then has the task to deliver all of the output data, includes the HTTP headers. It is therefore possible to extend SPIP simply by adding a PHP file into a sub-directory named exec that is listed in the list of directories stored in the SPIP_PATH global variable.

The exec directory only contains the files that define the functions directly callable using the exec URL parameter. The PHP code in these files must never attempt to write to the database (the few remaining exceptions to this rule are currently being eliminated). On the other hand, it frequently accesses the database in read mode in order to verify the rights of the requester and to determine the data to be displayed. Looking at SPIP as a Model-View-Controller architecture, the exec files perform the role of the Controller. Looking at SPIP using Lisp's (Print(Eval(Read))) architecture, it performs the Read segment. Eventually, this directory ought to become a directory of squelette templates. It is requested of new contributions to SPIP to consider this objective when the contributions are being coded.

The action directory, which has already been mentioned, essentially contains all of the scripts that access the database in write mode. Looking at SPIP as a Model-View-Controller architecture, the action files fill the role of the Model. From the point of view of the Lisp (Print(Eval(Read))) architecture, it is the Eval section. Here again, any contributions to SPIP consist of writing such scripts and calling them from the forms built using the generer_action_auteur function, which ensures the security access of those scripts, which itself will invoke the securiser_action function to verify the access rights of the requester. This architecture enables the calculation of these rights only when constructing the forms that call the write mode access scripts: rather than repeatedly recalculating all of these rights, these scripts simply verify that the key passed amongst the arguments is the same as that which they recalculated based on the other arguments, the requester's identity, and a random value that is periodically refreshed. These scripts do not generally return any results, so therefore also don't generally return any HTML code nor any call to the echo function (any remaining exceptions are currently being eliminated). On the other hand, they are often called with an HTTP parameter called redirect, which requests a redirection which will then be automatically triggered by public.php, which itself will retrn an HTTP 204 status message if that parameter is absent. In the case of forms constructed with the ajax_action_auteur function, that redirection leads to the script of the same name in the exec directory. This second script often only entails loaded the file with the same name from the inc directory, calling that file's main function, and returning that function's result to the client via the ajax_retour function. In this way it is very easy to extend SPIP in AJAX mode using this pre-constructed infrastructure.

The inc directory, the one with the most content, essentially contains the functions used to build the private zone pages returned to the client, these functions which ought to later become filters used by the exec files when those files are all squelette templates. Looking at SPIP as a Model-View-Controller architecture, the inc files fill the role of the View. From the point of view of the Lisp (Print(Eval(Read))) architecture, it is the Print section. Nevertheless, this directory also contains a lot of functions that are actually more relevant to the Control function and which should therefore really be reorganised. Most of the inc files are loaded via the charger_fonction function, and in time this will be the case for all of them. None of the functions in this directory are supposed to use echo. Contributions to SPIP are requested to respect these rules from now on.

The install directly only contains the functions necessary for SPIP installation. Each step may be overloaded or supplemented by others, the principal function exec/install.php using this directory following the same principle as ecrire/index.php does with the exec directory.

The urls directory contains the files that each define the same set of URL rewriting functions. Based on the numeric identifiers in a given table in the database, these are functions which calculate a name which is easier to read and write than the direct PHP script call that is actually executed by the HTTP server for that numeric index and that table. Here again, you only need to add a file into this directory to obtain a new set of rewrite rules, the name of which will be displayed for selection in the private zone configuration panel that deals with the different types of URLs (prior to SPIP 2.0, this panel did not exist in the private zone and these files were referenced instead by the type_urls global variable).

The lang directory only contains data files, PHP arrays which supply the language specific translations for the "idioms" used for all of SPIP's hosted languages, and for all the arguments that the _T function (defined in inc/utils.php) is expected to be passed. These files are loaded only by the inc/lang.php functions. By translating the reference files suffixed with fr into similarly named files suffixed with another language code is all that is required to make SPIP available in another language.

The charset directory also only contains data files, PHP arrays used to convert from one character encoding to another (utf, iso, ascii, html entities, etc). They are exclusively read by the functions in inc/charsets.php. Once again, just by adding a file into the directory makes it possible to declare a new encoding to SPIP, but SPIP actually already offers all encodings in common use, so adding such a file will be a rare event indeed.

The base directory contains the interface functions between PHP and the SQL servers that SPIP can access. In particular, the generic abstract_sql.php file contains the functions that should be used to communicate the the SQL servers, thereby avoiding any need to use the PHP database functions which would negatively impact the portability of any code. There should, of course, not be any MIME code in this directory.

The req directory contains the effective ports of SPIP's virtual SQL server to the real world servers (MySQL, PG) and similar others (SQLite).

The balise directory contains the PHP files associated with SPIP's dynamic tags. Their names are synonymous with the squelettes-dist/formulaires squelette template. Supplementing the SPIP public zone with a form F consists of creating an F.html file in your SPIP_PATH and an F.php file in a balise sub-directory of your SPIP_PATH. The role of the PHP file is to accept the entries requested by this form, and to possible redisplay it to request corrections to invalid data entries. It is without doubt the type of contribution to the public zone which is the most difficult to provision, since the accompanying mechanism requires twoo PHP execution passes, with different roles that must be understood completely. Before this mechanism existed, the strategy for developing forms consisted of writing templates that contained their own PHP instructions. it is still possible to do this, but the result won't be very efficient since the results will never be cached; and this would still not allow you to avoid understanding the two PHP passes intrinsic to the operation.

The public directory contains the squelette template compiler. This is a fairly complicated section of code, but since SPIP 1.8, 1.8.1 it has benefited from a programming interface which makes the compiler totally extendable without requiring the coder to understand all of its internal details. The least incomplete description of it is provided in French here.

The lib directory contains the library sub-directories developed outside the scope of SPIP which upon which it depends. At present, the only one supplied systematically is the safehtml library which supplies security tools for scriptable pages. To contribute to this section, please contact the separate dedicated site.

Final point: most of the SPIP files are used via the charger_fonction function, which loads an file and calls the function of the same name which ought to be defined in that file. This means that the PHP file name must be composed only of characters which are acceptable in a PHP function name: this means that you should avoid using the minus sign, the period sign, etc.

Programming rules

SPIP was started at a time when PHP automatically transformed global variables in to HTTP parameters. This suicidal style of programming was completely abandoned by PHP4. SPIP has followed a parallel evolution, but a little delayed in time. Even though the current code does not necessarily follow the rules that follow below, it is requested of all contributors that they respect them from here on in, without expecting SPIP to have completely abandoned the practice itself in a few odd locations. As a guide, carefully examining the ecrire/articles.php file is useful as it is currently the closest adherent to the specifications detailed below.

- Try to opt for writing functions. The philosophy of open source software is to be used in a maximum of different contexts, and so the code should be written as much as possible with a view to being reused outside of its initial development environment. Writing functions will no reference to any global variables and not executing any calls to echo or print will guarantee a silent loading and calls that do not have any undesirable side effects.

- Avoid the use of global variables wherever possible. They are responsible for numerous security holes and make the code virtually impossible to be reused. Alternatives to them are:

— constants, which have the advantage of indicating to the reader that their values will not change throughout the entire execution of the script;

— static variables, which have the advantage of indicating to the reader that they relate to values of long life duration but are only of interest to the function that declares them.

- Write code that does not generate any error or warning in error_reporting(E_ALL) mode. This makes it easier to update in the event of unintentionally undefined variables. If you really need to run the code outside of this mode, use the @ construct and limit the problematic code as much as possible, and opt for an error message into the log files using the spip_log function.

- Comment on the context, not the text. It serves nothing to paraphrase the names of its variables and functions, nor the PHP functions described in its manual: comments such as loop through the table of values before a foreach statement only serve to uselessly increase the size of the files. On the other hand, it's a good idea to indicate the argument types (PHP being a dynamically typed language, they can often be difficult to ascertain implicitly) and their presumed properties upon entry to the function (e.g. not null). When a difficult bug is corrected or expected, explain why the initial code was incorrect in order to avoid any later code refactoring reintroducing the fault under the guise of an attempt to optimise the code in question. Finally, SPIP has been developed in French, so try to avoid using terms not generally available in French dictionaries so that it is easier for non-native French speakers to understand what you have written (i.e. avoid local slang).

- Name your functions and variables sensibly. The organisation of the SPIP code is originally based on breaking it up into dedicated directories with strict naming conventions, but we still try to avoid inconsistencies like including multilingualism within a given name. Functions within the same file will tend to have a common prefix or suffix that is inspired by the name of the file itself.

- Test your code on a maximum number of different configurations. do not overlook that SPIP should work on all its supported platforms, both in terms of servers and clients. You will necessarily have several browsers deployed on your machine, and you should test your code using at least two of them. Wherever possible, try it out on several different hosts as well. Whenever a particular platform requires unusual coding techniques, detail them explicitly, specifying the date and version number the test was executed.

Presentation and coding rules

SPIP is concerned with the typographical quality of the pages that it sends out to HTTP clients, so it is therefore also concerned with the quality of its own internal files. It is highly recommended that you respect the rules below, which in any case are fairly standard in modern programming anyway.

Presentation

- The text of the functions should be of short line lengths, ideally less than the width of a standard screen, so that their entire structure is visible at a glance.

- The text of the functions should be indented, each block contained inside a pair of braces must be indented b an additional tab mark, a system which should be applied recursively for increasing logical depths.

- Use only the tab character for indenting, which allows the viewer to choose whatever equivalent space indenting that equates to according to the options set in their own text editor.

- Whenever a PHP instruction takes up several lines, insert a blank line both before and after it to make ti stand out clearly;

- HTML fragments, whether they be (or ?>) transitions of PHP expressions must for complete XHTML blocks: avoid inserting an opening tag at the start of a function and closing it at the end, which will not make it easy to relocate that pair should the need arise.
Typography - When using parentheses or brackets, avoid using spaces after the opening one and before the closing one. - Within PHP expressions, leave a space before and after any binary operators (+, =, *, AND, ...). - Any (!, ...) unitary operators must be immediately adjacent to the parameter to which they apply. - By convention, when calling a function, we do not insert any space before the opening parenthesis: "f($x)" and not "f ($x)". On the other hand, and to clearly distinguish the difference, we do insert a space before the parenthesis when it relates to a control structure integrated into the language"if (!$x)" and not "if(!$x)". - Any commas and semi-colons are followed by but not preceded by a blank space.
The overall structure of SPIP Mark — 2010-08-18T13:25:49Z SPIP is a CMS truly quite unique in its field. Beyond the underlying system that defines it as being "data driven" by using its famous BOUCLE (loop) constructs, it has always emphasised and facilitated methods for individual webmasters to "customise" it's operations and presentation to meet the particular needs and tastes of any given site. This is primarily accomplished by creating one's own squelettes (templates), by enabling the attachment of special PHP code fragments, and by overloading the basic functions in the "core" code (the default function xxx_dist() naming mechanism that we will address again later). Version 1.9 introduced an additional mechanism, that of administrator selected plugins. These are the results of wanting to open up SPIP to new additional functionalities without needing to over-burden the SPIP kernel (aka the core). In fact, the current tendency is to actually work on minimising this core code by transferring optional features out to the plugins. The SPIP 2.0 version has indeed been reduced and delivered with a collection of basic plugins that the user/administrator can activate as and when necessary. For example, there's a debate running as to whether news items should no longer be in the core but handed off to an optional plugin - many sites, in fact, have no need or call for news items at all, so it would be preferable to lighten the base system for those who do not actually need them. Already previously, SPIP 1.9 had completely reorganised the directory structures that it employed in order to clearly separate elements according to their life expectancies, according to whether they were modifiable or not, and according to whether their appearance is standardised or customised relative to the core code or to the site's own standards. One of the other targeted objectives with that release was to open up the possibility of sharing the kernel core amongst several sites, allowing them to share a common code base that no longer then needed to be duplicated. First up here, we will look at this new directory structure, in terms of what belongs to SPIP, what belongs to a specific site, what remains constant and what continually changes. In the following discussion, a number of directories have been renamed and/or deleted and/or added, so don't panic if you see something that you are unfamiliar with - check the version of SPIP that you are working with, and you should see that everything is, in fact, correctly structured as it ought to be. Distribution The site root The root folder of a SPIP site has been completely emptied and now practically only contains the index.php which redirects to spip.php, which is now the unique point of entry to the public HTML site (of course, RSS feeds are still available, but they are XML and not HTML). inc-public.php3 is a ghost file that has been retained for backwards compatibility. .htaccess is an optional file, essentially used for rewriting URLs. win_png.htc [1] onwards and rien.gif to ensure png transparencies under most versions of MSIE. ecrire/ This folder now contains all of the files that can be interpreted by the server (PHP and MySQL) for both the private and public (in the public/ sub-directory) display screens. The name of this folder (in French - "to write") is historical, because it was previously the location which contained the code for writing and modifying the site content. Paradoxically, it has now become a folder which never changes, as no one ever writes into it. In a standard installation, it only contains the scripts delivered with the standard distribution, and it is almost sacrosanct against any modifications of any kind whatsoever. Its index.php script is the entry point into ecrire/, the private zone of the site, aka the "back-end". dist/ [2] This folder contains all of the files deliverable to the client (HTML, JavaScript, stylesheets, images in various formats) as well as the format templating files commonly known in SPIP as squelettes, or templates or template files for English speakers. These squelettes are interpreted by the server in order to send pure MIME text content out to clients (most of the time this is HTML, but may also be RSS, SVG... maybe even JS or some other esoteric content format that you may require). These are the standard such templates delivered with the SPIP distribution, which you theoretically MAY modify, but which you really OUGHT NOT to as your changes would be lost if you ever upgrade your SPIP system - it is vastly preferred to copy them into a new directory that you should create in the root directory named squelettes/, and then modify them there instead, and they will automatically override the default ones in the dist/ directory. They are included in the standard distribution so that you at least have something to display any content that you insert in the SPIP database, even if you haven't done any template customising work yet. oo/ [3] This folder supplies the "accessibility" mode for SPIP, being a text only based presentation. It essentially only contains an index that links into the standard system. Adaptation config/ This folder, created at system installation time, contains the database connection script: connect.php and the script that assigns protections on files created by the server: chmod.php. It is also where the universal site options are specified in a file (that you must create yourself) called : mes_options.php [4] IMG/ This folder contains all of the document originals (in their original full sizes) associated with the site. It is subdivided into sub-folders for each possible type of document. Upon installation, it only contains the test documents used for constructing images so that the administrator can observe the available functionalities of the server when setting up the site configuration in the private zone. squelettes/ This is where all of the files: scripts, images, form... particular to the site are stored, and its structure exactly follows that of ecrire/ or dist/. For example, to redefine the the home page sommaire for the site, you need to copy and then modify the sommaire.html file form the dist/ directory. In addition, and of particular importance, the mes_fonctions.php script should be located here if/when you create one, so that it can be loaded on every recalculation of every page. Also note that you may create additional xxx_fonctions.php files which will be only loaded when the corresponding xxx page is requested (e.g. sommaire_fonctions.php) for the home page. When the system is first installed, you have no customisations of any kind, so this folder does not exist - you need to create it yourself when you start customising the SPIP installation. At this point, bear in mind that in recent versions of SPIP there are plugins available that supply their own entire sets of squelette templates, which are maintained within the plugin directory structure, and which case you will not see the squelettes/ directory appear even though the public and private zones seem to clearly indicate that the site has been customised. plugins/ This folder, which also needs to be created manually after system installation, is used to store all of the sub-folders for each of the plugins. For example, the crayons plugin is stored in the plugins/crayons/ folder. Temporary files local/ This contains all of the (re-)calculable files based on the site's data and uploaded or referenced documents. It essentially normally consists of caches of reduced images. There are also some other calculated caches stored here by certain plugins such as "coloration_code". This folder may will be emptied, without any other impact than requiring its contents to be recalculated at such time as they are requested by site visitors. tmp/ This folder is used to store all of the site's normal temporary files, such as the template caches, session data, log files, etc. It is also home to the dump/ sub-directory which stores all the database backups generated by the standard SPIP backup procedures provided in the private zone. This folder, too, can be emptied at any time without affecting the site, but BE WARNED that you may also be deleting your only backups. Accordingly, proceed with caution and copy at least one back-up to your local machine before deleting all of those stored on the server. [1] deleted from version SPIP 2.0 [2] From SPIP 2.0 onwards, this folder has been renamed as squelettes-dist/. Please read: Updating from 1 .9 .x to 2 .0 .x. [3] deleted starting from version SPIP 2.0 [4] Please read: The mes_options.php file See also: Extending SPIP #BIO Mark, Teddy — 2010-08-18T09:41:32Z Used in a loop (AUTEURS), the tag #BIO will show the biography of the author. The biography for any given author is the information entered in the administration zone just for that author. An author may only update his/her own details, except for site administrators, who can update the details for anyone. - Tags / BOUCLE(AUTEURS), #BIO The general principle Mark — 2010-08-18T09:38:15Z All of the content for a site managed with SPIP is stored in a MySQL database. In order to present these data to visitors of the site, it is then necessary to execute an operation which consists of reading those data, organising them, formatting them, and finally displaying an HTML page within a Web browser. Unless using an advanced content management system like SPIP, such operations can be quite unwieldy: - you need to know how to programme in PHP and MySQL, and to code "routines" that are relatively complex; - you must integrate these routines with complex HTML page formatting that is temperamental at best; - you need to develop an interface so that authorised users can modify the contents in the database; - you need to take account of performance issues: constantly using PHP and MySQL code consumes a lot of system resources, slows down visits to the site, and in extreme cases, can make your web server actually crash. SPIP offers a complete solution to overcome these difficulties and more: - formatting for the site is accomplished using HTML-formatted template files known as squelettes (French for skeletons), which contain simplified instructions indicating where and how to position the data extracted from the database on to the HTML page; - a cache system used to store every page and thereby avoid making so many calls to the database for every site visitor. This not only reduces the load on the server, but response time is much quicker, and the site remains visible even if the MySQL database for the site actually crashes; - a "private zone" that is used by administrators and editors to manage all the data used for the site. One basic template file for each type of page A key benefit and limitation of an automated publishing system is defining a template file that can, for instance, be used for publishing all of the articles for a site. Indicated in this template is information on where to position the title, the text, the navigation links, etc. for the article, and we then allow the system to generate each individual article's page by automatically positioning the corresponding data from the database into the correct positions as intended by the webmaster. This automated system then enables a consistent presentation across the site... and this also constitutes a limitation: it is unable to define a different interface for every single page (but we will see later that SPIP does nonetheless offer a considerable amount of flexibility to overcome this restriction). When you install SPIP, a set of such templates is offered to you by default. This set is stored in the dist/ directory at the root of your site. As soon as you modify these templates to your own needs, or if you want to install another such set of templates, it's a good idea to create a new directory called squelettes/ at the same hierarchy level in your site, which will take priority over the standard ones, and which you can then leave in place as they were. For more details about this subject, please read the article Where do I put the template files for my site? . Whenever a visitor requests a page called http://example.org/spip.php?article3437, SPIP will go to look for a template file called "article.html". SPIP therefore is basing its decision on which template to use based on the URL address itself: L'URL will call the template file named spip.php?article3437 article.html spip.php?rubrique143 rubrique.html spip.php?mot12 mot.html spip.php?auteur5 auteur.html spip.php?site364 site.html With two special cases of note: - The URL spip.php calls the sommaire.html template to generate and present the site's home page. - The URL spip.php?page=abcd calls the abcd.html template. In other words, you can create entire sets of templates which have not been pre-built into the system and name them however you choose to. This syntax is also used for other kinds of page like the site map or for returning results from a search request, for example: spip.php?page=plan, spip.php?page=recherche&recherche=squirrel. Whenever SPIP calls a template, it passes a context as "arguments" to that template In addition, you can see above that the URL can supply other elements than just the name of the template. For example, in spip.php?article3437, the number of the article requested is (3437); and in spip.php?page=recherche&recherche=squirrel, the word searched for is (squirrel). This constitutes what we call a "context", i.e. one or more "environment variables" that SPIP will provide to the template so that they can be used in the composition of the page. In fact, the article.html template needs to know the number of the requested article so it can go find the matching title, text and other fields from the database. In the same fashion, the recherche.html template needs to know what words the visitor has entered to search for in the database records. Within the URL, the environment variables appear after the "?" character. When there are several such variables, they are separated by "&" characters. So the 'URL spip.php?page=recherche&recherche=squirrel has two variables: page and recherche, to which two respective values are assigned: "recherche" and "squirrel". In the case of spip.php?article5159, SPIP has merely simplified the URL syntax which actually corresponds to : spip.php?page=article&id_article=5159 (and yes, you can try it yourself if you want!). It therefore also has two variables: page, with the value "article", and id_article with the value "5159". These variables enable SPIP to use the data from article 5159 in the database within the article.html template. How the cache works - made simple Simplified schematic of the cache system SPIP looks to see if there is a page corresponding to the requested URL already stored in the CACHE If the page exists, SPIP checks that it's not too old.If the page is too old, SPIP recalculates it using the appropriate template and data from the MySQL database. It then updates the CACHE before returning that same file back to the user. If the page is recent enough, that cached page is immediately returned back to the user. If the page doesn't exist in the cache at all, then it is calculated from the template and MySQL database. It is then also stored in the CACHE before being returned to the requesting user. When the next visit to that page is made, if the duration between the two visits is sufficiently short, then the recently calculated page stored in the /CACHE is returned without needing to recalculate everything and wait for the database. If the database has actually crashed, then it is always the cached page which is returned, if it has "expired". Note. We can see here that each page for the site is cached individually, and each recalculation is provoked by a visit to the site. There is generally not any overall recalculation of all pages in a single hit on a regular timed basis (this kind of "major process" often tends to overload the server and sometimes even make it crash). By default, a page is considered as expired after a period of 3600 seconds. [1] The .html file Within SPIP, we call the .html files our squelettes (French for skeleton, and commonly referred to in English as a "template" or "template file"). These are what describe the graphical interface of your site pages, in conjunction with any internal or external, default or customised CSS stylesheet rules that you may specify. These files are coded directly in HTML, to which are added several instructions telling SPIP where it should position any elements that it extracts from the database (of the style: "put the title here", "show the list of articles with the same topic here", etc.). The instructions for including and positioning such elements are coded in a special language, which is the subject of this entire on-line user manual. This language, as powerful as it may be, also constitutes the only real major hurdle for learning how to use SPIP. What's more, most of the keywords used in this language are derived from the French language, which can make learning SPIP additionally more tricky for those not conversant with that language [2]. "Yet another language?" Ah, yes, you will need to learn a new language. Fortunately, its structure is not very complicated, and it can be used to construct complex interfaces very quickly. In comparison to PHP and MySQL, you will see that you do, in fact, gain a lot of time since the SPIP language is actually a lot simpler than those other two. It is therefore a markup language, being one that employs tags quite similar to those in HTML itself. Note. In the same way that one can learn HTML by taking inspiration from the source code of sites that one visits, you can also inspire yourself from the templates used by other sites that work under SPIP. All you need to do is find the matching ".html" template file. For example, perhaps you would like to see the template for the articles that you are currently viewing now (view the source code to reveal the text of the template). A different interface for the same site In addition to the default page formatting for the various types of content on the site (rubrique.html for sections, article.html for articles, breve.html for news items etc.), you are able to create different templates for particular sections of the site and any content belonging to those sections. You only need to create some new .html template files and name them according to the following principle: - A different interface for a section and its contents (sub-sections, articles, new items, etc.): just append the template file name in question with "-number" (a hyphen followed by the number of that section). For example, suppose you create a rubrique-60.html file, then it will be applied to section n°60 and to all of its sub-sections instead of the standard rubrique.html. A template file named article-60.html will apply to all articles in section n°60. If that section contains any sub-sections, then any articles in those sub-sections will also adopt the new template. The same would apply for news items in the section with breve-60.html... and so on and so forth. - An interface for just one single section. (SPIP 1.3) You can also create an interface for one section, but not for its sub-sections. This is done by naming the file with an equal sign instead of the hyphen, i.e. "=number". For example, creating a file called rubrique=60.html will make it apply only to section n°60 and not to its sub-sections. The same principle applies to article=60.html, breve=60.html, etc. These templates are applied to the contents of section n°60 but not to the contents of any of its sub-sections, which will simply use the default formatting instead. - An interface for each language supported in a multi-lingual site. This is done by including the two-character language code in the file name just before the .html suffix, e.g. article.en.html, article.fr.html, article.de.html, etc. For full details on this, please read the article on Internationalizing Templates. Important note: the number indicated is ALWAYS that of the relevant section. Templates named article-60.html or article=60.html do not relate to article n°60 but to articles contained in section n°60. What can we put in the .html template files The .html files are essentially just "text" files, supplemented with instructions for inserting elements from the database. SPIP only analyses and process these instructions for inserting database elements (coded in SPIP's own special language); SPIP otherwise completely ignores whatever else is in these files which does not match any of its own known instructions. The files are therefore essentially HTML. You determine the page formatting, the HTML version you wish to employ, etc. You can obviously include CSS stylesheets, but also JavaScript, Flash... in summary: anything that you would normally put on a Web page anyway. But you can just as easily (and it's all just text anyway) create XML files instead (e.g. the backend.html generates XML for RSS feeds). Even more original: all of the pages returned to the visitor are extracted from the CACHE by a page written in PHP. You may therefore include PHP instructions within your template files, which will be executed when the visit is actually made. Used judiciously, this possibility opens up enormous flexibility to SPIP, so that you can augment it (perhaps by adding a counter, for example) or even alter certain page formatting elements depending on the data extracted from the database. [1] Once you understand SPIP's language syntax, you can change this period as you wish using the #CACHE tag. [2] There are a handful of operators and functions also available in English, but they really are the exception This article is only valid for SPIP 1.9 and later. For prior versions, please read the archived version.

L'URL	will call the template file named
`spip.php?article3437`	`article.html`
`spip.php?rubrique143`	`rubrique.html`
`spip.php?mot12`	`mot.html`
`spip.php?auteur5`	`auteur.html`
`spip.php?site364`	`site.html`

directory	role
`/`	contains the squelette templates. The template files are suffixed with `.html` for historical reasons but this does not imply anything about their contents. You can supply any file without that extension as the `page` parameter for the URL of a SPIP site and it will be used just like a squelette template that did have the extension. This directory also contains the stylesheets (with the `.css` extension) defining the default styling for the pages
`formulaires/`	contains the html section of the dynamic tags, form templates which use PHP code stored in the `ecrire/balise` directory
`icones_barre/`	contains the images used to illustrate the typographic toolbar in the private zone
`images/`	images used in the private zone
`javascript/`	JavaScript libraries (jQuery, typographical toolbar, ...)
`modeles/`	squelette templates that can be called using the #MODELE tag or with shortcuts in the form of
`polices/`	the fonts that can be used with typographical (textual) images
`vignettes/`	standard thumbnails for the types of document that can be associated with an article