Documentation SGEngine 2.2
- Introduction
- What's new?
- Installation
- Core system and the basic functions
- Modules available in this package
- TO DO
1. Introduction
SGEngine - is a multipurpose and flexible in configuration Content Management
System (CMS), which is written in programming language Perl.
Its main advantages are:
- Support of individual templates, those are responsible for design of website. Templates differ not only in color but also in structure and maintenance! You can give your visitors the chose to adjust the view of website.
- Modularity. Modules are small scripts, which can be written by anyone, who knows Perl. Modules provide dynamics of CMS.
- All modules included in this package have own HTML templates. This feature delivers from direct interference in module code when only applying of design changes are needed. This is especially relevant to those people who do not know Perl.
- Support of language packages.
- SGEngine has administrative interface with advanced capabilities to website management.
- As from version 2.0 of this bundle, script "Setup wizard" was included in it, which can help you to install CMS on your server within a few steps! You do not need any more to delve into configurations files!
So, if you are not Perl programmer also even do not know HTML, you can quite install SGEngine without someone's help and take advantage of one of prepared templates. If you are HTML guru or even be good on it, you are on forces to create own design and to use prepared modules. Well and if you besides work with programming language Perl, you can create own modules to your new site!
2. What's new?
+ Captcha - protection against spam-robots in guestbook and in comments
+ URLs are cut off by Apache mod_rewrite
+ New module "Navigating menu"
+ New template "Silver"
* HTML code of engine match with HTML 4.01 Transitional standard
* The module "Adding/Editing text files" is renamed into "File manager". Changes: listing of directories and files on a server and free navigation within a root directory; file upload to server directly from browser; and many other things. See 5.2 File manager
* URLs are unified
* A plenty of fine corrections and changes
- Not authorized users have no access to administrative interface
- Template "Black-White" is removed
- A plenty of fine bugs is corrected
The given documentation changes with each version. To receive the most extensive and clear representation about innovations in last version of this engine, we advise to familiarize with a variant of the documentation where all changes are noted by color.
3. Installation
3.1 Upgrading from the previous versions
If the version 1.1 or below of SGEngine has been already installed, consider that you does not become the current version 2.0 installed on top! However you can keep bases of news, comments and guestbook. They can be translated in a new format later. To install the new version of the engine with old bases do the following:
- Install the engine as it is specified in 3.2 New installation
- Start a script cbase.pl, by typing its address in an address line of a browser. This script converts old bases in new SGEngine format.
If you have installed version 2.0 or above, it is necessary to do following steps:
- Make the backup of all files on a server to keep all the changes done by you
- Install the engine as it is specified in 3.2 New installation
- Replace all bases from earlier made backup. Consider that since version 2.1 the switching of languages is supported, and the location of all base files has changed!
- If you changed design of already existing templates all changes will not be kept and, most likely, it is necessary to apply them again. If you created your own template it will need to be compared with new one. The last concerns basically only modular templates.
3.2 New installation
- Unzip contents of archive on a disk.
- Keeping structure, transfer all folders and files from a directory "www" to a directory on your server where are HTML documents stored. Most likely, it will refer to - "www", but not always! The variation "public_html" is possible.
- Keeping structure, transfer all folders and files from a directory "cgi-bin" to a directory on your server where are CGI scripts stored. Probably, it will refer to "cgi".
- It is necessary to give the rights 0755 ("drwxr-xr-x") to all files-scripts having extension .pl, .pm. This could be realizing by your FTP-client in a file properties. But consider, that some hosting-providers require own script rights to run it.
- Transfer, keeping structure, all other folders and files in the root home directory on your server.
- Start the script setup.pl with a browser. The "Setup wizard" will help you to finish the installation in few steps.
3.3 End of installation
If all has passed successfully do not forget to remove scripts cbase.pl and setup.pl, or to move them to the directory, where anybody except for you cannot start them. If there were problems go to our forum.
4. Core system and the basic functions
SGEngine is written in programming language Perl, that basic and distinctive property is fast and flexible work with text files. Whole package consists of two types of documents:
- scripts(.pl, .pm) - are executed on the server side files;
- content(.html, .css, .js, .tmpl, .ini, .lng, .jpg, .gif è ò. ä.) - are files which are generated or processed by scripts;
Templates consist only from content files. Modules are scripts which use modular templates for a conclusion of the information.
4.1 Structure of files and folders
- cgi-bin - root directory with scripts
- mylib - directory with configurations files
- menu - directory with menu language packages
- *.lng - menu language packages
- config.ini - main configurations file created by "Setup wizard"
- config_default.ini - default configurations file
- font.ttf - font file used by "Captcha" module
- russian.lng - language package
- Subs.pm - package with subroutines available for all modules
- menu - directory with menu language packages
- sources - directory with modules
- admin - administrative modules
- accessman.pl - access manager module
- add_news.pl - news manager module
- filemanager.pl - file manager module
- blist.pl - ban-list / bad words module
- dlcheck.pl - statistic and administrating of downloaded file module
- gbadmin.pl - administrating of guestbook module
- last_update.pl - last updating module
- navigation.pl - navigating menu module
- searchlog.pl - search logging module
- archive_news.pl - archive news module
- captcha.pl - "Captcha" module
- comment.pl - news comments module
- dl.pl - files download module
- feedback.pl - feedback module
- guestbook.pl - guestbook module
- last_update.pl - last updating module
- news.pl - news module
- rss.pl - RSS - news feed module
- sgsearch.pl - news searching module
- txt.pl - output of HTML and text files module
- view_news.pl - news viewing module
- admin - administrative modules
- admin.pl - access to an administrative part of the website
- index.pl - main script of the website
- cbase.pl - script "Old bases converter"
- setup.pl - script "Setup wizard"
- mylib - directory with configurations files
- close - closed directory for storage of passwords
- .htpasswd - file storing a login/password pair for access to an administrative part of a website
- administrators - file storing user logins for access to an administrative part of a website
- maccess - file storing names of modules, which are forbidden for starting to moderators
- log - directory with logs and bases
- language - directory defining language of logs and bases
- comments - comment bases
- guestbook.bas - base with messages in the guestbook
- l_update.log - log with last updating date
- news.bas - news base
- search.log - the cache of the news searching module
- badwords.bas - list with the forbidden words in the guestbook and comments
- banlist.bas - list with banned IP and nicknames for the guestbook and comments
- captcha.log - the cache of the "Captcha" module
- dl.log - downloaded files log
- language - directory defining language of logs and bases
- tmpl - directory with templates
- silver - "Silver" template
- dotted - "Dotted" template
- *.html - template files which are responsible for its structure
- accessman.tmpl - access manager module template
- add_news.tmpl - news manager module template
- blist.tmpl - ban list / bad words module template
- blist_table.tmpl -ban list / bad words module template
- comment.tmpl - news comments module template
- dlcheck.tmpl - statistic and administrating of downloaded file module template
- error.tmpl - output of a error or event template
- feedback.tmpl - feedback module template
- filemanager.tmpl - file manager module template
- form.tmpl - forms template
- guestbook.tmpl - guestbook module template
- navigation.tmpl - navigating menu module template
- rule.tmpl - template of the page rule
- search_list.tmpl - news searching module template
- searchlog.tmpl - search logging module template
- view_news.tmpl - news viewing module template
- text - root directory for text and HTML files used by engine
- language - directory defining language of text and HTML files
- www - root directory with HTML files, used by server
- css - directory with Cascading Style Sheets
- dload - directory with files downloaded from the server
- img - directory with graphic files
- js - directory with javascript-files
- index.html - index file redirecting on the main script
4.2 Templates
Each template of SGEngine represents a set of text files written on html, and also a file of Cascading Style Sheets. Cascading Style Sheets file is in directory /www/css. Html files could be found in the subdirectory of /tmpl, having a unique name and being name of a template. They share on two groups:
- "structural" have extension .html - are templates responsible for structure of the website, define its general appearance and the content.
- "modular" have extension .tmpl - are templates used by modules.
Structural
These template files, except for standard html-tags, contain internal tags of engine, which allow substituting other files of the template on their place, to start on this place a module or to substitute a variable from the language package. If the substituted file of the template also has internal tags they will be processed too. By default it is allowed to have 10 enclosed levels, this number can be changed in the configurations file. In structural templates following internal tags are used:
| <engine main{txt/file.html}> | This tag specifies, that the dynamic part of the website will be deduced here, i.e. result of work of the modules called from an address line. In braces the name of the module which will be used by default with parameters is indicated. In this case the output of text and html files module is called and the file.html file is passed. |
| <engine run{module}> | Instead of this tag the result of work of the module module will be inserted. |
| <engine tmpl{file.html}> | Inserts content of the file.html file from a folder of an actual template. |
| <engine txt{file.html}> | Inserts content of file.html file from directory with text and html files used by engine. |
| <engine print lng{xxx}> <engine print conf{xxx}> |
Inserts a line with a key "xxx" from the language package or the configurations file. |
| <engine print lng{copyrights}> | Deduces "All rights reserved" text. It necessarily should be in a template. |
Modular
These templates are used by modules and have extension .tmpl; their primary goal is to facilitate creation and editing of website design. With them it is not necessary each time to get into code of modules and try to discover html lines. Each module can use several templates and even to have the shared with others that besides saves time for correction. A modular template also as well as structural represents the text with html marking, into certain parts of which are variables of this module inserted. All these variables are described in the beginning of a modular template and look like: [%VARIABLE%]. The important areas of a template actively used by modules are marked out <!--AREA--><!--END:AREA-->.
Template setting
The website visitors can choose one of templates for permanent using. The template is set with the reference constructed as follows:
http://www.your_domain.zone/language/set_template/template
Where,
language - a kind of language (ru, en, de). This word is absolutely identical with the name of the directory, where dependent on language bases and logs are stored, and also the directory with text and HTML files;
template - a name of a template (dotted, silver), simultaneously being the name of the directory where files of a template are stored;
The name of this template is written in a cookie file which should be supported by browser. It enables each visitor to set the liked template and to see the website in that kind in which he find it most of all attracted.
4.3 Modules
Modules are the executed scripts written in programming language Perl. They give dynamic to a website working on SGEngine CMS. As a matter of fact, modules are not independent programs, it only a piece of the code which is called from the basic script index.pl. Therefore, to create a module it is necessary to know the following:
- A Module should begin with lines:
use strict;
Where,
use vars qw(%conf %lng @query $template);
my $tmp = '';%conf - global hash-array with configurations;
%lng - global hash-array with lines of the language package;
@query - global array with module parameters, passed through a URL;
$template - global variable with a name of an actual template;
$tmp - local variable for output of result. - A module can contain any program code, including subroutines, a call of other modules, etc., except for a direct output in STDOUT. The direct output in STDOUT should be replaced with an output in a variable $tmp.
- A module should return a variable $tmp with the line:
return $tmp;
- A module should be terminated, as it is necessary to any external subroutine in Perl, with the line:
1;
Parameters can be passed to the module through the reference. For example:
http://www.your_domain.zone/language/module/param_1/param_2/.../param_n