Standard

The primary purpose for Cliqon is the development of multi-lingual presentational websites that are independent of any pre-provided themes or templates, the management of the content for such a website and the development of administrative applications that may or may not require a frontend website.

Installation

When you download a production version of Cliqon you will create and check a proposed directory structure, have the opportunity to use an installation wizard to assist in the setup of the new website and the import the essential structural data. The installation wizard is only an aid and comprehensive instructions are provided in the document to assist with the manual installation of a Cliqon system. In addition there is no fundamental reason why an existing Cliqon website cannot be cloned to a new instance. This is particularly important as it allows the three versions of an application website to exist concurrently (development, training and production), using the same database if required.

MVC Framework

The use of the wording Model – View – Controller (or its acronym MVC) is a much interpreted definition. We describe Cliqon as a MVC framework as it has Models for the data, Controllers to start the processes and the possibility for several Views subdirectories. We use the plural of subdirectory because Cliqon needs to support more than one Views subdirectory because the Admin system is a View and has its own heirarchy of subdirecties such as CSS, Javascript, Components and Partials.

Folder structure

We hope that the heirarchical subdirectory system that we have chosen for Cliqon is intuitive and straightforward. The installation wizard checks that the folder structure is correct and warns of any missing subdirecties or incorrect folder permissions.

Routing – Controllers

The use of .htaccess or web.config files is not essential to the operation of the system but are advised for reasons of security. The appendices contain notes about installing Cliqon on webservers with different Control Panels. A good example is CentOS Webpanel which needs a particular setup of folders and permissions and our installtion notes are provided for that purpose.

Cliqon Framework supports a RegEx Router. The Routes are configured as a TOML array. The Router interrogates the routes configuration and hands off serving the URL to a suitable Controller as configured in the Routes file. The Router and Controller can differentiate between different types of Request protocol – GET, GET_XHR (via AJAX), POST and POST_XHR. Usin PUT and DELETE are optional.

In turn the Controller invokes the appropriate Class and Method to handle the requirement. The Class and Method called could be a standard Cliqon facility or a Module or Plugin that you have written for yourselves. As long as you clone certain conventions as to how Cliqon Routing works, almost anything is possible.

Configuration

You will be familiar with the software design paradigm called “convention over configuration”. Our configuration files follow that convention but as we cannot call these files or database records anything but “configuration” files, we will use a different term for the heirachy and say “cascading”. You will be used to the term Cascade with reference to Style Sheets. All the Configuration values in Cliqon Cascade in a similar manner.

As an example, it takes three sets of configuration values to create a grid displaying language strings – the first set we call a service, thus a grid is a service, the second is a table that corresponds to a table in the database and finally a model or collection which configures a type of record, in this case a string.

Each of these configuration containers with TOML formatted values can exist in three places (the third is automatic). The container could exist as a file or it could exist as a database record. Once in existence and required it will automatically create a cached version as a file, which will be used until one or other of the containers is changed, upon which event, the cached version will be refreshed.

The idea has been developed within Cliqon for many years and versions but has come to maturity with Version 4 and is now used throughout the system.

Generating HTML or JSON via API

The concept and process of generating content and data as a JSON stream instead of returning HTML to a browser was completed with version 4. At this moment in time Cliqon 4 contains the facilities support both mechanisms for publishing content – rendering a template containing HTML or returning a JSON stream (local browser or remote device [JSONP]). As and when we get to a Version 5 of Cliqon all mechanisms to render HTML will be removed.

We consider that the mixed approach is the correct approach as not every developer has had time to make the conversion. At this time we support five mechanisms – publish a page of HTML, generated from a page template; render a component of HTML generated from a component template; add a JSON stream of data to either of these which is consumed in the correct place (before end of body) by the page template; render a stream of JSON that can be consumed as a page template by the client and finally render a stream of JSON data that can be rendered as a component.

Authorisation and security

Following on from the above section, we needed to augment our facilities for statement management and security. We have always supported database driven sessions and Cookies. Thus UserNames, IDs’ and Access Level Controls have always been available for the purposes of managing User, Operator and Administrative access, at a fine level – that is using Read, Write and Delete controls, across menuitem, service, table, collection and field.

This level of security is enhanced by the provision of support for JSON Web Tokens (JWT) for all JSON local and remote communications. The raw facilities to support OAUTH are provided but the final development of this must be part of an end-user application.

Multiple languages

When we first developed the forerunner to the packaged Cliqon, which is now nearly fifteen years ago, the fact that we built into our framework, support for multiple languages was completely new and almost unique. Over the years we have tested our ideas on countless numbers of websites. For a long time, different language versions of a thing, such as a label string or document, would be held in different records. For some time now, we have kept alternate language versions within one record as JSON.

Thus one would expect to find a series of document fields where the system expects there to be a subarray structure within the JSON with language code and language string pairs. The following snippet is a good example: {“d_text”:{“en”:”Text”, “es”:”Texto”}}. Whilst there is no limit to the number of languages that could be installed and maintained, a practical limit of five is proposed. Once the language is in place it is easy to manage. Adding and deleting languages is automated but takes a while to achieve.

Templates – Razr or Javascript

As explained previously, Cliqon supports the use of template engine to render HTML. As Cliqon will gradually be moving away from all types of server side templating it makes no sense to provide any form of incredibly smart template engine such as Smarty or Twig. In any event, we have found the Razr template engine (which was originally developed by the Pagekit project team ) to be entirely adequate for Cliqon. It takes its idea from Razor templates within Microsoft.

Details and documentation for the Razr template language are provided in the manual.

Some years ago, we did our forward looking research and chose the Vue Javascript reactive framework for the administration module in Cliqon, as it worked well with both Bootstrap and jQuery which continue as essential aspects of the Cliqon project. Using Vue with PHP is like looking at two sides of grid or ladder. We can choose to connect the two components at almost any rung on the ladder – low or high. We can render a template with PHP and let Vue animate it with a data stream. Equally we can render just a JSON stream and let Vue create the template and then animate it. Both situations exist in Cliqon administration at this time.

As we have said previously, ibn the longer term we believe that the Server will only generate JSON and the client code will be responsible for all rendering.

Frameworks

We chose Vue for the backend and we use Vue for our own frontend and application projects. As developers, there is no reason why you should choose to do the same. The way the system is designed allows the Views and Mobile subdirectories containing “views” to use the Framework components that are appropriate for you, as the developer. If you want to use Ember, React or Angular this is perfectly feasible.

Process for building websites

The basic production version of Cliqon visualises that a website will be created in a particular way and order. However we do believe, from experience, that this is the way that experienced web developers and agencies build websites for clients.

The process starts by installing a production version of Cliqon. Then you can create or select and download a free or paid HTML website template. Full stack developers will not have a problem with the traditional and artificial differences between back-end developers and front-end designers, the latter may!

If the developer or agency has their own in house creative artists, the result you will be looking for is an HTML template, complete with any necessary javascript, images, fonts etc. If the developer has the responsibility for sourcing or producing the template, then the package sought is a straightforward package of HTML. Finally, we offer one suggestion and one aide for the design process. Any of the recent crop of website designers, such as Pingendo, do an excellent job in allowing the developer to produce the required HTML. The editor within Pingendo would allow the introduction of the Cliqon template variables, components and content. Cliqon 4 now offers, as a built in option, GrapesJS javascript layout constructor which also creates the necessary HTML site layout.

As a general rule, the HTML of the template will be copied into the Views subdirectory and the process of animating the template can begin.

Methods

Over the past 10 years that Cliqon has existed, we have developed a wide variety of core methods that you can use in the template. Although it is only an arbitrary definition, we think of a method call as something that returns a simple string of content, usually in the current language, which contains no formatting or element of presentation. One can imagine that a core method is used to access the database for a collection value and maybe format that value as might be necessary for a date or currency.

The list of static methods that can be used in that way is provided in the documention. It should be obvious that if we do not provide a core method, you can create one yourself as a Developer.

Widget

Over the same timescale of development, we have also developed a number of widgets or components that render a collection of variables and may contain formatting. As a general rule the components will be specific to a modern CSS framework such as Bootstrap or Material Design. Again the list of components is documented and includes complex methods such as menus, lists, tables and trees. We believe that this is an area where Contributors and Partners may make the biggest impact. We ourselves will be developing themes, templates and components as plugins that we will make available by our Cliqon website. Some of these plugins will require administrative facilities and wizards.