joeCMS: joe's own easy CMS
...yet another mini database free easy to use content management system

News

Impressum

05/2012 Version 1.1 released

02/2012 Ticker module

08/2011 Gallery invitation

10/2010 zip-Backup

09/2010 minor fixes

08/2010 Version 1.0 released

07/2010 first steps in joeCMS

Documentation

joeCMSjoe's own easy CMS

  1. What's this? Why?
  2. Overview
  3. Installing and starting
  4. The module types
  5. Administration
  6. A word on security
  7. Known bugs. What todo next and what will not be done
  8. Custom addons
  9. Credits

What's this? And why?

Yet another mini content management system in the www? Indeed, that's what this wants to be. One might say, "you haven't googled very well, have you?". I have. O.K., there are of course better cms, even lots of better mini cms. What I looked for where some simple things I wanted to be integrated into the thing:

The gallery thing was the real goal, because I like to show holiday pictures to my friends.

 

So I started with nearly no expierence on cms programming, yet some years of professional administrating some "drupal"-based websites with webshops and all this stuff. And so joeCMS is a php exercise course for me too.

I will be glad, if someone uses this. If not - no problem either. I'm using it. That's enough for me.

Overview

To give a little overview we best take an example. The website shown on the right side is built with joeCMS. It consists of 6 elements:

There are 2 elements more: links for the impressum (red) and for the admin's login (pink).

 

Headline, sideblock, footline, ticker and content area are showing simple html or php content, there are no limitations at all(!). All content is read by specific modules. As all elements are styled in a central stylesheet, simple plain text can be used as content as well.

 

Administration is done by one php program, which allows you to change the configuration data, change the menu and the content, upload and delete files and edit the styles and element blocks.

Until now there are two content page types:

There may be more in the future.

In addition there is a block type named "ticker" which is an independent block element but may be a page block too. That's because the ticker data is stored in a page - ticker.page and you can - if you want - link this page in the usual menu too. By appropriete setting of the corresponding CSS styles you can have 2 different views of the same content.

Installing and starting

Installing is easy. But first you have to check, whether your webspace or your server meets the install requirements. They are few:

  1. minimum 5 MB webspace (you can install joeCMS with even some hundred kbytes of webspace, delete the gallery pictures in the content/gallery subdir and the background picture in the files subdir therefore, but then you wouldn't have space for your content ;-)
  2. webserver should be apache2 (there may be others usable, if they run the below named php5.1+ modules)
  3. php 5.1 or higher with the following modules
    • exif - for the exif data extraction in the gallery
    • gd - for the thumbnail generation in the gallery upload
    • zip - for the unzipping of archives in the gallery upload and for the backup command
  4. the right to protect subdirs - usually with the .htaccess method, see A word on security for further information on this topic.

 

If you have downloaded the zip file, unpack it on your local machine (you can do this on the server, if you habe the rights to do so, but mostly you won't have them). You see a directory structure like this:

  joecms-example
    +--------/content
    +--------/files
    +--------/include
    favicon.ico
    index.php
    license.txt
    robots.txt

(There are of course files in the subdirs, if you open them)

 

Then change to the "include" subdirectory and there deeper into the "admin" subdirectory. Here lies the central configuration file "cms.config". Open it with your favorite text editor and edit the line Site="http://localhost/..." Simply replace the site uri with that of your intended webspace location. Usual that shall be something like Site="www.mydomain.tld" If you want to test joecms in a subdirectory of your webspace, you can do it by simply mentioning it here: Site="www.mydomain.tld/subdirectory" Then save this file.

Now upload the directories and files beneath "joecms-example" to your webspace location. After this your site should be available at the location you entered above.

Now at least you should do a little bit for your security: In the actual state everyone can use the include/admin/admin.php file which administrates your website. So you have to protect the /include/admin subdirectory. The usual method is to place a .htaccess file in this subdirectory and to generate a password for it. There are other methods resulting in the same: you are asked for username and password when calling the administration website.
If you have an account provided with a configuration system e.g. plesk or config-server, you probably will have a menu point "directory protection" to do this task. At A word on security you find more info on this topic.

That's it. Enjoy!

The module types

There are two module types until now:

 

 

The page module

The page module is used to display usual html content. Editing a "page" entry you can use php, javascript and plain html, so be warned! Security is your job!
A page can contain pictures as usual, just upload them with the file upload in administration program and link them in the "files" subdir as they will be uploaded there.
The content entered here is displayed in the "content" window, which you can customize in the style.css file in two ways: by changing the #content settings or by changing the settings for #page_[pagename] where pagename is the menu entry of your page, so this is page-specific.

The gallery module

If you want to show a picture gallery use this. Editing the menu entry of a gallery lets you set a gallery title and upload picture files. You can even upload a zip-archive, so it's easyer to upload more pictures. But be aware of the maximum file size shown in the upload section of the administration program.
Once you have uploaded pictures the admin program builds thumbnails for them and the gallery module shows some usual navigation symbols and the thumbnails to move through the pictures. Somehow special is the gear-wheel button starting (and by this changing to a switch-off button) a slide show of the gallery's pictures. The speed of the slide show is set in the admin config area (see below). The show restarts at the end of the gallery and as expected the switch-off button stops it.
Below the pictures on the right side the filename is displayed, if it's a jpeg picture and the jpeg comment field is filled, the comment is displayed on the left side.
If you are in the "direct edit" mode (see below) you can invite someone to your gallery by sending a mail to her/him. Below the pictures there is a text and a mailaddress field to fillout and a send button to press you will use to do so.

Administration

All the administration work of joeCMS is done via the script /include/admin.php. Usual you should have to authenticate (see A word on security about this) before you can use the script. You get the page shown right. It is divided in 5 sections:

Every section has its on purpose and you can work only in one a time. That maybe a lack of function but makes things a lot easier. Let's walk through the sections:

Configuration

First there is a Generate backup butoon. It does  what you would expect: it generates a file "backup.zip" in the sites root containing all files in and below the sites root. You get a "download" button to download the file to your local system. And you can delete the file manually after that, if you want. This can be usefull, if you have limited webspace.

As easy to see, next the central configuration options for the cms are set. They are a few until now:

ModificationDate
just shows the date of the last saving for the config file cms.config
Site
joeCMS must know, where it's working ;-) - this has to be set a install time (see above)
Title
what's used as the website's title (not shown on the screen (this is done by headline module), but used in the meta-tag 
Description
what's send as the website's description (meta-tag)
Keywords
what's send as the website's keywords (meta-tag)
UploadExtensions
which file extensions (the very last!) are allowed in file uploads (.zip is allowed for gallery picture upload without mentioning here, but only for galleries, if you want to allow it generally, do it here). Extensions have to be without "." and separated by comma. They include the appropriate UPPERCASE extension without naming it here.
PictureExtensions
the allowed extensions for gallery pictures. As above, uppercases are included and as told above, these pictures can be in a zip file
AdminpageRefreshTime
If you save something in the adminpage, the cms is refreshed automatically. If you want more time to read the messages before refreshing, give some more time here (in seconds)
DirectEdit
The direct-edit-Mode allows you to edit a page immediately without going over admin page. As for authentication proof you have to call once more the admin page after you set this to generate a security key. You see this by showing a "de_mode=" tag at the end of the link in the statusline of your browser.
Set this to on if you want to activate. Every other setting but cke deactivates the feature. If activated, every "page" type page has an "Edit" button on the top right side.
Special is to set to cke: to edit the file the CKEditor is started, a WYSIWYG-Web editor. Handy but doesn't work correctly with php code until now, so use it for clean html pages only! More information on the CKEdit homepage...
NavigationTitle
If you want another title for the menu block.
GalleryInvitationText
This text is used to build the message to invite someone to one of your galleries.
SlideshowTime
The time a picture is shown before changing to the next in milliseconds - the real time depends on your server too.
 
GalleryStyles
Special CSS-styles for the gallery can be set here, e.g. for the gallery text style...
TickerCategories
A list of categories used by the special custom/tickeredit.php program, which is used to build an agenda ticker, see custom addons.
TickerSpeed
The speed of the ticker rolling in ms per step. A value of 50 is usually ok.

 

Menu

This configures the navigation menu of the website. Every Menu entry has 4 fields:

Right next to the entries are "action" buttons allowing to move the menu entry up- and downward, to save a change of the entry, to delete an entry and to edit the entry's content.

 

Some more explanation

Menu link
means the page, where this entry should point to. This can be an internal type (page or gallery until now), so the name can be simply one word (good practice is to use small letters and numbers only), or just an external website, then you have to use the full syntax http://www.site.tld. External sites however can't be edited through the cms and the are shown in a blank window (tab) if the link is clicked.
Page type
you have to select the before mentioned page type here, either page or "gallery" as internal types or the external link type. A "page" means one file will be generated by editing, a gallery is a subdirectory of pictures shown on a special (fullscreen) page. There may be more page types in the future.
Menu name
is what the visitor of your site sees as menu entry and at the top of the selected page as title. If you want to disable the showing of the title an a single page, use #page_<singlepagename>#contenttitle { font:0.1px;visibility:hidden;} , (where <singlepagename> is the link name of this page) in the style.css
Menu position
can be "0","1","2". "0" means, no menu entry visible. You can however link such a page or gallery by including an usual "a href"-link to it with ?s=menuentry for this menu entry. The goal of the invisible marking is, you can use the edit functions for invisible entries too.
"1" means the menupoint will be shown at left, "2" means it will be shown indented as a submenu.

 

The action buttons
The "+" and "-"-buttons do what you would expect, they just move the menu entry one line up- or downward. The "+5" and "-5"-buttons as well, but 5 lines at one jump.
The "save" button saves your changes in the 4 menu fields.
The "delete" button deletes the menu entry. You are asked for confirmation and have the possibility to delete the appropriate content too - if the content is a page, it is deleted, but not the pictures that are maybe shown by this page (see file deletion below therefore). If it is a gallery, the gallery title page and all gallery pictures, thumbnails and appropriate subdirectories are deleted!

The edit button
The "edit" button's result depends on the page type: if it's a "page" you get the page edit view:
There you can edit the page content freely, no limitations, you can use html tags, php code, javascript functions. But simple text is enough and will be shown as controlled by style.css stylesheet (see below).
If the menu entry points to a gallery, the gallery edit view is shown: This view is divided in two parts: at the top you can edit the gallery's title, as in pages all kinds of entries (text, html, php, javascript) are allowed. Because of the styling in style.css usually plain text is enough.
Below this you have 5 upload fields. Here the gallery pictures are uploaded. You can select upto 5 files a time to upload, reopen the "edit" page to upload more. But you may need this seldom because in addition to the named allowed picture formats (usual jpg, gif, png) zipped archives are allowed to upload. The must not contain any subdirectories and non allowed picture files, these are skipped when uploading.
There are two special functions in galleries:

Thumbnail generation
After uploading is finished it's checked whether thumbnail pictures exist for every gallery picture, otherwise the are created. (Using thumbnails makes picture navigation much faster, especially on slow servers).
Picture descriptions
If the exif data of your pictures contains the "jpg comment" tag, the text found here is displayed as picture description (you can generate this tag easyly with the linux command exiftran -i -c "description" picuture file , I chosed this because of really confusing use of the normal exif comment tags by most programs and digital cameras).

 

The file upload section

Here you can upload single files (up to three a time) to the "files" directory. The allowed file extensions are shown, other files are skipped. The maximum file size of one file to upload is shown too, it depends on your servers setup. Just select with the file selector the files to upload and klick the "upload files"-button.

 

The file delete section

This is for deleting single files out of the "files" directory or the galleries directories. The files in the "files" and in all gallery directories are shown in select windows, you can select more than one file (by shift+click or ctrl+click as ususal) in more than one directory. A general confirmation is asked (say "yes" or "no" to all!).

 

Special file edit buttons

This is for edititing of files that are not in the menu tree and therefore can't be edited in the menu section and via DirectEdit:

styles.css
'The central stylesheet file. It's located in the protected area <YourSite>/include/admin/styles.css. It has 4 sections
  • Globals: general settings ... the main font, font size...
  • Site elements: formattings for the website elements: headline, menu, sideblock, footer, content, impressum (see below)
  • Type specific: special settings for different page types, page or gallery until now
  • Page specific: every page has a <div id="pagetype_pagename"> tag including the page content (pagetype is "gallery" or "page", pagename the link name of the menu entry), so you can override all your usual settings for a special page. A special area in this section is "adminpage", there are settings for admin page, but they are only for your convinience. The admin page works without them (see "secure mode" below)
A special thing is that you can include php codes here, the style.css is read by "include" php function. This is maybe useful if you want directory-independent local uri's, as in background-image:url(<?php echo $path; ?>/files/rainbow.gif); to include the background image in (maybe protected) subdirectories too.
The usage is identical to the editing of normal pages
It is maybe a good idea to analyze the styles.css in the example page to see how things are to be done...
Headline
Doesn't need long explanation... just edit like normal pages, usual html, php, javascript...
SideBlock
Neerly the same, just a html block, I use to show on the side of a page, often the right one, but this isn't necessary so, there could be some news or else. Just edit like normal pages, usual html, php, javascript...
Ticker
A html block too, but the content will be rolling up.  Just edit like normal pages, usual html, php, javascript... The rolling stops if cursor is over the ticker content.
Special: the whole stuff must be in paragraphs (<p>) and ususally you have to play around with the #ticker and #tickerbox settings in the style.css to get what you want...
You can use ticker as a page too, then you have to name it as "ticker" in the menu. Special styling can be done by #page_ticker ... then because #ticker and #tickerbox are used for the ticker function only and ignored if ticker page is presented by the page module
Footline
is as headline (if you want you can place them anywhere else by styles.css ;-) ... just edit like normal pages, usual html, php, javascript...
Impressum
Is somehow special, as it's not a page, but shown by a javascript alert. There was some trouble with some filthy lawyers last years trying to get money from people who didn't have an impressum, and if they had, it wasn't one click away from the visistor, where it has to be by their opinion. That should refer to business websites only but at least german law calls every website a business one, if there's something to download or any other content of that type.
Because it's shown by alert(), no html, php, javascript is allowed and even no linefeeds, no ticks "'", if you need a linefeed, just include "\n" therefore. The #impressum style in style.css is just positioning the link to impressum, not the impressum itself. It's the same with the #AdminLogin style.
Create Sitemap
creates a sitemap.xml in the sites root. It uses Binny V. Abraham's sitemap generator script. You may want to customize it before first use (file: include/admin/create_sitemap.php) but it's mostly self-explaining, otherwise you get more info at Binny's website. After generating the sitemap.xml you can upload it to google, if you have an account. You find the file sitemap.xml in the root of your website.
Edit Sitemap
you may want to edit the sitemap before uploading

 

Secure mode of admin page

As you may imagine, using errornous php and javascript codes in your pages may lead to errors in page presentation, if its usual content, you simply won't see the content but the other blocks are presented (content is the last block read, so if there is an error, the others are shown before). You can go to admin page then and correct the code.
But what happens, if you wrote invalid code inside the headline? Or in the styles? You won't see anything after this. Maybe you can use your browsers <BACK>-Button and get the editing page back and correct. But maybe not...
There's a workaround for this: call the admin page in "secure mode": http://<yoursite>/include/admin/admin.php?secure=yes - that will bring up the admin page without reading any blocks and styles before (config and menu file are read, indeed, they have to, if there are errors, you have to use your ftp account to correct). The page's view will be a little "unstylish" of course, but, depending on your browser's defaults, usable. All functions are available and you can try to correct your problem. After any submitting klick the normal view is loaded again, hopefully now as you expect. Otherwise you have to redo...

 

 

 

A word on security

As a matter of fact: there isn't that lot of it. If you are the administrator you can do neerly erverything. And if you worked properly, non-admins shouldn't have any possibility to do bad...

There are some things you can and should do to protect your site

Strongly recommended: protect the <YourSite>/include/admin directory by .htaccess or other method
Put a .htaccess file in this directory, which has the following content: 
AuthType Basic
AuthName "closed."
AuthUserFile YOURSERVERROOT/.config/.htusers
Require user username
YOURSERVERROOT has to be replaced by the absolute directory path of your webspace, usual it's something like/home/www/<your_ftp_username>/html or /srv/www/<your_ftp_username>/htdocs and you have to create an appropriate .config directory here and place a .htusers file here containing mainly one line: 
username:B0GhWKgQdx3fo
The code behind username is generated by htpasswd2 -n username (under linux) - you have to type twice a passwd and get the code back. (In fact, the above shown is the code for the password "test".) There should be a similar method for windows users. Often your web hoster has a admin module to do so, e.g. Plesk or config-server have.
If you did manage this, everyone trying to enter this subdirectory will be asked for the username and the password. That shall be enough protection for most circumstances.
Otherwise everyone who knows how - and everyone can read it here - can call the admin site and is master of your site as you are...

 

Set proper user rights
That means:
  • all files and directories not named below may be readonly (the usual "read/write" for owner, readonly for group and others is insufficent often because the uploading (ftp) user and the visiting user are handled as the same at cheaper servers). This means the root directory of your webspace may be (if not limited by other purposes) readonly too. There's one limitation: as sitemap.xml and backup.zip are placed in the websites root, you have to create them once (and must not delete them after!), before making the site's root readonly...
  • The subdirectories files and content have to be writeable by owner, if owner is the same user as the visitor, otherwise they have to be world writeable.
  • The same applies to the cms.config, cms.menu and styles.css files in the <YourSite>/include/admin directory. Therefore the above mentioned protection is really needed.
  • If you upload page and gallery files or directories or other files placed in "files" by ftp they have to be writeable in the above way too to be handled by the cms.

 

Known bugs. What todo next and what will not be done

Known bugs and open things

Version history

Version Problem, changes... Status
1.1 ticker module included done 05/2012
1.1. WYSIWIG editing with CKEdit included done 04/2012
1.0 Gallery invitation button for administrator in gallery editition included done 08/2011
1.0 the direct-edit mode didn't work on the web, on localhost it did, was a problem with $_SERVER['PHP_AUTH_USER'] that wasn't available always fixed 16.09.2010
1.0 config-variable for the »Navigation« headline of the menu block
editing a page fails, if the menu link entry contains a page anchor (page#anchor)
if not in security mode, there is a failing check for "security" variable, does no harm, but produces a php error		 fixed 17.09.2010
1.0 Backup and Sitemap creation should exist built 10/2010
1.0 first release 08/2010
0.1 development started 07/2010

 

ToDo-List

there will be more entries next time...

 

What will not be done...
 
Sorry, there are a lot of things I don't want to do or they are to big for me ;-)

 

Custom Addons

I'm not sure, whether it's a good idea starting to build custom addons. But there was the need for a structured agenda ticker editable by someone with nearly no html knowledge. So I wrote tickeredit.php which you find in the custom subdir. Maybe there will be more addons later or I will be integrating them into the main module structure. Time will show.

Credits

Willing or not willing, knowing or not, a lot of people contributed to this project and I want to thank them: