• Home
  • AppsCMS Library for PHP
  •  
Manual for AppsCMS page
AppsCMS Logo

Technical Manual


Applications Management System Library for PHP (AppsCMS) - V3.07.11
Features

The AppsCMS is a multiple application management library written in PHP for web applications and web worker sites. It provides base line functionality to improve security and provide most of the web server side configuration and operation code. Although the AppsCMS is a PHP programmers tool (hence it is called a library), it is easy to learn and understand. Providing a good foundation library for web applications.

The AppsCMS can run on an isolated network requiring no internet access.

Being a code library and relatively small, it can easily be version controlled by Git or SVN as a whole.

AppsCMS provides theme / brand control of maintain basic theme appearance.

It is not intended to emulate or replace larger and more complex Content Management Systems (CMS).

The AppsCMS has a focus on web applications (e.g. data storage, processing and control, results compilation, machine interfacing, control/configuration interfacing, status display, etc).

A recommended way to see what the AppsCMS has is to login as an administrator to the AppsCMS, turn on debug (if not already on), goto to "Admin->Debug Values" and "Search" to check out whats there. A good PHP coding Integrated Development Enviroment (IDE) should allow more understanding of the AppsCMS library.

The AppsCMS library can function as an initial web site to allow setup and configuration. And get a feel for the library.

Also, if doxygen is installed, running "cms/cli/cms_doxy_run.sh" from the bash shell command line generate reasonable source documentation. Extra "Admin" entries will appear in debug mode to view the generated documentation.

There are a large number of configuration and coding features built in to the AppsCMS library. It is recommended to read this manual and explore the code library with a PHP IDE.

To harden the AppsCMS and applications against virus ingress, the "cms/" and "apps/" directories can be installed as read only directories via squashfs filesystems. Users cannot change code in the read only filesystems from external sources.

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.

This manual uses dynamic generation to represent this AppsCMS installation and location.

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

Terminology

The AppsCMS and it’s technical manual uses some terminology that is unique to the AppsCMS. This terminology is described as;-

  • "(DOCROOT)" - the location in the file system on the Apache server of the AppsCMS installation. For this installation it is the "/home/vhosts/appscms.org/public_html/" directory. The location of "(DOCROOT)/" is automatically found by the AppsCMS and defined in the "DOCROOT_FS_BASE_DIR" global constant, from which all file system location defines are derived.
    NOTE: If in debug mode, the "Admin->Debug Values" page will show all the globally defined constants.
  • "(APP_DIR)" - is the application as described the "Admin->Apps / Bodies menu". The actual location of the application is in "apps/(APP_DIR)/" directory.
    NOTE: Applications which share an application directory in "apps/" (allowed by "Admin->Config->CMS_C_ALLOW_APPS_DIR_SHARE"), also share the same (APP_DIR).
  • "(APP_NAME)" - is the application name used by the AppsCMS, for indexing. The (APP_NAME) has the non alphanumeric characters replaced by underscores.
    For example: "My App1" directory would have an (APP_NAME) of "My_App1".
  • "(APP_KEY)" - is the unique uppercase alphanumerical representation of the application’s key.
    NOTE: Applications which share an application directory in "apps/" (allowed by "Admin->Config->CMS_C_ALLOW_APPS_DIR_SHARE"), also share the same (APP_KEY).

The AppsCMS uses "Pages" and "Applications/Apps" references.

  • "Pages" - refers to a simple, usually basic/static informational web pages, having only a body page often written in HTML as <div> body html code </div>. "Pages" do not have code their "(APP_DIR)", a single code file in "apps/bodies/" directory and are also referred to simple applications.
  • "Application" - refers to dynamic application web pages, having much of the application code in the "(APP_DIR)". "Applications" have code files "apps/bodies/" directory also, but is used as the code hook the code in the "(APP_DIR)".
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 to 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 would not be able to log in.

The non cookie method of having the session identity (or SID) 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 will 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.

The AppsCMS provides a client metadata cookie in "_cms_clientMeta" (as an encoded JSON). This cookie expires in 1 hour from last use. It provides metadata feedback for applications that need to know the dimensions (e.g. depth, width, height, timezone, language, etc.) of the client’s browser window.

Licence

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

The licence apply’s as follows;-

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

Which is the extent of AppsCMS files licenced.

Files in the "cms/lib/" directory are covered by there own respective licences. And are not licenced by the AppsCMS.

The applications and user web pages files are not licenced by the AppsCMS author. And belong to the licensing respective application authors. The Licence for the Applications are the user’s responsibility and are licenced 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.

Technical Information

AppsCMS is based around standard technology. Some effort was made to make the code compatible for browsers with CSS3 and HTML5. PHP coding is used to generate html web pages. The PHP code is written in "Object Oriented Programming" (OOP). The AppsCMS PHP code is written in the default namespace ("/") to simplified user page and application code creation. To further aid programmers and IDE auto complete lookups, the AppsCMS prefixes it’s functions and classes with "cms_". This also aids the application programmer in writing applications that sit on top of (extends) AppsCMS objects (e.g. a class).

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 to make updating and developing "apps/" code easier, separating critical site only files from unwanted alteration. Refer to Release Notes.

Data for users, administrators, managers, groups, page bodies, tools and configuration are stored in an 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 "apps/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 right column) in a drop down from the header or on the nav bar, and are displayed according to the group settings.
  • Links Table - stores the URL links information. This table contains values and controls are for the "Links" page (i.e. a type of bookmarks and documents index page. Bookmarks from Firefox and Chrome web browsers can be imported into the sections (folders) table and links (URLs) table.
  • Sections Table - controls the links page layout so that links are sectioned/grouped together for display and access control.

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 var/backups/AppsCMS-Backup-cms.sqlite-YYYYMMDD-HHMMSS.gz | sqlite3 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 js.

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 can use these methods to authenticate users (in authentication order);-

  1. General global (all users) PAM authentication can be used by enabling the PAM authentication option in the install page. If PAM authentication is available, PAM is used to authenticate AppsCMS users against host system credentials. Where the AppsCMS username is also available on the host server system. If authentication fails, the AppsCMS defaults to attempting next authentication method.
    The PAM authentication requires the system PECL PAM package to be installation along with some extra configuration. Talk to your server administrator.
  2. Individual users can be selected to use host server PAM authentication by enabling the PAM authentication option in the user’s configuration. The user authenticates using the same methods as the the general global PAM authentication.
  3. The username and password can be authenticated against a LDAP/AD server by setting a user’s auth preferences to LDAP. If authentication fails, the AppsCMS defaults to attempting next authentication method.
    The LDAP/AD server is usually part of a larger organisation’s centralized authentication systems, and will require install settings from your server administrator.
  4. The username and password can be authenticated against AppsCMS user settings. If authentication fails, the AppsCMS, login has failed.
  5. Applications can have their own authentication systems. See Applications Authentication.

The web site has an "Admin->Search" function to aid finding configuration, setup and page contents. Search (and filters) can be by exact match (of anded keywords), phonetic (sounds like) or levenshtein (similar match). The phonetic and levenshtein have enable/disable options. When the user is not sure of the exact words, these extra filters help find the required link, although they do produce more results.

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.

A secondary data mine type database (i.e. filesystem based) in the "var/variables/users/" directory is used to hold transitory user data (e.g. login count, login timeout, etc.). This saves having to manage database changes in the sqlite database from transitory data when using Git or SVN document version control systems.

Security and User Privileges

AppsCMS has in inbuilt security and privileges scheme to allow or restrict access.

Here is a simplified logic diagram, "User Privileges Diagram";-

UserPrivileges

In the "User Privileges Diagram", the logic elements are centered around the "CMS Groups Table", with the exception of the "CMS Users Table" providing an enable for each user to be an "Admin".

To make interfacing to privileges code, status methods are included in the "Ccms_base" class hierachy. If the applications / body code follows the recommended use of extend classes, the these mothods will be available under the "self::" static calls. Here is the privileges status calls;-

  • "is_cms_guest();" - returns true if the user is guest (not a logged in user).
  • "is_cms_user();" - returns true if the user is a logged in user (including addmins and managers).
  • "is_cms_admin();" - returns true if the user is a logged in user with admin privileges (either as an admin user or through an admin group).
  • "is_cms_group_manager();" - returns true if the user is logged in and the user is a manager for the application / body group or links manager group.
  • "is_cms_apps_manager($user = []);" - returns true if the user is an application / body manager.
    This method has two methods of logic to determine the user›s privileges;
    • If the $user[] parameter is empty, the logic uses the logged user›s details, returns true if the logged in user is the current applications / body manager.
    • If the associative array "$user[]" parameter is not empty, the logic uses the user[] parameters to determine if the user is in the "cms_users" table, if so, it uses that users credentials to determine if this user (the user may not be a logged in) is the current applications / body manager to return true. This allows a user›s identity to be used to provide privilege information about a user on another functionality. An example of this is the "Ccms_appointments_plugin" which uses a separate user database for booking appointments, allowing privileged management of the appointments.
      The values in the associative array "$user[]" parameters are keyed like;-
      • " *id " - matches to the "cms_user_id" column in the "cms_users" table. The id value takes priority and no other column is needed (but the is not usually available).
      • " *email " - matches to the "cms_user_email" column in the "cms_users" table.
      • " *email_confirmed " - if email confirmation enabled (default), "cms_user_email_confirmed" column must be "true" in the "cms_users" table.
      • " *mobile " - matches to the "cms_user_mobile" column in the "cms_users" table.
      • " *mobile_confirmed " - if mobile confirmation enabled (default), "cms_user_mobile_confirmed" column must be "true" in the "cms_users" table.
      • " *name " - matches to the "cms_user_name" column in the "cms_users" table.

From the authentication methods it is possible to determine the active privileges of the user.

Confirmation Notes:

  1. If email confirmation is enabled (default), email confirmation is done in two ways.
    1. When the admin creates the user account, a confirmation email is sent to the user providing a code to enter to verify the email address. The admin can skip this step if required and the confirmation is done another way.
    2. When the user logs in, a confirmation email is sent to the user providing a code to enter to verify the email address.
  2. If mobile confirmation is enabled (default), SMS messaging is enabled, mobile confirmation is done in two ways.
    1. When the admin creates the user account, a confirmation SMS is sent to the user providing a code to enter to verify the mobile number. The admin can skip this step if required and the confirmation is done another way.
    2. When the user logs in, a confirmation SMS message is sent to the user providing a code to enter to verify the mobile number.
Using Read Only Installed Code

AppsCMS can be installed with read only filesystems for the "cms/", "apps/" and apps/bodies/" directories directories via squashfs filesystems. The two "(DOCROOT)/" files "cms_lib_sqsh.sh" (for CLI ops) and "cms_lib_sqsh.php" (for web code) control the mounting of read only files via AppsCMS.

Important Note: To access non PHP files (e.g images, css, etc.) in "cms/" and "apps/" read only directories, the Apache web server needs to run in "perfork" mode (i.e. not running in "MPM" multiprocessing mode).

  • The AppsCMS "cms/" is provided as part of the AppsCMS install.
  • To use read only filesystems for the "apps/" and apps/bodies/" directories need to follow coding schemas rules. The configurations and settings (and some configuration images) are saved in "etc/" directory. And variables (caches, logs, variables, etc.) are saved in the "var/" directory. The read only filesystems are in a independent format and cannot be written to, and also by root and administrator users cannot write to.
  • Developers can use the supplied "cms/cli/cms_wrap_apps.sh" script to build the "apps_fs_sqsh.sqsh" (from the "apps/" directory) to make a read only applications squashfs filesystem.
  • Distribution and installation of the "apps_fs_sqsh.sqsh" needs to implemented by the user. To allow the read only file systems to be mounted, the "apps/" directory needs to be removed.
  • For users mounting the read only filesystems for CLI use is done by the "./cms_lib_sqsh.sh" script. This script has options, check "./cms_lib_sqsh.sh --help". Also mounting the filesystems with the "./cms_lib_sqsh.sh" script allows the filesystems to be viewed by the local host user (but not the web user). Ideal for development and debugging sessions.
  • Mounting the read only filesystems for web operation use is done by the web code including "./cms_lib_sqsh.php" script. Usually the server will hide filesystems the from all users accept the server, so the users (including root) cannot see it. Another benefit of this that the PHP-FPM provides faster web access, giving a higher performance web site.
Minimum Server System Requirements

AppsCMS requires the following server requirements to operate;-

  • Linux operationg system (e.g. RedHat/Centos 7, SUSE/openSUSE 15, Ubuntu 18, or higher versions).
  • Apache 2.4.x 64 bit installed on LINUX (tested on CentOS 8.5, openSUSE 15.4 and Ubuntu 22), recommend using "prefork" mode for read only code.
  • PHP 8.0 64 bit (recommended, tested on 7.4 and 8.0)
    Installed packages: php php-bcmath php-json php-pecl php-devel php-dba php-zlib php-sqlite php-curl php-zip php-dom php-opcache php-pear php-ctype php-tokenizer php-openssl php-mbstring,
    Optionally packages: php-mysql php-pdo php-gd php-iconv php-posix/php-intl php-xdebug,
    Plus the web server PHP engagement packages (e.g. apache2-mod_php).
  • 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,

During installation and configuration rebuild, a list of required packages is output.

Typical Server System Configurations

Example Apache 2.4 Vhost Config

Example Apache 2.4 Alias Config

AppsCMS 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 and installer files do not come with user set files that over write user settings, if required "(DOCROOT)" files outside of "cms/" don’t exist (e.g. "index.php", "ajax.php", "api.php", "login.php" and "logout.php") the AppsCMS will generate default files. The "ajax.php" is not normally required nor used if the originating code is generated by the AppsCMS and calls "cms/cms_ajax.php" directly. For reference (and possible update), a copy of these distribution "(DOCROOT)" files is available in the "cms/docroot_files/". If changes are made to the default "(DOCROOT)" files, the changes can be checked against files in the "cms/docroot_files/" directory.
Note 4: The AppsCMS installer script file defaults to installing AppsCMS library in a read only mode (approx 11MB). If a full read/write install is required use the zip (approx 19MB).
Refer to the Installation Notes. or to Installation Notes Extract.

Important Note: The Apache web server will needed to be stopped and started after a read only install or update. The server will need to be totally disengaged (i.e. a full stop/start, e.g. service httpd stop && service httpd start). And if in use, the php-fpm service will need to be totally disengaged (i.e. a full stop/start, e.g. service php-fpm stop && service php-fpm start). The normal restart only reloads the web server configuration files and will not release the previous squashfs mounts.

The installation comes as a self installing bash script for LINUX and a ZIP file for general installations. Available on the "https://github.com/AppsCMS/AppsCMS_Latest/ " and on "https://appscms.org/dist-pkgs/ " web sites.

Here is a list of the downloads;-

  • "applications" - sample applications directory.
  • "cms/images" - local images for README.md, etc. directory
  • "doxy" - doxygen generated documentation directory.
  • "examples" - code examples directory.
  • "local_tools" - sample local tools directory.
  • "AppsCMS-Docs-V3.07.11-[release].svn[nnnn].noarch.rpm" - system RPM install package for documents and examples (used as read only filesystem mounts and are mounted at (DOCROOT)/ automatically if installed).
  • "AppsCMS-Library-Latest.sh" - latest library install script.
  • "AppsCMS-Library-V3.07.11.sh" - library install script.
  • "AppsCMS-Library-V3.07.11-[release].svn[nnnn].noarch.rpm" - library system RPM install package.
  • "AppsCMS-Library-Latest.zip" - latest library system zip file (source code).
  • "AppsCMS-Library-V3.07.11.zip" - library system zip file (source code).
  • "AppsCMS-version.info" - file version information.
  • "Installation.md" - AppsCMS installation notes.
  • "LICENCE.txt" - AppsCMS licence.
  • "README.md" - AppsCMS ReadMe text.
  • "ReleaseNotes.md" - AppsCMS release notes.
  • "RPM" - the RPM system package repository directory.

For full user and administration experience use a CSS3 and HTML5 compatible browser (e.g. Microsoft® Edge, Mozilla Firefox, Google Chrome, etc.).

The installation is in the "(DOCROOT)/" directory (the server file system directory, accessed/served by Apache, where the AppsCMS web apps are installed).

A guide to installing and updating AppsCMS follows;-

  • Login to the web server as the user the web site is setup with (usually the user is the domain e.g. somedomain.com).
    Do not log in as root, administrator or any other privileged user.
  • If updating, backup the web site.

  • Typical CLI Installer Output

  • Typical CLI Update Output

  • For a AppsCMS read/write install or update, unzip the AppsCMS zip file.
    • Use "unzip AppsCMS-{VERSION}.zip cms/* -d (DOCROOT)" to update the AppsCMS cms library directory.
    • The "index.php", "ajax.php", "api.php", "login.php" and "logout.php" files can be extracted as required." The read only control file "cms_lib_sqsh.php", "cms_lib_sqsh.sh" and "cms_lib_sqsh.md" should always be extracted.
    • The read only library code file "cms_lib_sqsh.sqsh" is not extracted in a read/write installation (i.e. the "cms/" directory has copy of the AppsCMS installed).
    • Use "unzip AppsCMS-{VERSION}.zip filename2unzip -d (DOCROOT)" to unzip the file.
    • NOTE: The unzip utility command overwrites files by default. Do a backup first.
  • Additionally, where there is several web sites using AppsCMS on the same host server, the AppsCMS system RPM package can be installed. This will allow the AppsCMS read only library to be mounted in the web site (DOCROOT) directory from a common library. The AppsCMS library package is installed in the "/usr/local/share/AppsCMS" directory. The AppsCMS system RPM package provide utilities;-
    • "AppsCMS-info" to provide information about the install library package.
    • "AppsCMS-engage" to install/update (DOCROOT) files to engage the AppsCMS system library.
  • 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 css.
    After approximately 20 to 60 seconds the rebuild will finish displaying status of the rebuild processes.
  • Click the "User: Login" link. When no users are setup, a default admin user is;-
    Username: admin
    Password: password
    Strongly recommend the default admin username be disabled after you have setup another admin, more secure, user (with admin rights).
    Login to the web site. On a fresh install you should see the about page. For a update you should your home page.
  • Suggest going to the Setup and Configuration section.

If failures and non functional issues occur, see Trouble shooting

  • "sudo cms/cli/cms_set_permissions.sh" correct any permission problems. (If sudo access is not available, you will need to get the a sudoer or root to run it.)
  • "cms/cli/cms_rebuild.sh" check and update (and rebuild if necessary) AppsCMS will check and make the directory structure and add missing app directoruies, regenerate the css themes, etc.

IMPORTANT NOTE: The settings in the INI files for the AppsCMS and for applications in the "etc/ini/cms.ini" and the "etc/ini/apps.ini" files are read after the configuration DB values, in the Ccms::__construct() method (i.e. in the same code block).

SVN and Git AppsCMS and Applications Install and Update

Supplementary to installing from a shell install script or update from a zip file or remote AppsCMS repository, it is recommended for the AppsCMS and application installations and updates from SVN and Git repositories to run the web applications, it is recommended to execute the following scripts;-

  • First run "./cms_lib_sqsh.sh". This will mount any read only filesystems.
  • Second run "sudo bash -e cms/cli/cms_set_permissions.sh". This will set permissions for shell and web server access.
  • Third If a version less than V3.00 is in use, run "cms/cli/upgraders/cms_upgrade_appsV300.sh", to make changes required (and make the changes if requested, see --help) in code and settings.
  • Fourth If a version less than V3.03 is in use, run "php cms/cli/upgraders/cms_upgrade_cms_configs_V303.php", to make changes required in applications.
  • Fifth If a version less than V3.05 is in use, run "cms/cli/upgraders/cms_upgrade_V305.sh", to detect changes required (and make the changes if requested, see --help) in applications.
  • Sixth run "bash -e cms/cli/cms_rebuild.sh". This will build the latest settings, configuration DB and directory structure for this AppsCMS version. Run update scripts effecting constants, variables and locations (see --help for more info).

Important please more information section.

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, panel drop boxes are used to display tool and administration links. The header is identified by the HTML by <div id="cms_lo_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_lo_left_column">...</div>
  • "Right Column" - when enabled and displayed, occupies the right side of the window between the header and footer. The right column displays tool links and administration links. If no tools are setup and no user is logged in, the right column is not displayed. The right column can be turned off, then the tools and adminstration links are displayed in the left column. If the left column is turned off the right column is also turned off and other means are used to display tool administration link, either in the header or in the navigation bar. The right column is identified by the HTML by <div id="cms_lo_right_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_lo_nav_bar">...</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 js 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">...</div>. Inside the page body <div> there are sub "<div>s" for HTML page body control and access.
  • "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_lo_footer">...</div>

IMPORTANT NOTES:

If the navigation bar is enabled it takes priority over layout options.

If no navigation bar, left column or right column layouts are selected, the layout generator uses the default layout and places the "Menu", "Tools" and "Admin" drop down panels in the header to provide user interaction.
NOTE: If a custom header is provided in this layout configuration, the programmer needs to provide for user interaction.

For "tiny" devices (e.g. small screen devices, mobile phones, etc.) the layout uses the default layout.

For "tablet" devices use the layout as configured. Except AppsCMS allows the tablet to treat the first touch on the drop down as an open click.

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.

The AppsCMS settings are stored "etc/ini/cms.ini". The applications settings are stored in "etc/ini/apps.ini". The INI files are editable text files that can be changed in case of problems (typically during application development). Usually these values are changed through the "Admin" -> menus (which requires a AppsCMS system administrator to allow changes).

The AppsCMS configuration is stored in a database (SQLite by default or MySQL). These configuration values are permanent settings (e.g. support email, web site name, contact details, plug-in configs, etc.) and can be considered like hard coded values, and only changed through the "Admin" -> menus (which requires a AppsCMS system administrator to allow changes).

Applying Run Time Settings and Configurations

The AppsCMS provides the mechanisms for run time definition of constants;-

  • All settings and configuration values are defined when "https://your.web.site/site_alias/index.php[?optional_parameters]" is engaged. As all operations URLs generated by the AppsCMS contains the parameters for the required operation. And consequently the run time definitions are defined as part of the normal processing.
  • When calling AJAX operations through the "https://your.web.site/site_alias/cms/cms_ajax.php?parameters" the AppsCMS AJAX pre-processor defines the settings and configuration values.
  • When calling web sockets operations with the "WS Redir Enable"=true, the AppsCMS (DOCROOT)/.htaccess contains the websocket redirect configuration.
  • However, in some cases the standard "index.php", "ajax.php", "api.php", "login.php" and "logout.php" URIs may not be appropriate (typically CLI code), the best way to get the settings and configuration values defined is to;-
    require_once ( preg_replace('/\/(apps|cms)\/.*$/','',__DIR__) . '/cms/cms_init.php' );

    at the top of the opening PHP file. This will provide the minimum run code for setting up definitions.

The AppsCMS provides the five types of definitions identifiable by the prefixes in order of execution;-

  • "CMS_S_" are the AppsCMS settings from the "etc/ini/cms.ini" settings file. The first definitions to get engaged at run time are in "etc/ini/cms.ini".
    Important Note: If the "etc/ini/cms.ini" settings file is edit manually and the changed values are used in the generation, a rebuild maybe requires to engage the settings. Any theme settings will need a rebuild to engage (run "./cms_lib_sqsh.sh -r" from the command line).
  • "CMS_C_" are the AppsCMS configuration values from the database "cms_configs" table. The second definitions to get run time code. These are in SQLite ("etc/sqlite/cms.sqlite" or MySQL) AppsCMS database.
  • "LM_C_" are the AppsCMS "Links Manager" configuration values from the database "cms_configs" table.. And are not used by applications. These are in SQLite ("etc/sqlite/cms.sqlite" or MySQL) AppsCMS database.
  • "APPs_(APP_NAME)_" (i.e. lowercase "s") are the standard applications constant derived from the AppsCMS database "cms_bodies" table.
    NOTE: Changing name and directory values in the "Admin->Apps / Bodies" menu will require changing definition constants in the code.
  • These are in "apps/include/apps_config.php" are the common applications settings.
  • The last definitions to get run time code. These are in "apps/(APP_DIR)/include/app_config.php" are an individual application settings. Note: only the requested app’s "apps/(APP_DIR)/include/app_config.php" file is executed (providing variability in definition).
  • These are in "apps/include/apps_head_inc.php" contains the common <<head> includes for applications. (optional)
  • These are in "apps/(APP_DIR)/include/app_head_inc.php" are an individual <<head> includes for application settings. These are included last at run time. Note: only the requested app’s "apps/(APP_DIR)/include/app_head_inc.php" file is executed (providing variability in definition).
  • "public static function &get_head_text()" returns an array of text (meta values, etc.) to be checked for duplicates and inserted into the "<head>" to "</head>" section. For example;-
    		protected static $my_head = array(
			// type => data text arrays
			'title' => 'My Page Title',	// a new title to use
			'meta' => array('name="generator" content="From Me"','name="author" content="Me"', ... ),	// an array()
			'link' => array('rel="stylesheet" href="path/to/my/styles.css"', ... ),	// an array()
			'script' => array('type="text/javascript" src="path/my/js.js"', ... ),	// an array()
			etc.
			);
		return $my_head;	// it's a reference (i.e. static)

    Or a text string (not recommended) to insert into the "<head>" to "</head>" section.

Notes on Recommended Mode Definitions;-

  • For code running in command line (CLI) mode it is recommened that "CLI_MODE" is defined as "true". This improves CLI operation and reduces the run time over head.

As a system administrator and with the debug mode enabled, the defined values at run time can found (and there definition) in the "Admin->Debug Values" page.

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 "/home/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.
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 application base directory. See Directory Structure for directory information.
  • "apps/bodies/" - the application control directory. This directory has the initial code files (referred as "body files") or links for each application. For most applications, the code file may contain some configuration code and/or an include statement to code in the "apps/" directory.
  • " apps/include/" - common application code include directory.
  • "apps/include/apps_manual.php" - a common technical manual for all applications. There is an example file, "apps/include/example_apps_manual.php". Each application with a "(APP_DIR)" directory can have a manual configuration value in the application configurations, "Admin->Apps / Bodies", configuration page.
  • "apps/include/classes/" - the general applications classes directory (the autoloader looks in here for general apps classes).
  • "apps/include/plugins/" - the general applications plugins directory (the autoloader looks in here for general apps plugins).
  • "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/apps_rebuild.php" - used to check and rebuild the apps as required (optional). There is an example file, "apps/include/example_apps_config.php"
  • "apps/include/ini/" - the ini directory (the settings and install pages look in here).
  • "etc/ini/apps.ini" - the combined applications settings (one file to speed normal access).
  • "apps/include/ini/apps.defaults.ini" - the common default applications related settings.
  • "apps/include/ini/apps.comments.ini" - the descriptions/help text of common applications related settings.
  • Important Note: The "etc/ini/apps.ini", "apps/include/ini/apps.defaults.ini" and "apps/include/ini/apps.comments.ini" cannot contain values that are defined constants. The global constants are being defined when these files are being executed at runtime.
  • "apps/cli/" - common applications command line code.
  • "apps/lib/" - common applications library code.
  • "apps/icons/" - common applications icons (the icon selector will list icons in this directory).
  • "apps/images/" - common applications images (the image selector will list images in this directory).
  • "apps/js/" - common applications js code.
    • "apps/js/apps.js" - common applications js code, added by application author. The AppsCMS inserts a js link to the "apps/js/apps.js" file in the <head> html, loading the js file automatically for all applications.
  • "apps/css/" - common applications css (.css and .scss code).
    • "apps/css/apps.css" - static common applications stylesheet. The AppsCMS inserts a stylesheet link, using the minify plugin generated link, into the <head> html, loading the stylesheet automatically for all applications.
    • "apps/css/apps.scss" - static common applications stylesheet source code (.scss). The AppsCMS inserts a stylesheet ".scss" is compiled using the minify plugin (on the fly). The minify plugin returns a cached .css file link which is inserted into the <head> html, loading the stylesheet (.css) automatically for all applications.
  • "apps/include/apps_css.php" - application specific theme recipe file. If present, is the inputs to theme taken from the "(APP_KEY)_ThemeSettings" section of the "apps/(APP_DIR)/ini/app.comments.ini" values. This is used to generate the "etc/css/(APP_NAME)_app.css" file. When the the application is called the AppsCMS inserts a stylesheet link to the "etc/css/(APP_NAME)_app.css" file link in the <head> html, loading the stylesheet automatically.

Applications with an "apps/(APP_DIR)/" directory have these individual application directories created for it. "(APP_DIR)" being the app directory name (or rename) given to the application. The "(APP_DIR)" directory provides modularity and separation to applications. And to allow automated application install and uninstall.
NOTE: Applications can be allowed to share the same application directory ("Admin->Config->CMS_C_ALLOW_APPS_DIR_SHARE").

  • "apps/(APP_DIR)/include/" - application specific include directory.
    • "apps/(APP_DIR)/include/app_config.php" - application specific fixed configurations (the AppsCMS includes this file "Admin->Apps Config" menu if present).
  • "apps/(APP_DIR)/classes/" - application specific classes directory (the autoloader looks in here for app specific classes).
  • "apps/(APP_DIR)/plugins/" - application specific plugins directory (the autoloader looks in here for app specific plugins).
  • "apps/(APP_DIR)/ini/" - application specific configuration.
    • "apps/(APP_DIR)/ini/app.comments.ini" - application menu control and help file (the AppsCMS places these configs in the "Admin->App Config" menu).
    • "apps/(APP_DIR)/ini/app.defaults.ini" - application default values file (the AppsCMS uses these values as default config values in the "Admin->App Config" menu if present).
    • The "app.comments.ini" and "app.defaults.ini" are always used as a pair. The configured values are stored in the "etc/ini/apps.ini" and are defined as global constants prefixed by "APP_(APP_KEY)_". The comments and values appear in the results in the "Admin->Search".
    • The "apps/(APP_DIR)/ini/" may have an applications specific control JSON file here. It is not assumed to be configured through the AppsCMS menus and would be accessed by the applications.
  • "apps/(APP_DIR)/cli/" - application specific command line code.
  • "apps/(APP_DIR)/lib/" - application specific library code.
  • "apps/(APP_DIR)/icons/" - application specific icons (the icon selector will list icons in this directory).
  • "apps/(APP_DIR)/images/" - application specific images (the image selector will list images in this directory).
  • "apps/(APP_DIR)/js/" - application specific js code.
    • "apps/(APP_DIR)/js/app.js" - application specific js code, added by application author. When the the application is called the AppsCMS inserts a js link to the "apps/(APP_DIR)/js/app.js" file in the <head> html, loading the js file automatically.
  • "apps/(APP_DIR)/css/" - application specific css (.css and .scss code).
    • "apps/(APP_DIR)/css/app.css" - static application specific stylesheet. When the the application is called the AppsCMS inserts a stylesheet link, using the minify plugin generated link, into the <head> html, loading the stylesheet automatically.
    • "apps/(APP_DIR)/css/app.scss" - static application specific stylesheet source code (.scss). When the the application is called the AppsCMS inserts a stylesheet ".scss" is compiled using the minify plugin (on the fly). The minify plugin returns a cached .css file link which is inserted into the <head> html, loading the stylesheet (.css) automatically.
  • "apps/(APP_DIR)/include/app_css.php" - application specific theme recipe file. If present, is the inputs to theme taken from the "(APP_KEY)_ThemeSettings" section of the "apps/(APP_DIR)/ini/app.comments.ini" values. This is used to generate the "etc/css/(APP_NAME)_app.css" file. When the the application is called the AppsCMS inserts a stylesheet link to the "etc/css/(APP_NAME)_app.css" file link in the <head> html, loading the stylesheet automatically.
  • "apps/(APP_DIR)/include/app_scss.php" - application specific theme recipe scss source code file. If present, is the inputs to theme taken from the "(APP_KEY)_ThemeSettings" section of the "apps/(APP_DIR)/ini/app.comments.ini" values. This is used to generate the "etc/css/(APP_NAME)_app_sass.css" file. When the the application is called the AppsCMS inserts a stylesheet link to the "etc/css/(APP_NAME)_app.css" file link in the <head> html, loading the stylesheet automatically.

The "Admin->App Config" -> checks to see if a "apps/css/apps_scss.php" is present. If so the save process generates a "etc/css/apps_sass.css" from the "apps/css/apps_scss.php" for use in application web pages. This can be used to set extra theme or branding settings into the applications style sheet. See example_apps_scss.php" in the examples for help.

The "Admin->App Config" -> checks to see if a "apps/css/apps_css.php" is present. If so the save process generates a "etc/css/apps.css" from the "apps/css/apps_css.php" for use in application web pages. This can be used to set extra theme or branding settings into the applications style sheet. See example_apps_css.php" in the examples for help.

The application installation check method "public static function do_app_warnings($bld = false)"
Optional method in the application’s top class (e.g. "/home/vhosts/appscms.org/public_html/apps/(APP_DIR)/classes/(APP_NAME)_app::do_app_warnings()"). If present the do_app_warnings() method is called when an admin logs in. This can be used to check the application has all the system packages, directories, etc. it needs to operate. If $bld is true, the method is being called from the rebuild so the app should initialise as required.
NOTE: The top (or primary) application class needs to conform to "_app"e; class name suffix.

The application post ini settings saved method "public static function do_app_ini_saved()"
Optional method in the application’s top class (e.g. "/home/vhosts/appscms.org/public_html/apps/(APP_DIR)/classes/(APP_NAME)_app::do_app_ini_saved()"). If present the do_app_ini_saved() method is called after an admin saves the application config page. This can be used to make changes to an applications runtime configuration (e.g. reset caches, generate API URLs, etc.).
NOTE: The top (or primary) application class needs to conform to "_app"e; class name suffix.

The "etc/ini/apps.ini", "apps/include/ini/apps.defaults.ini" and "apps/include/ini/apps.comments.ini" global (all applications) configuration files that are used together to a connection between help messages, default values and the config values. Values in "apps/include/ini/apps.comments.ini" containing defined constants are repleaced with the defined values. (Use the "etc/ini/cms.ini", "cms/include/ini/cms.defaults.ini" and "cms/include/ini/cms.comments.ini" files as an example.) Values in "cms/include/ini/cms.comments.ini" containing defined constants are repleaced with the defined values. 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. Values in "apps/include/ini/example.apps.comments.ini" containing defined constants are repleaced with the defined values.

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 available in the "examples/AppsCMS-Examples-V3.07.11.zip" download to help show how to best these features of the AppsCMS.

Applications responding to API application calls can be engaged by the user povided "apps/api.php" or by "apps/(APP_DIR)/api.php" files. If present these application code files are checked by default after AppsCMS calls are checked.

Applications with API maps provide the summary map array by calling /home/vhosts/appscms.org/public_html/apps/(APP_DIR)/classes/(APP_NAME)_app::get_api_map();". The format can be Swagger V2.0 or AppsCMS format. The AppsCMS outputs the summary in Swagger V2.0 format, taking into account the role required to request each API call. See API Operation for more information.

Types of Applications

Application types in AppsCMS;-

  1. Close Coupled Application (Type 1)
    This application has its code intimately bound to other applications (and possibly to the AppsCMS library). This type loses modularity because of the close relationship with other applications. The AppsCMS supports application API server calls. The application usually has most of its code in "apps/(APP_DIR)/" directory or in the "apps/bodies/" directory. Cron available. API available.
  2. Simple Application (Type 2)
    A simple application with code in one file in the "apps/bodies/" directory. The simple application has no API support for API server calls. It uses the AppsCMS library functionality to minimize code requirements.
  3. Standard Application (Type 3)
    A standard application has all of its code in the "apps/(APP_DIR)/" directory. The application "body file" in "apps/bodies/" usually provides a hook, include or link to the application code in "apps/(APP_DIR)/" directory. This makes a modular application that is independent of other applications and AppsCMS library. It may or may not use the AppsCMS library functionality (leaving the AppsCMS to provide basic access control). Although in most cases the AppsCMS base classes are usually engaged to provide base line functionality from the AppsCMS library. The AppsCMS supports application API server calls. Standard modular is an independent application in its own application "apps/(APP_DIR)/" directory. Standard application has the AppsCMS standard directory allowing ajax, API and crom interfacing to the application by the AppsCMS. Standard applications have independent CRON job settings. Cron available. API available.
  4. Linked Application (Type 4)
    A linked (i.e. symlinked) application lives by itself (for the most part) but can use most of the AppsCMS library functionality (including global variables, plugins and classes). The AppsCMS library passes operation to the linked application after checking required credentials, etc. The link is usually a symbolic link (e.g. MyAPP.php -> /some/dir/code.php) into the "apps/bodies/" directory and does not have any code in the docroot structure. The linked application has no API support for API server calls. Some extra web server settings (e.g. FollowSymLinks option - often on by default) will be required to run this type of application.Linked (or symlinked) independent application in its own location.
  5. Basic Application (Type 5)
    A basic application has most of its code in the "apps/(APP_DIR)/" directory. The application "body file" in "apps/bodies/" usually provides a hook, include or link to the application code in "apps/(APP_DIR)/" directory. This makes a modular application that is independent of other applications and AppsCMS library. It may or may not use the AppsCMS library functionality (leaving the AppsCMS to provide basic access control). Although in most cases the AppsCMS base classes are usually engaged to provide base line functionality from the AppsCMS library. The AppsCMS does not support application API server calls. Basic modular is an independent application in its own application "apps/(APP_DIR)/" directory. Basic application does not have/need the AppsCMS directory like a standard application. The AppsCMS only provides the "apps/(APP_DIR)/" directory. The AppsCMS does not support for CRON job settings. Basic applications are more suited js frameworks (e.g. vueJS, AngularJS, etc.) having an empty "apps/(APP_DIR)/" directory.

When the app / body is created or edited, the recommended sub-directories for the type of application are checked / created when saved. When an application directory is changed then the application directory is moved to the new directory.

When an application is used, the defined constants for the application directories are also generated, negating the need to manually create them (see "Admin->Debug Values"). These auto-generated body / app constants are prefixed with "APPs_" to distinguish them from the fixed/standard constants (standard constants/defines are prefixed with "APPS_" or "APP_") (i.e. "APPs_FS_*" for filesystem access and "APPs_WS_*" for web access).

Primary Application Class

All applications can have a primary application class. For standard applications and close coupled applications the class is located in the "apps/(APP_DIR)/classes/(APP_NAME)_app.php" PHP source file. For other applications the class is located in the "apps/include/classes/(APP_NAME)_app.php", the C(APP_NAME)_app PHP class source file code.

The C(APP_NAME)_app class, the primary application class provide hierarchical access to the following optional methods;-

  • "public static function get_ajax_text($ajax)"
    Executes the applications AJAX code.
    Optional method.
  • "public static function get_ws_text($wsid,$op)"
    Executes the applications WebSockets code.
    Optional method.
  • "public static function do_app_warnings()"
    Checks the application requirements when the user logs in.
  • "public static function is_app_setup_key_funcs_used($key)"
    The "Admin->Apps Config" menu calls this method (function) for every KEY in the "apps/(APP_DIR)/app_comments.ini" If not required for this $key, the method returns false; Else the method returns true.
    Required if "show_app_setup_value()" or "input_app_setup_form_text()" or "get_app_setup_form_value()" is in use. Otherwise an optional method.
  • "public static function show_app_setup_value($sect,$key,$name,$value)"
    The "Admin->Apps Config" menu calls this method (function) for every KEY=VALUE pair in the "apps/(APP_DIR)/app_comments.ini" If not required for this $key, the method returns false; Else the method generates text to show the $value for $key.
    Used as "_show_func" similar to JSON format. Optional method.
  • "public static function input_app_setup_form_text($sect,$key,$name,$value)"
    The "Admin->Apps Config" menu calls this method (function) for every KEY=VALUE pair in the "apps/(APP_DIR)/app_comments.ini" If not required for this $key, the method returns false. Else the method generates form input element text to input the $value for $key using $name for the input element.
    Used as "_form_input_func" similar to JSON format. Optional method.
  • "public static function get_app_setup_form_value($sect,$key,$name,$value)"
    The "Admin->Apps Config" menu calls this method (function) for every KEY=VALUE pair in the "apps/(APP_DIR)/app_comments.ini" If not required for this $key, the method returns null (i.e. no input from form) Else the method gets the input element under $name from the posted form returns the value text to be saved.
    Used as "_form_get_func" similar to JSON format. Optional method.
  • "public static function &get_ini_app_input_ctl()"
    This method provides access to a HTML input generator for the applications INI settings to allow the application to. control (possibly generate if 'options_func' is provided) the form input elements. An example of the returned control array is;-
    		protected static $my_ini_ctls = array(
			'MY_CUSTOM_COLOURS' => array(	// ini_key to match
				'type' => 'multi_input',	// input or multi_select
				'col_heads' => 'Name:Hex RGB Colour',	// e.g. "Name" is first column heading : "Hex RGB Colour" is second column heading, etc.
				'val_sep' => ':',	// separator used values
				'data_sep' => '=',	// separator between name and value (e.g. name=>value), optional
				'options_func' => 'get_my_custom_colours_options',	// method name to use in the primary application class, optional.
				),
			// etc,
			);
		return $my_ini_ctls;	// it's a reference (i.e. static)
  • "public static function &get_api_map_summary()" for API mapping. See API Operation.
Languages

The AppsCMS is capable of translating HTML text. The language translation can be on an application/s or all applications.

Administration page for AppsCMS are always presented in the en-AU language, so any conflicts can resolved without showing in a language that can be read.

API Operation

The AppsCMS has a basic API front end for processing API requests. The AppsCMS has internal API calls available for admin and information and documentation. Admin requests are protected by a token provided that is generated by the AppsCMS. Informational API requests for open (non secured) data don’t need a token.

To access the API, the API interface must be enabled, the user must login as an administrator or login as a user with API access enabled.
Important Note: API operation requires the Apache rewrite module to be enabled. If not enabled, the "Admin->API Test" generates "Failed to load API definition." error.

The AppsCMS API interfaces use security tokens in the requests header and the response headers, and are not exposed through variables in "GET", "POST", "PUT", etc. Where the API client sends a session ID, the ID is used as the security token (similar to a web page), via the session cookie. This makes the API easier to use via web pages and ancillary network processes tied to a web page. If no session ID is available, the AppsCMS API will generate a unique security token to use.

The AppsCMS API can be changed by modifying or replacing the "/api.php" code.

All API requests and responses are by secure protocols (i.e. https/SSL).

API summary call maps makes the API self documenting.

An API mapping function, "public static function &get_api_map_summary()", in the Primary Application Class is used by the AppsCMS to obtain the API summary map from the application. The return value is an array that has the following minimum requirements for the API call. Here is an example of the return summary map for an application;-

Example API Map

The AppsCMS API interface can usually provide the correct defaults for the other details. The correct use of headers also will negate the need for details summary maps, as the header Content-Type, etc. will override the summary map. For most situations a complete summary/resource map is for the user’s API client, so the level of detail for user requirements.

IMPORTANT NOTE: The "path" variable will be prefixed with the (APP_NAME) by the AppsCMS in the global summary map.
When the AppsCMS is rebuilt or when installation/configuration is saved, the AppsCMS requests API summary updates from allowed applications.

Provided the API is enabled, see functional API client example;-

  • Click "Admin->API Test". This provides a "Swagger UI" from the "Swagger" distribution bundle installed as a library.
  • The download "examples/API_client-V3.07.11.zip" file contains a basic command line API client example.
API Authentication and Authorization.

The AppsCMS API can use these API authentication and authorization methods. See "Admin->Config->CMS_C_API_AUTH" to select.

  • "Session Cookie" - Session cookie authentication (always enabled) is for access to a single endpoint/server. The session cookie uses a browser session ID (SID) in the session cookie to authenticate access. The SID is passed back and forth between the client and server. The session cookie authentication is the commonly used by browser <-> server authentication, often used with web site authentication. With this method, "API_key" value is in the headers.
  • "JSON Web Token" - The JSON web token (JWT) authorization can be used and can provide authorisation to a multiple endpoints/servers.
    • For JWT, it is recommended that AppsCMS only uses SSL algorithms, using a private key and public key (OpenSSL) for authorization. (see "Admin->Config->CMS_C_JWT_ALG" to configure). A new SSL JWT uses new SSL private key and public key pair is generated for each API authenticated user. This is highest security available because after the JWT signature is generated, the private key is deleted, making it practically impossible to reproduce the same JWT. Only the public key is required authorize the API access. The user’s public key is saved on AppsCMS server. This means the authenticated user must be available on the AppsCMS server, has a user’s public key and the JWT can be authorised using the users’s public key.
    • For non OpenSSL JWT signatures are unique for each user. But security is much lower than using OpenSSL algorithms.
    • The JWT is not perpetual, it currently expires after a 1440 hours (see "Admin->Config->CMS_C_JWT_EXPIRE_HRS" to configure).
    • The JWT is POSTed back the API client under the "JWT" index, to use for subsequent authorisations.
    • To share authorization access to multiple endpoints, only the public key needs to be shared between endpoints.
    • If JWT is enabled, an API "/session/open" call returns a JWT in the response. All other API calls that contain a JWT in the request are authorised by the JWT. The JWT identifies the user on the AppsCMS server, therefore the user’s role and access rights are part of the JWT. And the AppsCMS server does not need (or use) session storage.
    • An optional user signature can be included in the JWT. (see "Admin->Config->CMS_C_API_USER_SIG" to configure, enabled by default). Having the user’s signature included in the JWT means that the user’s information at each API endpoint must be identical and unchanged (including the user’s modified timestamp).
    • To aid the propagation of a user’s public_key and configuration, a list of API endpoints can be used. (see "Admin->Config->CMS_C_API_ENDPOINTS" to enter endpoints). The endpoints are update when a user/client authenticates (new public_key) or when the user’s signature (if enabled) changes.
    Important Note: Tampering with the JWT will render the JWT useless. The JWT will no longer authorise against the public_key on the endpoint.
Web Sockets
@TODO rewrite section

The AppsCMS provides settings and configuration values for websockets redirection to connect the client to the websockets daemon/server running the applications real time code.

Access (DOCROOT)/.htaccess File

To use the AppsCMS API, it is required that some form of rewrite from virtual folder (the API path is a virtual folder location) to a PHP file. The following insert to the (DOCROOT)/.htaccess file is recommended;- 

					
########### AppsCMS (DOCROOT)/.htaccess insert begin #########################
#
# Generated by AppsCMS V3.07.11 from configuration/settings and for manual insertion into (DOCROOT)/.htaccess

# ensure PHP handler is engaged
<FilesMatch \.php>
	SetHandler application/x-httpd-php
</FilesMatch>

DirectoryIndex index.php

# global PHP settings.
	php_value max_execution_time 30
	php_value memory_limit 128M
	php_value post_max_size 8M
	php_value max_file_uploads 20
	php_value upload_max_filesize 2M


<IfModule mod_security.c>
	SecFilterEngine Off
	SecFilterScanPOST Off
</IfModule>

<IfModule mod_rewrite.c>

	RewriteEngine On
	# RewriteCond %{HTTPS} off
	# RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

	# API disabled

	# redirect/upgrade client websocket connections
	# optional need firewall 9504 port opened for non local redirect
	RewriteCond %{SERVER_PORT} "-eq 9504"
	RewriteCond %{HTTP:Connection} Upgrade [NC]
	RewriteCond %{HTTP:Upgrade} websocket [NC]
	RewriteRule /(.*) ws://127.0.0.1:9504/$1 [P,L]
	# Note: ws_ip and port need to the same as configured in Admin -> Install -> WS_REDIR_SVR_IP and WS_REDIR_HTTP_PORT

	# If the request is a file, folder or symlink that exists, serve it up
	# else direct to index.php
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-l
	RewriteCond %{REQUEST_FILENAME} !-d
	RewriteRule .* index.php [L]

</IfModule>

# running "./cms_lib_sqsh.sh --rebuild-all" in the (DOCROOT)/ directory will set all directories .htaccess files and index the class autoload data.
# no need to limit access at (DOCROOT)/ here
<Files "*">
	Require all granted
</Files>

########## AppsCMS (DOCROOT)/.htaccess insert end ##########################

Plugins

NOTE: Plugins have an important difference to classes (although a plugin is a class), in that a plugin has its own set of configuration features.

Users defined plugins can be placed in "apps/include/plugins" or in the "apps/(APP_DIR)/plugins/". The plugin class needs to be extended from the "Ccms_plugin_base" class (e.g. "class Cmy_plugin_class_name extends Ccms_plugin_base", The "C" prefix is a convention adopted in the "AppsCMS" for classes and plugins.). 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 upon reading the autoloaded class file.

AppsCMS V3.07.11 provides the following included plugins in the "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.
    • 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).
  • GeoIP - finds the geographical location of a IP address using a users’s Maxmind credentials.
  • Translate - a language translation and cache plugin.
  • Minify - a js (JS) and stylesheet (CSS) minifier/compressor.
  • Appointment booking calendar - provides a basic appointment/scheduler with SMS (when enabled) and email notification.
  • SMS messaging - provides an SMS messaging interface for SMS notification. Requires configuration values from a provider.
Plugin Extensions

Plugins can have extensions used to add entry/s to the "Admin" menu and to the "Main Menu" menu. The "Main Menu" menu items can be selectively added to the navigation bar, left column or right column.

The plugin can 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;- 
    	{
		"app_name": "(APP_NAME)", (required, can be plugin class name on the common apps extensions).
		"app_dir": "(APP_DIR)", (optional, not present on the common apps extensions).
		"app_uri": "(app_uri)", (optional, e.g."index.php?app=4" where 4 is the app/body ID or (APP_NAME), not present on the common apps extensions).
		"0":{
			"text": "Setup App Config",
			"uri": "index.php?app=(id/(APP_NAME)/(APP_DIR)&admin_params ... ", (URL direct to to page with parameters)
			"func": "someClass::getConfig", (or callable class::method or function, no 'uri' element)
			"title": "Setup App Configuration ..." (optional)
		},
		"1":{
			"text": "Setup App Something",
			"uri": "index.php?app=(id/(APP_NAME)/(APP_DIR)&other_admin_params ... ", (URL direct to to page with parameters)
			"func": "someClass::getOtherConfig", (callable class::method or function, no 'uri' element)
			"title": "Setup App Something ...", (optional)
			"params": "Array of key = value params passed to callable methods/functions (optional)."
			"app_name": "(APP_NAME)", (optional, used by uri, as required)
			"app_dir": "(APP_DIR)", (optional, used by the AppsCMS to include the application CSS and JS files)
		},
	}
  • "public static function get_menu_uris()"
    to provide application entries to the left column, right and navigation bar selectively. The entries are used as part of the selection lists. The returned values are an array. For example in JSON form;- 
    	{
		"app_name": "(APP_NAME)", (required, can be plugin class name on the common apps extensions).
		"app_dir": "(APP_DIR)", (optional, not present on the common apps extensions).
		"app_uri": "(app_uri)", (optional, e.g."index.php?app=4" where 4 is the app/body ID or (APP_NAME), not present on the common apps extensions).
		"always": true	(true = always show, don't filter)
		"0":{
			"role": "admin|manager|user|(empty|public)", (optional, sets level of access to menu item, else follows page settings)
			"text": "Get Transactions",
			"uri": "index.php?app=(id/(APP_NAME)/(APP_DIR)¶ms ... ", (URL direct to to page with parameters)
			"func": "someClass::getTransactions", (or callable class::method or function, no 'uri' element)
			"title": "By account ..." (optional)
		},
		"1":{
			"role": "admin|manager|user|(empty|public)", (optional, sets level of access to menu item, else follows page settings)
			"text": "Import transactions",
			"uri": "index.php?app=(id/(APP_NAME)/(APP_DIR)&other_params ... ", (URL direct to to page with parameters)
			"func": "someClass::someOtherMethod", (can be a URL or a callable class::method or function, no 'uri' element)
			"title": "Import CSV or XML file", (optional)
			"params": "Array key = value params passed to callable methods/functions (optional)."
			"app_name": "(APP_NAME)", (optional, used by uri, as required)
			"app_dir": "(APP_DIR)", (optional, used by the AppsCMS to include the application CSS and JS files)
		},
	}
  • Notes:
    • Local URLs are with reference to <base href meta data in the page header.
    • There is no limit to the number of admin URIs except for the ability to fitted them on the window.
    • The variable name "body" is interchangeable with the variable name "app" in URIs.
  • "public static function read_app_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_app_settings_ini()"
    Is used to 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.
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_app_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 js, 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 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 Apache Manual" in the "localtools/" directory, where "/var/www/manual" is the path to the Apache Manual web pages.

To help separate images and icons for tools, that are not part of the tool files, two directories are for tool images and icons used by AppsCMS, usually for menus, etc.

  • "localtools/" base directory for local tools.
  • "localtools/images/" directory is used for local tool images. Images used by the tool are also packaged when building a tool package.
  • "localtools/icons/" directory is used for local tool icons. Icons used by the tool are also packaged when building a tool package.

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

WYSIWYGs

The AppsCMS can use WYSIWYG HTML page editors. WYSIWYGs are configured by using the AppsCMS WYSIWYG configuration editor. Use "Admin->Search->WYSIWYG" to find configuration. WYSIWYGs are installed in the "apps/lib/" library directory as a third party library. There is a simple default configuration in the "/home/vhosts/appscms.org/public_html/etc/ini/cms_wysiwyg.json" file.

The AppsCMS WYSIWYG configuration element are;-

  • title - Title for WYSIWYG (not the name).
  • type - Type of WYSIWYG, select from browser, system, library or custom.
  • comment - A general comment about the WYSIWYG.
  • library_uri - An initialisation URI (typically to js, php, etc.) to setup the WYSIWYG (provided by WYSIWYG,optional).
  • engage_class - WYSIWYG engagement class. Used to extend the AppsCMS base WYSIWYG "Ccms_wysiwyg" class for more customisation. Typically, the "engage_class" overrides the "library_uri" and "engage_uri", and the "library_uri" and "engage_uri" are empty. However, if the "library_uri" and "engage_uri" have values, the AppsCMS base "Ccms_wysiwyg" class will still engage these values.
    The "engage_class" is used to extend the AppsCMS "Ccms_wysiwyg" class. The WYSIWYG code execution then uses to "engage_class". The "engage_class" is usually custom code written for the particular WYSIWYG. If no "engage_class" is available, the AppsCMS falls back to using the "library_uri" and "engage_uri" values.
    Note: if not overridden by the "engage_class", a <textarea> with a id and name of "ws_text_area" containing the html to be edited by the WYSIWYG editor is generated.
  • engage_uri - The URI (typically js, php, etc.) to engage the WYSIWYG (usually a custom script,optional).
  • configurable - Boolean true/false value to indicate the WYSIWYG in configurable.
  • enabled - Boolean true/false to indicate whether the WYSIWYG is enabled.
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?cms_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/sitemap.xml.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/sitemap.html.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".
Successful sitemap generation looks like this;- 
				Starting -> sitemap generator for AppsCMS V3.07.11.
				INFO: Created sitemap "/web-site-root-directory/sitemap.xml" (Link=sitemap.xml)
				Finished -> sitemap generator for AppsCMS V3.07.11.

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 "/home/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, js, 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/programmers definitions 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->Debug Values". This displays a searchable list of all the AppsCMS definitions. Code execution type global defines to aid in identifying operation are provided;-
    • "WWW_CALL" defined at the start of web execution.
    • "AJAX_CALL" defined at the start of AJAX code execution.
    • "API_CALL" defined at the start of API code execution.
    • Note: The code type defines can be overridden by user provided replacement/hierarchically code. If is recommended that this code also provide the global type defines.
  • A feature allowing snippets of code to be tested in the AppsCMS. Test code can be engaged (see Test Debug Settings) in debug mode. When test code is set up, the link "Admin->Debug Code" to appears to engage the test code.
  • An optional virtual folders feature in the application configuration can be used to allow direct URL access to an application. For example: instead of using "index.php?app=[id]&var_name1=var_val1&var_name2=var-value2" or "index.php?app=[id]&var_name1=var_val1&var_name2=var-value2" etc., the URL can use the "[virtual_name]/?var_name1=var_val1&var_name2=var-value2 etc." URL, this goes direct to the application using [virtual_name] including the GET variables (via the body file).
    Also, if you provide "[virtual_name]/somefile.php?var_name1=var_val1&var_name2=var-value2 etc." in the request URL, AppsCMS will direct to the applications somefile.php with the GET variables being set.
    Note: Before a virtual folder is engaged the AppsCMS will run the normal initialization.
    Important Note: The virtual folder uses the web server rewrite module via the standard/default (DOCROOT)/.htaccess config.
  • Base Classes (Objects) for Apps - The Ccms_app_base() class in intended to link in many AppsCMS methods for use in applications. The Ccms_app_base() class is actual a methods library/stack to provide common useful methods and provide correct access into the AppsCMS code.
  • POSIX Class (static methods) for Apps - The Ccms_posix() class contains POSIX and operating system informational functions.
  • Applications Configuration INI Settings and CSS Style Sheets - a AppsCMS maintained setup and themed css.
    The AppsCMS has code to produce annotated columns and headings for settings that contain multiple values or name=value pairs in the "/home/vhosts/appscms.org/public_html/etc/ini/apps.ini" settings file.
    There are examples in the "examples/AppsCMS-Examples-V3.07.11.zip" download, 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 application specific code to be implemented.
  • Proxies - Two types of proxy types are implemented;-
    • A pseudo proxy to access files directly accessible by AppsCMS but not directly accessible from the client side. And to keep private files away from indexing / multiview generated pages. These files are usually on storage systems that are not part of the AppsCMS server file system.
      These are implemented by a URI, for example "cms/cms_proxy?proxy={object_signature}". Where the "{object_signature}" is genrates by the AppsCMS and stored in a database against the proxied file, and the file delivered as required on call. See the "Ccms_proxy" PHP class for more details.
    • HTTP / HTTPS reverse proxy to allow access to web sites/apps behind the the firewall. This uses an inbuilt reverse proxy mechanism that not require Apache or Nginx configs to implement. The reverse proxy is based on an AppsCMS application. The application type is set to "Reverse Proxy" and instead on providing an application body filename, a proxy destination URL is entered instead.
    • Note: There is no websocket proxy in the AppsCMS. Websockets proxies are best implemented on the web server with application websocket initiators over the AppsCMS application code.
  • Geo Location - Geo location can be added to any form by including Ccms_location::add_JS_browser_geolocation_form_text() 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->contact us" to find the settings.
  • 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.

    • Example Control JSON Structure.

    • 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.
  • Application information and documents: The default location for these files is the "apps/docs/" directory.
    The AppsCMS has mechanisms for displaying the web site’s information to the "Admin" Users;-
    • Select ReadMe file link. Suggested readme document file types;-
      • "apps/docs/README.md",
      • "apps/docs/README.txt"
      contains the main web site’s "README" file for display.
    • Select Realease Notes file link. Suggested release notes document file types;-
      • "apps/docs/ReleaseNotes.md",
      • "apps/docs/ReleaseNotes.txt"
      contains the main web site’s "Release Notes" file for display.
    • Select Terms and Conditions file link. Suggested Terms and Conditions document file types;-
      • "apps/docs/Terms.php",
      • "apps/docs/Terms.html",
      • "apps/docs/Terms.md",
      • "apps/docs/Terms.txt"
      contains the main web site’s "Terms and Conditions" file for display.
    • Select EULA file link. Suggested EULA document file types;-
      • "apps/docs/EULA.php",
      • "apps/docs/EULA.html",
      • "apps/docs/EULA.md",
      • "apps/docs/EULA.txt"
      contains the main web site’s "EULA" file for display.
    • Select Licence file link. Suggested Licence document file types;-
      • "apps/docs/Licence.php",
      • "apps/docs/Licence.html",
      • "apps/docs/Licence.md",
      • "apps/docs/Licence.txt"
      contains the main web site’s "Licence" file for display.

  • Typical Client Metadata Session Structure

  • Legal requirements information.
    The AppsCMS has provisions for controlling and displaying "required" information. The following provisions are available for standard applications and local tools;-
    • "readme" (only available to group managers and admins),
    • "release_notes" (only available to group managers and admins),
    • "terms",
    • "licence",
    • "acknowledgement",
    • "cookies",
    Use "Admin->Search->terms or licence, etc." to find the settings.
  • App SSL Files. The default location for SSL (e.g. cert, key, ca) files is the "etc/ssl/" directory.

The <body> element requires js events to manage drag and drop. The "CMS_S_DRAG_DROP_PRELOAD_BOOL" setting controls whether the AppsCMS drag and drop js is included for application pages (the AppsCMS drag and drop js is always included for admin pages). In the "AppsCMS" the drag events are defined initial by;- 

	<div id="cms_page_body_XXX" ondragover="cms_drag_over(event);" ondrop="cms_drop(event);">

To allow applications to access these events, the JS initialize body event functions can be overridden and replaced;-

  1. "cms_drag_start(event)" looks for app_ov_drag_start(event) replacement function,
  2. "cms_drop(event)" looks for app_ov_drag(event) replacement function,
  3. "cms_drag_over(event)" looks for app_ov_drag_over(event) replacement function.
  4. "cms_remove_drag_events()" to remove drag and drop events.

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 "examples/AppsCMS-Examples-V3.07.11.zip" download.
  • The "etc/" is for settings, images, css (i.e. theme generated css), 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 been 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.

Chronological Timing (CRON Jobs)

The AppsCMS has chronological timing interface to setup and run CRON jobs on Linux based operation systems. Each CRON job has a crontab entry under the web application home user account (not under the web server).

Crontab entries can be configured directly for standard and close coupled applications. Standard and Coupled applications have there own CRON job timing and initiator scripts (shell or PHP). They are configurated in the "Admin->Apps / Bodies" configuration. Crontab entries are setup, engaged and deleted by the AppsCMS from entries in the page/apps configuration page, "Admin->Apps / Bodies". This operation needs to be run as the user who owns the web "(DOCROOT)/" directory (not Apache which runs as another user with no shell nor IO privileges). Depending on the system configuration, Apache may be able to change the effective user negating the need to manually log in to the "(DOCROOT)/". AppsCMS will indicate results either way.

For other applications AppsCMS uses a common crontab timing configuration. If enabled the AppsCMS looks for and runs "bash -e apps/cli/apps_cron.sh" (or "php apps/cli/apps_cron.php" if "apps/cli/apps_cron.sh" is not available).

If CRON jobs are enabled (currently disabled.) and after configuring the required settings in to CRON job configuration/s, AppsCMS will attempt to change local user’s crontab. If the web server does have sufficient permissions, a warning to generated to indicate the failure. In this case, login in as the local user (i.e. the owner of the "(DOCROOT)/", e.g. "/home/(username)/public_html", which gives direct access to the web code). This gives you access to the user crontab entries. Goto the "(DOCROOT)/" directory and enter "cms/cli/cms_cron_control.sh --start" or enter "php cms/cli/cms_cron_control.php --start". This will update the user’s crontab and engage the crontab cronjobs listed in it.

The AppsCMS takes possession of the local user’s crontab. Running the commands "cms/cli/cms_cron_control.sh --start" or "php cms/cli/cms_cron_control.php --start" as the home user will initialize user crontab.
NOTE: "cms/cli/cms_cron_control.sh" is a wrapper for "php cms/cli/cms_cron_control.php".

The AppsCMS commands "cms/cli/cms_cron_control.sh" and "php cms/cli/cms_cron_control.php" have options to --start, --stop, --run, etc. Running these scripts with the "--help" shows the available options.

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?cms_action=cms_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".

Typical Successful Rebuild Output

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: , SVN: 3501 2024-11-30

For direct access to AppsCMS version information use "index.php?cms_action=cms_version".

Utility Scripts

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

  • "cms/cli/cms_set_permissions.sh" - Linux scripts to restore web server permissions (runs as "sudo cms/cli/cms_set_permissions.sh"). This script will check for "apps/cli/set_app_permissions.sh" and run it if found.
  • "cms/cli/cms_rebuild.sh" - Linux version to rebuild configuration. Runs "cms/cli/cms_rebuild.php" - is a PHP sub script for rebuild configuration and reset the caches , etc. NOTE: Running "cms/cli/cms_rebuild.sh" runs the "cms/cli/cms_backup_settings.sh" before rebuilding.
  • "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_access_checks.sh" - Scans "apps/", "cms/", "etc/" and "var/" web site directories check for the presence of ".htaccess" files. And optionally, rebuild/rewrite the ".htaccess" file to the correct "ALLOW" or "DENY" access controls.
  • "cms/cli/cms_include.sh" - A common CLI definitions and functions for inclusion in other scripts.
  • "cms/cli/cms_generate_sitemap.sh" - Linux version of CLI sitemap generator.
  • "cms/cli/cms_generate_sitemap.php" - is a PHP sub script of CLI sitemap generator.
  • "cms/cli/cms_import_links_manager.sh" - Linux version to import Links_Manager data.
    Important Note: User and Group permissions need to be checked and/or reassigned after running this script.
  • "cms/cli/cms_import_links_manager.php" - is a PHP sub script to import DB data.
  • "cms/cli/cms_wrap_submission.sh" - Linux script used to help submit community feedback containing code with requested changes.
  • "cms/cli/cms_cron_control.sh" (executes "php cms/cli/cms_cron_control.php") - Linux script to control CRON jobs.
  • "cms/cli/cms_wrap_apps.sh" - Script to wrap the "apps/ directory into "apps_fs_sqsh.sqsh" read only squashfs archive.
  • "cms/cli/cms_dumpsqlite3.sh" - Script to SQLite database.
  • "cms/cli/cms_stats.sh" - Script to provide code statistic.
  • "cms/cli/cms_doxy_run.sh" - Script to generate "doxygen" documentation. Runs the "doxyen" .conf files in "cms/doxy/" directory.
  • "cms/cli/cms_DB_create.sh" - Script to create the AppsCMS MySQL database. Runs "cms/cli/cms_DB_create.php" script.
  • "cms/cli/cms_DB_query.sh" - Script to test MySQL databases.
  • "cms/cli/cms_config.sh" - Script to get/set configuration values from the CLI.
  • "cms/cli/cms_doxy_run.sh" - Script to generate Doxygen documentation from source code. When the results are available, the document links appear in the "Admin->Doxy CMS", "Admin->Doxy Apps" and "Admin->Doxy Apps & CMS" (combined).

The most utility scripts have a help option (e.g. -h|--help) where options are available or they need required option/s.

Code Examples

Code examples are available for download in "examples/AppsCMS-Examples-V3.07.11.zip". The appropriate part of the "examples/AppsCMS-Examples-V3.07.11.zip" directory can be unzipped and copied to the appropriate "(DOCROOT)/" directory. to engage the examples. (e.g. at the "(DOCROOT)/" run "cp -v -r examples/ ")

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

In "examples/AppsCMS-Examples-V3.07.11.zip" are examples;-

  • A "examples/apps/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 "examples/apps/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 "examples/apps/bodies/example_contactus_cms_body.php" is available to help show how to use the Ccms_contactus plugin.
  • A "examples/apps/bodies/example_login_cms_body.php" is available to help show a custom login page.
  • A "examples/apps/bodies/example_modal_test.php" is available to help show how to use the Ccms_modal class with the Ccms_contactus plugin.
More Information

LICENCE.

README.

Version.

Release Notes.

Installation Notes.

Directory Structure

AppsCMS

 		×

Send Us an Email:

Subject: AppsCMS V3.07.11 Feedback
Name:
 *** 
Phone Number:
 optional 
Email Address:
 optional 
Message:
0/1000  *** 
CAPTCHA Image  
Enter Check Code:  ***   
 

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