Entation to Be Used by Developers and Webmasters
Total Page：16
File Type：pdf, Size：1020Kb
Programming with SPIP DOCUMENTATION TO BE USED BY DEVELOPERS AND WEBMASTERS SPIP’s version 2.1.0+ / August 2010 SPIP’s version 2.1.0+ / August 2010 SPIP is both a publication system and a development platform. After a quick tour of SPIP’s features, we will describe how it works and explain how to develop with it using helpful examples wherever possible. This documentation targets webmasters with knowledge of PHP, SQL, HTML, CSS and JavaScript. Contents Preface..................................................................................... 7 Notes about this documentation............................................... 9 Introduction ............................................................................ 11 The templates ........................................................................ 15 Contents of the directories ..................................................... 87 Extending SPIP .................................................................... 101 Functionalities ...................................................................... 197 Forms ................................................................................... 229 SQL access.......................................................................... 253 Creating your own plugins.................................................... 303 Examples ............................................................................. 315 Glossary ............................................................................... 321 Index .................................................................................... 325 Table of contents.................................................................. 335 Preface The beginnings of this book date back to the late 2008. Matthieu was starting his work on this documentation for developers, and said to us: “... whatever we do, let’s do it with an open licence so that other people will be able to take over after I’ve done my part and then take it even further ... perhaps one day it could even be published in hard copy”. A SPIP book with an open licence: a dream nurtured for years was now showing its first signs of taking solid form. The idea had become firmly sounded out and recent new technologies were available to help make it a reality. Anyone who wants to print a book can now find all kinds of simple tools on the internet to help with the task. It’s great to think that at a modest cost you can order a one-off copy of any text. And the feeling when you first receive the printed copy — can you imagine? The first version of this book is coming out in the magical atmosphere of the Troglos meeting, and that is a positive sign. Version 1.0 of the book can be seen as the end of one adventure, but it is also the beginning of another. All the technical elements required are now in place for other books. They only need to be written — on a SPIP site, of course! Add a cover, and send it all to the printer. SPIP SPIP HOORAY! Ben. Notes about this documentation License and rights The fruits of long hours of writing, this documentation is a combination of knowledge from the SPIP community. All of this work is distributed under the open Creative Commons license - Attribution - Share Alike (cc-by-sa). You may use these texts for any purpose whatsoever (including commercial), modify them and redistribute them on the condition that you allow your readers the same rights to share. Continuous improvements This work - still in progress - has been subject to numerous proofreadings but is certainly not guaranteed exempt from any error. Please don’t hesitate to offer improvements or point out mistakes by using the suggestion form available on the documentation internet site (http://programmer.spip.org). You may also discuss the organisation (of the content or technical presentation) and the translations by using the discussion list "spip-programmer" (requires subscription). Write a chapter If you feel motivated by this project, you may offer to write a chapter about a subject that you have mastered, or rework an existing chapter to make it clearer or more complete. We will do our best to accommodate your efforts and support you in such activities. Translations You may also contribute to the translation of this documentation into English or Spanish. The site’s private zone (http://programmer.spip.org) is used for discussing the translations that are currently being prepared. Having said that, we’re not planning to translate the documentation into other languages until such time as the organisation of the various chapters has been stabilised, which might yet take several months. Computer code and properties of languages With the aim of retaining compatibility, the computer code segments which serve as examples only contain ASCII characters. This means, among other things, that you will not find any language diacritic marks in the comments that accompany the examples anywhere in the documentation, a matter normally of considerable importance in French, and almost none in English. Therefore, we ask that you expect such absences to occur and ignore them. Happy reading! Introduction An introduction to SPIP and a presentation of its general principles 11 What is SPIP? SPIP 2.x is a free software package distributed under the GNU/GPL3 licence. Originally a Content Management System, it has gradually become a development platform making it possible to create maintainable and extensible interfaces independently of the structure of the managed data. What can SPIP be used for? SPIP is particularly suitable for websites and portals with regular community contributions, but it can also be used for a blog, a wiki, or a social network. More generally, SPIP can manage the storage and presentation of any data stored in MySQL, Postgres or SQLite databases. Extensions are available which also offer interaction with XML. Requirements and basic description SPIP 2.1 requires PHP version 5.0 or higher and at least 10MB of memory. It also requires a database (MySQL, Postgres or SQLite are supported). The public website (front-office) is visible to all visitors by default, but it can be restricted to certain users, by section, if required. The private interface (back- office) is accessible only to persons authorised to manage the software or site content. The templates (aka squelettes) The whole website and its private area are calculated from templates that are made of static code (mainly HTML) and SPIP elements. These templates are, by default, stored in the squelettes-dist (for the private area) and prive (for the public-facing pages) directories. For example, when a visitor makes a request for the home page, SPIP creates an HTML page based on the template named sommaire.html. Each type of editorial object in SPIP has a default template to display it, such as article.html for articles and rubrique.html for sections (or "rubriques" in French). 12 # Introduction SPIP analyses and compiles these templates into PHP code which it stores in a cache. These cached files are then used to produce the HTML pages — which are themselves also cached — and then returned to the site visitor. Quick overview SPIP transforms templates into static pages. Templates are mainly composed of loops (<BOUCLE>) which select elements, typically sets of records, and tags (#TAG) which display the properties and values of those elements, typically fields from the records or system-wide functions and preconfigured values. List the 5 most recently published articles: <B_art> <ul> <BOUCLE_art(ARTICLES){!par date}{0,5}> <li><a href="#URL_ARTICLE">#TITRE</a></li> </BOUCLE_art> </ul> </B_art> In this first example, the <BOUCLE_art()> loop performs a selection from the ARTICLES table in the database. It sorts the data in reverse chronological order and returns the first five elements. For each article that the loop selects, the #URL_ARTICLE tag is replaced with the URL calculated for that article’s page, and the #TITRE tag is replaced with its title as stored in the database. Typical HTML resulting from this kind of loop: <ul> <li><a href="Recursion">Recursion</a></li> <li><a href="Parameter">Parameter</a></li> <li><a href="Argument">Argument</a></li> <li><a href="Modifying-all-of-your-templates- in">Modifying all of your templates in one hit</a></li> <li><a href="Display-an-authoring-form-if">Display an authoring form, if authorised</a></li> </ul> 13 The templates SPIP generates HTML pages from templates, which each contain a mixture of HTML, SPIP loops and criteria, and SPIP tags and filters. The major strength of SPIP is its ability to easily extract database content using a simple and understandable language. 15 Loops A loop typically displays content retrieved from the database. It generates an optimised SQL query that extracts the desired content. The syntax of loops A loop declares both a database table from which to extract information as well the criteria for selection. <BOUCLE_loopname(TABLE){criterion1}{criterion2}> ... for each object ... </BOUCLE_loopname> Every loop has a name (which must be unique within the template file), this name is used together with the word “BOUCLE” (English: "loop") to mark the start and the end of the loop. In this example, the loop’s name is “_loopname”. The table is specified either by an alias (written in capital letters) or by the real name of the table (matching the case), for example “spip_articles”. The example uses the “TABLE” alias. The next components of a loop are the criteria, each of which are always written enclosed in braces.