Upgrade From 5.0.0

If you are upgrading from 5.0.0 you will need to do the following:

• Stop your server and make a backup just in case

• Open the box.json in the root of your project and make sure the following package scripts exist, if not, add them

"scripts" : {
    "contentbox:migrate" : "migrate up migrationsDirectory=modules/contentbox/migrations",
    "contentbox:migrate:up" : "run-script contentbox:migrate",
    "contentbox:migrate:down" : "migrate down migrationsDirectory=modules/contentbox/migrations",
}

• Open a box shell in the root of your project

• Remove the resources folder in the root: rm resources --force --recurse

• Run update --force to update your installation to the latest release

• Run run-script contentbox:migrate:up to upgrade your database to this patch level

• Startup your engines!!

Release Notes

Bug

• regression - the author preferences UI form should not overwrite all preferences when saving

• Adding a category when creating a new blog post causes an error

• Upgrade to ContentBox 5.2 from 5.0 does not allow pages to save

• PAGES_EDITOR permission should allow for publishing/unpublishing for editors

• Pagination stops working intermittently when navigating the site tree

• Media manager context menus breaking intermittently and only a full reload will fix

• Publishing time is decimal formatted not Time Formatted

• Do not allow to set yourself as your own parent in pages

• Import dialog broken regression on all editors

• Retrieval Order Field will Only Accept Numbers up to 99

• Blog entry content should not have parent modifier

Improvement

• Link the swagger resources to the actions in the api module

New Feature

Task

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book are copyright by and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -

• All ColdFusion examples designed to run on the open-source Lucee Platform or Adobe ColdFusion 11+

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software, and resources described in it.

Contributing

We highly encourage contribution to this book and our open-source software. The source code for this book can be found in our where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education, and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is a good earth to seed and plant.

ContentBox v5.x is a major version update and will require the following instructions to update your v4.x installations. Please follow this guide or contact us at so we can assist you during your upgrade process.

1. Requirements

All Upgrades to ContentBox should be done with the assistance of So make sure you have CommandBox installed in the server/machine you will be upgrading.

Install CommandBox Dependencies

Once you have CommandBox installed, let's make sure we have some global dependencies installed so CommandBox can work with ContentBox automated upgrades:

This will install the module and the module that will be used to provide upgrades in the future. This is only done once. ContentBox 5 already ships with these dependencies once you install it.

Environment (.env)

The upgrade process and the database migrations rely on environment variables/secrets in order to connect to your database and migrate it. Create an .env file in the root of the ContentBox installation and add in the configuration according to your database and configuration preferences.

If you are running CommandBox as your server of choice, then you can update your .cfconfig.json in the root of your application to the following:

Once your environment file is seeded open the box.json of the ContentBox 4 and add the following configuration.

Once this is done we can reload the CommandBox shell with the command reload and it's time to make sure migrations can connect to your database with the variables and connection information:

2. Backups

Please make sure you backup your source code and your database. We are not liable for broken installations.

3. MySQL UTF8mb4

If you are using MySQL you will need to make sure your database and your tables are all using the following character set: utf8mb4 and NOT just utf8. ContentBox 5 requires the charset to be utf8mb4.

We also suggest you use the utf8mb4_general_ci collation for your database, tables and columns as well.

4. Run the Updater

We have prepared a CommandBox task that will upgrade your installation in one easy execution.

*nix/Mac

If you are in a Linux or Mac environment you can execute the task using the following shell commands from the root directory of your application.

Windows

If you are in windows, download the following task:

and place it in the root of your project. Then issue the following CommandBox shell command to execute it.

5. Final Steps

The updater will update your installation and run the migration scripts. However, it will also override the following files:

It will create .bak files for the originals so you can manually merge in any changes you had before.

Once you do, go ahead and startup the engines! You are upgraded!

Optional Steps

If you had developed themes, modules, models, or any type of extension based on ContentBox 4, you will most likely have to update your code to match the new interfaces, methods and approaches.

ContentBox Models Namespace

If you had custom models, modules, themes and widgets, please do a search for the old injection namespace of @cb for ContentBox models. Then replace it with the new namespace @contentbox.

Renamed CBHelper Methods

• layoutRoot() => themeRoot()

• customHTML() => contentStore()

Renamed Author Object Methods

• author.getName() => author.getFullName()

Fixed

• 5.x Updater was not running the right migrations

• Migration names cannot have a period or the migrations fail due to a CFC instantiation issue

• CBHelper siteBaseURL is not accounting for multi-site

ContentBox Modular CMS - v5.x

ContentBox is a professional open source hybrid modular CMS (Content Management System) that allows you to easily build websites, blogs, wikis, complex web applications and even power mobile or cloud applications. Built with a secure and flexible modular core, designed to scale, and combined with world-class support, ContentBox will get your projects out the door in no time.

Versioning

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bump the minor (and resets the patch)

• Bug fixes and misc changes bump the patch

License

• Copyright by Ortus Solutions, Corp

• ContentBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Let's get started with some system requirements for running ContentBox sites on all deployable options

Java

You need Java 8+ to run ContentBox.

CommandBox

You will need to have CommandBox for installation, upgrading and optionally for running your ContentBox sites. Please see our CommandBox Installation section.

ColdFusion (CFML) Engine

ContentBox can be deployed to the following CFML Engines:

• Adobe ColdFusion

  • 2016 (End of life is December 2021)

  • 2018

  • 2021

• Lucee 5+

Databases

Here are the supported databases for ContentBox:

• MySQL 5.7 (InnoDB ONLY!)

• MySQL 8+ (InnoDB ONLY!)

• Microsoft SQL Server 2012+

• HypersonicSQL

• Apache Derby

• PostgreSQL

• Oracle 11g+

If you have another database engine that needs ContentBox support, please let us know and we will be able to help you (https://www.ortussolutions.com/contact).

Microsoft SQL Caveats

We have seen an issue where an error will be reported that cbPermission cannot be inserted. This is an issue where for some reason the JDBC driver will switch context and create the tables in the master schema and not the schema you chose. So please verify that the master schema has tables that start with cb_* and remove them and re-run the installer.

URL Rewriting

ContentBox relies on Search Engine Safe (SES) URLs and URL Routing. The majority of CFML engines already allow for these types of URLs out of the box and ContentBox supports it out of the box. However, if you would like to use full URL rewriting (which we recommend, that's where the index.cfm is not showing in the URLs) you will need to use a web server rewriting tool and ContentBox will configure it for you.

So before you install ContentBox make sure that you are using one of the supported rewriting engines show below:

• CommandBox Server (Default)

• Apache mod_rewrite

• IIS 7 rewrite module

• Tuckey rewrite filter

• Nginx

The ContentBox installer will create rewrite files automatically for you for Apache, IIS7, and express editions. For Nginx or other rewrite engines, you will need to add the rewrites yourself and then manually modify the routing file.

ContentBox Routing Full Rewrite Support

Edit config/Router.cfc and set setFullRewrites to true. That's it!

function configure(){
    // Configuration
    setValidExtensions( 'xml,json,jsont,rss,html,htm,cfm,print,pdf,doc,txt' );
    // Process Full Rewrites then true, else false and an `index.cfm` will always be included in URLs
    setFullRewrites( true );
}

File Permissions

ContentBox needs some files/folders to be writable at runtime.

Installer

{Root}/Application.cfc
{Root}/config/ColdBox.cfc
{Root}/coldbox/system/aop/tmp

Engine

Here are the folders for the core engine to work accordingly

# Engine Operation (REQUIRED)
{Root}/coldbox/system/aop/tmp

# Media Manager
{Root}/modules_app/contentbox-custom/content

In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 5.0

Version 5 is a major architectural shift for ContentBox as we go Multi-Site and Hybrid headless API, with over 145 different improvements and new features.

Version 4.0

Version 4 focused on upgrading its internal core to ColdBox 5 and providing more modular development around its core. We introduced the contentbox-custom module so you can have your assets externalized from the CMS core. We also added tons of security features such as two factor authentication.

Version 3.0

Version 3 also focused on a major ColdBox upgrade and a completely new admin interface.

Version 2.0

In this version we introduced the content hierarchy and pages. It was a major leap to a full fledged CMS.

Version 1.0

Our initial CMS release

ContentBox 5 is a major update for this CMS and it includes a major architectural change to move the CMS forward for the next 10-15 years. We have introduced multi-tenancy and a complete headless approach to ContentBox. It has become one of our biggest releases since our initial release since 2011.

You can find our release notes here and we will discuss our major areas of improvement for this release. If you need to upgrade your previous versions of ContentBox, please see our upgrade guide.

ContentBox CLI

We have used the power of CommandBox, to build a ContentBox CLI (contentbox-cli) module that will assist you with installations, upgrades, maintenance and much more. Once CommandBox is installed you can run the following to install our cli:

box install contentbox-cli

That's it. This will install the contentbox namespace which will assist you in your ContentBox adventures. Please see the installation guide on usage.

ColdBox 6 Core

We have upgraded our core to ColdBox 6 and we have received a tremendous amounts of benefits (https://coldbox.ortusbooks.com/intro/release-history/whats-new-with-6.0.0). Here are some of the features we get with this upgrade:

• Performance, performance, performance. ColdBox 6 has been finely tuned to make your applications much more performant and stable under high load.

• Better new CFML engine support

• Asynchronous programming. We have introduced the concepts of the async package to the core and ContentBox will leverage more of these features for background job processing, automation and much more.

• New logging facilities and enhancements

• Better exception handling for developers

• REST Handlers and highly performant REST Routing

• Singleton View Rendering. You will find that all renderings are way faster than before.

• Much more!

CBSecurity 2

We have migrated our cbsecurity module to the latest version to give you a wealth of features (https://coldbox-security.ortusbooks.com/intro/release-history/whats-new-with-2.0.0) such as:

• Fortified rule engine

• Annotation based security engine

• JWT support

• Security Services

• Cross site request forgery support

Multi Site Support

Although multi-tenancy been one of ContentBox's most requested features, we were hesitant for many years to comply due to the size of the needed refactoring. However, we have finally created a great base for making ContentBox multi-tenant. You can now configure 1 or 10000 sites under the same ContentBox umbrella. The new installer actually creates two sites for you: a development/staging site and a production site. That means that you can manage different content environments all under the same deployment.

Here are some of the features you get with multi-site ContentBox:

• Ability to register an infinite number of sites

• Site detection by regular expressions or patterns on incoming URIs

• Site detection by header identifier if using the headless CMS or reverse proxies

• Each site can contain its own

  • Categories

  • Blog

  • Pages

  • Content Store

  • Menus

  • Commenting System

  • Themes

• Admin site switcher

• Admin site control bar

• Clone content or entire content hierarchies from one site to the other

• Publish content directly to different sites

• Move content between sites

• Much more coming soon.

Admin UI Revamp

The entire admin UI has been revamped and streamlined. You will find it much more breathable and easier to work with, especially from mobile devices and smaller screens. We are also starting to prepare a major theme change and customization that might be introduced in the final release or scheduled for a minor update.

We have also started our migrations to Alpine.js and Tailwind for the reactivity and overall look and feel of the admin module.

PostgreSQL Support

We have completely changed our ORM structures and custom queries so it can be friendlier to other RDBMS. In this release we focus on portability of the host database and finally have core PostgreSQL support.

Performance

We have analyzed the entire ORM structures, queries and CFML code in this release thanks to FusionReactor's Profiler. We have streamlined the way the CMS loads and the results are impressive. In ContentBox 5, first loads are about 70% faster and page executions are around 30-40% faster than ContentBox 4.

No More Admin Auto Updates

This is such a controversial feature to be able to deliver patches via the admin. We have completely dropped the capability to patch the CMS from within the CMS. It caused more issues than it solved and in Windows it was pretty much impossible.

We have moved to a CommandBox + Migrations approach and the results are amazing. No more broken installs, half done db updates and more. Now you can simply run two CLI commands and be done with it. Here is a typical flow for updating your system:

# stop the server
stop
# Update ColdBox and ContentBox
update coldbox,contentbox
# Run Migrations
migrate up
# start it up again
start

Release Notes

Bugs Squashed!

• [CONTENTBOX-1085] - Preflight check has a race condition where duplicate settings can be inserted and stop app from starting

• [CONTENTBOX-1106] - ColdBox modules directory renamed to modules_bak during upgrade to ContentBox 4.2

• [CONTENTBOX-1107] - Custom Module Dependencies are not respected by ContentBox ModuleService

• [CONTENTBOX-1111] - When deactivating modules, module widgets still remained registered

• [CONTENTBOX-1115] - Regression cachelayout setting missing from UI on pages and blog entries

• [CONTENTBOX-1118] - media service had a hardlink to the UI module which threw an exception when the UI module was removed

• [CONTENTBOX-1126] - BaseContent has expireDate as required via validation but not in the model

• [CONTENTBOX-1127] - Problem with multiple select options in RecentPages widget

• [CONTENTBOX-1128] - Problem in RecentPages widget on filter by category

• [CONTENTBOX-1132] - Fix CB admin bar image alignment on tailwind sites

• [CONTENTBOX-1133] - Fix ContentBox "latestversion" updater error #445

• [CONTENTBOX-1134] - Fix content sidebar toggle label #444

• [CONTENTBOX-1143] - multi domain bug when using cgi.http_host just like ColdBox, move to cgi.server_name instead affects all caching cleanups

• [CONTENTBOX-1151] - Bug in Widget View clearing out cached widget query

• [CONTENTBOX-1152] - ACF incompats with relocate() after applicationStop() due to ungraceful app metadata wiping by ACF

• [CONTENTBOX-1155] - Admin Views Accessible even if logged out: cbsecurity not firing.

• [CONTENTBOX-1157] - CB 5, Context menu Sitemap not visible, see screenshot

• [CONTENTBOX-1158] - ms sql server doesn't support sqltype boolean

• [CONTENTBOX-1196] - When cloning and marking to publish, not publishing due to missing publish date

• [CONTENTBOX-1198] - Site settings for comments are not being transferred

• [CONTENTBOX-1182] - "\" doesn't go to global search

• CONTENTBOX-1331 zipSlip fix for zip extractions

• CONTENTBOX-1330 Error in Menu Sandbox

• CONTENTBOX-1329 Listing Options do not work in Media Manager

• CONTENTBOX-1327 Content Store, Entries and Pages Clone Error

• CONTENTBOX-1318 If Page and ContentStore Item Have the Same Slug an Error is Thrown

• CONTENTBOX-1317 Deleting a ContentStore Item from the Options Menu Throws an Error

• CONTENTBOX-1316 Text Filter on Widget Insert is Broken

• CONTENTBOX-1311 Truncate Auth Logs Function Throws SQL Error on SQL Server

• CONTENTBOX-1307 ContentBox Menus and Submenus Default Order to Publish Date, not the Order

• CONTENTBOX-1306 "Create Page" button in Admin throws Error

• CONTENTBOX-1304 No Longer Able to Drill Down in Site Map

• CONTENTBOX-1302 Theme is reset to default when saving a site

• CONTENTBOX-1298 Prevent Re-Slugification of ContentStore Slugs on Every Save

• CONTENTBOX-1290 Add Backward Compatibility Alias for @cb for ContentBox Models

• CONTENTBOX-1284 Saving content on one site, if your site selection clears, will result in the

• assignment of page to default

• CONTENTBOX-1277 The model namespace of cb was always wrong. It should have been contentbox if not, no module settings woud have ever been set.

• CONTENTBOX-1276 RenderView Widget Attempts to Render Before View has Been Set

• CONTENTBOX-1268 Regression - menu() in the cbHelper does not return the menu children in data mode

• CONTENTBOX-1266 Data Snapshots in Admin are not Site Aware

• CONTENTBOX-1256 DIFF Screen forces everything onto a single line and is unusable in a modal

• CONTENTBOX-1251 Change tray icons to relative paths so CommandBox can open them correctly

• CONTENTBOX-1245 contentstore saving did not account for original slug in order to change downstream hiearchies

• CONTENTBOX-1240 Ordering pages on the sitemap breaks the javascript

• CONTENTBOX-1231 exception when visiting newly created sites due to theme not being activated

• CONTENTBOX-1224 Site Data Does not Export

• CONTENTBOX-1220 Cache cleanups interceptor missing events for entry and content store removals

• CONTENTBOX-1214 Font issues when loading admin

• CONTENTBOX-1206 Respect carriage returns on comments

New Feature

• [CONTENTBOX-1121] - Upgrade javaloader to v2.0

• [CONTENTBOX-1123] - Upgrade to cborm 3 and get all of it's goodness

• [CONTENTBOX-1135] - Upgrade to ColdBox 6

• [CONTENTBOX-1136] - Upgrade to CBSecurity 2

• [CONTENTBOX-1139] - New configuration for site is using cfconfig with environment variables

• [CONTENTBOX-1140] - Upgrade the usage of `bit` sql type to `boolean` sql type to avoid issues with major DB vendors and also to support PostgreSQL natively

• [CONTENTBOX-1141] - Multi-site capabilities for all content and installations

• [CONTENTBOX-1142] - All administrator js/css libraries updated to latest versions

• [CONTENTBOX-1149] - Installer can now create a production and development site for you thanks to multi-site support

• [CONTENTBOX-1153] - update security rules to match cbsecurity 2.0

• [CONTENTBOX-1179] - Upgrade to cborm 3

• [CONTENTBOX-1192] - Use Docbox 3 to generate the docs instead of the old approach

• CONTENTBOX-1308 Refresh tokens support

• CONTENTBOX-1301 Remove all $(document).ready() and move to DOMContentLoaded events to avoid relying on jquery and allow for deferred js

• CONTENTBOX-1300 Load all js assets with defer to allow for modern JS libraries and for non blocking to DOM loading

• CONTENTBOX-1291 Add ability for all search based content type services to have a array of property list return

• CONTENTBOX-1275 Consolidate the editors (pages,contentstore,entries) to a single content editor

• CONTENTBOX-1274 content version Diff ignore whitespace by default

• CONTENTBOX-1269 Content Object Helpers

• CONTENTBOX-1264 Enable Setters on Primary Keys to allow for migration of uuids to be consistent

• CONTENTBOX-1257 Add export all and export selected to bulk actions

• CONTENTBOX-1254 Add ability to load .env files on demand for NON commandbox installations

• CONTENTBOX-1253 Ability to configure all orm settings via env variables.

• CONTENTBOX-1252 Add filtering to geek settings by site

• CONTENTBOX-1249 Remove the dsn creator in preference to our cli based approach

• CONTENTBOX-1248 DSN Creator should update the dialect once the process starts

• CONTENTBOX-1246 Allow json as native markup for content storaage

• CONTENTBOX-1244 Ability to have unique slugs on a per content type basis instead of before which was unique across content types

• CONTENTBOX-1242 Use the browser's timezone to display all date times to users

• CONTENTBOX-1241 Add cbswagger documentation to resources and api module

• CONTENTBOX-1238 tailwind polyfills

• CONTENTBOX-1234 ContentBox core now registers a contentbox-tasks schedule executor that can be used for scheduled tasks

• CONTENTBOX-1232 Add an option to open a site from the site manager

• CONTENTBOX-1225 Add a clear entire template cache from the admin

• CONTENTBOX-1222 new buildContentCacheCleanupKey() on content objects so we can clean multiple permutations of the same content

• CONTENTBOX-1219 Introduce category count caching to speed up renderings

• CONTENTBOX-1217 Rearchitecture of the active content to NOT be a relationship but using the versions relationship

• CONTENTBOX-1213 New Updater task and start of tasks that can ship with ContentBox

• CONTENTBOX-1205 Add support for markdown comments from the ui

• CONTENTBOX-1168 Responsive UI Verifications

• CONTENTBOX-1153 Upgrade to cbSecurity 2

Task

• [CONTENTBOX-1110] - Drop lucee 4.5 support

• [CONTENTBOX-1138] - Drop support for `runtime.properties.cfm` in favor of cfconfig datasource additions

• [CONTENTBOX-1144] - Remove autoupdates capabilities in order to rely on CommandBox for patches and updates

• [CONTENTBOX-1166] - Upgrade v4 migration to only run on v4 systems

• [CONTENTBOX-1177] - Removal of full screen button as all browsers support this now

• [CONTENTBOX-1181] - Remove the textarea editor, it's useless

Improvements

• [CONTENTBOX-1108] - Add restrictions on orm cfc locations for faster startups on Application.cfc

• [CONTENTBOX-1109] - Remove directory browsing for production installations

• [CONTENTBOX-1116] - Change the order of the logout function, to the announcement has the oCurrentAuthor still, for logging purposes.

• [CONTENTBOX-1117] - Update dsn creator to support lucee 5.3 mysql jdbc path

• [CONTENTBOX-1120] - Intercept installer relocation to check if the installer module is even installed else present a nice message

• [CONTENTBOX-1125] - Add a setting for the timeout in the forgot password workflow

• [CONTENTBOX-1131] - Encode theme settings in active theme page

• [CONTENTBOX-1150] - CSS Updates to match new admin theme

• [CONTENTBOX-1156] - CB5 - Multi site - feature to allow URL Path

• [CONTENTBOX-1161] - DSN Module Update to latest CFML engine settings

• [CONTENTBOX-1197] - Refactor formulas to methods so they can give a performance boost and increase encapsulation

• [CONTENTBOX-1193] - update express to latest stable lucee

• [CONTENTBOX-1194] - update express to latest tomcat 9

• [CONTENTBOX-1195] - update tuckey rewrites to latest based on commandbox

• CONTENTBOX-1328 Inconsistent spacing between panels under Details

• CONTENTBOX-1324 Create Setting - Core Checkbox With Global Option Seems Redundant

• CONTENTBOX-1319 SSL Options on Relocation Widget Should Default to Current Protocol

• CONTENTBOX-1315 Settings Area is Extremely Slow to Load on Large Site

• CONTENTBOX-1314 Stats for Subscribers Should be Placed under Comments Menu

• CONTENTBOX-1313 Site Selection Cookie Should Either Not Expire or Expiry Forwarded on Request

• CONTENTBOX-1310 Drag and Drop Ordering on Large Site Tree is Very Slow

• CONTENTBOX-1305 Issue a warning when you will save content that is published and into draft mode.

• CONTENTBOX-1299 Finalize migration to ColdBox 6 REST instead of REST Template assets

• CONTENTBOX-1297 Increase Column Size of Content slugs, title, featuredImage, featuredImageURL

• CONTENTBOX-1294 CKEditor Allow access to ContentBox Plugins Insert Buttons in Source Edit Mode

• CONTENTBOX-1293 SubPage Menu Widget should Default to Current Page

• CONTENTBOX-1289 Dashboard Should Be a Single Link in Admin and "About" should be in "System"

• CONTENTBOX-1288 Clicking in to a Content Objects Children should Reset Page Scroll

• CONTENTBOX-1287 Allow transactional argument to SiteService@save

• CONTENTBOX-1283 Allow Categories to be Internal/UnPublished

• CONTENTBOX-1282 Migrate post to pre js for assets to save on minimization and inline js that is used.

• CONTENTBOX-1281 Admin current working site id should be set in a cookie instead of cache to provide longevity.

• CONTENTBOX-1279 Loading Site Config Page on Large Site is Extremely Slow

• CONTENTBOX-1273 rework all settings tabs to have their own form and validation to avoid validation issues in different tabs you don't get notified with

• CONTENTBOX-1272 ACF increase post parameter list for mass setting updates

• CONTENTBOX-1255 Add JSON Diffing support for ContentStore items in the history panel

• CONTENTBOX-1250 Add quoted table names, join columns and columns to preserve case on all RDBMS systems

• CONTENTBOX-1239 Also the DSN name is now hard-coded in the cfconfig file so you can have a database named something other than "contentbox"

• CONTENTBOX-1223 Update the clear page wrappers call to include multi-site regex expression to clear stale data

• CONTENTBOX-1218 Add an isPreview to the addContentVersion() so the max content checks are not executed on previews

• CONTENTBOX-1216 registering info for contentbox logging as the default.

• CONTENTBOX-1215 If a post has been written in a certain markup, make sure the editor adheres to it

• CONTENTBOX-1211 Granular performance optimizations for content object iteration and rendering

• CONTENTBOX-1210 Optimize avatar image creation by using a request cache

• CONTENTBOX-1209 Optimize the way site() does discovery and site usage by adding a request cache

In this section you will deploy ContentBox so it can run on any running Adobe or Lucee CFML engine. The first step is to use CommandBox and our contentbox-cli package so we can install and configure ContentBox for usage in any CFML Engine. We won't be using CommandBox as our server, just as a package manager and CLI.

Install CommandBox

​

​CommandBox is a ColdFusion (CFML) Command Line Interface (CLI), REPL, Package Manager and Embedded Server. We will leverage the CLI in CommandBox to install, deploy and configure ContentBox.

Requirements

• MacOS, Windows or Linux

• JDK 8+

• A clean, empty directory on your machine

Download CommandBox

You can download CommandBox from the official site: http://www.ortussolutions.com/products/commandbox#download and install it in your preferred Operating System (Windows, Mac, Unix).

Starting CommandBox

Once you download and expand CommandBox you will have the box.exe or box binary, which you can place in your Windows Path or *Unix /usr/bin folder to have it available system-wide. Then open the binary and CommandBox will unpack itself your user's directory: {User}/.CommandBox. This happens only once and the next thing you know, you are in the CommandBox interactive shell!

We will be able to execute a-la-carte commands from our command line or go into the interactive shell for multiple commands. We recommend the interactive shell as it is faster and can remain open in your project root.

Install ContentBox-CLI

We can now install the contentbox-cli package:

install contentbox-cli

Once installed you can always run contentbox help to get the list of available commands and help information.

Creating Your Database

Create a database in your RDBMS of choice. Make sure you note the name of the database, the connection details and the credentials for it.

Creating Your Datasource

Now go to your CFML engine administrator and register the contentbox datasource that points to the database you just created.

Resources

• https://docs.lucee.org/guides/cookbooks/datasource-define-datasource.html

• https://helpx.adobe.com/coldfusion/configuring-administering/data-source-management-for-coldfusion.html

Creating A ContentBox Site

Now that we have our CLI installed, database and datasource created, go or create a new directory where we will create our site. Most likely this folder will be your web root in your CFML engine installation or a sub-folder within that web root. Let's assume it's the web root of your current CFML Engine installation.

# Create a new directory and go into it.
mkdir mysite --cd
# Run the installer wizard
contentbox install-wizard

The wizard will take you by the hand and ask you all the relevant questions about your installation:

1. Name of your site

2. Which CFML Engine you will be running ContentBox on (Lucee5, Adobe 2018+)

3. Password for the ColdBox HMVC Reinits

4. Database of choice (MySQL5+, MSSQL, PostgreSQL, Oracle)

5. Database credentials

6. Development or production site

7. Latest ContentBox version, specific or be bleeding edge

8. Deploy a CommandBox server or not. This should be false, as we are only deploying our code to the CFML engine we have already installed.

Confirm your settings and the installer will configure the entire site for you including ORM dialects, environment variables and much much more.

Web Installer

Now that we have installed ContentBox on disk and configured your CLI to connect to your database for delivering database migrations, we can finalize the installation via the web installer. Now open the installer by navigating to the root of the project. Let's assume you are running your CFML engine on port 8500:

http://localhost:8500

ContentBox will automagically create all the necessary database tables, indexes, and constraints for you. After it does this, it will present you with our ContentBox installer, where you will fill in:

• Administrator Account

• Site Information

• Notification Emails

• Email Information

• URL Rewriting

• Enjoy your ContentBox installation!

We are so excited you are here and ready to get started with ContentBox Modular CMS one of the most modern ColdFusion (CFML) Content Management Platforms. There are several ways to install ContentBox, so make sure you explore all the options. We strongly recommend using our contentbox-cli to install ContentBox as it is the easiest way to get started.

CommandBox is a ColdFusion (CFML) Command Line Interface (CLI), REPL, Package Manager and Embedded Server. We will leverage the CLI in CommandBox to install, deploy and configure ContentBox.

Requirements

• MacOS, Windows or Linux

• JDK 8+

• A clean, empty directory on your machine

Download CommandBox

You can download CommandBox from the official site: http://www.ortussolutions.com/products/commandbox#download and install it in your preferred Operating System (Windows, Mac, Unix).

Starting CommandBox

Once you download and expand CommandBox you will have the box.exe or box binary, which you can place in your Windows Path or *Unix /usr/bin folder to have it available system-wide. Then open the binary and CommandBox will unpack itself your user's directory: {User}/.CommandBox. This happens only once and the next thing you know, you are in the CommandBox interactive shell!

We will be able to execute a-la-carte commands from our command line or go into the interactive shell for multiple commands. We recommend the interactive shell as it is faster and can remain open in your project root.

Install ContentBox-CLI

The first step in our adventure is to install the contentbox-cli package that will handle installation, scaffolding, and management of ContentBox sites.

install contentbox-cli

Once installed you can always run contentbox help to get the list of available commands and help information.

Creating Your Database

Create a database in your RDBMS of choice. Make sure you note the name of the database, the connection details and the credentials for it. You will need them in the next step.

Creating A ContentBox Site

Now that we have our cli installed, go or create a new directory where we will create our site.

# Create a new directory and go into it.
mkdir mysite --cd
# Run the installer wizard
contentbox install-wizard

The wizard will take you by the hand and ask you all the relevant questions about your installation:

1. Name of your site

2. Which CFML Engine you want to run it on (Lucee5, Adobe 2018+)

3. Password of the CFML engine administrator

4. Password for the ColdBox HMVC Reinits

5. Database of choice (MySQL5+, MSSQL, PostgreSQL, Oracle)

6. Database credentials

7. Development or production site

8. Latest ContentBox version, specific or be bleeding edge

Confirm your settings and the installer will configure the entire site for you including ORM dialects, environment variables and much much more. It will also startup the chosen CFML server so you can continue with the web installer.

Web Installer

The web installer will then take you through adding your first administrator user, email configurations and your production and development site in one box. Once you follow the wizard, ContentBox is up and running! Enjoy!

Starting & Stopping

You can use the CommandBox commands to interact with the embedded server:

• server stop to stop the server

• server start to start the server

• server restart to restart the server

• server log to view the log files

• server help to get help on your server commands

What's Next

You now have a fully functional ContentBox installation with two sites: development and production. You can now start creating your content, themes, modules and much more.

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late '70s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development, and all open source professional services under the ColdBox, CommandBox. and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox, and anything “BOX”, and contributes to many open-source projects. You can read his blog at www.luismajano.com

Luis has a passion for Jesus, tennis, golf, volleyball, and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers, and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

Jorge is an Industrial and Systems Engineer born and raised in El Salvador. In 2004 he moved to Monterrey, Mexico to complete his Bachelor's studies at ITESM. In 2009, after graduating, he went back to his home country where he worked as Operations Manager for SIHAM, Industrias Bendek S.A. de C.V. from 2009 to 2012.

In 2012 he moved to Switzerland and married his beautiful wife Marta. In 2013 he joined Ortus Solutions as a Project Manager and currently serves as Ortus Business Manager.

He is passionate about delivering value to customers through the modernization of business processes, tools, and technologies, and has been part of the Ortus Modernize or Die movement since its inception.

He has been blessed with 3 children: Sofia, Isabella, and Jorge, and loves spending time with his family. He enjoys a nice kickboxing workout session and is a mountain-bike-weekend-warrior. On Sundays, he serves as a Worship Pastor at Iglesia Cristina Hispano-Suiza in Pratteln and rejoices in the Lord Jesus Christ.

Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17

Quick Setup

The Quick Setup will take you through 8 easy steps in order to configure and install a ContentBox Express Edition with an embedded database so we can start working with ContentBox. Ready, set, go!

Note If you prefer a container (Docker) approach, then use the .

Step 1: Download

Go to and click on the download ContentBox Express Edition for your operating system.

Once downloaded, extract the contentbox-express-{version}.zip (we recommend you to do this in a new folder).

Step 2: Start it up!

Open the bin folder and double click startup.bat (Windows) or execute the startup.sh (Linux, Mac) and Kaboom! ContentBox will start to deploy a local embedded server with an embedded database.

Warning If you are in Unix or Mac OS X, make sure you give the bin folder execution permissions. You can do this by running chmod -R +x bin to give the directory execution permissions.

Step 3: Running the Installer

Once the server is online go to your browser and type http://localhost:8085 which is the port that ContentBox Express uses and hit enter. Your browser should now open the install wizard. Read the instructions and click on the Start Installer button to start the process.

Hint If you go back again to the bin folder you are going to find a new folder called contentboxDB. This is the ContentBox Express embedded database. This doesn’t mean you can’t use other data bases with ContentBox Express Edition, but it has been done this way out of convenience.

Step 4: Administrator Information

Fill out the setup details for your ContentBox Administrator and click Next Step.

Step 5: Site Setup

Fill out basic information for your ContentBox Site and click Next Step.

Step 6: Email Setup

You can connect ContentBox to any email system in order to send notifications. By clicking Next Step without changing anything ContentBox will use by default the email settings in your application server (default).

Step 7: URL Rewrites

ContentBox Express Edition already has Full URL Rewrites enabled. So just use the dropdown to select ContentBox Express and it will automatically configure ContentBox for full URL rewrites. We also support iis, nginx, apache, and CommandBox.

Step 8: Done!

Click Start Installation! ContentBox will prepare the database and process the final configurations so it can start running.

You are done! Go ahead and visit your site by clicking Visit Site and log into your Contentbox Administration by clicking Visit Administrator.

Danger : Please make sure you delete the contentbox-installer and contentbox-dsncreator modules after installation. The administrator will warn you about it and you can even delete those modules from the admin dashboard.

Welcome to ContentBox!

The Administrator Module Login Screen

The login URL to use to access the ContentBox administration module is:

https://your.domain.com/cbadmin/

You will need to use the username and password that you created during install, or one that your system administrator has provided for you.

The express version of ContentBox is a fully embedded running server powered by , an open-source CFML engine, and Tomcat. It comes bundled with a JRE for your operating system or one without a JRE can be downloaded as well.

Requirements

Make sure your system has a working Java Runtime 1.7+ environment if you are downloading the express version with no JRE. A quick test to see if your system supports Java is to open a terminal or command prompt and typing:

You should see something like this:

Just make sure what it is Java 1.7+.

Step 1: Download Express

The first step is for you to download ContentBox () or you can use the command below:

Once downloaded expand the archive

This will expand into the folder of your liking.

Step 2: Permissions

On some operating systems like Linux or Mac, you will need to enable run permissions. So drop into a shell or terminal in that folder you expanded and type:

This will add execution and write permissions to the bin folder which is required.

Step 3: Run it

Go into the bin folder and execute either the startup.bat or startup.sh or startup.app according to your OS. Then visit the site in a browser on port 8085 by default.

Step 4: Setup Server Passwords

Make sure you visit the following URLs and set up a server and web application password for the underlying engines:

Step 5: Create A Datasource

You can now visit your application under http://localhost:8085 and you will be presented with our datasource wizard. Since we are in express edition, just choose the embedded database and follow the instructions.

Step 6: Run ContentBox Installer

That's it! We are now ready to run the ContentBox installer wizard. ContentBox will automagically create all the necessary database tables, indexes, and constraints for you. After it does this, it will present you with our ContentBox installer, where you will fill in:

• Administrator Account

• Site Information

• Notification Emails

• Email Information

• URL Rewriting

• Enjoy your ContentBox installation!

Changing the Default Port

Go to the conf/server.xml and look for the following:

Just update the port to whatever you desire.

ContentBox sports its very own . As with the , the [major].[minor].[patch] versioning mirrors the upstream product version, so it's easy to pull deploy a specific version, should your application require it.

Playing around

CommandBox Image Features

Persisting Data Between Restarts

The above run command produces an image which is self-contained, and would be destroyed when the container is stopped. If we wanted to run a version in production, we would need to persist, at the very minimum, the database and your custom assets (widgets, modules, themes, and media library). In order to do this, we need to mount those resources into the Docker host file system.

By convention, the express H2 database is stored at /data/contentbox/db inside the container. In addition, the custom content module which contains your custom themes, widgets, modules, and media library are stored under /app/modules_app/contentbox-custom.

Mountable Points

Let's mount both of those volume points so that our database and user assets persists between restarts:

Now, once our image is up, we can walk through the initial configuration. Once the configuration is complete, simply stop the container and then start it without the environment variable INSTALL in place. The H2 database and uploads will be persisted and the installer will be removed automatically on container start.

INSTALL Setting Caveats

Please remember that the INSTALL environment variable is ONLY used to go through the ContentBox installer wizard. Once the database is seeded with the installation process, you will no longer use it unless you want to reconfigure the installation.

Custom Database Configuration

If you would like to connect your container to an external database system, you can very easily do so, which would allow us to connect from multiple containers in a distributed fashion (MySQL, Oracle, MSSQL, etc). If not, you run the risk of file locks if multiple container replicas are sharing the same H2 database.

To programmatically configure the database on container start, environment variables that represent your datasource configuration should be provided. There are two patterns supported:

1. DB_DRIVER configuration - which may be used for Adobe Coldfusion servers

2. DB_CLASS configuration - which configures a datasource by JDBC driver and connection string (Both Adobe and Lucee)

An example container run command, configuring a MySQL database would be executed like so:

To use the DB_DRIVER syntax for Adobe Coldfusion, an example run command would be:

Granular Environmental Control

A number of environment variables, specific to the ContentBox image, are available for use. They include:

• INSTALL=true (alias: INSTALLER) - Adds the installer module at runtime, to assist in configuring your installation. You would omit this from your run command, once your database has been configured

• BE=true - Uses the bleeding edge snapshot of the ContentBox CMS, else we will defer to the latest stable version of ContentBox.

• HEALTHCHECK_URI - Specifies the URI endpoint for container health checks. By default, this is set http://127.0.0.1:${PORT}/ at 30s intervals with 5 retries and a timeout of 60s

• FWREINIT_PW - Allows you to specify the reinit password for the ColdBox framework

• DISTRIBUTED_CACHE - Allows you to specify a CacheBox cache region for distributing ContentBox content, flash messages, cache storage, RSS feeds, sitemaps, and settings. There are only three cache regions defined in this image: default, template and jdbc. jdbc is the default cache that will distribute your data, default and template are in-memory caches. Please see the distributed caching section below to see how to register more caches.

• H2_DIR - Allows you to specify a custom directory path for your H2 database. By convention, this is set to /data/contentbox/db within the container

• ORM_SECONDARY_CACHE - If true it will activate the ORM secondary cash to the ehcache provider. By default, it is turned off.

• ORM_DIALECT - You can choose the specific ORM dialect if needed, if not we will try to auto-detect it for you.

• HEADLESS=false - If true then this image will not publish an Admin module, just the core, REST and UI modules.

Automatic Session Distribution

By default, the ContentBox image will use the Lucee Open Source CFML engine for running the application. It will also configure the datasource to store user sessions so you can easily scale the image or send it to Docker Swarm, Kubernetes, etc for scalability.

You can also use the SESSION_STORAGE environment variable to switch the connection to any backend you like.

Distributed Caching

By default, our image configures a jdbc CacheBox cache region that will be used to distribute settings, sessions, flash data, content, RSS feeds, sitemaps, etc. This means that out-of-the-box, your ContentBox containers can use the database to distribute its content within a swarm or set of services. However, if you would like to use your own CacheBox providers or a more sophisticated distributed cache like Redis or Couchbase, you can.

Healthchecks

The image contains built-in capabilities for health checks for the running application. You can customize the URL entry point by using the HEALTHCHECK_URI environment variable. By default, this is set http://127.0.0.1:${PORT}/ at 30s intervals with 5 retries and a timeout of 60s.

In Short

The ContentBox image for Docker re-vamps the entire Modular CMS game by de-coupling your customizations and user assets from the underlying framework. It can make your source code lighter-weight, as well as providing you with a standardized development environment, which matches your production container strategy.

If you already have a ColdBox application and you wish to install ContentBox into it, you most definitely can.

System Requirements

Please note that ContentBox 4.x requires ColdBox 5.x

Step 1 : Dependencies

Since version 3.5.0, you can now simply issue a command in CommandBox to install the ContentBox module into an existing ColdBox application. Just open a box shell in the root of your ColdBox application and use the following command:

This will install the ContentBox module with all of its dependencies under the /modules/contentbox and the ContentBox installer module under /modules/contentbox-installer.

Step 2 : Application.cfc Updates

Now open your Application.cfc and you will add the following updates:

Mappings

ORM Settings

Step 3 : ColdBox.cfc Settings

Open your application's ColdBox.cfc and you will add the following settings:

That's it! Once all those settings, mappings and module installations are done you can now visit the installer module to continue with the installation process: http://localhost/index.cfm/cbinstaller

Step 4: CacheBox.cfc Settings

Open your CacheBox configuration file: config/CacheBox.cfc and add the following cache declarations:

Once these updates are done, then you can start up the server and visit the installer URL: http://localhost:port/cbInstaller

Step 5 (Optional) : UI Route

By default ContentBox is in take over mode. Meaning that the UI module will intercept all calls made to the application and process them as pages or blog entries. If you DO NOT want this to happen, then you can segregate the UI module into a single entry point URL like blog or site or pages. You can do this by opening the following file: modules/contentbox-ui/ModuleConfig.cfc and looking for the following code:

Now update the this.entryPoint to whatever you like the entry point URL to be. Restart the application and voila!

ContentBox is upgraded using CommandBox via the CLI. If you are upgrading from minor to minor/patch level, most likely you won't need to follow an upgrade guide. However, if you are upgrading between major versions make sure you visit each of the major versions' upgrade guide first.

Make a full backup

Make sure you backup your database and source, just in case. We recommend running this against a development instance first and then moving on to production instances.

Update Command

When you are ready with your backups, open up a CommandBox shell using box in the root of your project.

This will update ColdBox and ContentBox respectively and any other dependencies listed in your box.json

Run database migrations

Now that the ContentBox source has been upgraded, let's run the database migrations

Once they run, you are ready to roll!

Professional Updating

The ContentBox team can also do the heavy lifting for you as we are a professional open source project. So just contact us and we will update or install any ContentBox instances in a secure and fast way!

Issues Upgrading

Contentbox has many options for creating and managing content, which are accessible through the ContentBox Administrator:

1. Blog entries

2. Categories

3. Content Store Items

4. Media Manager

5. Menu Manager

6. Sitemap ( Pages )

In the following chapters you'll find an quick overview of each one of these options.

ContentBox allows you to create and publish content directly from the Administrator. There are two main sections where you can do this

• Blog | You can create and publish blog posts.

• Sitemap | You can create and publish pages

[Content + Categories] Categories is very simple, it's just categorization. This is where you can create as many categorize as you see fit.

Our about page is very useful. Apart from your build information, it contains keyboard shortcuts! ContentBox has a lot of keyboard shortcuts available for you, and once they are memorized, you can easily navigate using them. Also, for you module developers, we have an API based on a jquery javascript library. You can do data binding for your own shortcuts, so it's very easy if you want to offer your own keyboard shortcuts.

Across the top of the ContentBox Dashboard is the header bar. Let's take a look at the icons and buttons, from left to right. On the upper left, next to the ContentBox logo (which will return you to the dashboard), is a button that allows you to toggle the menu. Clicking this button allows the main content of the page to occupy more real estate. To the right of this button is a robust global search feature that categorizes your search results into ContentStore, Page, and User.

In the upper right corner of the header are four buttons. The first is the House icon which takes you to the active site's homepage. To its right is the Plus icon, which allows you to add content, including new pages, new content store items, new users, new media, and new menus. The third button, second from right, is a Gear icon which allows you to perform cache-clearing functions, including RSS caches, content caches, the template cache, and more. You can also reload ORM as well. You can even reload every single module that you have available at ContentBox - your entire application - from this menu.

In the main section of the Dashboard you have three tabs: Content Reports, Recent Comments, and Recent News. The data in the Content Reports tab contains your latest edits, followed by other types of content: Future Published, Expired, and Drafts.

To the right of the main, three-tabbed section you can find the right panel, which is divided up into three sections: Data Snapshots, Latest Logins, and a Help Section. Under the first section, Data Snapshots, you can check on the Top Hits & Comments, Discussion Counts, and Content Counts. These expandable menu selections allow you to drill down to get more detail on your site's popular pages, pending approvals, and other important statistics.

Everything you see through the site has what we call a Quick View. By right-clicking on any instance you can get the content immediately as a Quick View so you can edit or actually view it and see the content within. Note: You can’t Quick View the Content Store.

As you can imagine, there are a lot of widgets you can use in ContentBox. Most widgets have specific and larger functionality… sometimes you might want something quick and simple… like outputting a single variable. You can output any RC or PRC variable with a simple helper function.

What does RC and PRC mean:

• RC - Request Collection

• PRC - Private Request Collection

The underlying framework (ColdBox) will merge the incoming URL/FORM/REMOTE variables into a single structure called the request collection structure that will live inside the request context object. We also internally create a second collection called the private request collection that is useful to store data and objects that have no outside effect.

Syntax

The code below allows you to easily output from any of these source:

${rc:name}

This will output the name variable from the RC scope.

Accessing URL Variables

This means you can output URL variables in your content. Look at this example, with the following url

mydomain.com/?name=Gavin Pickin

You could access the name with ${rc:name}

You can tap into more items in the RC and PRC scopes as well, but you have to remember, you cannot output a struct to the page, only strings.

This gives you some nice options for form submissions, searches, and ways to add more information to a normal pages if you write your own modules.

Escaping Dynamic Output

If you actually want to use the text above, without trying to output a variable, you can escape the code.

<escape>${rc:name}</escape>

If you do not escape the variables, and the variable doesn't exist, you'll see an error message like this:

Error translating setting on target prc:page.renderContent(): The variable: page.renderContent() is undefined in the request collection (private=true) Keys Found: META,currentLayout,CBENTRYPOINT,currentRoutedURL,layoutmodule,currentView,CBROOT,layoutoverride,CBWIDGETROOT,CBSETTINGS,COMMENTSCOUNT,CATEGORIES,cbox_incomingContextHash,currentRoute,CBADMINENTRYPOINT,COMMENTS,PAGEOVERRIDE,OCURRENTAUTHOR,CBTHEME,CBTHEMEROOT,currentViewArgs,PAGE,viewModule Error translating setting on target rc:lastname: The variable: lastname is undefined in the request collection (private=false) Keys Found: namespaceRouting,event,pageSlug,format,namespace

Settings

Any setting stored in ContentBox can be output using the following markup: ${setting_name}. This is a great way to create site-wide static settings that can be output in any editor.

ContentBox is a CMS built by developers, for our own use. We obviously try and cater to the usual CMS functionality features, but being developers, we tried to throw a couple of extra goodies into ContentBox.

In this section, we'll give you a few tips about the different editors available and some of the features common to all of the editors.

Blogging capabilities are an essential component for any website and web application. Blog entries help provide more context around products, services. It inherently creates more online presence and, if managed properly, better search engine results.

ContentBox comes with a built-in blog which you can turn ON and OFF from System > Settings. The default setting is ON.

The main Blog page in your ContentBox Administrator shows a table with all your blog posts. We have 3 useful indicators.

• Shows if your post has been published

• Shows the numbers of views

• Shows the number of comments

And you also have quick actions:

Where you can check the info related to each individual post

And entry actions

Editor Auto Save

We have introduced local storage auto saving capabilities for all editors in ContentBox. No matter the implementation, we will provide auto-save capabilities. This is a great way to know that silently your work is secure. I don't know how many times I select all and type by mistake. This feature has saved my bacon, and now you know about it, it could save you too.

Escaping Markup Translations

With any Bulletin Board Forum, or CMS, they each have their own syntax for special markup. You can now use the <escape></escape> syntax in any content editor to escape ContentBox translations for settings, markdown, etc.

Editor Responsive Previews

All live previews are now responsive, meaning you can choose from the responsive previewer the type of device and get immediate feedback of the content result in real-time.

Editor UI Updates

The content editors have been completely re-designed for a mobile first paradigm. They sport new tabbed interfaces for history, comments, custom fields and editing. You also have much more real estate when editing and even full screen editing support...including auto shrinking the left side bar, with an option to shrink the right sidebar too.

Running a website, on top of your normal job duties can be a lot of work. Time is valuable, and important when trying to plan your content and the corresponding social media publication. This is the reason why we created an important ( but often overlooked ) feature, Publication and Expiration dates for content. You might be surprised what in ContentBox is date controlled.

Blog Posts

This is most useful when scheduling blog posts. Blog posts can take a long time to write, and post, and with busy schedules this might not get done. This is why at Ortus Solutions, we try to write our blog posts, and schedule them ahead of time. When editing a blog post, in the right hand side 'sidebar', you will see these options at the top of the sidebar.

You can set the publish date / time, and the post will go live at the right time for you.

Expiration dates are useful too, but not a normal use case for blog posts… but these scheduling options are not just available for blog posts. Expiration dates work great for webinars or other events, where a sign up page should be removed after event sign ups close, or maybe a special or promotion that should only who while it's active. This will even show and hide menu items in your navigation.

Pages

Lets look at the Page Details version of the Publishing options

As you can see, they are exactly the same. This makes it familiar and easy to work with. This is also the case for Content Store items… which gives you even more options in regards to scheduling content.

Content Store Items

ContentStore items can be included inside of pages and blog posts too, which means you can include a time-based piece of content into your homepage, to show upcoming events, or show a link to a signup page for an event, and then hide the link when the registration period is over.

This is a nice feature, which at the surface looks simple but useful, but with this feature working with ContentStore items as well, the options are endless.

Developers are getting more and more familiar with Markdown, and it's actually preferred by a lot of developers when it comes to writing documentation and blog posts, and that is why we give you native support of Markdown in the ContentBox editor. We also threw in a few other features when adding support, some might just save you hours of work.

We have included a new code editor that supports HTML and Markdown natively. This will allow developers or editors to write in native markup and have all the integrations into ContentBox.

The new editor also sports real time previews and side-by-side editing in full screen. Your editing experience is about to get a whole lot better now.

[Look & Feel + Layouts] Now, Look and Feel are obviously very important. So you have our layouts section. As you can see some of our sections are tied to forgebox [ForgeBox upper right corner].

Again this is administration permission, but you can actually talk into ForgeBox [click ForgeBox] so you can connect to ForgeBox. It will bring you all the different setups available that you can install immediately. If you download a layout, for example, you can then go to your Manage Layouts.

[click manage layouts / left side panel] and you can see that the new layout will be there. If you want to set it as your current layout you can go ahead and activate it [click Activate for the layout]. You can go to your site and check your new layout. So very easy [back to admin \/ active layout] you can now start skinning or downloading themes.

If you are building themes just please remember to contribute to ForgeBox so everybody can benefit.

[Manage Layouts] Management is for you to be able to see which layouts you have. Activate them, upload them, if you need to upload a new theme [Upload layout / up right], rebuild the internal registry, or do any kind of clean up.

The menu manager allows you to create 'Menus' to be used in a variety of ways in your ContentBox Website. A Menu can contains several Items, which can be from a range of Item types, Content like Pages and Blog posts, Media, Submenus, URLs, JS or Free type. Menus are easy to create, and give you a lot more options that relying on pages inside your traditional Sitemap structure.

By default, ContentBox sites use the Sitemap to generate a menu for display. To use a Menu instead of the Sitemap, you have to install a Theme which supports Menus, and then select the Menu you wish to use as you main site Menu.

Some Themes may support additional menus for top menus, footer menus, side bar menus. Please refer to your Theme.

Menu Data

• Title: The name of the Menu

• List Type: ( ul | ol ) Unordered List or Ordered List

• Menu Slug: This is the code referenced slug, to be used to retrieve the Menu in the Theme or View, where required.

• CSS Classes: Optional CSS Classes to be added to the Main Menu List itself ( ul or ol - when supported by the Theme )

• List CSS Classes: Optional CSS Classes to be added to each of the List Items ( li - when supported by the Theme )

Item Types

• Content

• Media

• Submenu

• URL

• JS

• Free

Each content type has it's own set of attributes.

Common Attributes (Shared by all Item Types)

• Label - Read Only - Same as the Item Content field below.

• Item Content - This is Name/Title that shows in the Menu Item itself.

• CSS Classes - Optional additional CSS classes to be added to the list item

Type: Content

Content refers to a Page, or Blog Entry. You can search and select the content item you wish this item to link to. The Item Content ( visible label for the menu item ) automatically populates when you select an item for Content Item.

In Addition to the Common Attributes listed above, this type also includes:

• Content - This is a search and selection tool to help you select a page or blog entry for this Menu Item to link to.

• URL Classes - Additional CSS for this Menu Item's HTML Element

• Target - Allows you to select how the link is treated by the browser, allowing

  • _self

  • _blank

  • _parent

  • _top

• Data Attributes - Allows you to add one or many data attributes for the menu item. You can use JSON ( {"me":"you"} ) or a comma-delimited list ( me=you,icecream=awesome )

• Title - An accessible title, commonly used by browsers as a tool tip.

Type: Media

Refers to Media from the Media Manager

In Addition to the Common Attributes listed above, this type also includes:

• Media - This is a search and selection tool to help you select a media item from the Media Manager for this Menu Item to link to.

• URL Classes - Additional CSS for this Menu Item's HTML Element

• Target - Allows you to select how the link is treated by the browser, allowing

  • _self

  • _blank

  • _parent

  • _top

• Data Attributes - Allows you to add one or many data attributes for the menu item. You can use JSON ( {"me":"you"} ) or a comma-delimited list ( me=you,icecream=awesome )

• Title - An accessible title, commonly used by browsers as a tool tip.

Type: Submenu

A Submenu type allows you to select an entire Menu to be included in the current Menu, as a Menu Item.

In Addition to the Common Attributes listed above, this type also includes:

• Select Sub-menu - This is a drop down select list of all of the Menus available for selection.

• Data Attributes - Allows you to add one or many data attributes for the menu item. You can use JSON ( {"me":"you"} ) or a comma-delimited list ( me=you,icecream=awesome )

• Title - An accessible title, commonly used by browsers as a tool tip.

Note: This relies on the Theme you are using, to utilize this feature.

Type: URL

A URL allows you to add any linkable URL you might desire into your Menu.

In Addition to the Common Attributes listed above, this type also includes:

• URL - The URL you wish to use for this menu item

• URL Classes - Additional CSS for this Menu Item's HTML Element

• Target - Allows you to select how the link is treated by the browser, allowing

  • _self

  • _blank

  • _parent

  • _top

• Data Attributes - Allows you to add one or many data attributes for the menu item. You can use JSON ( {"me":"you"} ) or a comma-delimited list ( me=you,icecream=awesome )

• Title - An accessible title, commonly used by browsers as a tool tip.

Type: JS

Not all menu items will be Links to other HTTP resources, with todays applications, we are commonly using more and more JavaScript, and the Menu Manager allows you to add JavaScript into your Menu Items as well.

In Addition to the Common Attributes listed above, this type also includes:

• JavaScript Code - JavaScript to be excuted when this Menu Item is clicked.

• URL Classes - Additional CSS for this Menu Item's HTML Element

• Data Attributes - Allows you to add one or many data attributes for the menu item. You can use JSON ( {"me":"you"} ) or a comma-delimited list ( me=you,icecream=awesome )

• Title - An accessible title, commonly used by browsers as a tool tip.

Type: Free

This is a menu item that creates a 'free-text' menu item. This item only uses the common attributes, Item Content, and CSS Classes... listed above.

Preview

As you add, edit, and delete Menu Items, you can preview those menu items in page. You can refresh the menu by clicking the refresh icon next to the title Preview if the preview has not updated as expected.

Content categories can be edited in the administrator, located under the left hand menu 'Content'.

Each post ( Page or Blog ) can be filed under zero, one or many categories. Categorization helps group content and gives users more options for navigating your content.

Links to your categories of blog posts show up in the right hand menu of your blog layout (theme implementation may vary), and show up as 'Tags' for your blog entry.

The category manager is simple, including a simple search, listing Categories with their associated slug, and a list of pages and entries currently associated with this category, and options to 'Edit' or 'Delete'.

You can perform Bulk actions using the checkboxs next to Category Name, and clicking 'Bulk Action', which allows you to perform one of the following tasks:

• Delete Selected

• Import

• Export All as JSON

• Export All as XML

Add a new Category

To add a new category, click the green button labeled 'Create Category' in the top right hand corner of the category manager. Clicking the 'Create Category' button pops a modal window up like below, asking for category name, and slug.

Category Name This is the name of the category, displayed wherever the category is used.

Slug The category slug is the unique id refereneced throughout the site, including the URL. If you leave the slug blank, the system will generate a slug for you, for example: If your category is called 'Recipes', the generated slug would be 'recipes' and the url would be http://www.yoursite.com/blog/recipes In some cases, you would prefer a slug different from the auto generated slug, for example: If you category is called 'Tasty Recipes', instead of 'tasty-recipes' for a slug, you could use 'recipes' or 'food' and the url would use the slug of your choice, so the url would be http://www.yoursite.com/blog/food

Save Category Once you have entered your category information, click 'Save Category' to save the category, and return to the Category list.

Cancel - Close Modal Clicking the X (close) or 'Cancel' button will cancel the creation of the new category.

Edit Category

To edit a category, click the name of the category from the category list, or click the green edit icon.

Update the category name, and slug as needed, and click 'Save Category' when you are happy with the changes. Closing or Canceling will revert your changes to the last saved version.

Note: The Category Slug is an important part of the url creation, so changing the slug will affect your existing links.

Delete a Category

Deleting a category is a simple action, but can have a lot more impact that you might initially think. A category slug is used to create urls, and removing a category will render all those previous url links invalid. Deleting a category does not remove the content that belongs to that category, but does remove one of the ways to view that for your user.

Deleting a single Category

You can delete a category, one at a time, using the red delete (trash can) icon button on the line of the category you wish to delete.

Deleting Multiple Categories

If you wish to delete multiple categories at once, you can select the check boxes next to the categories you wish to delete, and click the 'Bulk Actions' button, and select 'Delete Categories' from the drop down menu.

Deleting a Category with associated Pages or Entries

When you delete a category that has associated content, pages or entries, the category is deleted, and the association is deleted, but the original page / entry is not deleted.

Export Categories as JSON/XML

For convenience, ContentBox has easy import and export options for your categories. To export all of your categories, simply click 'Bulk Actions' and select 'Export All as JSON' or 'Export All as XML'. Your browser will prompt you to download the Categories.json or Categories.xml, depending on the option you chose.

The JSON/XML includes just the 3 base fields, category, slug, and categoryID, as shown below in a json example.

[{"category":"Homepage Rows", "categoryID":2, "slug":"homepage-rows"},{"category":"Slider","categoryID":1,"slug":"slider"}]

Media Manager

The Media manager is a WEB UI to be able to interact with your Media. You can access the Media Manager from the Admin Menu under Content, in addition to buttons within different Content Editors.

The Media Manager has many options, but by default will look like the image below.

Icons

Refresh Listing - Refreshes the current folder location

Go Home - Return to the Home ( Root ) directory of the current library

Create Folder - Create a new folder in the current location

Rename - Rename the currently selected File or Folder

Delete - Delete the currently selected File or Folder

Upload - Brings up the Upload form, to allow you to select a file to upload. Remember, Media Manager also allows HTML5 styled uploading, so you can drag file(s) into the media manager to upload them. Folder Uploading is not supported in this version, but will be added in an upcoming update.

Download - Download the currently selected file.

Quick View - Preview the currently selected image in a modal window. Only supports Images.

File Listing - This shows the current folder in File Listing / Details view. This is the default listing style, shown in the screenshot above.

Grid Listing - This shows the current folder in Grid Listing / Thumbnails view. This is a great way to preview directories of images. This view can seen in the screenshot below.

File / Folder Context Menus

Context Menus ( otherwise known as right click menus ) are available for Files and Folders. Files have the following context menu items

Folders have the following context menu items

Status Bar

The Status Bar has useful quick view information.

• Full file path breadcrumbs

• Filename, File Size, and last modified date-time stamp.

Libraries

Next to the Module Name - 'Media Manager' you will see Content in a yellow label. That is the current Library you are looking at. There are several Libraries available for you to choose. To switch library, click the drop down select labelled Switch Library in the top right like the image below.

Depending on your security settings, you will be able to directly browse, upload, rename and delete filtes from the Content, Modules, Updates and Widgets locations.

Media Manager Settings

There are a lot of configurable options for the Media Manager, to fit in with your use cases. Media Manager Settings are found in the administrator under System > Settings > Media Manager

Directory Root:

The relative path or ColdFusion mapping in your server that will be the expanded root of your media manager. The default is modules/contentbox/content. This is restricted to relative paths to ensure the user of the Media Manager cannot access content outside of the web root. If you would like to use a folder outside of the web root, please create a coldfusion mapping ( and web accessible mapping if required by the Media Provider ) to ensure the folder is relative to the web root.

Media Providers

Media providers are used to deliver your media files securely and with greater flexibility as you can place your entire media root outside of the webroot.

CF Content Media Provider ( default )

This provider uses the ColdFusion cfcontent tag to deliver and stream files securely to the user. This uses a ContentBox route __media, that translates the path into a cfcontent call and delivers the content.

Forward Media Provider

This provider will forward to the real physical location in the server for the media path requested via the internal servlet page context, so no real media path URL will be shown to the user. Use only if the media root is web accessible and a relative web root path, so double check your media root.

Relocation Media Provider

This provider will relocate to the real physical location in the server for the media path requested. Use only if the media root is web accessible, so double check your media root.

Provider Caching Headers:

If enabled, the media provider system will issue caching headers for all assets. You can use the cbcache=true URL param to issue no caching headers on any asset.

Default: true

FileBrowser Options

File Browser options includes a series of user options ( Yes / No ):

• Allow Creation

• Allow Deletes

• Allow Downloads

• Allow Uploads

Accepted Upload File Mime Types

HTML5 Uploads

Size Limit - Maximum size of the file upload in mb - defaults to 100mb

Max Similtaneous Uploads - Number of uploads allowed at the same time - defaults to 25

Quick View Image Width ( Pixels )

When using the Quick View for images, images are shown in a modal window, with a maximum width defined by this setting.

[Content + Media manager] Media manager is an embedded media manager that we ship with ColdBox. If you are an administrator you have different libraries [Switch Library drop down menu; top right] that you can manage. For example, [click widgets in the DDM] you can manage the widgets, so you can install manually other widgets or download some of the widgets that you have available here.

[Switch Library + Update] You can check out the auto update channel so you can actually do any type of modifications. It’s up to you what you want to do with this [switch to list view]. Obviously, an administrator can choose all the different things [select new ‘blog folder’ & click X to delete] and all different permissions. You can do this [hover in circle] as well.

Widgets are small pieces of software that you can add to your ContentBox website to perform a specific function. There are several Widgets built into ContentBox that are used for various parts of your website, and you can insert widgets into blog posts and pages to make your website even more dynamic.

Widgets are one of the ways ContentBox is extendable, you can install modules and themes that overwrite existing widgets, or are brand new... or you can create or customize your own widgets.

Widgets are maintained through the Administrator under Look & Feel > Widgets. You can managing existing widgets, upload new widgets, or download widgets from Forgebox.

In this section of the documentation, you will learn how to use Install, Manage and Use Widgets To learn how you can develop your own widgets, read this section under Developing for ContentBox

When installing a CMS, one of the first steps you would normally take, is install a theme. We wanted to give you a head-start and give you a theme that gives you plenty of options to customize your site, colors, social media icons, and even a hero style homepage. In ContentBox 3.1 we even updated Themes to have better documentation, so it's easier to get started with your theme. Let's see what the default theme can do for you.

Theme Settings

Theme settings is where all of your configuration happens. In ContentBox 3 we added a lot of functionality to make the Theme Settings easier to work with, for Devs and Users. The first you will see if the groupings of settings. This allows a User to focus on one set of settings at a time. With a complex theme, having all of the settings visible at once can be very overwhelming.

Default Theme Settings

Since each theme controls their own settings, lets look through the Default Theme's settings.

Colors:

When you expand your group, you will see all of the settings of that group, displayed with a Group Introduction, a label for each setting, optional setting description ( not shown in the example below ) and an optional help modal ( the blue ? Icon below ) . In colors, you can choose one of many Bootswatch themes. Bootswatch is a set of color swatches made to extend the traditional Bootstrap framework. Below you will see a selection of the swatches.

Here is an example of an optional help modal, for settings that require more information for the user.

Changing the color dramatically changes your sites appearance. Lets look at your site default ( green ) and some options.

Of course you have plenty of options, visit bootswatch.com for thumbnails and more information on each swatch.

Header

Logo URL:

You can choose whether you would like to use Text for your Logo, like the screenshots above, or you can choose to use a logo. One important thing to note here is the size is not restricted, please ensure your resize your logo.

Show Search form field in Header.

Not a fan of the large search box, change your selection here to hide it.

Footer

The footer is just a text field, so you can add some copy to your footer. I decided to spice things up with Bacon, here is a footer with Bacon Ipsum.

HomePage

The home page has lot of options, as you can see in the screenshot below. You can change the header title, add some text, give text for the button and add the link that the button links to, as well as selecting a preselected background image, or your own custom background.

After changing a few settings, your homepage now has a nice hero image, like the screenshot below.

Blog Sidebar Options

When looking at the blog part of ContentBox, you'll see you have loads of options on the right hand side.

This might be too much for some sites, so you can choose whether to show / hide some of those mini widgets.

Turn them off, and hey presto, no more side bar mini widgets.

This is just the default theme. We have many more, and others are being developed, and can be shared easily through Forgebox.

What are modules

Modules are self contained bundles of code, that contain their own configuration, routes, handlers, views, widgets, interceptors, and can contain other modules. They are a vital part of ContentBox, and the ease in which you can use, and develop for ContentBox.

ContentBox is built on Modules

ContentBox itself is made up of 3 separate Modules ( and their submodules ), ContentBox, ContentBox-Admin and ContentBox-UI. One of the best security features of ContentBox is the fact that you can remove the Admin module from your production installs, removing the ability for the admin to get hacked, because it is not even present on your production server.

ContentBox

Lets add a widget into a page. In this example, we're going to insert a simple ContentBoxBadge Widget which has no parameters or arguments. We show you how to create this Widget in the Developing for ContentBox section of the documentation.

Lets browse in the admin to Content > Sitemap and click on a page. Find the location in the text you would like to add your widget, and click the Green ContentBox Widget icon ( circled below ).

Pick a Widget out of the list, you can filter the widgets, or select by category ( categories are defined in the Widget properties ).

Click anywhere on the Widget itself, and the Insert Widget Dialog will open like the screen below.

If there were arguments, you could adjust them here. If this is the widget you want, and the preview looks good, click Insert Widget. Back to Widgets allows you to return to the Widget list to look for a different widget. Cancel returns you to the Content Editors.

Once inserted, click Publish, and then you'll see a Widget placeholder like this.

If you right click on the widget, you can get a Widget Context menu like below. You can edit, or remove a Widget through that context menu, or just double click the Widget placeholder to edit directly.

This example has no arguments or parameters to change, but if you did, you would be able to edit those here, and click Update Widget to save those changes.

You can preview the page using our Responsive Previewer which allows you to see what your page will look like, in desktop, tablet and phone views ( horizontal and vertical ).

When you are happy, ensure you save / publish your page to keep your changes. Once saved, you can view it on the front end of the website.

This option is under Users in the left side navigation bar. This is a list of all permissions available for the site.

There is a quick search box at the top of the permissions page if you are looking for a specific permission.

On the permissions page you will see 4 headings.

• Permission - This is the name of the permission

• Description - This explains the permission and what access it allows for the user

• Roles Assigned - This shows you how many users are using this permission currently.

• Actions

  • Green Icon - Edit the permission

  • Red Delete Icon - Delete the permission.

Creating Permissions

Click Create Permission to add a permission. A permission consists of:

• Permission ( commonly known as a slug / name )

• Description

A Permission Slug can be referenced from inside of code used in Widgets, Modules, Themes, restricting access however you see fit. Creating a permission allows you to assign the permission to Roles and/or Users, but will not be functional without code referencing the Permission ( slug ).

A Permission ( slug ) can also be referenced from inside the Security Rules as well. Security rules are used to secure ContentBox according to incoming events or URLs, much like a firewall. See that System > Security Rules for more information on how Permissions are used.

Bulk Actions

In the top right section of the page, you will see a Bulk Actions button next to Create Permission. This allows you to do the following:

• Import

• Export All as JSON

• Export All as XML

Import

This is a nice feature when you manage several sites. You can setup permissions on one site, and then export them, and import them into the other sites you manage.

For safety reasons, when you Import Permissions, by default you will not override any content. If you have existing Permissions, that you want to be updated, please set Override Content to true. Otherwise existing content will be skipped during the import process.

Export as JSON / XML

Exporting to JSON or XML is a simple process. Click Bulk Actions and select your format, and in seconds you will see a file download prompt pop up, asking you to open or save your file ( in most browsers ).

Importing from a *.cbox file

Once you have exported the content, you will have a *.cbox file. To import the file, in the admin, click on Tools > Import.

To import your cbox file, select Import ContentBox Package and then select the file by browsing your computer, and click Start Import.

Word of Warning - Whenever you are migrating data, you should always create a full database back up just in case. We have designed the import and export to be as effective as possible, but it always pays to be safe, when working with data.

Importing from another Blog System

To get to the Import Tools, in the admin, click on Tools > Import.

The Import Tools page displays 2 main options, ContentBox Package ( .cbox ) or Database Import. In Tip 10, we talked about importing from a ContentBox package, but in this tip, we are going to click Import from Database and then enter your database connection criteria to complete the import.

Datasource Options

This server must have a defined datasource to the source blog database in order to import it. Please make sure this datasource exists in the ColdFusion administrator. If you have not done this yet, please login into your ColdFusion Administrator ( or Lucee admin ) and setup the datasource for the database you wish to import.

Enter the Datasource name that you created, and Username/ Password if required.

Source Content

1. Next we have to choose the type of data you are importing, and any special setup you might have used. Select the Importer Source - Mango, WordPress, BlogCFC or MachBlog ( please let us know if your CMS is not on this list and would like us to enter it )

2. Table Prefix - when installing the blog, some blog software allow you to select a table prefix. To import your data correctly, we need to know what Prefix the database is using.

3. Default Author Password - Since systems encrypt passwords, we cannot simple copy them over, we need to create new ones. Please enter a default author password to set this as the default, and then you can modify them once they are imported into ContentBox.

4. Since Roles are not the same between blogs, please select the default Author Role you wish to use for Authors imported through this process. You can manually change them after the import.