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+ / May 2010 SPIP’s version 2.1.0+ / May 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 ...................................................................... 195 Forms ................................................................................... 227 SQL access.......................................................................... 251 Creating your own plugins.................................................... 301 Examples ............................................................................. 313 Glossary ............................................................................... 319 Index .................................................................................... 323 Table of contents.................................................................. 333 Preface The beginnings of this book date back to 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 participate in 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, it’s not expected 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.0 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 The whole website and its private area are calculated from templates that are composed of static code (mainly HTML) and SPIP elements. These templates are, by default, stored in the directories squelettes-dist and prive. 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 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 transforms these templates into PHP code which it stores in a cache. These cached files are then used to produce the HTML pages — which are cached in their turn — and then returned to each 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 of 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 example, this <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 for its page, and the #TITRE tag is replaced with its title. 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, containing a mixture of HTML, loops and criteria, tags and filters. Its strength is the ability to extract database content using a simple and understandable language. 15 Loops A loop displays some content stored in database. It generates an optimized SQL query that extracts the desired content. The syntax of loops A loop specifies both a database table from which to extract information as well the criteria for selection. <BOUCLE_nom(TABLE){criterion1}{criterion2}> ... for each object ... </BOUCLE_nom> 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. Here, the name is “_nom”. The table is specified either by an alias (written in capital letters) or by the real name of the table (written in upper and lowercase letters as the case may be), for example “spip_articles”. The example uses the “TABLE” alias. The next components of a loop are the criteria, which are written between braces. For example, the criterion {par nom} will sort the results according to the “nom” column of the database table. Example This loop lists all the images on the site. It draws its data from the database using the DOCUMENTS