Documentation

About

AdaptCMS is a general content management system. Currently in Alpha stage, the CMS is for developers or those that have used/are comfortable using CMS's - though if you have a copy, I'm sure you fall in between that. Re-writing it in cake, I wanted to take advantage of my new experience with modern technologies - already this is done, with using cakePHP, jQuery, ajax, Bootstrap and it's not even a beta version.

The general idea of AdaptCMS is to be a CMS that can be used on any content website, that is extremely customizable and easy to use. Please not that being early on, their is a significant amount of features that are in with no regards to the experience of the end user - Admin Roles with permissions is probably the best example. Often the case is that I don't have a clear idea of how I want it to work/look like, so don't think that it will stay that way. Anyways, enjoy!

Installation

First step is to download AdaptCMS and upload all the files to the location you want your site to appear at. You should see something like the following:

Any files/folder that need permissions, will be listed and explained how to fix to proceed. Once there are no errors, you will need to enter in your database information.

Any error will be displayed here, if it cannot insert in the MySQL information or if the information was incorrect, correct and continue on. AdaptCMS will attempt to setup the database tables and data, there should be no issues.

The last step is setting up the default admin account.

If everything goes okay you should see something like below. You're all done! Feel free to delete the 'installer' folder and chmod the database file. You will be supplied with links to your new frontend and admin area.

Getting Started

Access your site at - yoursite.com, update the db/sql and you can then access the admin area at site.com/admin (details are above). From there, you will want to spend time in the admin - that has received a good 85% of the work thus far. What I recommend checking out first is Appearance, an admin feature that is already (in my opinion) a significant upgrade over previous adaptcms versions.

If you can figure things out, editing permissions via Roles is a nice detailed area.

Admin - The Basics

There are many basics that many of the below admin features adhere to. One, is a trash area. This allows an admin to delete an item and for that item to not be useable in the frontend area of the site, yet still be recoverable. We recommend utilizing this feature for most things on the site, unless you are 100% sure you will never need it. For some things, permanently deleting something has little/no effect - however if you say, delete a Category? Permanently deleting that will delete the category, articles, article values and fields. So please, be careful!

As for the meanings of the standard functions in AdaptCMS, we'll go over the names and what they are/similar names for them:

  • Articles - Content, Posts

    This is the oil in the machine of a website. Also called content (AdaptCMS 2.x) or Posts (wordpress), this is where you will spend most of your time. This feature links back to quite a bit - Fields, Article Values (stored data), User and Category.

  • Categories - Sections

    Called Sections in AdaptCMS 2.x, categories help organize your articles. Some common uses for categories are with gaming websites (news, reviews, previews, etc.), news websites (us, world, politics, technology, etc.) and a blog site would simply have a Blog category.

  • Users - Members

    This is a feature that outside of the admin area, isn't absolutely necessary. Some sites wish to simply post content or have pages of content, but a growing site often requires users to signup.

  • Fields - Custom Fields

    One of the most important aspects of articles, are fields. This allows you to extend the useability of AdaptCMS for whatever type of content website you wish to build. Adding a system field for a Game Category is one such use, a post field for a Blog category. With the new fields in AdaptCMS, you have endless posibilities of use.

  • Pages - Static Content

    Not always utilized, but almost every site on the internet utilizes pages. Often it's an About Us or Contact Us page. Most people use this for static content, something that is not an article but they wish to use a WYSIWYG editor so they don't have to edit a template to simply edit some static content.

Admin - Articles

Currently the permissions for Articles in the admin are simply add, edit, delete and index. In the future, control will be added to determine if a user can only edit/delete their own content or possibly only certain categories.

The index list details the basic information on an article - a link to the frontend view and title of the article, category, user, created date and options. In the index area you can delete an article and then view deleted articles (and either restore/permanently delete them) by selecing Trash under the view tab.

At it's very default, the fields for adding/editing an article are Title, Slug and Tags. All other fields need to be added via admin fields. The Title field is a non-unique field, Slug is a unique field - by default it takes whatever you enter in as the title and converts it to a slug-format. Such as Halo 4 Article becomes halo-4-article. Tags are a feature where you can essentially group articles by a common theme, without having seperate categories. One example useage is tagging a new review as xbox 360 - that way you can view a page such as yoursite.com/articles/tag/xbox-360 - and it will list all content that is tagged with xbox 360.

Additionally, you can choose a publish type. When adding an article, you can either Publish Now (meaning the article goes instantly live), Save Draft (which sets it to inactive, not live until published) or Publish Later. If you Publish Later, a field will popup marking the time in an input box and the date to publish the article, in a date box. When you click the date box a calendar will popup, allowing easy access to enter in the date you want. After you pick the date you want, simply click submit and the article will not appear live until that precise time/date.

Relating Articles is another big part of Article management. Brought over from AdaptCMS 2.x, but made much easier (for myself ;) ) and better performance, being used in cakePHP. Simply search for an existing article to relate it to, you can pick a Category to refine the search, and as you type in a keyword the results will finetune. Just click on the article you want to add and it will be added to the list below.

One note is regarding article values, a term used often. Essentially, an Article Value is data that is stored for an article - custom field data in lamen terms.

Admin - Users

As most modules, the permissions for users right now are add, edit, delete and index. I expect additional functionality to include whether a user can activate/de-activate users as well as (possibly) an option if they can change a users password.

This is going to be pretty quick, as user management is currently quite simple and straightforward. You can add a user and you must enter a unique username, password (and another, to confirm the password), valid email address and a role. When editing a user, the only change (besides there being values in the inputs ;) ) is that there is simply one password field, only enter anything in if you want to change the users password.

Users also have a trash area. When a user is deleted and sent to the trash, if that user attempts to login they will receive notification of a non-existent account. As well, if a user account is not activated, they will receive a message dependant on the setting for new user accounts. (staff activation or email activation, email by default)

The last feature is an ajax function on the main index page for user activation. By each user you will see if the account is activated or if it has not been activated. The user activation setting does not affect this feature - when you click on either icon, it will change the icon to the opposite as well as update the users status to that. So if you click on , you will activate that users account and vice-versa. This is intended for quick activation of multiple accounts without having to click around multiple pages.

Admin - Fields

Fields have functions of index, add, edit and delete. There are currently no plans to add any additional admin functions or extend permissions further.

Managing fields requires no more than past AdaptCMS versions, but allows for greater customizability. To start, you must name a field with the title input. You also must select at least one category to assign the field to, as well as a field type. The other options you have are a label (the name that will appear on the article edit/add page - spaces, capital letters, it can have it all unlike title), description (same as label, but appears as a little popup), field type, field limit minimum (minimum amount of characters that must be entered when adding/editing an article containing this field), field limit maximum, field order and required field.

Field Order is currently a number field, this will be upgraded in the near future into a drag functionality so you can see and manipulate the physical order of the fields as it would appear on the article page. The Field Type is how it will appear - such as a text input or more, here are all current field types and what they do:

  • Text Input - Just as it sounds, a simple input, like when you login. A username field is a text input.
  • Text Box - This is a box, such as when sending an email or posting on a forum - a big box that in this case, has a WYSIWYG editor for text manipulation. (bold, italic, colored text, etc.) This is the only type that enables the field limit minimum/maximum options.
  • Dropdown Selector - A dropdown menu can be used for multiple purposes. Usually the case is field data that will not change and the user can/must select just one option.
  • Dropdown Selector Multiple - As the name mentions, it is exactly the same as the above type - except a user can select more than one option.
  • Radio - The circle inputs you often see on forms, it's uses nowadays are rare, but they serve the same purpose as a dropdown - except smaller. A male/female field is the most often use for a radio button.
  • Checkbox - Essentially the combination of a dropdown and a radio, checkboxes allow you to click multiple options.
  • File - This is the only field that works with an outside feature. The user selects a file and it is uploaded just as you would be uploading a file through the admin files feature. If it's an image, a thumbnail is created.
  • Image - Same as File, but must be an image file.
  • Website URL - A text input, but the entered value must be a valid website url. (the site doesn't have to exist, but must be a http://www.site.com type value)
  • Number - Text input, value must be a valid number.
  • Email - Text input, must be a valid email address.
  • Date - Text input, but when you click a date picker will popup and you select a date.

Fields also have a trash area, any article values related to a field will only be deleted when a field has been permanently deleted.

Admin - Appearance

Appearance in the admin handles Themes, Templates, Theme Assets and the Default Theme Setting. When you first install AdaptCMS, there is a Default theme which is what you see in the frontend and backend. This theme cannot be deleted or renamed, whereas whenever you add any or download any theme - those work essentially the same, except that they can be renamed and deleted if the account has permissions to.

One of the new and useful feature sets in this version is Theme Assets. When you edit an existing Theme (including Default), you will have a Theme Assets tab which lists all css/js/images in the themed directory. With the Default theme, this location is '/app/webroot/( js|css|img )', whereas an added/downloaded theme is '/app/webroot/themes/{ThemeName}/( js|css|img )'. With these feature you can add, edit and delete assets. Currently this is done by modifying the files feature, but this will be re-worked in the future. Essentially, with Theme Assets, you can manage all website assets (and in combination with uploading files) - so you don't have to edit anything through FTP which makes things easier.

Templates is an area that will be expanded upon both in language in these docs, as well as usability/user-friendliness in the future. Currently there are two main points of functionality. First, you can add/edit/delete templates - there is no template language, so right now it's PHP. As with other features, both templates and themes can be deleted and are not permanent until you delete them from the trash.

To help find templates (there's a lot of them just for the one theme!), there is an AJAX quick search right above the template list. Simply search by the name of the template and/or location and the most relevant results will appear. Click on the one you want to go to the edit page.

There are two important points regarding the Default theme and the use of templates. For the most part, they are self-explanatory. 'Admin Edit' named template with the location '/Articles/' controls the view template for when editing an article in the admin area. But what is a little different and works how the user wants to - is article templates in the frontend. By default, there is a 'View' template in the Articles folder which controls the view of an article and 'View' in the Categories folder which controls the list of articles for a category. However, there is a built-in customize-ability.

When a category is added, a template '{category-slug}' (ex. news) is added inside the Categories folder (the default template will copy from whatever is inside the view template) and the Articles folder (same as before, copied from view). When a category is deleted, these templates are deleted. This allows you to set specific category list templates and an article view based on category.

The last important point is regarding overwriting with new themes. The default theme is as it sounds, the base theme. If I add a new theme and add a template 'Index' in the Media folder - if this new theme is picked as my theme, then when I go to the index of media - it should be using that template. The great thing though is that you can leverage the way templates work by using the aptly named 'Default' theme templates and only add templates to your theme that will differ from the Default theme. This is great because you can often have only a handful of templates, rather than have a massive amount of unnecessary files.

Admin - Categories

Categories of admin functions of index, add, edit and delete. As of now, there are no plans to add additional admin functions for categories.

I'll keep this one very short, managing categories involves just the title field, which is the name of the category and is used across the website. (frontend and admin) This field is unique and cannot have special characters in it, as it is used for folder names for templates among several other things.

Categories do have a trash area as well. The effect of this is in regards to articles. If an Article belongs to a category that is in the trash, it will not be shown in the frontend of the site, nor the backend. Once a category is permanently deleted, all articles and related data are also permanently deleted, as well as fields linked to it.

Admin - Files

Files, like most every other admin function, have the basic add/edit/delete and trash functionality in the admin. When you go to add a new file, you have the option of Upload File (primarily for images, but also if you don't want to copy and paste css for example) or Add File. If you choose to add a file, new to this version of AdaptCMS, you will enter the contents of the file, the File Extension (mainly document types - html, php, css, etc.), File Name and an optional caption.

If you choose to Upload the File, then several things may happen. First, if you choose to watermark and it's an image - it will apply this watermark by default. As well, if it's an image, a physical thumbnail will be generated in the 'thumb' folder under '/app/webroot/uploads/'. When you go to edit this image, you can re-size it or rename.

If you delete a file, it does have a trash so it will not be deleted until deleted permanently in the Trash Area.

Admin - Roles

By default, Roles have 3 types setup - Guest, Member and Admin. Admin has access to everything, member has access to everything on the frontend and guest has access to all frontend items that are not hooked up to needing an account. (such as editing your profile) When you add a new Role, you have the option of a default setting - Default Member, Default Guest.

Default Guest is used to determine what Role a non-logged in user will be attributed to. There can only be one Default Guest enabled role, so if you add a new one and select that option, the obviously named role 'Guest' will have the option removed. Default Member works the same way in regards to being one of a kind. The difference is with registration, whatever group is picked - when someone attempts to register, this is the default role they will be assigned to. If you delete a Role with one of these flags, you will not be allowed until a new role to replace it is created.

The main functionality when editing a Role is user permissions. You can add a new permission type and add a permission value, but this functionality is more temporary. You can edit - by view, what a role can access. Currently this is only view, but new functionality is coming. Un-ticking a box will mean that a user assigned to that role will not be able to view that action.

Admin - Pages

Pages are pretty simple - you can add, edit and delete static pages. They also have a trash area so deleting is not immediately permanent. The title field is unique.

Admin - Settings

Under Construction

Admin - Modules

Modules is a brand new feature to AdaptCMS, letting you setup dynamic blocks of data with total control of where they appear. It has the typical add, edit, delete and trash area. Essentially this feature will take a feature such as Categories and allow you to enter in different parameters and where this data will be accessible. Then on the frontend you can simply display this data however you want. Module title is a unique field.

When adding a Module, you first must pick what component this is. Example ones are 'Articles', 'Categories', 'Polls'. You then must select how many to display - if you pick one, then you can select which specific one to list. After that, you have to pick a location of where this data can be accessed - this is done, so that instead of doing a massive amount of queries on every page, you can set either a global location or specific areas that this will be available.

If you pick a specific view, you will see you have to pick a 'controller' (a component, such as articles and pages), then an action (ex. view) and optional to pick a specific item to have the data available on. (such as only the contact us page) Then that's that! Otherwise, in the frontend, you simply access the module data in the specified area through the $ module_data variable. Inside of that array contains the module data by slug.

Frontend - Account

There are currently limited features for Accounts. Of course the basic login, logout and register are there. When signing up, if enabled and a key entered - you can register through facebook. You can also login straight into facebook if activated.

There are several settings for accounts. You can choose to either enable or disable captcha for User Registration, you can enter in Security Questions as well. User Status is another setting (staff activation, email or none), the user registration email subject, user password reset (x amount of days before a user must enter a new password) and lastly - how many security questions to show, if any.

It's basic at the moment, but logged-in users can edit their profile - new password, change security questions/answers, change selected theme, etc. If given permission there is also a view profile functionality for user accounts - by default this shows a users basic information and lists any articles they have posted.

Frontend - Articles

A list of articles (paginated) can be seen at 'site.com/category/{category-name}' and you can view a specific article at 'site.com/article/{article-slug}'. All article data, fields/article values, related polls and comment data is accessible at both areas.

The comment system has been significantly upgraded for the new AdaptCMS version. AJAX means quick and easy posting, there's a setting that if enabled - non-logged in users must fill in captcha for their post to go public. Comments are also fully threaded, currently up to 3 levels deep - with plans to enhance.

Frontend - Media

There are two major areas of functionaliy for Media in the frontend. First, is the index which is a paginated list of Media Libraries - which includes all basic media information and the newest added file information for each library.

The second is the view functionality for a media library. This is a paginated list of all images associated with the specified library, by default fancybox is setup so visitors get an easy and appealing way to view the library images.

Plugins

Plugins are often what makes a CMS popular or hurts their rise in popularity. With AdaptCMS and using the cakePHP Framework, we like to think we have an easy and approachable system. As long as you following the cakePHP Plugin conventions, which can be seen here, you can do as you wish with your Plugins.

Plugin - Polls

The Polls plugin has a full admin area - add/edit/delete and trash area. When adding a Poll, you have to enter a title and enter at least one option. Simply click "Add Option" for another option text field.

To use the Plugin in the frontend area, you need to add a new Module - checkout the documention on Modules here