The web page
Page header
  Home Default Settings for AppsCMS (Draft)    
Page body
AppsCMS body
Manual for AppsCMS page
Top AppsCMS Logo

Users Manual - Applications Management System for PHP (AppsCMS) - V2.09rc2

Contents
Introduction

This technical manual is to aid administrators, managers and web developers using the AppsCMS.
Supplementary to this manual is the Installation Notes. The Release Notes list the AppsCMS change history. General information is available in the About AppsCMS page.

The web site has a search function to aid finding configuration and setup values.

NOTE: The AppsCMS is not designed to operate inside a frame or iframe.

Cookies

The AppsCMS uses session cookies (i.e. not third party cookies) to allow the browser to provide the user›s session identity. The session identity is the unique key (generated by the user›s browser) used to identify the user uniquely that one web browser and is provided to the AppsCMS server via a session cookie. The identity connects only with that one browser on that particular user›s machine. The session identity is stored in a cookie on the user›s computer Without the session cookie, the user should not be able to log in.

The non cookie method of having the session identity in every URL (or some browser side script to do the same thing) is not used on the AppsCMS. The session identity is passed back to the server on every page load as a query parameter. The non session cookie method is very insecure as the browser URL shown in the address bar exposes the session identity and the URL can be easily copied to any another browser, the rights and privileges of the original user are also follow (because the server has no way to tell the difference). It is also not secure as the session identity will be stored in the browser history even when the browser is reopened at a later date (where a session cookie would be deleted when the user closed the browser). This non session cookie method is not recommended.

The recommended method for session identity is by the browser›s session cookie. If no session cookie, no login should be allowed.

The browser session identity is used as a unique key to save and retrieve a user›s state on the server.

License

The AppsCMS is under "BSD-3-Clause" and has the "https://opensource.org/licenses/BSD-3-Clause".

The license apply’s as follows;-

  • With the exception of library files in the "cms/lib/" directory, the AppsCMS license applies to all other files in the "cms/" directory.
  • And applies to "index.php", "login.php" and "logout.php" files (in the web DOCROOT directory),

` Which is the extent of AppsCMS files licensed.

File in the "cms/lib/" directory are covered by there own respective licenses. And are not licensed by the AppsCMS.

The applications and user web pages files are not licensed by the AppsCMS author. And belong to the licensing respective application authors. The License for the Applications are the users responsibility and are licensed separately.

The author of AppsCMS is open to submissions from the user community for changes in the "cms/" directory to be included in the next release. Submissions can be emailed to AppsCMS . A submission script is available at "cms/cli/cms_wrap_submission.sh" is available to produce a ZIP archive of the "cms/" directory.
Important Note on Submissions: It is usual for submissions to be credited to the submission author. The submission author needs to provide permission for an acknowledgment (in the release notes) to be added.

Code Examples

Code examples are available in the cms/examples/ directory. The "/var/www/vhosts/appscms.org/public_html/cms/examples/" directory can be copied the "/var/www/vhosts/appscms.org/public_html/cms/" directory to engage the examples. (e.g. at the doc root run "cp -v -r cms/examples/ .")

The examples show basic functionality. The explanations given here assume that the example code has been copy to the functional location.

Technical Information

AppsCMS is based around standard technology. Some effort was made to make the code compatible for browsers with CSS2 and HTML4. CSS3 and HTML5 is used on compatible browsers. PHP scripts are used to generate html web pages.

See Compatibility for browser support information.

Installation setup is stored in INI files. Theme customization is also stored in INI files, and is used to generate CSS style sheets. Accompanying installation and theme setting pages are included to make changes. The default settings provide an operational AppsCMS.

The setup and configuration files are saved in the "etc/" for setting JSON, INI and sqlite (e.g. cms.ini, cms.sqlite, etc.) files. Setup control JSON and INI (e.g. cms.comment.ini, cms.default.ini, etc) files remain in "cms/include/ini/" or "apps/include/ini/" respectively as part of the code base. Execution data is saved the "var/" directory (counts, exports,logs, sessions, etc.). This is the make updating and developing "apps/" code easier, separating critical site only files from unwanted alteration. Refer to Release Notes.

The AppsCMS can use WYSIWYG HTML page editors. The WYSIWYGs can be the system installed TinyMCE and CKEditor editors, or can use WYSIWYGs installed in $quot;etc/wysiwyg/" directory. They are supported by code built into the AppsCMS. There are six to eight (depending on the server) WYSIWYGs available and the WYSIWYG selection is in the Admin -> Config menu.

Data for users, administrators, managers, groups, page bodies, tools and configuration are stored in an SQLite2 or SQLite3 database. SQLite was chosen due to its easy installation (no database setup required) and it is very suitable for small projects. Automatic database installation code is provided. The SQLite database is initialized when the first web page is generated after installation. Providing an empty initialized database with the default configuration settings.

A basic description of the configuration database tables used;-

  • Configuration Table - stores company name, web titles, image control, etc., used in the web pages.
  • Users Table - stores username, encrypted password, group memberships, sort order/priority, enable/disable and administrator enabling.
    NOTE: That when the AD/LDAP authentication is used and no local password is supplied, a default local password of the date in YYYYMMDD format is used.
  • Groups Table - stores group, enable/disable, administrator and managers.
  • Page Bodies Table - stores the page body / application primary control values. The actual page content is stored in the "page_bodies/" directory using the filename configured. The body file is often used as a connector or control file for local application and often includes files in the "apps/" directory.
    NOTE: The applications may have further configuration settings in the applications.
  • Tools Table - stores the tools information. A special directory, "localtools/", has been set aside inside the AppsCMS file structure for handy tools, local "hacks" and try outs. Tools have sort order/priority, new page and enable/disable. Stores tool links , group memberships, sort order/priority and enable/disable. The tools appear in left column or in a drop down from the header or on the nav bar, and are displayed according to the group settings.

When the Admin->Config->Allow CSV Export and Import = True, the corresponding database table is exported to the exports/ directory on each save. The CSV can be downloaded from the relevant AppsCMS setup editor page. The CSV can be altered as the commentary included in the CSV file and uploaded back to the AppsCMS database. The CSV format uses the standard comma delimiter and double quotes for the enclosure (as required) to separate column data.
The AppsCMS setup editor page has a file browse button and an upload button to upload and import a CSV table file from your local computer. Before an uploaded file is imported, the AppsCMS backups up the database to the backups/ directory.
To restore a backup on LINUX, in the web root directory run:
"zcat backups/AppsCMS-Backup-cms.sqlite-YYYYMMDD-HHMMSS.gz | sqlite3 /var/www/vhosts/appscms.org/public_html/etc/sqlite/cms.sqlite"
Substitute your filenames as needed.

Setup and operational features should be self evident. All install, setup and configuration settings have accompanying information builtin describing each particular setting. The idea was to keep it simple. Remove anything that wasn’t useful or looked too complicated (i.e. make it easy to customize), by providing just the basics. The result has been to make use of CSS to remove as much code as possible. As a result the code has minimal javascript.

AppsCMS theme settings are numerous and should be self evident. AppsCMS is intended for general small web sites required for the generation of user/owner managed web sites. AppsCMS can be set to be easily identifiable (due to page headers and footers) so that users know the web site entity.

The web site contents use What You See Is What You Get (WYSIWYG) code editor. The easiest way the use and manage the WYSIWYG editors is to use the server installed TinyMCE and CKeditor WYSIWYG editors. These can be installed as standard packages on most servers. There is a direct mode (’None’ selected as the WYSIWYG config) of editing page bodies directly.

The web site can authenticate user against a LDAP/AD server by setting a user’s auth preferences to LDAP. The settings are part of the install settings.

The web site has a search function to aid finding configuration, setup and page contents.
NOTE: The AppsCMS will also work in an aliased directory (e.g. "http[s]://host.url/website_alias/").

The AppsCMS requires session cookies (also know as transient cookies) to be enabled to allow login. The session cookie locks your browser to the server session and provides additional security information about the identity of the session end to end. If the session cookie is disabled, a warning is shown on screen. Third party cookies are not used by the AppsCMS, so third party cookies can be disabled.

The AppsCMS has a content cache functionality to speed up deliver of content that does not change between successive requests to the web server. The content cache provides a 80% to 95% time reduction in the background AppsCMS operation on sections like nav bar, header and menus that require a large amount of processing each time they are displayed but do not change. The page bodies, custom header and custom footer can also be cached selectively. The content cache is cleared at login, logout, saving settings and configuration rebuild.

The AppsCMS has many defined constants, class objects, methods / functions and variables available to the web programmer. The use of an autocompleting IDE is recommended. The AppsCMS is in debug mode there is a debug selection in the Admin menu which will the global defines and various other other information.

Plugins

Users defined plugins can be placed in "/var/www/vhosts/appscms.org/public_html/apps/include/plugins/". The plugin class needs to be extended from the "Ccms_plugin_base" class (e.g. "class Cyour_plugin_class_name extends Ccms_plugin_base", The "C" prefix is a convention adopted in the "AppsCMS" for classes and plugins.). Examples of plugins are in "/var/www/vhosts/appscms.org/public_html/cms/include/plugins/" directory. Also, plugins inherently have their own config values (standard classes do not) stored in the config DB "cms_configs" table. And appear in the "Admin -> Config" page prefixed with "Plugin".

IMPORTANT NOTE: The AppsCMS class autoloader finds classes and plugins by their PHP filename and the class name being the same (removing any "C" prefix). The class file may have hidden classes, not directly loaded by the autoloader, within the autoloaded class file which are included in the primary PHP class map apon reading the autoloaded class file.

AppsCMS V2.09rc2 provides the following included plugins in the "/var/www/vhosts/appscms.org/public_html/cms/include/plugins/" directory;

  • Social Media - a plugin to interface a group of social media sub-plugins;
    • Facebook - a general Facebook ® sub-plugin.
      NOTE: At this time, the "center_right" position, the Facebook generated fly out goes off the right side of the screen and cannot be viewed, it is disabled at this position.
    • Google +1 - a general Google +1 ® sub-plugin (not displayed on most tablet devices).
    • Linkedin - a general Linkedin ® sub-plugin (not displayed on most tablet devices).
    Social media links are not displayed on tiny devices (e.g. iPods, iPhones, etc).
  • Email - a general server side email plugin for use with other plugins.
  • Gotcha - a security plugin for use with the Email plugin, etc.
  • Contact Us - a standardized server side contact us web code/page generator plugin.
  • Map Latitude Longitude - a standardized server side map code/page generator plugin. A basic implementation intended to show location for "contact us" pages is included.
  • Authentication - a standardized external authentication that provides a method to authenticate from external sources. Takes a local application plugin_name and uses the plugin_name::auth(username,password) method to authenticate users.
  • Media Converter - a media converter plugin for converting files (e.g. Markdown .md and text .txt) to html format. And to encapsulate images (e.g. mp4, .png, .gif, etc.) for the user’s web site. Engaged by using "Ccms_media_conv_plugin::get_file_href(URI,NAME)" to generate the link. The files are shown are in standard page for the user’s web page (i.e. branded to the user’s branding). The media plugin is primarily intended for documentation purposes.
    WARNING: The plugin will not show external information (i.e. from outside this web site scope).

A "cms/examples/page_bodies/example_cms_body.php" is available to help show how to use some plugins and local applications. The "_body" suffix in the filename is recommended to avoid filename clashes.

A "cms/examples/page_bodies/example_welcome_cms_body.php" is available to help show how to use the a "full view" welcome or splash page using the AppsCMS facilities.

A "cms/examples/page_bodies/example_contactus_cms_body.php" is available to help show how to use the Ccms_contactus plugin.

A "cms/examples/page_bodies/example_login_cms_body.php" is available to help show a custom login page.

A "cms/examples/page_bodies/example_modal_test.php" is available to help show how to use the Ccms_modal class with the Ccms_contactus plugin.

Server System Prerequisites

AppsCMS requires the following server requirements to operate;-

  • Apache Web Server 2.2.x installed on LINUX or MS Windows (other PHP compatible web servers should be suitable),
  • PHP 5.3 to PHP 7.2 (recommended) with PHP SQLite installed, or php-pecl-sqlite installed,
  • AppsCMS can be setup as an adjunct to an existing web site, or as a new web site (If a new web site, the apache web server configuration needs to be setup for the new web site.),
  • An SSL certificate, self signed or registered for SSL/https web site encryption,
  • http (port 80) for default home/links page and https (port 443) for login and user designated pages,

If server packages are available for WYSIWYG web page editors, TinyMCE V3 or Ckeditor V4, it is recommended that these be installed on the server. These should be automatically detected by the AppsCMS.

To install on Windows, a server bundle like WAMP or XAMPP will need to be installed and setup. It is also recommended that Wget for Windows be installed also.
NOTE: "xampp-win32-5.5.19-0-VC11-installer.exe" (apache, php, MySQL, etc.) was installed and setup on Windows ® 7 Ultimate for development of AppsCMS.

To use country checks, the PECL geoip (geoip >= 2.0) is required. For LDAP authentication the "php-ldap" module is required. For system process access the "php-process" module is required.

Installation and Update

Note 1: The server set up is beyond the scope of this manual. Some general server side setup information is given here. If help is required, contact your system administrator or tech support.
Note 2: The actual methods used on a particular server may vary from the steps shown here.
Note 3: The AppsCMS zip file does not come with user set files that over writes user settings, if they don’t exist the AppsCMS will generate default files.

The installation comes as a self installing bash script (2,2MB) for LINUX and a ZIP (1.6M) file for general installations. Available on the "https://github.com/AppsCMS/AppsCMS_Latest/blob/master/AppsCMS-Installer-latest.sh" repository and on "http://appscms.org/" web site.

For full user and administration experience use one of the following PC browsers on a desktop or laptop PC;-

  • Windows Internet Explore V11 or higher,
  • Firefox V31 or higher on Windows, LINUX or Apple MAC,

A guide to installing and updating AppsCMS follows;-

  • If updating the AppsCMS, backup the web site.
  • Download the AppsCMS zip file "AppsCMS-latest.zip" to the web site’s directory.
  • Unzip the "AppsCMS-latest.zip" with the overwrite and update options turned on into your web sites directory.
    e.g. unzip -u -o "AppsCMS-latest.zip"
      where (-u = update, -o = overwrite)
    This will unzip the AppsCMS file structure into the containing (the web site’s) directory.
    If you wish to restore AppsCMS to it’s default file structure contents, leave the update option off. And then run Rebuild Setup, see below.
    e.g. unzip -o "AppsCMS-latest.zip"
    NOTE: This does not change existing settings, but will remove any code changes made outside of the release.
  • Pointer your browser at "http://your.web.site/site_alias/index.php" (site_alias/ is part of your server setup, usually empty).
    When the AppsCMS is first accessed, it will create an empty SQLite database and rebuild all the CSS stylesheets.
    After approximately 20 seconds and went well, the first run web site looks like this;-
    First run
    NOTE: The filename of the log includes the domain name of the web site.
    On an update the appearance will be different.
  • Click the User: Login link. On a fresh install you see this;-
    First login
    On an update the appearance maybe different.
  • When no users are setup, a default admin user is;-
    Username: admin
    Paswword: password
    Strongly recommend the admin username be disabled after you have setup another, more secure, user (with admin rights).
    Login to the web site. On a fresh install you see this;-
    Admin empty
    On an update the appearance maybe different. Run the "Admin->Rebuild Setup" to rebuild the web site.
  • Important Note: If upgrading from V2.07 or less, run "cms/cli/cms_update_appsV207.sh" to upgrade your applications.
    Sorry no Windows equivalent available.
  • Suggest going to the Setup and Configuration section.

If failures and non functional issues occur, see Trouble shooting

Browser Window Layout

There is an overall web site style settings (part of the Theme settings);

  • "Block Style" - uses absolute positioning in the browser’s window. The page body scrolls between fixed positions of the header and the footer. The tool links, admin links and navigation bar also have fixed positions in the browser’s window. The browser’s window is more easily navigable.
  • "Inline Style" - uses inline/relative positioning in the browser’s window. Scrolls the header, tool links, admin link, navigation bar, page body and footer as one entity. This can make the separate areas of the browser window difficult to navigate to. The AppsCMS detects the type of device being used to display the web pages, and is not designed to be administered from tablets or very small devices. Where the browser cannot be identified or compatibility issues are known, the AppsCMS will use inline style.

The general arrangement of the AppsCMS window layout sections is;-

  • "Header" - top section of the window. This can be the standard web page header from the AppsCMS which contains standard features. The standard features can be configured by the administer. Or the entire header can be replaced with a customer header. Or the header can be turned off. If the left column is turned off and the navigation bar is turned off, drop boxes are used to display tool and administration links. The "Header" is identified by the HTML by <div id="cms_header">...</div>
  • "Left Column" - when enabled and displayed, occupies the left side of the window between the header and footer. The left column displays tool links and administration links. If no tools are setup and no user is logged in, the left column is not displayed. The left column can be turned off, then other means are used to display tool administration link, either in the header or in the navigation bar. The "Left Column" is identified by the HTML by <div id="cms_left_column">...</div>
  • "Navigation Bar" (Nav Bar) - when enabled, is a narrow horizontal links bar that occupies the window to the right side of the left column, under the header and above the page body. The contents of the nav bar are configured in the Config settings. If there are tools enabled and if the nav bar size allows, all the tool links are placed in on the nav bar as single items. If the left column is turned off, the tool links and administration links are added to the nav bar. The "Navigation Bar" is identified by the HTML by <div id="cms_navbar_wlc">...</div> with a "Left Column" or without a "Left Column" has <div id="cms_navbar_nolc">...</div>
  • "Page Body" - occupies the remaining window area, written by the web site’s author. This is the window area that displays the web site’s content. Although the sections other than the "Page Body" have automatically generated default content, the "Page Body" section has number of extra html code features (including javascript support) to simplify code and enhance effects for overlays and ajax data presetation. The "Page Body" is identified by the HTML by <div id="cms_page_body_wlc">...</div> with a "Left Column" or without a "Left Column" has <div id="cms_page_body_nolc">...</div> Inside the "Page Body" <div> there are sub "<div>s" for HTML "Page Body" control and access. These are;-
    • Enclosing the "Page Body" content is a custom HTML element, <cms_page_body_elem> ... </cms_page_body_elem>. By default, the <cms_page_body_elem> element is to help stop branding and links in the other sections being covered (and made inaccessible to the user) by "Page Body" code/content.
    • Inside the <cms_page_body_elem> element is two <div>s when the page is not in "full page view".
      • First there is <div id="cms_page_base"> ... </div> which contains the normal "Page Body" code/content.
      • Second there is <div id="cms_page_overlay"></div> which is intended for overlays and modal dialogs (usually from javascript code). The most common use for this <div> is to present modal boxes to users. Defaults to empty and set to display=none.
      • The <div id="cms_page_overlay"></div> is meant to be place on top of <div id="cms_page_base"> ... </div> when the <div id="cms_page_overlay"></div> is active.
      NOTE: there is a <div id="cms_page_body_base_overlay"> div around the <div id="cms_page_base"> and the <div id="cms_page_overlay"> to allow the overlay to work. This is not normally changed by the implementer.
    • There several javascript helpers methods that can be used with these "Page Body" sections;-
      • "Cpage_body.get_body_elem();" - returns the <cms_page_body_elem> object.
      • "Cpage_body.get_base_div();" returns the <div id="cms_page_base"> object{
      • "Cpage_body.get_overlay_div();" - returns the <div id="cms_page_overlay"> object.
      • "Cpage_body.show_overlay(overlay_content,base_opacity,base_class,overlay_class);" - sets the "opacity" (default = 0.45) of and appends "base_class" to <div id="cms_page_base">, appends "overlay_class" to <div id="cms_page_overlay"> and displays/shows the "overlay_content" in <div id="cms_page_overlay">.
      • "Cpage_body.hide_overlay();" - restores the <div id="cms_page_base"> and turned off/hides the content in <div id="cms_page_overlay">.
  • "Footer" - bottom section of the window. This can be the standard web page footer from the AppsCMS which contains standard features. The standard features can be configured by the administer. Or the entire footer can be replaced with a customer header. Or the footer can be turned off. The "Footer" is identified by the HTML by <div id="cms_footer">...</div>
Static Setup and Configuration

Use a recommended administration web browser.

After logging into the AppsCMS, an "Admin" menu in the left column (default), in the header (as a drop down) or on the Nav Bar (as a drop down), depending on any previous settings, will appear. The contents of the "Admin" menu are self explanatory, having tooltips (i.e. small pop up boxes with explanatory text) for each link.

The AppsCMS comes with an AD/LDAP authentication and search on login system. The authentication provides username and password login function, and optionally a AD/LDAP directory search function. The search function is mainly intended for local application and not directly used by the AppsCMS. There is optional AD/LDAP authentication search parameters available to interrogate the AD/LDAP server. The search results are placed in the $_SESSION['ldap'] array for use by application code and is available across sessions. The contents of $_SESSION['ldap'] are removed at logout. The AD/LDAP operation is controlled by installation settings in the "Admin->Install" in the "Auth Settings" section (more information available under "Auth Settings"->"Comments/Help").

After installation or update, the following guide is useful;-

  • Suggest checking out the "Admin" links to get a feel for the available settings.
  • If looking for a possible setting, try the "Admin->Search" link.

To further the general control and operation of the web site, the following maybe useful;-

  • Web site administrators can redirect the web site to another URL. Administrator can still login (using the "https://your.web.site/site_alias/login.php" URI) and administrator the site.
  • Web site administrators can close the web site. Administrator can still login (using the "https://your.web.site/site_alias/login.php" URI) and administrator the site.

Notice: The GROUP_PERMISSIONS setting is depreciated and will be removed in future versions. Default is to use web site DOCROOT group else the web server group.

Dynamic Configuration

Subsequently to the static setup configuration, the AppsCMS can use dynamic control configuration plugins for INI file values at the time of user engagement. The dynamic control plugins needs to be included in the included plugins configuration setting ("CMS_C_ENABLED_PLUGINS" setting).

Dynamic control uses a macro based on the "%%class::method%%" format, where the "class" is a user supplied plugin class name in "/var/www/vhosts/appscms.org/public_html/apps/include/plugins/" directory. The "method" is the user supplied static method in the "class". The dynamic control plugin also has a static method to identify it as a dynamic controller, "is_dynamic_controller()" which returns "true" if it is a dynamic control plugin. Otherwise it is not present or returns "false". See Plugins for more information on plugins.

The "KeyName" from the INI file are supplied to the "class::method" as formal function parameters. e.g. "class_name::method_name(Keyname);".

This allows dynamic configuration to be implemented (e.g. by user name, by group, etc.) to set AppsCMS definitions to dynamic states at web page generation.

NOTE: Dynamic configuration is NOT intended for theme options as the theme is set when the save button is clicked.

Local Tools

The AppsCMS has a local tools directory at "localtools//", for the installation of web based tools and extras. The local tools directory provides somewhere to put web applications / pages (tools). Each tool should be given a unique directory to occupy. Examples of tools are;- conversion tables, code checkers, procedures, manuals, just to name a few.

If you have tools installed on the host that are not under the "localtools//" directory, these tools can be accessed by using a symlink. This allows these non-local tools to be appear in the Local Tools setup.

Synlinked Local Tools EXAMPLES:
On LINUX, to setup HTdig, make a symlink by going to the "localtools//" directory, and execute "ln -s /usr/share/htdig htdig", where "/usr/share/htdig" is the path to the HTdig web pages. This allows HTdig to be used as the Local Tool.
A similar tool setup can used for the Apache Manual. Execute "ln -s /var/www/manual ApacheManual" in the "localtools//" directory, where "/var/www/manual" is the path to the Apache Manual web pages.
On Windows, a similar symlink can be set by using the mklink command. Execute "mklink /D ApacheManual C:\\xampp\apache\manual" in the "localtools//" directory, where "C:\\xampp\apache\manual" is the path to the Apache Manual web pages.
NOTE: Windows may not have the "mklink" command installed. If not contact your system administrator.

During tool setup, the "./localtools//" directory is searched for filename extensions of .htm .php .html and .txt The tool could be a complete sub-web site.

Local Applications

The AppsCMS has a local applications directory at "./apps/", for the installation of applications and provide greater flexibility. The application directory provides somewhere to put local applications. This provides scope for larger and/or more free form code. The layout of the file structure under the "./apps/" is under the local web programmer's control.

However, the AppsCMS requires some directory structure to allow code integration.

  • ."apps/" - the local application base directory.
  • ."apps/include/" - the include directory.
  • "apps/include/apps_manual.php" - a technical manual for applications. There is an example file, "apps/include/example_apps_manual.php"
  • "apps/include/apps_config.php" - fixed configuration values for apps runtime (optional). There is an example file, "apps/include/example_apps_config.php"
  • ."apps/include/classes/" - the class directory (the class autoloader looks in here).
  • ."apps/include/ini/" - the ini directory (the settings and install pages look in here).
  • ."etc/ini/apps.ini" - the application related settings.
  • ."apps/include/ini/apps.defaults.ini" - the default application related settings.
  • ."apps/include/ini/apps.comments.ini" - the descriptions/help text of the application related settings.
  • ."apps/plugins/" - the plugins directory (the plugins autoloader looks in here).

The Admin -> App Config -> checks to see if a "apps/include/apps_css.php" is present. If so the save process generates a "apps/include/apps_css.php" for use in application web pages. This can be used to set extra theme and style sheet settings. The "apps/include/example_apps_css.php" is provided to help.

The "etc/ini/apps.ini", "apps/include/ini/apps.defaults.ini" and "apps/include/ini/apps.comments.ini" are used together to a connection between help messages, default values and the config values. Use the "etc/ini/cms.ini", "cms/include/ini/cms.defaults.ini" and "cms/include/ini/cms.comments.ini" files as an example. When present, the settings are managed by "Admin -> App Config" menu, are read in and values are defined with a prefix of "APP_" plus the ini file keyname for use in the code. There are example in "etc/ini/example.apps.ini", "apps/include/ini/example.apps.defaults.ini" and "apps/include/ini/example.apps.comments.ini" to help.

The access to the local applications is controlled by the AppsCMS authentication. A AppsCMS authenication plugin is provided in the AppsCMS.

By default, direct (authorised or not) access to files in ".apps/" directory is denied. Access should be provided from page body contents pages/code. This ensures root document jumps are not possible.

A note on apps classes; it is recommended that the base class on all apps classes should be Ccms_app_bass (e.g Cmy_class extends Ccms_app_base ). The Ccms_app_base class provides interface to the main AppsCMS and provides general functionality.

Examples of local applications are;- web page content provided by high level programming, specialized interface displays, just to name a few. Example files are given thought the "apps/" directory to help show how to best these features of the AppsCMS.

Applications may require secure access to inbuilt APIs via SSL on the HTTPS protocol. To aid in providing secure access the AppsCMS monitors the called PHP code for "api.php" and can by configuration force SSL to be be used by redirection. If the API client cannot redirect, the client will be disconnected.

Local Applications Authentication

In addition to the local applications the AppsCMS can use a user provided authentication. The "Capps_auth" class is the "apps/include/classes/apps_auth.php" class file.

The AppsCMS requires the "Capps_auth" to have following public static methods;-

  • "public static function is_page_allowed($name)"
    Returns true if page is allowed. Used for fine control of pages.
  • "public static function is_navbar_element_allowed($name)"
    Returns true if nav bar element is allowed. Used for fine control of nav bar elements.
  • "public static function login($user, $password)"
    Authenticates the $user (per application requirements). If authenticated, executes any application login code and returns "true" else return "false" for login denied.
  • "public static function init($user)"
    Called just after the web server session has started and the $_SESSION variables are available. The $user value will be false if no user is logged in or the user name if logged in. This is for applications initialization. If "init($user)" is ok it returns "true". Else returns "false" for denied (and will subsequently log the user out of the AppsCMS).
  • "public static function is_login_current()"
    Used to check if apps user is still current with a remote second authenticator, possibly. Return null is not used or don't know, false = no, true = logged in still,
  • `
  • "public static function logout()"
    Log out current user (per application requirements). If logged in it returns "true" else return "false" if not logged in.
  • "public static function get_short_name()"
    Provides a short name (e.g. a well known acronym) that is suitable user selection text (i.e. in a drop down).
  • "public static function get_title()"
    Provides a title for the authentication method (i.e. text for tooltip or bubble).
  • "public static function get_JS()"
    Provides the APP AUTH login javascript, if used (called before get_html).
  • "public static function get_html()"
    Provides the APP AUTH login html, if used.
  • "public static function do_apps_warnings()"
    Optional method. If present the Capps_auth::do_apps_warnings() method is called when an admin logs in. The do_apps_warnings() can be used to check that the system requirements are met.

IMPORTANT NOTE: The "Capps_auth" class provides authentication only for the AppsCMS. It does not provide the AppsCMS login execution code. Other application code is engaged by the user supplied code.

An example at "apps/include/classes/example_apps_auth.php" file is included.

Local Applications Extension Plug In

An application extension plugin can be used (available under the "CMS_C_APPS_EXTEND_PLUGIN" config key) to add entry/s to the Admin menu. As well method substitution for "Ccms_base" class methods. The plugin is placed in the "/var/www/vhosts/appscms.org/public_html/apps/include/plugins/" directory so the AppsCMS can find it.

The plugin needs to have the following static methods to integrate into the AppsCMS;-

  • "public static function get_admin_uris()"
    to add the entry/s to the Admin menu. The returned values are an array. For example in JSON form;-
    	{
    		"0":{
    			"text": "Setup App A",
    			"uri": "apps/AppName/config.php", (can be a URL or a class::method)
    			"title": "Setup App A ..." (optional)
    		},
    		"1":{
    			"text": "Setup App B",
    			"uri": "CsomeClass::someMethod", (can be a URL or a class::method)
    			"title": "Setup App B ..." (optional)
    			"no_body" true	(optional, set true if the uri does not provide a page body)
    		},
    	}
    					
    NOTE: If URLs are with reference to <base href meta data in the page header.
  • "public static function read_apps_extend_comments_ini()"
    Is used retrieve an array of the extended applications control JSON. This allows the controls to be searched. It is associated with index 0 from the "get_admin_uris()" return;
  • "public static function read_apps_extend_settings_ini()"
    Is used retrieve an array of the extended applications settings JSON. This allows the setting to be searched. It is associated with index 0 from the "get_admin_uris()" return;
  • "public static function get_apps_extend_settings()"
    Is used generate the setup page from the extended applications settings JSONs and read in and save the POSTed data from the browser..
Sitemap

The AppsCMS has a search engine compatible XML sitemap generator and a HTML sitemap generator builtin. As changes are made to configuration and contents of the web site, the sitemap is automatically updated. To manually update the sitemap goto "http://your.web.site/site_alias/index.php?action=update_sitemap".
NOTE: If the sitemap filename is not setup, no sitemap file is generated.

The XML sitemap is available at "http://your.web.site/site_alias/.xml" (replace "your.web.site/site_alias/" with your domain name and alias, if any, for AppsCMS installation).
The HTML sitemap is available at "http://your.web.site/site_alias/.xml" (replace "your.web.site/site_alias/" with your domain name and alias, if any, for AppsCMS installation).
NOTE: The name of the sitemap can be configured in the "Admin->Install->Xml Sitemap File" setting. The primary link URL in the sitemap is the same URL in "Admin->Config->Main Web Site URL" setting.

The sitemap can be generated from the command line. `

`
  • On a LINUX server, in a console shell, goto the web site’s "cms/cli/" directory and run "cms/cli/cms_generate_sitemap.sh".
  • On a Windows host, in a command shell, goto the web site’s "cms/cli/" directory and run "cms/cli/cms_generate_sitemap.cmd".
Successful sitemap generation looks like this;-
				Starting -> sitemap generator for AppsCMS V2.09rc2.
				INFO: Created sitemap "/web-site-root-directory/sitemap.xml" (Link=sitemap.xml)
				Finished -> sitemap generator for AppsCMS V2.09rc2.
			

Where sitemap name is set to "sitemap".
If any errors or warnings occurred, these will be printed out. `

Special Code

The AppsCMS has a special code directory for PHP code (e.g. for Google analytics code and social media code) at "/var/www/vhosts/appscms.org/public_html/etc/ext/". Any analytics (e.g. from Google) code or special socal media code should be placed in this directory. The code (usually PHP, HTML, javascript, etc.) is included at the appropiate point by the AppsCMS.

Coding Shortcuts and Builtin Features

The AppsCMS has many coding shortcuts and builtin features that are accessible to applications. These include:-

  • Global Definitions - The AppsCMS works out where it is and presets the coders/programmer with all the "DOCROOT" file structure defined. It is important to use these "defined" constants to maintain future proofing your code. Login as an administrator (and turn on the debug mode if necessary) and click on "Admin -> AppsCMS Debug". This displays a searchable list of all the AppsCMS definitions.
  • Base Classes (Objects) for Apps - The Capps_base() class in intended to link in many AppsCMS methods for use in applications. The Capps_base() class is actual a methods library/stack to provide common useful methods and provide correct access into the AppsCMS code.
  • Applications Configuration INI Settings and CSS Style Sheets - a AppsCMS maintained setup and themed stylesheets.
    The AppsCMS has code to produce annotated columns and headings for settings that contain multiple values or name=value pairs in the "/var/www/vhosts/appscms.org/public_html/etc/ini/apps.ini" settings file.
    There are examples in the "cms/examples/" sub-directories.
  • Dynamic Configuration - Allows the configuration settings to modified dynamically via another process (local or remotely) by user supplied code.
  • LDAP/AD Authentication - Just setting the LDAP settings and enabling users to use LDAP/AD, user authentication can be used.
  • Remote Authentication and Data Control Retrieval - This feature allows "glue" logic and code to be implemented.
  • Geo Location - Geo location can be added to any form by including Ccms::Ccms::add_JS_geolcation_to_form() function. The latitude, longitude, accuracy and time are captured by the AppsCMS and store in the base classes (and also in the session data). The AppsCMS Ccontactus plugin and the standard footer uses the Geo location code and can provide detailed application information. The Geo location can be enabled/disabled, and the time to live (TTL) of the location can be set. Use Admin -> Search -> "location" to find the settings.
  • JavaScript Calendar - The AppsCMS doesn't currently use the this calendar but many applications do. The calendar is singular and will follow the date event elements as they are clicked. An example are shown in the example_cms_body.php file. The Ccms_html() code class creates the engagement JavaScript. Check the get_JS_calendar_resource() method adds the initialization code and set_JS_calendar_init() method that generates the interaction code.
  • INI / JSON File Configurator - The Ccms_edit() code class is used by the AppsCMS to configure install, theme and apps settings engine. It uses a suffix detection to generate the appropriate input element. The configurator uses a three file system, one containing the settings in use (e.g. cms.ini, apps.ini), one being a default settings file (e.g. cms.default.ini, apps.default.ini) and one file containing and explanation of every setting in the first ini file (e.g. cms.comment.ini, apps.comment.ini). These three files can also be used for JSON file types (e.g. .JSON) because the Ccms_edit() code class is abstracted from reading the files (by the caller providing the arrays) and therefore can be used with remote files. At present the depth off the arrays is limited to standard INI format (i.e. [section][name] = value). There is html element creation code is in Ccms_edit() code class. This can also be used for JSON file type settings also, with some extra features for generating input elements.
    • INI files are usually used where it maybe necessary to edit settings manually. INI files are used by the AppsCMS for this reason. However they only have a simple [sect_name]key = "value" scope and cannot given value type nor possible selections. To help the Ccms_edit class has the Ccms_options class as a base to key name suffixes to allow a limited number of selections. Mainly suitable for theme settings and basic true/false (boolean) settings.
    • The JSON file format allows a much broader scope for settings allowing type and selections settings controlled from the comments.JSON (i.e the controlling JSON). The "apps_comments.json" is the controlling entity for the Ccms_edit class.
      For example;-
      {
      	"_comment":"A comment for the section (shown in debug readonly)",
      	"_important_note":"Array keys must obey the JSON rules of only alphanumeris and underscore characters (no spaces in keys).",
      	"Order_Online": {
      		"comment":"A comment for the section (shown).",
      		"_comment":"A comment for the section (shown in debug readonly).",
      		"_ID":"System Value: an ID (shown in debug readonly).",
      		"take_out": "The Ccms_edit class generates the html as this key value is not an array",
      		"Beverage": {
      		"_comment": ["Because this key value is an array and has a text element",
      				"the Ccms_edit class uses the array to control input generation (optional)"],
      			"text": "The text / definition / help shown with the key name Beverage.",
      			"input": {
      				"_comment": "A plain input (optional)",
      				"type":"text|number|password|checkbox|textarea|hidden|file (number can have precision, checkbox return is 'on' or 'off')",
      				"params":"(e.g. size=\"10\" length=\"80\")",
      				"_function": "Cclass::method_get_options_or_params_etc_to_add_to_input()",
      				"prec": 2
      				},
      			"select": {
      				"_comment": "A selector (optional)",
      				"type": "single|multiple",
      				"options": {
      					"-1": {
      						"text": " -- Select Please -- ",
      						"params": "disabled selected hidden"
      						},
      					"0": "Coke",
      					"1": "Coffee",
      					"2": "Tea",
      					"3": "Chia",
      					"4": "Water"
      					},
      				"_function": "Cclass::method_get_options_or_params_etc_to_add_to_select()",
      				"params": ""
      				},
      			"_show_func":["Show value (readonly) static function/method to generate text",
      					"only (e.g. Csomeclass::showmethod($sect,$key,$name,$value) (optional)"],
      			"_form_input_func":["An input static function/method to generate the input html for",
      					"the form (e.g. Csomeclass::inputmethod($sect,$key,$name,$value) (optional)"],
      			"_form_get_func":["An get from form static function/method to read the form",
      					"value (e.g. Csomeclass::gettmethod($sect,$key,$name,$value) (optional)"],
      			"__comment": ["The func variables are: $sect = sect_name (1st level),", 
      					"$key = key (2nd level), $name = the form element name to use,",
      					"$value = the current"]
      			},
      		"2nd_key": {
      			"and so on": "..."
      			},
      		"and so on": "...",
      		"Nth_key": {
      			"and so on": "..."
      			}
      		},
      	"2nd_section_name": {
      		"and so on": "..."
      		},
      	"__OrderDate":"Order date (not shown)."
      	}
    • The values are in the settings values JSON.
    • Where settings values JSON has an array under the key name the value array is not shown. The values are maintained in the settings value JSON.

There are many inbuilt feature and useful classes and methods in the AppsCMS intended for end coders and code integrators to use. Beware changing the "AppsCMS" code in the "cms/" directory. An update will overwrite any changes in the "cms/".

Basic features and hints;-

  • The "cms/" is the "AppsCMS" code directory. This should regarded as a code library and a "AppsCMS" update will over write this directory.
  • The "apps/" is intended for free coding. Usual each application has its own sub-directory here. The installation will setup the basic directory for standard code locations (e.g. includes,classes,plugins,etc.). To help start coding there are examples applications and code in the "cms/examples/".
  • The "etc/" is for settings, images, css (i.e. theme generated stylesheets), etc. that are required for operation. Basically the configuration directory (similar to /etc on LINUX).
  • The "var/" is for transient data (e.g. caches, backups, logs, session data, etc.) and would not normally be saved (similar to /var on LINUX).

There AppsCMS has been progressively hardened over time. Thanks to the feedback from users and community since V0.01 in 2013, the AppsCMS has beeb growing and it will continue to grow. Many things that can go wrong (e.g. missing "var/" directories, lost settings, etc) are checked and rebuilt on Admin login. When this happens the AppsCMS will tell you what it has done via the logs files (and on screen optionally). The "" is intended for end coders and code integrators to use. Beware changing the "AppsCMS" code in the "cms/" directory. An update will overwrite any changes in the "cms/". The "apps/" is intended for free coding, but does have example files that will be updated. The "etc/" is for settings, images, etc that are required for operation. The "var/" is for transient data (e.g. caches, backups, logs, session data, etc.) and would not normally be saved. If a change is done to the "cms/" directory, submit the code using "cms/cli/cms_wrap_submission.sh" script to make a ZIP archive and submit in a feedback email.

Trouble Shooting

The AppsCMS has installation and updating trouble shooting functions built-in.
NOTE: This does not change existing settings, but will remove any code changes made outside of the release.

If the web site is basically functional, logging in as an administrator and going to the "http://your.web.site/site_alias/index.php?action=rebuild_setup" link will rebuild the web site settings. This can take a minute or so to complete.

If after an update or other problems, the web site is non functional, there is a recovery command available to help fix this.

  • On a LINUX server, in a console shell, goto the web site’s "cms/cli/" directory and run "./cms_rebuild.sh".
  • On a Windows host, in a command shell, goto the web site’s "cms/cli/" directory and run "cms_rebuild.cmd".

Successful rebuild output looks like this;-

				Starting -> rebuilding setup for AppsCMS V2.09rc2.
				INFO: Installation check.
				INFO: No install issues detected.
				INFO: Checking AppsCMS V2.09rc2 database for updates.
				INFO: Checking table cms_users
				INFO: Checking table cms_groups
				INFO: Checking table cms_bodies
				INFO: Checking table cms_tools
				INFO: Checking table cms_configs
				SUCCESS: Checked cms.sqlite tables - success
				INFO: Installed plugin configs for maplatlong, email, contactus.
				SUCCESS: Update cms_main_styles.css
				SUCCESS: Update cms_block_styles.css
				SUCCESS: Update cms_inline_styles.css
				INFO: DB updated to V2.09rc2.
				Finished -> rebuilding setup for AppsCMS V2.09rc2.
			

If any errors or warnings occurred, these will be printed out.

CAUTION: The update will use default settings for new features. Take note of the messages (e.g.ERROR, WARNING, and INFO). The default settings for new features may need to changed to more appropriate values.

A basic installation guide is available in the Installation Notes.

File Version Control

When a manager or administrator are logged in, the AppsCMS can use "Subversion" (SVN) and Git, if available, to aid in administration and checking of the site. Hovering the mouse over the "About AppsCMS" or manual pages shows the current SVN and Git version status of the website. This reports the SVN revision number of the web site. The revision numbers can used to identify changes.

Current version details: Default Settings for AppsCMS, SVN: 369 18/03/2019 18:56:49

Utility Scripts

The "cms/cli/" directory contains utility scripts;

  • "cms/cli/cms_backup_settings.sh" - backs up settings to a datetime named file in "var/backup/" (e.g. ;var/backups/AppsCMS-Backup-20170801-163930.zip).
  • "cms/cli/cms_generate_sitemap.cmd" - Windows version of CLI sitemap generator.
  • "cms/cli/cms_generate_sitemap.sh" - Linux version of CLI sitemap generator.
  • "cms/cli/cms_generate_sitemap.php" - is sub script of CLI sitemap generator.
  • "cms/cli/cms_rebuild.cmd" - Windows version to rebuild configuration.
  • "cms/cli/cms_rebuild.sh" - Linux version to rebuild configuration. NOTE: Running "cms/cli/cms_rebuild.sh" runs the "cms/cli/cms_backup_settings.sh" before rebuilding.
  • "cms/cli/cms_rebuild.php" - is sub script for rebuild configuration and reset the cache.
  • "cms/cli/cms_set_permissions.sh" - Linux scripts to restore web server permissions.
  • "cms/cli/cms_wrap_submission.sh" - Linux script used to help submit community feedback containing code with requested changes.
More Information and Feedback

AppsCMS Logo.

README.

Release Notes.

Installation Notes.

Directory Structure;-

\ (DOCROOT/alias)		Web site base directory (maybe DOCROOT or a directory / alias under DOCROOT).
│
├── apps/		Base directory for web applications (apps code supplied by user). Contains fixed code.
│   ├── include            Apps include directory.
│   │   ├── classes        Apps classes directory (autoload classes looks in here).
│   │   └── ini            Apps fixed INI and JSON hard coded control files directory.
│   ├── javascript         Recomended Apps javascript directory.
│   ├── lib                Recomended Apps libraries directory.
│   ├── plugins            Apps plugin directory (autoload classes looks in here).
│   ├── stylesheets        Recomended Apps stylesheet directory.
│   └── (other)            Other Apps directories as required.
│
├── cms/		Base AppsCMS directory (this directory is overwritten by AppsCMS updates).
│   ├── cli                AppsCMS command line operations (e.g. rebuild, backup, etc.).
│   ├── dist               The AppsCMS installer creates this directory to save install files (e.g. AppsCMS-Vn.nn.zip).
│   ├── examples           Example code for user directories (copy this directory to document root to engage the examples).
│   │   │
│   │   ├── apps           Example apps/ directory layout.
│   │   │   ├── example_app1                       Example app 1 directory (contains app 1 files)
│   │   │   │   └── example_app1.php               An example app 1 code file.
│   │   │   ├── example_app2                       Example app 2 directory (contains app 2 files)
│   │   │   │   └── example_app2.php               An example app 2 code file.
│   │   │   ├── images                             Common app images
│   │   │   ├── include                            Common app include files.
│   │   │   │   ├── classes                        Apps class files (autoload classes looks in here).
│   │   │   │   │   ├── example_app1.php           Example app1 class.
│   │   │   │   │   ├── example_apps_auth.php      Example apps authentication class.
│   │   │   │   │   └── example_dyn_cntl_base.php  Example dynamic control base class.
│   │   │   │   ├── example_apps_config.php        Example apps configuration file.
│   │   │   │   ├── example_apps_css.php           Example apps theme generator file.
│   │   │   │   ├── example_apps_manual.php        Example apps code / applications manual file.
│   │   │   │   ├── ini                            Example apps ini settings configuration directory.
│   │   │   │   │   ├── example.apps.comments.ini  Example apps configuration comment file.
│   │   │   │   │   └── example.apps.defaults.ini  Example apps default configuration file.
│   │   │   │   └── plugins                        Apps plugins files (autoload classes looks in here).
│   │   │   │       ├── example_app_extend.php     Example apps extended plugin class.
│   │   │   │       ├── example_app.php            Example apps plugin class.
│   │   │   │       └── example_dyn_cntl_app.php   Example apps dynamic control plugin class.
│   │   │   ├── javascript                         Apps common javascript directory.
│   │   │   ├── README-apps.txt                    Apps README file.
│   │   │   └── stylesheets                        Apps common style sheets file.
│   │   │
│   │   ├── etc                                    Etc directory examples.
│   │   │   └── ini                                INI directory examples
│   │   │       └── example_cms.wysiwyg.ini        Example WYSIWYG configuration file.
│   │   └── page_bodies                            Page bodies (or apps links) directory.
│   │       ├── example_cms_body.php                   Example body file (may be an app or a standard web page).
│   │       ├── example_contactus_cms_body.php         Example use of the contactus plugin.
│   │       ├── example_login_cms_body.php             Example use of a login page.
│   │       └── example_welcome_cms_body.php           Example of a full view web page (header, body and footer all integrated).
│   ├── images             AppsCMS images directory (used by the AppsCMS).
│   │   └── manual         Images for the AppsCMS manual..
│   ├── includes           AppsCMS includes (not include like apps) directory.
│   │   ├── classes        AppsCMS classes directory (autoload classes looks in here).
│   │   ├── ini            AppsCMS fixed INI and JSON hard coded control files directory.
│   │   ├── ops            AppsCMS operations directory (e.g. login, login, edit config, etc.).
│   │   └── plugins        AppsCMS plugin directory (autoload classes looks in here).
│   └── lib                Local copy of AppsCMS 3rd party libraries, a directory for each library.
│       └── README_libs.md AppsCMS readme on 3rd party libraries.
│
├── etc/		Config base directory (this directory contains the configuration files).
│   ├── ext                Directory for external code (e.g. Google Analytics, etc. code).
│   ├── images             Custom images based directory for web site.
│   │   ├── backgrounds    Custom/uploaded background images directory.
│   │   ├── icons          Custom icom=ns directory.
│   │   └── upload         Custom/uploaded web page images directory.
│   ├── ini                Edited configuration/options INI and JSON file directory.
│   ├── sqlite             The AppsCMS sqlite configuration database directory.
│   ├── wysiwyg            User installed WYSIWYG html editors.
│   └── (other)            Other Apps config directories as required.
│
├── localtools/		Local tools directory (supplied by user).
│
├── page_bodies/		Web body/apps code directory (supplied by user).
│
└── var/		Temporary / transitory data directory (should not need to be backed up).
   ├── apps               Applications directory for Apps.
   ├── backups            Backups directory.
   ├── cache              Cache directory.
   ├── exports            Exports directory.
   ├── logs               Logs files.
   ├── sessions           PHP user session data directory (if used).
   ├── Trash              General directory for deleted files (local recycle bin).
   ├── variables          Variable storage directory (e.g. counts, stats, etc.).
   └── (other)            Other Apps variable directories as required.
	

Hints, corrections and suggestions are always welcome. Email Feedback.