Adding a File Format

Since version [SPIP 1.4], it has been possible to attach documents to articles — and, optionally, to sections.

For security reasons SPIP doesn’t allow all types of documents to be attached. As a matter of fact, allowing any documents to be uploaded on a distant server from a Web interface can cause very serious security problems. That’s why a list of authorized documents exists, and for the very same reason SPIP doesn’t offer any interface for this list to be edited.

The panel for adding a document

As you can see the list of authorized documents is rather well-stocked as it is, and we regularly add items to it according to users’ requirements as expressed on mailing-lists.

Before going any further, please read the following carefully:

-  Attaching documents is potentially dangerous, and can introduce a huge security breach into your site. Some file formats — executable from the server — must not be allowed on any account. In particular, never allow PHP-format files to be uploaded (.php, .php3...) as your site’s security would be totally threatened. You’re strongly advised to get informed before adding file formats.

-  We purposefully chose not to install an interface into SPIP enabling the list of authorized formats to be edited, with a view to keep that possiblity for advanced users only. To achieve any changes you need to use a database management tool, such as phpMyAdmin. Tackling a database manually without using the interface and any SPIP built-in functions can potentially wreck your site. If you aren’t sure what you are about, don’t try it. If you’re familiar with phpMyAdmin don’t use it on SPIP’s database. In any case, make a back-up of your SPIP site before doing any manual changes in the database.

-  By the way, there’s no point in adding a file format unless visitors on your site can use, i.e. “read” that type of file. Having a file format requiring an extremely specialised software on a site aimed at the general public doesn’t make much sense. Before adding a file format, you’d better check if it can be used by your visitors — namely, with a software or a plug-in that are free and easy to install, and on any OS (Mac, Linux, PC, etc).

-  For all these reasons, we want to lay the stress on the fact that such changes mustn’t be made unless you are fully aware of the consequences. If you’re in doubt get information from experts, or even simpler, convert your files into an authorized and widely-used format. For instance, a FrameMaker document can’t be read directly by all; if it’s a mere matter of distributing its content you can just as well make it a PDF file which can be directly downloaded by your visitors rather than try adding the “FrameMaker” format to the SPIP-authorized file list.

* *

To add a file format to the authorized list on your SPIP-driven site use phpMyAdmin, or any equivalent software which give you access to database management.

A new item must be added to the spip_types_documents table.

A few types of documents in phpMyAdmin

-  id_type. Leave this field blank. id_type numbering is done automatically by mySQL.

-  titre (title). Here enter the name of the file format — usually that of the programme which is required to create and read that format. Give it a short name, as generic as possible. On a multilingual site don’t use a language-specific name — for example, a German-speaking visitor won’t probably be attracted by a file described as a “vector image for Illustrator”, while “Adobe Illustrator” will be a more effective description.

-  descriptif. This field is to be left empty as it isn’t used.

-  extension. This is the most important field. This is where the file extension is entered. For example, “rm” and “ram” for Real file formats, “pdf” for an Acrobat PDF file, “gif” for a GIF format file, etc.

-  mime_type. This field is to be left empty as it isn’t used.

-  inclus (inset). You have the choice between “embed”, “non” (no), “image”. Be careful in choosing the setting as it affects the way your site works and the way this type of file will be “fetched” in your site to be displayed to visitors:

  • “non”: this file format can’t be included directly (inside) an HTML page; it can only be displayed through a hypertext link. For example, a PDF file can only be displayed inside an HTML page, and therefore the only way to attach it is to make a hypertext link enabling the file to be opened in a new window — or to be downloaded on the visitor’s hard disk. So for a “pdf” format file “non” must be entered in the inclus field.
  • “embed”: this file format can be directly displayed inside an HTML page where it will be read on a browser extension, such as a plugin. This is the case of most multimedia file formats used on the Web, like Flash, Shockwave, video clips, etc.
  • “image”: describes image formats that are displayed directly in the HTML page without a particular extension being required — to display them, use the HTML <img src=...> markup. You shouldn’t have to add any files of this type as the list provided with SPIP is quite exhaustive. (Note this carefully: some formats concerning images made with “drawing” softwares can’t be displayed directly as “image”, and an extension is required to read them; such formats will therefore be “embed”, or even “non”.)

-  upload. Shows uploading that file format is allowed through SPIP Web interface. “oui” (yes) is therefore selected.

-  maj. This field being automatically managed by SPIP, it must be left blank.

* *

After completing these steps you can create a new icon, i.e. a preview thumbnail, corresponding to that file format. To ensure graphic consistency with the default icons provided with SPIP, the thumbnail size will be approximately set to 48-pixel wide and 52-pixel high.

Any image formats can be used (GIF, PNG, JPG), but it’s best to choose a format allowing background transparency.

-  Your file name will be made up of the following items:

  • extension of the authorized file format;
  • graphic format of the thumbnail (“.gif”, “.png”, etc.);
  • for example, a thumbnail saved in a PNG format, and created for the PDF format will be called “pdf.png”.
  • N.B. names ending in “-dist” are exclusively used for files distributed with SPIP. So don’t use “pdf-dist.png” since it is the one used by SPIP developers. If you use this name your file will be likely to be overwritten on your next SPIP upgrade.

-  This thumbnail can be uploaded by FTP into the /IMG/icones (icons) directory.

Author bealach Published : Updated : 26/10/12

Translations : عربي, català, English, Español, français, italiano, Nederlands