BS-CMS Documentation

Learn more about the BS-CMS flat file CMS system. Find out about our flat-file CMS and how to use it to create your website quickly and correctly.

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. 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 and 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 such as sitemaps.org. The human sitemap is intended for humans to help navigate your website. At present the human sitemap is not automatically added as the sitemap.xml is. However, the code needed to create the human sitemap page is automatically generated for you. Under the admin panel's menu select Page->Human Sitemap. You will see the unordered list code needed to create the human sitemap. A limitation of this is that you must manually update the human sitemap anytime a new page is added or a page is deleted. I hope to make the human sitemap feature function automatically in a future release of BS-CMS.

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.

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. Please note that in a future release of this CMS we would like to add a button/function that would clear out the activity file, so check for updates to this CMS regularly.

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. Any user can also delete any other user. 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.

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.

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!