BS-CMS Documentation

First Important Step after Installation

BS-CMS comes with an so-called built in homepage. The homepage is always the first page in the CMS, so it is important that this page is never deleted. If this page is deleted then BS-CMS likely will not work and will need to be re-installed. The thing to do after installation is to simply edit the homepage (page / , index 0 in the pages.xml file) to suit your needs. Please note that the second included page is the so called human readable sitemap, this is index 1 and any template or style can be applied to it. The human readable sitemap is automatically created and updated. Next you can begin to add more pages to your website as needed. I also recommend creating regular backups of the system, see more about backups in the section below.

Themes Information

BS-CMS comes with two default themes. Base1 and Base2 are Bootstrap© derived themes included with BS-CMS. Base2 is set as the active theme by default. These two themes serve several purposes. The first purpose is that they are fully functional, usable themes that can certainly be used to create a new website with. The second purpose is to demonstrate the Theme system of BS-CMS. The 2 included themes are kept fairly simple for the main reason that anybody with a little html/php knowledge can look through them and modify them to create their own themes to meet their own needs. Themes in BS-CMS can be as simple or as complex as one would like. At a minimum a theme has only a few requirements, such as an image of 400px x 300px, a theme.xml file (see Base1 or Base2 theme.xml files for reference), and a header and footer. Of course themes can be much more complex if one would like, with many css and javascript files. The point is that the user gets to decide just about everything with themes in BS-CMS.

Selecting a Theme

One can have many themes in the /themes folder within BS-CMS, however only one theme can be active at one time. Selecting the active theme is a straight forward process. On the Themes tab of the admin area, select the radio button which says 'active theme' of the theme that you would like to be the active (used) theme for your website. Next, at the bottom of the page, after all of the theme listings is the button 'Set Active Theme'. Click this button to save the active theme. This is a very important step as the theme selected will not be the active theme until the button is clicked and an alert message pops up saying 'active theme saved'. It is common for a user to simply check the radio button for the theme that they want to be the active theme, then leave the Themes page/tab thinking that the selected theme is now active. It is not active until the 'Set Active Theme' button is pressed and the pop up message appears!

Creating new pages

Creating a new page for your website is a simple process. Keep in mind that the page could be any kind of page, such as a blog post or standard, static page. To create a page, simply click on 'Pages' on the left admin menu to expand it and click on 'Create a Page'. You will be presented with a form style editor which should look somewhat familiar if you have used other CMS' before. The page name and url is required to create any page, and meta title and description are good ideas for seo reasons. The URL is probably the most important part. The URL should be in the form of /page (i.e. /about-us) and should not include any file extensions (.php, .html, etc), nor should it contain any special characters (i.e. %,&,*,$, etc), and it should not contain any spaces. You can make psuedo folder type links, i.e. /service/service-page-1 or /cities/city-page-1 as well. Once at least the URL is set and the unique page name is set then you can move on to the wysisyg (what you sees is what you gets) editor. This editor is the tinyMCE editor and should be familiar if you have used wordpress or other CMS'. You can add your content for the page here. See the section below for information on how to add images and image galleries. If you prefer to work in html code (instead of wyswyg mode) simply click on 'tools -> source code' from the editors menu. When you are ready to publish the page, click on the ;POST' button beneath the editor. If the page is created you will receive an alert saying the new page is created. If something went wrong (for example, you tried to add a page name that already exists, or you forgot to add a page name or URL) you will get an alert message telling you what went wrong. If you get such a message, return to the 'Create a Page' section and try again.

Adding Photos or Galleries to pages

Using the TinyMCE editor to add photos or images to your page is fairly straight-forward. To add an individual image simply select the photo icon in the toolbar, then in the popup window, select the upload button. Then choose a photo from your local computer then choose the settings, for example the desired alt tag and width/height settings, then click upload. The photo will be added to the editor. (note: if you need to add additional information to the image, for example if you need to add a class ((i.e. class="float-img-right")) you can do so in the html / source code view of the editor, look for that in the menu of the editor.

To add a photo gallery is also fairly simiple, however requires an extra step. From the TinyMCE editor click on the 'Add Gallery' button and a popup appears. The auto gallery script will automatically add all needed scripts and codes to make the gallery based on the images you select. To make a gallery click on 'select files' to select at least one image from your local machine (typically you would choose many images, holding down the ctrl key as you select multiple images), give your gallery a title (this is optional, if a title is supplied it will be outputed as an heading 2 before the actual gallery thumbnails), and click the 'Submit' button (within the popup window). This is an important step and the photos will not be added unless the Submit button is clicked before clicking the 'Insert and Close' button at the bottom of the pop-up. After clicking 'Submit', click the 'Insert and Close' button at the bottom of the pop-up. The chosen photos appear in the TinyMCE editor (along with all the necessary code in the background to make the thumbnails and to make the gallery work.)

The photo functions of the editor work the same whether you are creating a new page or editing an existing page.

Editing Existing pages

To edit an existing page, simply click on the 'Pages' button on the left side admin menu. From there, click on Edit/Delete Pages' to bring up the Edit/Delete panel. Find the page that you want to edit and click the orange 'Edit Page' button to bring up the information for that page as well as the editor. Make the changes that you would like and click on the 'Save' button to save any changes. Upon successful updates you will receive an alert message and the page will redirect to the admin dashboard.

Deleting pages

To delete an existing page, simply click on the 'Pages' button on the left side admin menu. From there, click on Edit/Delete Pages' to bring up the Edit/Delete panel. Find the page that you want to delete and click the red 'Delete Page' button. You will see a confirmation alert dialog, if you really want to delete the page then click 'OK' and the page will be deleted. You will then be presented with an alert message stating that the page has been deleted and the page will redirect to the admin dashboard. You can return to the Edit / Delete panel to confirm that the page has been deleted.

Sitemaps

There are typically two types of sitemaps for any website. One for robot crawlers (such as Google or Bing) and one for humans. The sitemap.xml file is typically used by robot crawlers to discover pages of your website and index them into their search engines and other bots may use the sitemap.xml file for other reasons or purposes. The sitemap.xml is automatically created for your website within BS-CMS. It is also automatically updated whenever a new page is added or an existing page is deleted. There is no need for any plugin or sitemap generators, it is created and updated automagically. The human sitemap is intended for humans to help navigate your website. The human sitemap is also automatically added and updated when needed as the sitemap.xml is. The human sitemap function simply outputs an unordered list of all of the pages within the CMS. No style is applied. However, it is possible to apply a style by updating the sitemapClass.php file in the admin/ folder. And of course any template can be applied to the human sitemap. The human sitemap is the second page (index 1) in the pages.xml file, and if it is deleted, then whatever page replaces it will get an unordered list of all pages added to the body. Therefore, it is a good idea not to delete or modify the human sitemap page (except the style as mentioned before and/or the template associated with it.

Creating Backups

BS-CMS makes it very easy to create backups of the whole system. The whole system includes, the core system files, as well as any content added by the user (i.e. pages, images, etc.). Simply navigate to the 'System' tab on the admin menu and select 'Backups'. On the backups tab, you will see a button to create a new backup of the whole system as well as a list of previous backups. The previous backups can be downloaded or deleted. We recommend creating regular backups (especially after making many changes) in case something goes wrong. To restore the system simply upload the backup to your webserver (typically by FTP, and overwrite any existing files), your system will return to the state it was in at the time of the backup.

System Updates - Keeping Your System Up to Date

BS-CMS uses Github to maintain updates and to set the latest version. An built in update system has been implemented which will always check to see if the version that you are using is the latest version (based on the latest release on Github). If an update is available you will see an alert in the 'System' section of the Dashboard page of the Admin Panel, along with a button to automatically apply the update and install the latest version. It is highly recommended to make a full backup of your system BEFORE clicking the update button! A full backup can be made in the Backup section under the System tab of the Admin Panel. Any update will not overwrite user files, such as images and pages. As such, after the update, your system will still have all the same content (images, pages, menus, themes, backups, logs, etc.) but will have any newly added features and fixes. It is a good idea to keep your system up to date!

Site Title, Favicon, and Logo

The site title, favicon, and site logo can be set during the installation process, however they are optional so it is possible to install the CMS without them. Whether or not they were set during installation, they can be changed or updated later by navigating to System->Settings from within the admin panel. The favicon is used for each page of your website (with the exception of the admin panel), and the recommended size is a 32 pixel by 32 pixel png image for the best results. Similarly, the logo is used mainly for meta data as it is set as the meta logo image for each page of your website. The site title is currently not implemented in this release but can be used for various purposes in future releases (such as using in themes).

System Activity

The activity tab under the System menu item within the admin panel will give information about important activities that have been completed. The main activities that are tracked are creating pages, editing pages, deleting pages, adding users, and deleting users. You can clear out the contents of the Activity File (and delete all records of activities) by clicking the Clear Activities button.

Users

This CMS supports multi-users. There must be at least one user, and that is the user created when the system is installed. However, after the initial installation, more users can be created. Currently the User system of this CMS is very limited. Basically all users have all rights and roles, meaning that any user can create, edit, delete pages, menus, themes, etc. I realize that this is a drawback and a limitation and in future releases we hope to correct this by creating roles for users, similarly to Wordpress where users could be admin or a reduced role (such as only being allowed to edit existing pages). Since this is an early release I just wanted to get it up and running and usable and so advanced features, such as user roles and permissions were intentionally left out. Remember to check for updates as this limitation should be addressed in future releases.

Visitor / Page Tracking

BS-CMS includes a very basic visitor tracking system which will add an entry to a text file anytime a page on your website is visited. Only very basic information is recorded, the visitors ip address, the page they visited, and the date and time. A list of all visitor activity can be viewed under the System tab of the Admin Panel in the Tracking tab. If your website has a lot of traffic, this file will fill up pretty quickly. You can clear out the file by clicking the Delete Tracking Contents button (at the end of the output). Keep in mind that this is just a basic tracking system and provides very limited information. It is in no way intended as a replacement for more robust, accurate, and informative tracking software and systems, such as Google Analytics. It is just intended to provide basic information of page visits.

Common Problems

In this early release there are bound to be certain bugs or defects that will be dealt with in future releases. One known 'bug' is when saving the menu the updated menu structure will not be shown in the admin panel until a hard refresh is completed (although the live site will show the updated menu structure immediately). Also you may receive a 'confirm form resubmission' alert upon the hard refresh. Simply confirm the form resubmission and the updated menu structure will appear correctly within the admin panel. Typically performing a hard refresh (Ctrl + F5 or Command + R for mac) will help some admin panel issues. Please feel free to help out by a) submitting any bugs or known problems through my GitHub channel and b) offering a solution to any such bug or issue.

Installing to a sub-directory?

If you have installed BS-CMS to the root directory, typically public_html or htdocs, then rock on! However your results may vary wildly if you have attempted to install BS-CMS to a sub-directory, in fact it may not work at all. I am aware of this issue and simply did not have the time to address it fully for this early beta release. I will address this known issue in the future and release a more stable version that functions completely and correctly within sub-directories. At the least you will need to make two changes in the code to get BS-CMS to work when installed to a sub-directory. The first is in the htaccess file in the root of the system, change the line:
# Edit this in your init method too if you script lives in a subfolder
RewriteBase /
, just add the directory name after the /. Then, in the main index.php file, also in the root of the system, change the last line,
Route::run('/');
change the / to /sub-directory to match the name of the sub-directory that the system is to be installed in.

Installing to XAMPP or other local LAMP stack

If you have installed BS-CMS to XAMPP or any other local LAMP stack, it may function as expected or it may not function as expected. There could be many reasons that BS-CMS fails to function on this type of installation. Typical reason that it would fail to function include unsupported (old) versions of PHP, missing PHP dependancies or modules (such as simpleXML or ModRewrite). I cannot provide support for such an installation and as such it is up to the user to troubleshoot any problems with a local installation.

If you are experiencing issues with updates or backups, this post about certificates on Stack Overflow might help: https://stackoverflow.com/questions/28858351/php-ssl-certificate-error-unable-to-get-local-issuer-certificate

Licensing

BS-CMS is released under the MIT license agreement. Meaning it is free to use for any purpose, private or commercial. You may also modify it to suit your needs. However you may not pass it off as your own work! And you should give credit and include the license that this software includes. It is released without any warranty, expressed or implied. Use at your own risk. I take no responsibility for any damage, including, but not at all limited to data loss. Please also remember that this is essentially a beta release and may contain security flaws, so again use at your own risk!