Yonodune - 2012-12-13

Welcome to Publicms

Overview

Publicms is a very light CMS, it does not require any database, only php (version >= 5). Combined with a tool like LibreOffice, it provides a very simple way to create static web sites.
The principle is quite simple, once your template theme is defined, just create locally your HTML pages (with your favourite HTML editor), focus only on the content of the pages, then publish them on your site.
If you want to publish documents, you just have to convert them in HTML format (for example with libreoffice html export).
Moreover, Publicms features can be extended with plugin mechanism. Default plugins are provided which allow to list files of a directory, to display images of a directory.

Features

  • Modern page with header, menu, content, news, footer, CSS theme
  • Template theme can be easily created
  • Partial compatibility with GetSimple template theme (http://get-simple.info/extend/all_themes.php)
  • Files can be built locally with any HTML generator tool
  • All relative URLs built locally will be converted automatically to work on the site (subdirectories allowed)
  • Features can be extended with plugins
  • Page can be protected individually (secured area plugin)
  • Files listing and image gallery available (print dir plugin)
  • News support with RSS feeds
  • Publicms can be install in any directory
  • Multi-language site support
  • No database by default
  • Two levels menu available

Install

First Install

  • Download publicms-xx.tgz file on https://sourceforge.net/projects/publicms/
  • Extract publicms-xx.tgz
  • Extract publicms-sample-xx.tgz
  • Extract publicms-core-xx.tgz
  • Upload files on your web sites
    Note that php shall be able to write in tmp directory and cache/compiled directory (so in most case you have to allow write access on these directories for everybody)

Upgrade

  • Download publicms-xx.tgz file on https://sourceforge.net/projects/publicms/
  • Extract publicms-xx.tgz
  • Extract publicms-core-xx.tgz
  • Copy all directories and files extracted from publicms-core-xx directory in your local directory (overwrite files)
  • Upload files on your web sites
    Note that as directory structure has been changed between 0.4 and 0.5 version, you have to move your pages on data/pages.

Site first installation quick start

  1. Upadate header.html, news.html and footer.html with LibreOffice
  2. Create specific html files
  3. Update menu.html and link menu item with your specific html files
  4. Publish all files on the web site (filezilla, ftp, …)
    Directory tree and file description

The root directory contains the following special files :
index.php : PHP main index file
The root directory contains the following special directories :
data : contains all HTML pages
theme : contains the different themes, one directory by theme. Each theme directory shall contain a file named template.php
src : php source files
src/plugins : plugin extensions, all php files in this directory will be loaded as plugin
tmp : directory for generated file (for example RSS news.xml file)
cache/compiled : directory where html files compiled will be store
The data directory contains the following special files :
header.html : shall contain
the title of the site (title of the page),
the Publicms settings (special meta tag in the HTML header)
the web site header
menu.html : shall contain the web site menu list (two level available)
news.html : shall contain the news component (if enabled), the RSS feed xml file will be generated at each update of this file
footer.html : shall contain the web site footer

Build pages

With your favourite HTML editor (LibreOffice is recommended), update special publicms files (header.html, menu.html, news.html and footer.html) and create your specific files in data/pages directory. To link specific files with the main page you have to create links in the menu.html file. If you want to test locally your site (only tree architecture, not theme), load the menu.html file in your navigator and check the different links. All links will be modified in order to work correctly on the web site.
To improve speed, limit the size of your HTML files, so don't embed multimedia data (called them with external links). Note that your HTML files shall be modified to be displayed from the site. It is possible to keep these modification to improve speed, just give write access to php for cache/compiled directory.
Note that the current menu selected is determined from the directory structure. So page_X.html will select pages/menu1.html if page_X.html is placed in a directory pages/menu1 (or a subdirectory).
Remark : with LibreOffice if you don't want to see your identity in the HTML page, go in file>Properties>General and unchecked Apply User data.
It is possible to call directly php code by creating an hyperlink to publicms://php with the php code to execute.

Settings

The Publicms settings shall be set in the html head tag of the header.html file. Each parameters of the setting shall be placed in a meta tag. To edit these parameters you have to select in LibreOffice File>Properties>Specific properties tab.
The following parameters are available :
<meta name="publicms_home_page" content="home.html"> : default home page
 <name="publicms_theme" content="default"> : theme selected, shall be a valid directory in them directory
<meta name="publicms_shortcut_icon" content="images/mysite.ico"> : icon to display
 <meta name="publicms_use_component_news" content="yes|no"> : use or not the news panel component
* <meta name="publicms_use_component_XXX" content="yes|no"> : use or not the XXX component

Moreover, each HTML user page can have the following parameters :

  • <meta name="publicms_add_div_content" content="class_name"> : allows to have a specific appearance for this page, a div tag with the class class_name will be added in the page content
  • <meta name="publicms_menu_page" content="menu.html"> : set a specific menu for the page
  • <meta name="publicms_use_component_news" content="yes|no"> : use or not the news panel component for the page
  • <meta name="publicms_use_component_XXX" content="yes|no"> : use or not the XXX component for the page

RSS support

The RSS file tmp/news_rss.xml is generated when the news.html file is updated. Your RSS link shall point to this file. Note that write shall be enable for the tmp directory.

External theme installation

Unzip the theme in the theme directory and change the theme selected with the meta tag <meta name="publicms_theme" content="default"> of the header.html file (replace default with your theme name).

Multi-language site

If you want multi-language site support, you have to create a directory with your language mnemonic in data directory (example data/fr, data/de, data/it, …). Create header.html, menu.html, new.html and footer.html files localized in these directories and create your specific pages localized.
When the main site url is called, the localized directory is detected automatically from the navigator preferred languages.

Uninstall

To uninstall remove all files.
In some cases, as php run with a different user, it is not possible to remove files generated by php. In this case remove only the data directory and load in the navigator your main site url. A specific clean function will be called to delete php generated files.

Security

We can defined three levels of users :

  • the user used to push files on the site (for example with ftp) : site host user
  • the user used when php script is run (for example www-data) : php user
  • the user used to access files to the site from everywhere * with the navigator : end-user
    The configuration depends on the policy of your site host, so you have first to check what you can do. In most of cases, site host user and php user access are defined with unix permissions, and end-user access are defined with .htaccess file.

The minimum access required is the following :

  • All files and directories shall be only accessible in read by php user except for cache/compiled and tmp directories where write is required
  • The end-user need only to have read access to resources referenced in html files (image, video, audio, css files, …). For all others files read access can be forbidden (php files, html files, ...). So all directories except data and theme can have full access denied and directory indexes shall be disabled.
    As compiled files can be accessed by php user (potential vulnerability), it is possible to disable this feature by removing write access for cache/compiled directory.

Plugin

Overview

Plugin allows to generate HTML content directly from PHP code.
All php files in src/plugins directory will be loaded as plugin.
Each plugin provides a set of function. To call a plugin, you just have to add an hyperlink to publicms://php with the specific php code to call. The code will be executed when the page is loaded.
To disable a plugin, set the constant PLUGIN_NAME_ENABLE, located at the beginning of the plugin file, to false.

Plugin publicms_about

This plugin allows to display several information about publicms (current version, plugins installed, themes installed, …).
PHP function : plugin_publicms_about_get_info();

Plugin getsimple_template_import

This plugin allows to import directly GetSimple themes.
download GetSimple template on http://get-simple.info/extend/all_themes.php
unzip it on the theme directory
change the theme selected with the meta tag <meta name="publicms_theme" content="default"> of the header.html file (replace default with your theme name)
Note that the GetSimple theme support is partial. Indeed, the theme shall no required GetSimple plugin.

Plugin plugin_publicms_print_dir

This plugin allows to print files of a directory or display image gallery.
PHP functions :
- plugin_publicms_print_dir($dir_i, $type_i = "all", $display_i = "list")
- $dir_i : directory relative to index.php dir
- $type_i : “all” print all files, “image” print only images
- $display_i : “list” print file listing, “gallery” print images in the navigator
- plugin_publicms_print_dir_get_zoom("less")
- Insert zoom less link
- plugin_publicms_print_dir_get_zoom("more")
- Insert zoom more link

Plugin plugin_secured_area

This plugin allows to add protections on directories with login and password mechanism.
To add protection :
- go on the page index.php?page_name=admin/admin.html
- choose a directory to protect (all sub directories will be protected)
- Set a user and a password
- Click on protect
Note that the admin directory shall be protected first, for security reasons.
To add a protection on the whole site, set a protection on / directory.
The only way to remove a protection is to delete manually the corresponding file in admin/.protected directory.

Plugin plugin_url_compatibility

This plugin allows redirect some old page name on new page name.
Edit the file data/plugins/url_compatibility.php and set in an array the redirections.
Example
function url_compatibility_get_array() {
// [old URL] = "new URL"
// Redirect old page about.html in pages/about.html
$compat_array_l["about.html"] = "pages/about.html";
return $compat_array_l;
}

Development

Debug

To debug uncomment the line ini_set("display_errors", 1); in the index.php file (remove //).

Add Theme

  • Create a new directory in the theme directory
  • Create the template.php file in this directory
    The following functions are available for dynamic informations :
  • publicms_get_charset()
  • publicms_get_site_name()
  • publicms_get_page_title()
  • publicms_get_html_header()
  • publicms_get_theme_url()
  • publicms_get_page_header_body_attribute()
  • publicms_get_page_header_content()
  • publicms_get_navigation()
  • publicms_get_page_slug(echo_i)
  • publicms_get_main_config_field(fieldName, defaultValue)
    This function returns the value of a main configuration field
  • publicms_get_component(component)
    This function echoes the content of the HTML page * component.html
  • publicms_get_use_component($component_name_i)
    return true if component_name_i shall be used, else false
  • publicms_get_page_content()
    This function echoes the content of the current HTML page
    Note that you can uncomment the line ini_set("display_errors", 1); in the index.php file to debug your theme.

Add Plugin

  • Create the PHP file in the plugin directory
  • Create the PHP function in the file (prefix it with plugin_publicms_)
    // To enable / disable plugin => true false
    define("PLUGIN_MY_PLUGIN_ENABLE", true);
    if (PLUGIN_MY_PLUGIN_ENABLE) {
    function plugin_publicms_my_plugin($context_i)
    {
    // Context can be
    // PLUGIN_STEP_AFTER_PAGE_SET
    echo “My first plugin” . ;
    }
    }
    Called the publicms_register_plugin function in the PHP file
    publicms_register_plugin('publicms_my_plugin', 'plugin_publicms_my_plugin', '0.1', PLUGIN_MY_PLUGIN_ENABLE);
    Insert PHP code in your HTML page to call the plugin
    <?php plugin_publicms_my_plugin(); ?>

Change log core

Version 0.6

Create the PHP file in the plugin directory
Create the PHP function in the file (prefix it with plugin_publicms_)
// To enable / disable plugin => true false
define("PLUGIN_MY_PLUGIN_ENABLE", true);
if (PLUGIN_MY_PLUGIN_ENABLE) {
function plugin_publicms_my_plugin($context_i)
{
// Context can be
// PLUGIN_STEP_AFTER_PAGE_SET
echo “My first plugin” . ;
}
}
Called the publicms_register_plugin function in the PHP file
publicms_register_plugin('publicms_my_plugin', 'plugin_publicms_my_plugin', '0.1', PLUGIN_MY_PLUGIN_ENABLE);
Insert PHP code in your HTML page to call the plugin
<?php plugin_publicms_my_plugin(); ?>

Version 0.5

  • Place all html files in data directory
  • Add support of two level menu
  • Change way to call plugin : directly with a specific hyperlink
  • Change way to find the current activated menu : directly found from the directory tree
  • Add page pre-compilation to improve speed (may be disabled)
  • Add multi-language site support
  • Add a function to remove created files

Version 0.4

  • Add init hook in plugin interface
  • Update plugin interface
  • Add header / page field publicms_use_component_
  • Add page field publicms_menu_page

Version 0.3

  • Add template theme feature
  • Add plugin extension feature
  • Add partial compatibility with GetSimple themes (plugin)
  • Add About plugin to display publicms features

Version 0.2

  • Add RSS support
  • Add publicms_add_div_content setting field to add a specific * div class to a page.
  • Use the charset defined in the header.html file instead of UTF-8.

Version 0.1

Initial version

Change log secured area pluginn

Version 0.3

Update to be compliant with new internal plugin interface

Version 0.2

Update with new directory tree (data directory)

Version 0.1

Initial version

Change log print_dir plugin

Version 0.3

Update to be compliant with new internal plugin interface

Version 0.2

Deny access to directory outside data directory

Version 0.1

Initial version

Change log publicms_about plugin

Version 0.3

Update to be compliant with new internal plugin interface
Print if plugin is enabled or disabled

Version 0.2

Update to be compliant with new internal plugin interface

Version 0.1

Initial version

Change log getsimple_theme_import plugin

Version 0.4

Update to be compliant with new internal plugin interface

Version 0.3

Add some i18n getSimtple function

Version 0.2

Update to be compliant with new internal plugin interface

Version 0.1

Initial version

Change log url_compatibility plugin

Version 0.1

Initial version

 

Last edit: Yonodune 2016-11-08