Easy web content management with Pivot

Introduction

Pivot is a small CMS/blogging tool written in PHP which doesn't require a database server since data are saved in flat files (under pivot/db/standard-X/, formatted by PHP's serialize() ).

Besides its normal goal as blogging tool, you can also use it to manage a regular, brochure web site, provided your needs are basic, eg. Pivot won't allow you to easily link to another document on the site (must look up the relative URL of the target document such as entry_123.html, and type its reference in the source document, etc.)

Setup

Download and unzip the package in your web server's htdocs/ directory. The Pivot code should be located in its own subdirectory, eg. htdocs/pivot/, so that once its files are generated, your blog lives in the root of the site above, ie. htdocs/
cd /htdocs

chmod 777 pivot
chmod 777 pivot/archives
chmod 777 pivot/images
chmod 777 pivot/pivot/pv_cfg_settings.php
chmod 777 pivot/pivot/pv_cfg_weblogs.php
chmod 777 pivot/pivot/templates
chmod 777 pivot/pivot/templates/*
chmod 777 pivot/pivot/db
chmod 777 pivot/pivot/db/*
chmod 777 pivot/pivot/db/standard-00000/*

Aim your browser at http://localhost/pivot/, and create an admin account (the password must be at least 6 characters long)
Log on as admin
In the bar at the top of the page, click on "Rebuild the Frontpage(s)"
Aim at http://localhost/, and you'll see a test blog

Post-install customizing

Once you're logged on as admin, here are the different steps to take to customize your site through the Administration section on the left-side:

Users: In addition to the all-powerful admin account that you created to log on, it's a good idea to create a separate account with only editing rights. At this point, since you haven't created your own categories yet, don't check the default categories to which this new user can post. We'll do that next.
Categories: Create categories to which entries can be set, and make sure the new user you just added is allowed to post to such and such categories
Templates: Edit the templates to suit your site, especially pivot_template.css, frontpage_template.html, entrypage_template.html, and _sub_entry_standard.html. Make sure frontpage_template.htm includes [[subweblog:XXX]] where entries for each subweblog will be included, as Pivot parses this file to make a list of subweblogs your site offers
Weblogs: You can just modify the existing Test weblog. Stuff worth changing:

Weblog name and tag line ("Payoff")
Front page (Index) and Filename from PHP to HTML extension and Live Entries to No if you want Pivot to create static HTML instead of rebuilding them every time a user hits your site
Archive Type to No if you don't want to archive any entry
On Page 2, you are presented with the sub-weblog entries found in the frontpage_template.html template, ie. all the [[subweblog:XXX]] bits, and for each subweblog, you must tell Pivot which categories of entries will be included in each of these subweblogs. This is useful when a given article must be included in different subweblogs (eg. an article about an actor belongs to the Actor subweblog and the Movies subweblog)
Still on Page 2, change the Number of Entries if you want more entries to remain on the frontpage (useful if you use Pivot to handle a document site instead of a blog, so that entries don't fall off)
On Page 3, Generate Feeds to No if you don't want to provide an RSS feed

Maintenance: Finally, you can rebuild the site through this option at the bottom

The links at the top are shortcuts to often-used actions like rebuilding the frontpage or index. The full navigator bar is located on the left. Clicking on any section displays a list of the sub-items it contains. You can always go back to the main page by clicking on the Overview item.

Wishes

Support for XMLRPC API's (Blogger, metaWeblog, etc.) so I can use a dedicated app like wBloggar to manage entries. Alternatively, a basic set of functions that could be called from an XMLRPC-capable dedicated application would do
Extra tags

[[last_edited]], so that an entry that has been edited since its initial posting should move up in a subweblog. Currently, the editor has to change the "Created on" item manually to force it to move up
[[start_ulr]]: [[home]] includes the home page. Needed if CSS located at root of blog, but blog not located at root of site (so "/" isn't OK)

Make archiving optional, so that all the entries for a given category are displayed (currently, just use a big number for Number of Entries" to make sure all the entries are displayed at all times)
Allow setting a different charset for an entry (eg. if the page contains Japanese, use ShiftJIS, while Latin1 for entries in Western languages)
One-click generation of the static version of a blog, and upload by FTP to a bare web server
Easy import from either plain, self-contained HTML, or popular CMS
Option to use SQLite to enhance performance so as to use Pivot even for high-demand sites (since PHP5 comes with support for SQLite, it should be standard on web servers in the near future)
Can run without having to CHMOD 777 (hosting web servers often won't allow this: SITE CHMOD 777 blog -> 500 SITE not understood")
Search feature to locate an entry (not fun if you have hundreds of entries)
optionally, entries should be named after their titles, so as to generate significant URL's (eg. either entry_123.html or pivot.html)

Q&A

How can I copy/paste some JavaScript without having it messed up?

In the Administration section, click on Users, select the user account you are currently using to edit the entry, and set "User WYSIWYG editor" to No.
Next, in the Configuration section, set "Use WYSIWYG editor" to No, and "Default Text Processing" to None.
Copy/paste the JS in the edit box, and save
Put the settings back to what they were originally so that regular entries that you create or modify next are handled correctly by Pivot.

How can I add a picture in a entry?

First, you must upload the picture through the Manage Media sections, or directly through the yellow icon when creating an entry. Next, add this kind of tag in the entry:

[[image:mypic.jpg::center:0]]

How to include HTML in entries?

Particularly useful for tables... The only way seems to be to first design the page in a WYSIWYG HTML editor, launch a browser that supports WYSIWYG editing such as IE or Firefox (Opera 7.54 doesn't), and copy/paste the HTML.

How to customize singlepermalink?

If you wish that links to entries in the home page not be underlined, you can add a new section in the CSS file, and edit the snippet_singlepermalink() in pivot\modules\module_snippets.php, ie:

A.nolink {

text-decoration: none;

}

and...

function snippet_singlepermalink($text, $title) {

[...]

$code = sprintf("<a class='nolink' href=\"%s%s\" title=\"%s\">%s</a>",

What does the label [[date]] refer to? What's the difference with [[diffdate]]?

Looks like both refer to the date the entry was originally created, except the former includes the hour:minute and is shown in every entry, not just the first one for the day. The format can be set in a blog's "Date display settings" section.

One entry is not showing up in the front page

If this entry was created manually (eg. by using a home-made import script), make sure the serialized output is correct. Pay special attention to the number of characters indicating how long the string that follows is. Otherwise, Pivot will silently ignore the whole entry. If you did make a mistake, corrected it, but Pivot still ignores this entry, delete the index file (eg. index-standard-00000.php), and rebuild them.

How come only ten entries are listed in a subweblog?

By default, Pivot only displays the ten most recent entries. Edit your blog, and change the default to a higher number for the ad hoc subweblog ("Number of Entries").

Is there a dedicated Windows application to edit entries?

As of April 2004, Pivot doesn't support the standard XMLRPC-based blogging API's, but since Pivot is developped in PHP, this often-asked feature will most likely be available in the not-too-far future.

An alternative route is to write a dedicated application that includes a partial or fully WYSIWYG HTML editor to generate basic, standard HTML, remove any unneeded stuff through regular expressions (ie. when using the free dhtmled.ocx ActiveX control that comes with IE 5, you'll get the usual FONT sections spread generously throughout the document), and upload the cleaned-out HTML file to the Pivot site through FTP. Next, a PHP script that would be part of the Pivot distribution will call PHP's serialize() to turn HTML into an entry under htdocs\pivot\db\standard-00000\, which you will finally turn into a Pivot-generated article by clicking on the familiar "Rebuild All File" in the Administration section.

Importing existing pages

From MovableType

http://www.movabletype.org/docs/mtimport.html

http://www.pivotlog.net/help/help_converting_movabletype.php

From GreyMatter

Place all the entries of GM in the pivot/conversion folder. These are the files that are called '00002207.cgi', or something like that.
Go to the maintenance screen in Pivot, and choose 'Greymatter Conversion', at the bottom. You have to be logged in as the user admin to do this.
Fill in the form values of the screen you see, and you should be good to go.

From standard HTML pages

Pivot author Bob den Otter told me that the format for the entries is actually the output of the PHP serialize() function. So the simplest solution to import regular, stand-alone HTML pages into Pivot is to write a PHP script that use regex and serialize() to generate entries under htdocs\pivot\db\standard-00000\ .

http://fr2.php.net/serialize
http://www.google.fr/search?q=php+serialize&ie=UTF-8&oe=UTF-8&hl=fr&btnG=Recherche+Google

<?php

$data = array("2004-03-29-21-28","date","publish_date");

$serialized_data = serialize($data);

echo $serialized_data . "<p>\n";

$serialized_data='a:2:{i:0;s:12:"introduction";i:1;s:107:"If you can read this, <a title="The Pivot Site" href="http://www.pivotlog.net/">Pivot</a> is working.. Yay!";}';

$postData = unserialize($serialized_data);

foreach ($postData as $value) {

echo $value . "<p>\n";

}

Here's some code to generate entries:

<?php

echo " "; //Just to avoid err 200

for ($iCounter=21;$iCounter<25;$iCounter++) {

//how to format 00000.php?

$fp = fopen ("000" . $iCounter . ".php", "w");

fputs ($fp, 'a:13:{s:4:"code";i:' . $iCounter . ';s:12:"introduction";s:8:"my intro";s:4:"body";s:9:"Entry #' . $iCounter . '";s:8:"category";a:1:{i:0;s:10:"mycategory";}s:4:"date";s:16:"2004-04-10-16-20";s:12:"publish_date";s:16:"2004-04-10-16-20";s:9:"edit_date";s:16:"2004-04-10-16-20";s:5:"title";s:9:"Title #' . $iCounter . '";s:8:"subtitle";s:11:"my keywords";s:4:"user";s:5:"admin";s:10:"convert_lb";s:1:"0";s:6:"status";s:7:"publish";s:14:"allow_comments";s:1:"1";}');

fclose($fp);

}

Transplating a site from one host to another

htdocs\pivot\db\standard-00000\ : all <number>.php (index-standard-00000.php can be regenerated)
htdocs\pivot\langs\pvl_eng.php (if you added labels; needless to say, choose the ad hoc language for your site)
htdocs\pivot\templates\
htdocs\pivot\pv_cfg_settings.php
htdocs\pivot\pv_cfg_weblogs.php
htdocs\images (if you uploaded any)
Administration | Maintenance | Rebuild the Index
Administration | Maintenance | Rebuild All Files
Administration | Maintenance | Rebuild the Frontpage(s)

Keeping home and work hosts in sync

Just copy/paste "htdocs\pivot\db\standard-00000\.." : all <number>.php (index-standard-00000.php can be regenerated), and hit the relevant links in Administration | Maintenance

How to add a category?

Add a new category through Administration | Categories | Create new category, eg. "mycategory" (no spaces allowed)
Administration | Templates, and add a new part in the frontpage_template.html template, eg.

<div class="block">
<h3>My Category</h3><p>
[[subweblog:mycat]]</p>
</div>
Administration | Weblogs, select the blog, go on to page 2, and tell Pivot to which subweblogs you wish to assign the entries set to this new category. In this example, the "mycat" subweblog will contain entries that belong to the "mycategory" category
Add a new entry, and set its category to "mycategory"

How to forbid archiving?

Ie. in case you want all the entries to be shown on the front page at all times, edit the blog's properties, go to the "Archive Settings" section, and set "Archive type" to "No archives".

How to generate a static Pivot site, and upload it to a basic web server?

Here's how to upload a site to a web server that doesn't have PHP (besides, pages usually show faster since the PHP interpreter doesn't have to parse them every time):

Administration | Weblogs

Edit Weblog 'Fred's Shack'

URL to Weblog (test to see if Pivot handles this correctly)
Front page (Index) (PHP -> HTML
Frontpage Path (CHECK in case you don't want the pivot/ directory to be located right below the blog front page)

Entry Settings

Live entries = No
Filename (PHP->HTML)

Archive Settings

Index File
Archive Path

Administration | Templates: Open all the templates, and check URL's (eg. where the CSS file is located, etc.)
Administration | Configuration

File Upload

File Upload Path

Administration | Maintenance (CHECK Don't know which one's are required to update the whole thing in one go)

Rebuild the Frontpage(s)
Rebuild All Files
Rebuild the Index
Rebuild the Search Index

Using your favorite FTP client, upload everything that is located at the root level of your site (ie. index.html, the CSS file, and all the entry_ files), along with the images/ subdirectory, and possibly the archives/ subdirectory (CHECK if you chose to enable archiving)

How to move the most recently edited entries to the top?

When using Pivot to manage articles as opposed to stuff that isn't supposed to change past their original publishing, you probably want the articles that you recently re-edited to be moved up in the page. As of March 2004, the only way apparently is to change the "Created on" tag manually. This is a bit strange since an entry also has a Last edited on" item.

How to add "description" and "keywords" meta tags?

When editing an entry, switch to "Extended View", and add a Subtitle item, which we'll use for keywords, while we'll reuse the Title item to fill the description tag:

What's the difference between a subweblog and a category?

A subweblog is really a container for entries in a weblog. An entry can be marked to belong to more than one category, since it often happens that an entry might be of interest to different people, with different interests.

So, subweblog = set of entries from one or more categories. This lets you share entries among different sections of your blog, or even among multiple Pivot blogs that live on the same server. It also has the advantage of not requiring your knowing in which sections of the site an entry will be published, since all you do is tell Pivot to which categories you want this new entry to belong to. Pivot will do the rest.

How to display a list of articles, with their TITLE as link to the article?

Edit _sub_entry_standard.html this way:

<h2>[[singlepermalink:%title%:Permanent link to entry '%title%']]</h2>

How to supress the dashes that underline an H2 section?

Edit the CSS file.

In the Links section, how to change the title?

Edit pivot\langs\pvl_eng.php (choose the ad hoc language if you are using a different language than English.)

Can't upload a picture

You need the GD2 package so PHP can generated thumbnails. Newer PHP installations should include GD2.

Can't create thumbnail

could not make thumbnail
http://www.mijnkopthee.nl/remote/crop.php?img=http://localhost%2Fimages%2F10214.jpg&dx=0&dy=0&sx=1&sy=45&dw=172.65306122449&dh=180&sw=47&sh=49&ext=jpg

Saving an entry as draft

... equivalent to CTRL-S while writing a piece

Adding tables

Go to the Configuration section, scroll down to Various Settings, and set "Use Wysiwyg editor" to "No" and "Default Text Processing" to "None". Next, go to "My Info > Edit my personal settings", set "Use Wysiwyg editor:" to NO. I'm not sure if it's needed, but you might want to log out, stop and restart IE, and log back in. Now, although you can still see the WYSIWYG toolbar in IE, but when using its controls, you'll see the HTML tags show on the screen, so you can add all the HTML you want :-)

Pivot as a desktop CMS

Since Pivot is such a light tool, you might want to combine it with a light web server such as Abyss so as to provide users with a very simple to use CMS solution. Here's how to set things up:

Install PHP. Unless you know PHP well, you might prefere the Windows installer version of the tarball (I assume the former installs system stuff)
Install Abyss, and set it up to support PHP. Use the familiar <?php phpinfo(); ?> script to check that PHP is up and running
Proceed as above

How to backup data

Just download all the files under pivot/db and pivot/templates/ .

"To take advantage of the backup functionality, you will need the Zlib library. If you don't have this, pivot will work just fine, but you will have to do backups manually."

Temp

(WYSIWYG provided only for IE5+ or possibly Mozilla)

Php version 4.2.0, without register_globals..

Php runs in safe mode..

Home