|
|
Softcomplex CMS (SCMS) is the web application designed to simplify the static content management of the websites. The content is described in secure administrative interface as the hierarchy of folders, documents and includable text fragments mirroring the logical and physical structure of the website. The documents are then generated according to the described rules and saved in the file system of the website.
Typical web site contains large number text resources that are static or can be static for example:
Often multiple files contain the same text fragments and when change is needed all those files must be updated at the same time. For example most of the website's HTML documents may have same basic layout, header, navigation, footer etc. Still all those documents have unique content and features, additionally often there is a need to have some documents that don't comply with common design idea of the site.
Below is the list of commonly used approaches and disadvantages associated:
| Method | Disadvantages |
|---|---|
| Create separate static file for each text document |
|
| Use the templates filled by server side scripts |
|
The dilemma over the maintaining the similarities and difference is anything but new and there is well known solution to it - inheritance. While descendant inherits some of the properties and behaviors from its parent(s) is can have some of those properties redefined and it can also have additional (personal) ones. The very same approach can be applied to the files in web site's hierarchy.
The idea of SCMS is to take the best of two worlds: have separate static file for each text document, but generate them to the server's disk based on the hierarchy of inheritable elements only when update is needed.
Below is the list of advantages this approach offers:
The SCMS generates the directories and files of the website based on the data entered by the administrator in the control panel. The information is organized as the hierarchy of the site's elements of several types (classes).
The SCMS mirrors the physical structure of the websites by utilizing the same approach - hierarchical tree. Just like the folders, files and links in the file system of the website, entities of different classes form the tree of the system. The elements of the tree are connected by the links. Multiple sub-elements can be linked to the one parent (i.e. folder contains multiple documents), and one element can be linked to the multiple parents (i.e. same document is mirrored to multiple folders).
To describe the content, the system uses very basic set of classes: project, folder, document, template, script and variable.
The project represents a single website or a group of the websites. One SCMS installation can support unlimited number of projects thus unlimited number of the websites hosted on the same server can be managed using the same administrative interface.
The project is a container class. Projects, folders, documents, templates, scripts and variables can be linked to the project.
The project itself don't create anything on the disk, but requires existing base directory.
The folder represents a directory (folder) in the website's structure.
The folder is a container class. Other folders, documents, templates, scripts and variables can be linked to the folder.
When generated the folder creates the directory on the server's disk if one doesn't already exist.
The document represents a file in the website's structure.
Templates, scripts and variables can be linked to the document. In its properties the document references the template or script as its text source.
When generated the document creates new or updates existing file on the server's disk.
The template is a named multiline fragment of text.
The template can't have any tree elements linked to it, but it can include (refer to) other templates, scripts and variables in its text. The references are replaced with actual text when the template is generated.
The template does not create any files or directories on the server's disk.
The script is the named reference of the script file or program in the file system of the server that generates the multiline text fragment. The scripts are used to pull the text from the dynamic source such as the database. Note that "document" class must be used for the server side scripts of the website, the "script" class is for the scripts and programs specifically created for SCMS.
Although the script can use some files and directories on the server when it runs, the SCMS only uses script's text output and doesn't map it in any file in the structure of the website.
The variable is a named single line of the text. Additionally to user defined variables system supports some internal variables. For more information on internal variables see section 3.4.3
The variable can't have any tree elements linked to it.
The variable does not create any files or directories on the server's disk.
As it was discussed earlier, the entities of different classes are linked to form the tree hierarchy. Each time the entity is created the system automatically links it to the parent. Every entity of the system is a part of the hierarchy and has at least one link. Additional links can be created for the same entity so it can have multiple locations in the site's structure. Links can be added and deleted at any time, but when the last link of the entity is removed the entity is deleted from the system.
The links can have optional local name, this makes it possible for the same entity to appear at different locations of the tree under different names. If no local name is specified the default name from the properties of the entity will be used instead. Same name can't be used under one parent by the multiple containers (project, folder, document) or multiple inclusions (template, script, variable).
To ensure accurate representation of the website's structure the SCMS only allows the links between entities of particular classes. The table below summarizes allowed combinations:
| Class (parent) | Allowed down-links (children) |
|---|---|
| root | projects |
| project | projects, folders, documents, templates, scripts, variables |
| folder | folders, documents, templates, scripts, variables |
| document | templates, scripts, variables |
| templates | none |
| scripts | none |
| variables | none |
Because the system supports multiple parents per entity, it also limits links between some entities to ensure the integrity of the hierarchy:
The referencing allows to embed the text fragments one into another and use the same text fragments in multiple locations. Only entities of the classes that contain text can be referenced - templates, scripts and variables.
Each document has the required property referencing the name of template or script that will be used as the source of its contents. Then when the document is being generated the template is searched for special tags that SCMS replaces with the text of the referenced template, script or variable. The reference tags are only resolved in the text of templates, the system will ignore them in the text produced by the scripts and in variables.
The reference tag has following syntax:
<SCMS NAME="name" FILTER="tpl,scr,var" OPTIONAL="yes|no">where:
Below are some examples of the reference tags:
<SCMS NAME="right_pane"> <SCMS NAME="header" FILTER="tpl"> <SCMS NAME="products" FILTER="tpl,scr"> <SCMS NAME="copyright" FILTER="var"> <SCMS NAME="hot_news" OPTIONAL="yes">
Additionally to user defined entities the SCMS exposes some useful internal variables to the templates:
The tags have following syntax:
<SCMS NAME="created" FORMAT="aAhHisdDlFMmYy"> <SCMS NAME="modified" FORMAT="aAhHisdDlFMmYy"> <SCMS NAME="generated" FORMAT="aAhHisdDlFMmYy"> <SCMS NAME="webroot"> <SCMS NAME="sysroot"> <SCMS NAME="relpath" ESCAPE="yes|no"> <SCMS NAME="docname" ESCAPE="yes|no">where:
| Letter | Description | Values |
|---|---|---|
| a | part of the day (lower case) | am or pm |
| A | part of the day (upper case) | AM or PM |
| h | hour in 12 hours format | 1-12 |
| H | hour in military (24 hours) format | 0-23 |
| i | minutes | 00-59 |
| s | seconds | 00-59 |
| d | day of the month (2 digits) | 1-31 |
| D | week day (short name) | Mon-Sun |
| I | week day (full name) | Monday-Sunday |
| M | month (short name) | Jan-Dec |
| F | month (full name) | January-December |
| m | month (numeric, 2 digits) | 01-12 |
| y | year (2 digits) | 00-99 |
| Y | year (4 digits) | 2005-2100 (practical) |
SCMS will use the internal variable only if no entities with same name found in the available scope of the document. This allows user to mask the internal variables with custom entities if needed.
The entities are referenced by the name. The tree is searched for the referenced name starting from the local scope and if it is not found there the search continues on the parent levels up to the root of the hierarchy. Because of the support for the multiple parents each document can have multiple locations in the file system of the website thus each instance of the document has own path (up-line in the hierarchy). The references are searched for each instance of the document in its specific path so the resulting text may be different for the copies of the same document.
The document references its base template, templates include other templates, scripts or variables. This creates the nesting hierarchy - the "parts map" for the document assembly. The depth of the nesting hierarchy is not limited, but the system will check for the reference loops such as template referencing its own name or more complex situations such as template A includes template B which includes template C which includes template A.
For successful installation of the Softcomplex CMS all of the below requirements must be met:
The installation script will attempt to ensure that above requirements are met and notify the user about any problems detected.
Follow the steps below to install and test SCMS on your webserver.
Download the product distribution package. SCMS is available for free download at the Softcomplex.com website at: http://www.softcomplex.com/products/scms/download.html
The system consists of multiple files and directories, to simplify the download process the files are archived using most commonly used compression algorithm - zip. Unzip the files to your local computer preserving the structure.
Login to your server using FTP client or web based file manager and verify the existence and if needed create following directories:
| Description | Recommended web path | Special requirements |
|---|---|---|
| web root of the system | /scms/ | regular folder in publicly accessed part of the site's structure |
| scripts root | /cgi-bin/ | allows CGI/Perl scripts execution, this folder most likely already exists on the server |
Using FTP client or web based file manager upload files from the local folder containing uncompressed files of the system to your web server. Contents of the cgi-bin folder must be uploaded to the scripts root directory, all other files and directories (except the folder "about" and its contents) should be uploaded to system's web root folder created in previous step.
Using terminal connection, FTP client or web based file manager set the permissions on following files and directories:
| Path | Permissions | Comments |
|---|---|---|
| /cgi-bin/mgr.pl | 755 | the file that processes all web requests, after the installation this will be the only CGI script of the system |
| /cgi-bin/scms_check.pl | 755 | temporary installation script checking for required components |
| /cgi-bin/temp/ | 777 | the directory for system's temporary files, after the installation it can be moved to the location not accessible from the web |
| /cgi-bin/logs/ | 777 | the directory for system's log files, after the installation it can be moved to the location not accessible from the web |
All the rest files of the system must be readable by the web server. Usually this is the default setting so no actions are normally required for this.
Using remote client, web panel or local console login to your MySQL database engine and create the database for the SCMS. The system can also share existing database with other applications on the server as long as there is no name conflicts. To reduce the chances of any conflicts all names used by SCMS in the database start with "cms_".
Create a database login ensuring it at least has rights to select, insert, update and delete. Again, the SCMS can use existing database user account.
Select the database and run the SQL script "about/scms_ddl.sql". Any errors reported by the database at this stage must be investigated and fixed.
Run SQL script in "about/sample_projects.sql" if you want sample projects preloaded in the system. Note that this script deletes all existing projects so it should not be executed after custom projects are defined in the system.
Edit cgi-bin/classes/m_config.pm on the server updating the following variables:
| Variable | Default value | Comments |
|---|---|---|
| CONF_WEB_DOMAIN | none | this is the http address of your domain without trailing slash. Example: http://www.softcomplex.com |
| CONF_WEB_ROOT | /scms/ | This is the absolute web path of the directory created in step 5.3 above. The path must be specified without the domain and with trailing slash |
| CONF_WEB_CGIBIN | /cgi-bin/ | This is the absolute web path of the scripts directory created step 5.3 above. The path must be specified without the domain and with trailing slash |
| CONF_SYS_ROOT | none | The system path to the documents root directory created in step 5.3 above. Path must be specified with trailing slash. Example path: /home/~tigra/public_html/scms/ |
| CONF_SYS_CGIBIN | none | The system path to the scripts directory from step 5.3 above. Path must be specified with trailing slash. Example path: /home/~tigra/public_html/cgi-bin/ |
| CONF_MAIL_DOMAIN | none | the domain name that will be used in the message IDs of the emails generated by the system. Example domain: softcomplex.com |
| CONF_DSN_NAME | none | Database connection string containing the database server address and database name. Example: DBI:mysql:scmsdb:localhost where scmsdb is the database name (must match the database created in step 5.6 above) and localhost is the server's name/address. |
| CONF_DSN_USER | none | The database user name (must match the user name created in step 5.6 above) |
| CONF_DSN_PSWD | none | The database password (must match the user name created in step 5.6 above) |
Other variables should stay unchanged unless directories of the system are moved from their default locations.
Most servers require the path to the interpreter in the first line of the CGI scripts. You may need to edit first lines of mgr.pl and scms_check.pl if the Perl interpreter is not located at /usr/bin/perl While editing make sure to preserve UNIX endlines (CR, not CRLF).
Run validation script (scms_check.pl) by requesting its URL in the browser (i.e. http://www.softcomplex.com/cgi-bin/scms_check.pl). Any errors reported by the validation script must be investigated and fixed.
System's user interface can be accessed at:
<CONF_WEB_DOMAIN><CONF_WEB_CGIBIN>mgr.pl?class=scms&form=indexor
<CONF_WEB_DOMAIN><CONF_WEB_ROOT>
examples:
http://www.softcomplex.com/cgi-bin/mgr.pl?class=scms&form=index http://www.softcomplex.com/scms/
The path in index.html needs to be adjusted if value of CONF_WEB_CGIBIN is not /cgi-bin/
The default login info is:
Check if system load properly and no error reported. Then click "settings" link and change default login information.
Delete cgi-bin/scms_check.pl using FTP client, terminal session or web based file manager.
The user interface of SCMS consists of four sections: header at the top, navigation at the left, property page at the right and footer at the bottom.
The login name and password is used to protect the SCMS from unauthorized access. The default login information the system is installed with is:
Password is case sensitive, login name is not. The default login details must be changed immediately after the installation (see section 6.4.9 below).
The session closes when "logout" link is clicked at the right side of the header.
The SCMS uses the tree navigation component similar to one found in Microsoft Windows Explorer. Click on the entity in the tree brings loads the information about that entity in the property page.
The tree switches to selection mode to:
When item is selected the tree will also find and highlight other instances of the same entity in the tree.
The filter can be applied so the tree will only display the physical items - those that are saved to the server's disk when project is generated.
The item links in the "scope" and "contains" sections of the property page (see section 6.3 below) can also be used to navigate between the elements of the hierarchy.
In the property view (default) mode property page displays information about currently selected entity, details about its links and paths as well as commands available in current context. The page reloads with the specific form when command is called.
The property page of the container entities (projects, folders and documents) also displays the list of the contained items (directly or indirectly, depending on the filter selection). [up] and [down] links in this section can be used to adjust the order of the elements in the container
The property page of the inclusions (templates, scripts and variables) displays the scope (all items that current entity is visible to) for each of its locations.
Below is the list of the commands supported by the system. The command is called in the context of the currently selected item. The command links are placed on the property page so they clearly indicate what they will be applied to (the entity itself or its link).
New entity is created by clicking one of the links under "Create new" section at the bottom of the property page. This section only appears for the entities that can contain down links (projects, folders and documents) and only lists allowed classes. The root level projects are created from the home page of the system.
When form is filled and submitted, the new entity of selected type is created and linked to the parent item.
The properties of any existing entity can be edited at any time. The edit form preloaded with current values is opened when [edit] link is clicked by the class name at the top of the property page. The system updates the information after the form is submitted and validated. Any problems with the submitted values will be reported to the user.
Any existing item can be introduced to additional location by creating a new link. Clicking [add] link in "Locations" section of the property page loads the form asking for optional local name. The tree is switched to selection mode listing the classes that can have down links as well as current item at its existing locations. Form can be submitted only after additional parent is selected in the tree. To leave the form without creating the link click on [cancel] link in the tree or at the bottom of the form.
The default name of the entity is specified in its properties and can be changed using the "edit" command (see section 4.6.2 above). Additionally to that the entity can have the local name assigned independently to each of its links (also see 4.6.3 above) It will be used instead of the default name at that particular location. To specify or update the local name click the [rename] link by the link and submit the form. To reset the local name to default submit the form with local name field blank.
Although the item can be moved in the hierarchy by creating the link in new location (see 4.6.3 above) and then deleting the old link (see 4.6.7 below) the easier way is to use [move] link located next to each link. This procedure is similar to creating a new link.
The command [generate] located by each location at the property pages of the physical items (projects, folders and document) runs the documents generation process. When this command is called for project or folder the system will verify if the target folder exists and attempt to create it if needed. After that the system will run generation for all direct and indirect downlinks of the current item recursively. When called for the document this command assembles the document based on its nesting hierarchy (see section 4.3.5 above) and saves it as the file at the path the command was called for.
The [delete] command located next to each link on the property page is used to remove the link from the hierarchy. The system will also delete the item itself if the command is applied to its only link. Because links and items can't be restored the confirmation page will be displayed before any changes applied to the hierarchy.
The link to the settings page is available at the left side of the header. On this page the administrator can update the login information as well as other system settings.
There are many way to do the job done with SCMS but planning the project will help to use the system at its best:
Full text of the user agreement is available here and in the distribution package, but here is some of the main points behind the legal wording: