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

Requirements

All Upgrades to ContentBox should be done with the assistance of CommandBox CLI. So make sure you have CommandBox installed.

Backups

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

Upgrade Process

There are two parts to the upgrade process:

1. Update the source code using our updater recipe

2. Run the database migrations via the ContentBox administrator panel

1. Source Code Updater

Please make sure your CFML engine has been completely stopped.

*nix/Mac

If you are in a linux or mac environment you can execute the recipe using the following shell commands from the root directory of your application.

# Download recipe
curl -o updater.boxr https://raw.githubusercontent.com/Ortus-Solutions/ContentBox/development/build/patches/4.2.1/updater.boxr
# Execute recipe
box recipe updater.boxr

Windows

If you are in windows, download the following recipe:

http://raw.githubusercontent.com/Ortus-Solutions/ContentBox/development/build/patches/4.2.1/updater.boxr

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

box recipe updater.boxr

That's it! The updater will take care of upgrading your 3.x source code to the latest 4.x source code.

2. Database Updater

Once your recipe finalizes, startup the CFML server and go to the ContentBox administrator (localhost:port/cbadmin) and navigate to the System > Updates section. Then click on the Download Update tab and paste the following updater URL:

https://downloads.ortussolutions.com/ortussolutions/contentbox/4.2.1/contentbox-patch-db-4.2.1.zip

This will download the database updater and run it. Once finalized, your installation is ready to rock!

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.

Intro

ContentBox v4.1.0 is a minor release sporting a focus on stability from our 4.0.0 release and some great new improvements. Let's explore this release:

Upgrading

This is a minor release, so a simple box update contentbox will get you upgraded to this release.

ColdBox Upgrade

ContentBox has been upgraded to work with ColdBox 5.1.x

New Editor Interceptors

All content editors have the following new events being announced:

• Editor Navigation Tab Area

  • These events fire after the final tab in a content editor, usually so you can add your own tabs

    • cbadmin_pageEditorInBody

    • cbadmin_ContentStoreEditorNav

    • cbadmin_entryEditorNav

• Editor Navigation Body Area

  • These events fire after the final tab content panel, usually so you can add your own tab panels

    • cbadmin_pageEditorNavContent

    • cbadmin_contentStoreEditorNavContent

    • cbadmin_entryEditorNavContent

Admin Menu Services

If you are building custom ContentBox modules that attach menus to the admin menu, then this update is for you. All remove and add methods for menus now will not throw up if you reference a non-existent menu or sub menu. Cleanup is now easier since you can remove at your heart's content without worrying of getting an exception.

API Service Updates

• ContentStoreService@cb

  • findPublishedContent()

    • Added a sortOrder argument

  • search()

    • parent argument can now be an entity or an entity ID

    • New slugPrefix argument which you can use to root a search on a specific content hierarchy. Ex: slugPrefix = "products" will search for all content under products/*

• ContentService@cb

  • findPublishedContent()

    • parent argument can now be an entity or an entity ID

    • New slugPrefix argument which you can use to root a search on a specific content hierarchy. Ex: slugPrefix = "products" will search for all content under products/*

• CommentService@cb

  • search()

  • Added a sortOrder argument

Release Notes

Bug

New Feature

Improvement

The source code for this book is hosted in GitHub: https://github.com/ortus-docs/contentbox-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp and cannot be altered or reproduced without 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 - https://www.ortussolutions.com/products/commandbox

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Lucee is a trademark of the Lucee Association of Switzerland.

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 GitHub repository where you can submit pull requests.

Charitable Proceeds

15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - https://www.harvesting.org/. 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 Children’s Home (https://www.harvesting.org/) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

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 good earth to seed and plant.

   ____            _             _   ____            
  / ___|___  _ __ | |_ ___ _ __ | |_| __ )  _____  __
 | |   / _ \| '_ \| __/ _ \ '_ \| __|  _ \ / _ \ \/ /
 | |__| (_) | | | | ||  __/ | | | |_| |_) | (_) >  < 
  \____\___/|_| |_|\__\___|_| |_|\__|____/ \___/_/\_\

ContentBox Modular CMS - v4.x

ContentBox is a professional open source modular CMS (Content Management System) for ColdFusion (CFML) and Java engines 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

ContentBox is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

ContentBox Modular CMS is open source and licensed under the Apache 2 License. Ortus Solutions, Corp, the makers of ContentBox, can also offer commercial and supported versions as well.

• Copyright by Ortus Solutions, Corp

• ContentBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

The ContentBox discussion group and community can be found here:

https://community.ortussolutions.com/c/communities/contentbox/15

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/Ortus-Solutions/ContentBox

• By Jira: https://ortussolutions.atlassian.net/browse/CONTENTBOX

Professional Open Source

ContentBox is a professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Website: https://www.contentboxcms.org

• Source Code: https://github.com/Ortus-Solutions/ContentBox

• Bug Tracker: https://ortussolutions.atlassian.net/browse/CONTENTBOX

• Twitter: @gocontentbox

• Facebook: https://www.facebook.com/gocontentbox

• Vimeo Channel: http://vimeo.com/channels/contentbox

• YouTube Channel: https://www.youtube.com/channel/UCKLYx772weG6Eh06ny-lJBg

• Ortus Community: https://community.ortussolutions.com/c/communities/contentbox/15

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

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.

• Deploy the source using the CommandBox Server with a supported modern ColdFusion (CFML) engine.

• Deploy the source to any modern ColdFusion (CFML) engine (Adobe 11+ †, Lucee4.5+)

• Leverage the ContentBox.war and deploy to any Java enabled server

• Run an express self-contained version

• Install into an Existing ColdBox MVC application

• Run as a docker container: https://hub.docker.com/r/ortussolutions/contentbox/

So let's get started.

† There is a known compatibility issue in Adobe ColdFusion 2018 Update 3 which has been raised with Adobe.

   ____            _             _   ____            
  / ___|___  _ __ | |_ ___ _ __ | |_| __ )  _____  __
 | |   / _ \| '_ \| __/ _ \ '_ \| __|  _ \ / _ \ \/ /
 | |__| (_) | | | | ||  __/ | | | |_| |_) | (_) >  < 
  \____\___/|_| |_|\__\___|_| |_|\__|____/ \___/_/\_\

ContentBox Modular CMS - v4.x

ContentBox is a professional open source modular CMS (Content Management System) for Modern ColdFusion (CFML) and Java engines 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

ContentBox is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

ContentBox Modular CMS is open source and licensed under the Apache 2 License. Ortus Solutions, Corp, the makers of ContentBox, can also offer commercial and supported versions as well.

• Copyright by Ortus Solutions, Corp

• ContentBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

The ContentBox and discussion group can be found here: https://community.ortussolutions.com/c/communities/contentbox/15

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/Ortus-Solutions/ContentBox

• By Jira: https://ortussolutions.atlassian.net/browse/CONTENTBOX

• By Slack: http://boxteam.herokuapp.com/

Professional Open Source

ContentBox is a professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Website: https://www.contentboxcms.org

• Source Code: https://github.com/Ortus-Solutions/ContentBox

• Bug Tracker: https://ortussolutions.atlassian.net/browse/CONTENTBOX

• Slack: http://boxteam.herokuapp.com/

• Twitter: @gocontentbox

• Facebook: https://www.facebook.com/gocontentbox

• Vimeo Channel: http://vimeo.com/channels/contentbox

• YouTube Channel: https://www.youtube.com/channel/UCKLYx772weG6Eh06ny-lJBg

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its 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

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 70’s, 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. Luis resides in The Woodlands, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

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 and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion 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 running and bike riding with his family.

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 in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in persuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.

Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Cristian who loves to play the guitar, worship and rejoice in the Lord!

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

Gavin Picking

In this section you will install ContentBox by using the source download option and deploy it to your favorite ColdFusion (CFML) engine of choice.

Step 1: Download Source

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

Expand the archive into your web root or a sub folder of your favorite CFML engine.

Please also note that you can also download two more types:

1. Module - The ContentBox module so you can deploy into any existing ColdBox application

1. Site - A pre-configured site like the installer but with no DSN Creator and ContentBox Installer

Step 2: Create Your Database

Now that the source is deployed in your webserver, it is time to create your database in your favorite DBMS engine. ContentBox is built with Hibernate ORM technology, so in theory it should work in all major database systems. You can even use an embedded database like Apache or Hypersonic.

Make sure your database supports utf-8 or utf-16 character sets if you will be using multi-lingual or localization support.

Step 3: Create A Datasource

You can now visit your application and will be presented with our datasource wizard. You can either use our datasource wizard or you can create the datasource yourself manually in the CFML administrator.

Datasource Creation Wizard

The datasource wizard requires your CFML Admin Password, or your ( Railo/Lucee ) Web Context Password to create the datasource.

Note: Depending on your CFML Engine Install, the Web Context Password might not be set. To use the Datasource Creator Wizard, you will be required to access the admin, set the password, then continue the installation.

Step 4: 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!

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. The full CommandBox installation instructions can be found here: . We will do the short version.

Download CommandBox

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

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 just 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.

Creating A ContentBox Site

Now that we have CommandBox we can use it to install and startup a ContentBox site using the embedded server (Lucee 5.x). You can use an embedded database or connect the embedded server to any database server as well.

Code Installation

Open a CommandBox shell in your directory of choice by typing box or executing the box binary and after the welcome screen type the following commands:

ORM Dialect (Optional)

Open the Application.cfc and look for the orm settings especially the dialect setting. Uncomment it and update it accordingly:

• Derby

• PostgreSQL

• MySQLwithInnoDB

• Oracle10g

• MicrosoftSQLServer

Start the Server

Go back to the shell where you installed the code and run:

The server will be created and started for you using the latest Lucee version. A browser window should pop up after and you can run the installer.

Setup Admin Password

Once you start the engine make sure you log in to the CFML web admin using the URL below in order to setup the CFML engine password. You will need this password to create the datasource via the wizard.

This will install the latest stable ContentBox and run an embedded server (Lucee 5.x) for it. After this you will get the ContentBox installer. Just follow it through.

ColdFusion Engine of Choice

Since we are leveraging CommandBox, you can replace the server start command to use any version of Lucee or Adobe ColdFusion. Below are some choice for the engines we support:

Custom Datasources

To change the datasource you can go into the CFML engine administrator and change it. Just look in your taskbar for an Ortus Logo like the one below:

Click on open server admin and go into the datasources section and create one.

Installation Slugs

ContentBox is partitioned into three installation slugs from ForgeBox in order to allow for more flexible installation structures. We used the installer above, but you can use the following approaches as well:

1. contentbox - Installs ContentBox as a module into any existing ColdBox application.

2. contentbox-site - Installs a new ColdBox site enabled for ContentBox with a dependency on contentbox for its module but no installer or DSN creator are installed.

3. contentbox-installer - Same as above but with our DSN Creator and Installer Module available.

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!

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 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 setup 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 in to 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 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 which 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 availabe 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 healthchecks 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 makes your source code lighter-weight, as well as providing you with a standardized development environment, which matches your production container strategy.

You can also deploy ContentBox to any Java enabled servlet container by downloading our ContentBox war file.

Step 1: Download WAR

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

Step 2: Deploy WAR

Drop the war into the web application folder of your favorite servlet container or use any of their deployment tools to do so. Then startup the engine and let the war be expanded.

Step 3: Create Your Database

Now that the war is deployed in your server, it is time to create your database in your favorite DBMS engine. ContentBox is built with Hibernate ORM technology, so in theory it should work in all major database systems. You can even use an embedded database like Apache or Hypersonic.

Make sure your database supports utf-8 or utf-16 character sets if you will be using multi-lingual or localization support.

Step 4: Create A Datasource

You can now visit your application and will be presented with our datasource wizard. You can either use our datasource wizard or you can create the datasource yourself manually in the CFML administrator by visiting the URL for the administrator:

Step 5: 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!

Intro

ContentBox v4.2.0 is a minor release sporting a focus on performance, security and stability from our 4.x release and some great new improvements. Let's explore this release:

Upgrading

This is a minor release, so a simple box update contentbox will get you upgraded to this release.

ColdBox Upgrade

ContentBox has been upgraded to work with ColdBox 5.3.x

Release Notes

Bugs

• [] - AdminBar not showing up anymore

• [] - When cloning a content object, the markup type is not copied over

• [] - contentbox-security/interceptors/CheckForForceTwoFactorEnrollment.cfc is fireing on too many events

• [] - cb helper getCurrentCustomFields() does not check for null custom field arrays

• [] - Remove spaces from fb.min.js filenames in Filebrowser handler

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

• [] - Hello user module is missing version property - error when populating module config

• [] - Deactivate modules if its directory does not exist in disk

• [] - Widgets do not appear in panel until Reinit

• [] - Folders in a module's widgets directory are treated as components

• [] - Widgets - insert button missing

• [] - CommentForm blowing up on previews on empty content objects

• [] - Exception when import permission groups in a user

• [] - Content types .print and .doc not rendered

• [] - ACF blows up with async orm announcements

• [] - Page preview not working throwing exception on missing layout

• [] - Generated Meta Description showing HTML

New Features

Improvements

Intro

ContentBox v4.0.0 is the first major release of ContentBox and it sports tons of new updates, improvements and bug fixes including a major upgrade to which in itself gives us tons of new updates and features. So let's start exploring the major areas of improvement of this release.

ColdBox 5

The entire ContentBox core has been migrated to leverage ColdBox 5.x. This introduction has given us a plethora of features not only for development purposes but also great stability, and speed. The major areas of improvement are:

• Performance, performance, performance

• Container and Environment support and detection

• Full null support

• Inheritable entry points for Modules

• New modularity events

• modules_app inception

• Default Module Exports

• Simplified URL Routes

• Enhanced Routers for core and modules

• Named Routes

• Event Caching Improvements

• Default JSON renderings

• Rendering Regions

• Faster Integration Testing

ContentBox Modules Full URL Routing

In 4.x, modules can leverage the full power of ColdBox Routing as each module has its own Router.cfc now. No more are you bound to just simple moduleEntryPoint/handler/action URLs, you can now use the full expressive power of ColdBox Routes:

ContentBox Modules Inception

Thanks to ColdBox 5, your ContentBox modules now support full inception of child modules. Even the children will respond to full URL routing using the pattern shown previously.

New contentbox-custom Module

This is one of the major updates for this release in order to adhere to our containerization and portability strategies. Let's investigate the problem first:

In previous releases, custom code (media library, themes, widgets, and modules) had to be installed in specific folders inside of the contentbox module, which is installed by CommandBox.

This is fine and dandy, but the issues arise once you want to put your custom code into source control but NOT the ContentBox source. It makes no sense to store the ContentBox source code in source control since the inception of CommandBox and package management. This created many issues in figuring out how to JUST add your custom pieces to source control and then came CommandBox 4 which allowed inline updates and just destroyed custom code.

Then came our containerization strategy where we wanted a simple mount point for all custom code. This was painful under the 3.x layout.

Conventions

This gave way to the creation of the contentbox-custom module which is a module stored under the modules_app convention. This module will store all custom code and can be stored in source control without interfering with ContentBox source code.

Core and Custom Locations

This also gave fruition to a new feature where now you can use the custom module for your custom media library, modules, themes and widgets, but also gave way to also store CommandBox controlled core modules and themes. This means that when you install modules and themes from ForgeBox they will install under the previous locations because they are managed by CommandBox.

Custom Module Configuration

You will also find the ModuleConfig.cfc in the root of your custom module with the basics to bootstrap the module by ContentBox. The rest is up to you. You can now leverage a full module to bootstrap all your custom code. You now have the power to control the loading/unloading of all your custom assets. Yeayyy for modularity.

Custom Widgets

If you wanted to create custom widgets before you either had to place them in themes or in the core location. Now you can store them in the custom module under the _widgets folder and have them available globally.

Widget Discovery

Since the addition of these new locations for widgets we have also added a discovery process when using widgets just by name in content markup or retrieval:

• Check custom location: modules_app/contentbox-custom/_widgets

• Check active theme widgets folder

• Check core location: modules/contentbox/widgets

Custom Media Library

The new custom module will also house your media library under the _content folder. The ContentBox v3 upgrader will move your library here (if it exists).

Docker Container Mount Point

If you are leveraging the CommandBox or ContentBox docker images, you can now easily mount your custom source code by just pointing it to the modules_app/contentbox-custom folder.

Multi-Factor Enrollment

We have now added the capability for users to enroll and unenroll in multi-factor authentication according to their provider of choice or admin's choice :)

Release Notes

Bugs

New Features

Improvements

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.

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 ContentBox Dashboard

Before diving into ContentBox, we recommend you to take a few minutes to get to know your Dashboard.

Home

Under Recent Content you have: Recent Pages, Recent Entries and Recent Content Store.

On the right panel you have Data Snapshots where you can check Top visited Content, Top commented Content, Discussions and Content. 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. Then you have the whole layout of the administrator. On the upper right corner you have who you are and the about information about the software. There is also the add\/remove Sidebar button so that you can remove the Sidebar to have more reading space. On the upper left you have your administrator commands [the house icon on top] opening the site, [the plus icon] adding new data, [pencil icon] creating posts [the pencil icon + close] and some administrative options [master 3xWheel icon:] like the ability to clear the caches, reload the applications, reload the ORM, reload the administrator, and reload every single piece of module that you have available at ContentBox. You have a Global Search which searches pretty much anything in your ContentBox.

About

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 you can very easily navigate throughout it once you memorize them. Also, for you module developers we also have an API based on a jquery java script library. And you can very easily do data biding for your own shortcuts so if you want to offer you own keyboard shortcuts it’s very easy.

Updates

Our sophisticated auto-update system offers 3 ways of getting updates from Ortus Solutions. Check for updates: We have a Stable Channel which can check against new ContentBox releases. We also have a Bleeding Edge Release: all our releases will go in our release cycle so all our releases will be in the bleeding edge channel 1 or 2 weeks before actually making to a stable channel.

Download Updates:

If you are upgrading from an old version of ContentBox, or you are a Ortus Solutions support client, we have the capability to give you an URL for specific patches.

Upload Updates:

If you don’t have internet access you can upload the patch and it will be delivered through your ContentBox installation. Options 2 and 3 are great avenues for those companies and individuals that have support contracts or other special project arrangements with Ortus Solutions.

Content

ContentBox provides many options for managing content, including:

• The ability to create pages which can be hierarchical

• An integrated blog which gives you instant, turn-key blogging capabilities

• The super-flexible Content Store which allows you to create and store any kind of content that you’d like. Whether you’re creating custom localized content, simple lists, or a complex content-delivery system for your mobile app, the Content Store is specifically designed to accommodate whatever your site or app needs. In conjunction with a RESTful API, you have a powerful content repository that can be used however you want!

• Categories which allow you to quickly and easily organize all your content in whatever way you choose

• An easy-to-use Media Manager which not only provides storage for your documents, images and other assets, but is also integrated into content creation tools to make using media in your content quick and easy.

Pages

Let’s get started with Pages. Inside pages on your right panel you see that we have set up filters to filter out the view of the pages. You also have Global Actions: Delete Selected, Draft Selected, Publish Selected, Import, Export All and Show All.

Page Editor

Inside Pages click Create Page and the Page Editor will open. Name your page by giving it a Title and ContentBox will give you the permalink for the page. By default, the Page Editor uses CKeditor for a WYSIWYG editor. ContentBox also offers different other editors that are available in your installation.

Hint Remember that editors are programmable so any module developer can actually register new editors in your system.

The Page editor has markup support [button right beside Editor Button]. HTML markup is currently supported by default.

ContentBox’s implementation of CKEditor comes with support for a number of plugins, including:

• Insert code snippets [page icon beside (right) to World],

• iframe [the world]

• Youtube or embedded media

• Insert Lorem Ipsum Dolor [T] to create content.

• Contentbox Widgets

On the right panel you have the Paging Details.

Publishing

ContentBox allows you to publish the page on a specific date and time, as well as set an expiration date to expire the content on any schedule you choose. Additionally, commit messages can be included (and even required) via the change log, providing built-in version control of your content.

When saving content, a number of options are available:

• Save: Preserve a snapshot of the page as is, and continue editing

• Draft: Save a draft of the content and close Page Editor

• Publish: Publish the content to your site and close Page Editor

Hint You can collapse the side bar and still have your Quick Edits controls right from the gear widget [on the up right corner].

Display Options

Display options allows you to control many aspects related to how the page will be displayed within your site.

• Parent: Choosing a parent determines the hierarchy of the page within your site. For a “top-level” page, simply choose “No Parent”

• Layout: Specifies which layout the page will use. It can inherit default settings, or use a custom setting.

• Mobile Layout; Specifies what layout the page should use when viewed on a mobile device. Set to “None” to use the normal layout for the page.

• Show In Menus: Tells ContentBox whether this page should show up in automatic menu builders. If set to “No”, the page will not show in ContentBox menus.

• Menu Order: If your page is shown in menus, you can specify the order that this page should appear.

Modifiers

Modifiers allows you configure extra information about how your page will be accessed.

• Creator: Allows you to configure who is displayed as the author of this page. This is particularly useful if several editors have modified the page, but a specific author should be acknowledged

• Allow Comments: Allows you configure if comments should be allowed for the page.

• Password Protection: Allows you to specify a particular password needed to access this content. This password can be shared with allowed visitors to provide secure access to specific pages.

Caching Settings

ContentBox provides administrators with granular control over how content is cached within your site. Each page can be configured with the following caching settings:

• Cache Page Content: When set to “Yes”, the content of your page will be cached (based on global or page-specific timeouts)

• Cache Page Layout: When set to “Yes”, the content of your page, as well as the page layout HTML, will be cached (based on global or page-specific timeouts).

• Cache Timeout: Specifies how long (in minutes) the page should be cached. Set to “0” to use the global setting

• Idle Timeout: Specifies (in minutes) the idle timeout for your page. Set to “0” to use the global setting

Categories

ContentBox allows you to provide additional organization of your content by setting one or more categories. You can choose from a list of already-configured categories, or even add new categories by adding a comma-separated list of categories in the “New Categories” text field.

HTML Attributes

To help you configure your page for Search Engine Optimization (SEO), ContentBox provides the ability to specify HTML attributes for your page, including:

• Keywords: List of keywords that will be added to the <head> of your page

• Description: Text description of the content that will be added to the <head> of your page

On the bottom of the page you have the Page Excerpts. You can create summaries of your Page Excerpts pages and then in your UI use them as you see fit.

Custom Fields

One of the most powerful features of ContentBox content is the ability to attach metadata which can be done via Custom Fields. You can add as many Custom Fields as you like in the form of key-value pairs.

• A little Tale: How the metadata works

  The metadata is stored in the object itself and then you can retrieve it using the CBhelper when you are building themes, widgets and events.

After you are done editing your page, you can go ahead and Publish it [click publish]. You will then be redirected to the Pages page where you will see that your page is published.

Child Pages

In addition to specifying the parent of a page via the Page Editor, ContentBox also allows you to quickly create “child” pages via the main Page Manager.

On the Pages page, find a page you have already created and click Page Actions and select Create Child. Page actions button) in the product row at the right edge; click ‘Create Child’]. The Page Editor will open as normal. However, in this scenario, the new page will automatically be added to the selected parent page.

When you Publish your Child Page you will be redirected to the Parent Page Hierarchy View where you will be able to see all the Child Pages for the parent page. Just like with Pages, when you have created multiple Child Pages you have also complete control of manipulating how the Child Pages are rendered. So again, you can choose which Child Page should be last or first with simple drag and drop.

You can then continue to go back in your hierarchy and you can go back home [click home button]. The “+” sign beside a page indicates that that pages has at least one Child Page.

Hint Visit your page to see the changes you have made to your site. We recommend you Clear Content Caches.

Global Actions

The Pages manager provides a number of global actions [Global Action button; drop down menu\/beside create page button] that make managing your content easy. These actions include:

• Delete Selected: Will delete all selected pages (via checkboxes)

• Draft Selected: Will put all selected pages into draft status (via checkboxes)

• Publish Selected: Will publish all selected pages (via checkboxes)

• Import: If you have a ContentBox page export file (.json) from another site, you can use the Import option to quickly import the file and add the page to your site*

• Export All: Allows you to export all your pages as either XML o r JSON. This is particular useful if you need to transfer content from one site to another.

• Show All: By default, ContentBox “pages” your view to provide the best performance. However, you can select “Show All” to view the full list of all the pages in your site.

Page Actions

Each page in the Pages view has an actions column which allows you to quickly execute several actions on your page.

Page Info

Provides detailed information about your page [go to about row on the list and hover over the ‘’i’’], from last edited date to page-rendering configuration.

Clone

If you have a page that you’d like to use as starting point for a new page, you can Clone a selected page by choosing “Clone” from the Page Actions menu. When cloning a page, you can specify a new, custom title for the page, as well as whether or not the new, cloned page should be automatically published. Additionally, you can clone entire hierarchy of pages [hover over products]. Interesting: ContentBox will look into the content of cloned pages and update any slug that points to any point of the hierarchy so anything that is slash “myoriginalpage” page will be rewritten to slash\/new-myoriginalpage.

Delete

Choosing “Delete” from the Page Actions menu will delete the selected page, as well as any child pages.

History

Choosing History from the Page Actions menu will open the history channel for the selected page. You can view how many versions of the page exist, as well as compare the current version [black dot (left side under diff) to the last item] with the latest version [click compare versions; red button]. Comparing two versions will display a comparison chart of the data that have changed between versions. If needed, content versions can roll back to previous versions. When content is rolled back, ContentBox will create a new version number for the current version with the rollback.

Widgets. An Easy Example.

Widgets are one of the most powerful tools in ContentBox. Let’s start with an easy sample: Creating a News Page.

[Pages view] Create a New Page [Create Page] and name it “News Page” [title]. Inside the CKEditor [ckeditor window] type: “Welcome to my news!” and give it a heading [heading 2].

Click Create a New Widget and type “RSS” in the Quick Filter. Select the RSS Widget . You will see that it gives you an error because you need to fill out the required info for the widget. To do this, get the RSS link for your favorite news site and paste it in the feed URL field. If your link is valid, you should see a list of links display in the Widget Preview area.

Before clicking Insert Widget there are a few things you can modify. For example, maxItems allows you to select very easy how many items you want to be displayed in. You can also use showBody in order to show the body or collapse the body of the news article.

Now that you are done configuring the options that the RSS widget offers, click Insert Widget. You should now see a graphical representation of your widget within the CKEditor content editing area.

Hint You can configure your inserted widget anytime by double-clicking the widget content, or by choosing “Edit Widget” from the context menu

You can actually have a Quick Preview by clicking the EYE or typing the Keyboard shortcut: Ctrl + P. The Quick Preview allows you to see how the changes you have made to your page (like your new widget) are going to render on your site before publishing them.

Inside the Page Editor

Apart from the widgets you also have the ability to insert entries from the Content Store [ contentstore icon], to link to specific pages [ link icon], or to link to a specific entry [pencil icon]. You can also insert different media items and images [image icon].

For example, to link a few words [select a word from TEXT] to a specific page, highlight the desired words and click the [Link Page] icon. This will display a list of all pages in ContentBox from which you can choose the desired page to link to and even specify whether the link should be SSL or not. The same can be done with ContentBox blog entires.

You can also insert from the Content Store [ccontentstore icon]. You can try inserting something from the Content Store you will see it creates a kind of pseudo Markup. ContentBox will automatically render this content when the page is viewed.

Hint [clicking the eye or type CTRL+P] to get a preview and to actually see the translation of that markup.

As an administrator here you have full control of how this editor looks like. So for example right now you are seeing every single option known to man. However you can basically limit this for editors. You can limit actually all the controls that you are seeing. So you have all control of how everything looks and feels. So if you need to make it simpler you can really do so very easy.

You can also insert images from the media manager gallery [click image icon\/beside ‘A’], you can insert an image and say, browse server [click browse server], and you'll see that it’ll give you our ColdBox file browser [will pop up]. You can see the different medias that are available in the system [ ICONS\/quit list view]. You can actually create new media very easily by drag and drop.

Content Response Formats

When you are in your site (not in the admin) there are also pretty cool things you can do. We created what we call a print renders. You can now come in and say, I want to view my page as print. You just need to add <.print> to the page URL and hit enter. And you will see that it changes the whole format to print version. You have complete control of this layout as well. By convention you just have the same layout called underscore print. You can create one called underscore pdf as well or add “.pdf” to URL, and you'll see that it’ll produce a pdf output of your page as you designed it. You can also produce a word document by adding <.doc> to the URL of the page.

The Blog

The Blog [Content dropdown menu + blog], it basically reuses almost the same things. Actually under the hood, you can say we have an ORM object model that you can very easily extend and create custom content types, so, entries actually are just another custom content type based on a custom content object that we provide in ContentBox. You have the same capabilities [Global Actions] except there is no hierarchy but the rest it’s the same as if you were writing a normal page except these are based on blogs.

The Content Store

[Click Content dropdown ContentStore] The contentstore is one of the most interesting features of ContentBox which allows you to store any piece of content, whether it can be Java Script, HTML CSS internalization bid, anything that you like can be stored, binaries images RSS feeds, you name it. You can store anything you want in the content store.

This is also a custom content type based on ORM object. Same capabilities [global actions] of export, draft, importing, are available to you. The same actions pretty much. [3xGears] You have history, so you have version control, you have the ability to export them, edit them, clone them, delete them, etc.

When you create content [click create content] is a little bit different than the other ones. You have a title for your content. The slug is the unique identifier that you will access this content piece with; and a short description. And then in the editor [click the editor box] you can choose this to be content [circle around blank area] or if you wanted just a simple text area [change Editor dropdown menu to Text Area] you can move to a simple text area [click OK].

[Content Store Editor opens] and [click typing box] just type a content as you see fit. Or if you want, what we call [drop down menu Editor, select Edit\/Area + cancel\/ok] our coders.

Example: [coders editors drop down, default HTML] And right here is our coders editor and you can see that you can even say [drop down menu] 'I want to type in ColdFusion', you can go ahead and start typing here [type asdf + enter x3] and it’ll do some syntax highlighting for you.

But the whole thing is for you to be able to create content. Give the metadata [scroll down] to specific content.

You can also choose publishing schema [scroll up, topright corner side bar] for your content, different caching characteristics [hover over caching open\/close] if you are an administrator and also, categorize [open\/close categories] your content as you see fit. [click BACK] [Content Store view opens] So the Content Store is very powerful and you can pretty much do anything you like with it and then retrieve or build your own modules to get that content out.

Categories

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

Media Manager

[Content + Media manager] Media manager is and 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 managed for example if you want to manage the widgets [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. So it’s up to you what you want to do with is [switch to list view]. Obviously, and administrator can choose all the different things [select new ‘blog folder’ & click X to delete] and all different permissions and right that you can do with this [hover in circle] as well.

Comments

[Click Comments + Inbox] It’s basically an inbuilt commenting system. It has lots of capabilities [Global Actions] from approving to moderation. You have a lot of settings [comment + settings] available for commenting as well, from enabling ‘Site Wide’ comments, to disabling them. URL translations, security captchas, moderation rules, notification rules, so you have a lot of flexibility when it comes to your comments so you can attach comments to anything e.g. pages, blog entries, etc except the Content Store.

Look and Feel

[look & Feel + Layouts] Now, Look and Feel are obviously very important. 0So you have our layouts section. As you can see some of our sections are tide 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 is 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 into 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.

Blogging capabilities are essential component for any web site and web application. Blog entries help provide more context around products, services. It inherently creates more on-line presence and, if managed properly, better search engines 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

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.

Let's get started with some system requirements for running ContentBox sites:

Java

ContentBox will run in any Java 1.7+ enabled servlet container as a WAR or self-contained express edition.

ColdFusion (CFML) Engine

ContentBox source can be also be deployed to the following ColdFusion CFML engines:

• Adobe ColdFusion 11+

• Lucee 4.5+

Databases

ContentBox can run on any database engine that Hibernate ORM supports (), but we officially support the following:

• MySQL 5+ (InnoDB ONLY!)

• Microsoft SQL Server 2008+

• Oracle 11g+

• Hypersonic

• H2

• Apache Derby

• PostgreSQL (Experimental)

IMPORTANT: Dialect Choice

Example Code

Dialects We Support

• Derby

• PostgreSQL

• MySQL

• MySQLwithInnoDB

• MySQLwithMyISAM

• Oracle10g

• MicrosoftSQLServer

MSSQL Caveats

If you are running MSSQL server then we would recommend you update the Application.cfc with the ORM dialect for MSSQL. We have seen many weird dialect issues with MSSQL if this is not done:

We have also 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.

MySQL Caveats

If you are running MySQL server with MyISAM as your default table engine, you will need to either make the default InnoDB or use the InnoDB dialect. You can do this by adding a dialect section to the ORM settings in the Application.cfc: dialect = "MySQLWithInnoDB"

PostgreSQL Caveats

We have seen some issues on some versions of PostgreSQL where Boolean values of numerical 1 and 0 are not been translated correctly. If this is the case in your version of PostgreSQL you will see some cannot cast Boolean to Integer exceptions. If this is the case please contact us and we will show you how to update your installation to allow for these conversions.

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

• 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 4.0+

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

Older Versions of ContentBox

Edit config/routes.cfm and remove any reference to index.cfm. That's it!

File Permissions

ContentBox needs some files/folders to be writable at runtime. We use this for our installer, ForgeBox cloud deployments, auto-updates and more. The following directories need read/write permissions for the installer only to work:

Installer

Engine

Here are the folders for the core engine to work accordingly

ContentBox sports automatic updates via the administrator panel Dashboard > Updates. You can connect to the following update channels:

• Stable: Where all our official stable releases go

• Bleeding Edge: This is where we release beta or test versions

Once an auto-update package is detected you can then opt to install it.

As with all automated installers, we recommend you create backups of your source and database before applying or at least testing in a staging or development version of your site.

Database Migrations

ContentBox contains Database migrations for you. It will only do additive migrations, so no remove or dropping ever occurs on patches. We highly advice you to do so and point you in the right direction via the release notes.

Manual Uploading Patches

Once a patch is released in our update sites you can then choose to manually download the patch and apply it manually yourself. We store all patches in our integration server that can be found here:

Patch Types

There are three types of patches you can manually download and apply:

• Full Patch: Includes source, framework and database content updates

• Database Patch: Includes database content updates only

• No ColdBox: Includes source and database content updates only

Patch Structure

Each patch contains the following structure:

• Update.cfc : Contains the code needed for pre and post installation procedures

• deletes.txt : Contains a list of all source files that will be removed from your installation

• patch.zip : Contains all the new or modified source files that need to be deployed

  You can then use the upload patch functionality in our Updates panel to upload the patch and install it.

We do not recommend running the Update.cfc or patch files manually. Let the installer do its job.

Manual Downloading Patches

You can also use the Updates panel to point to a download URL so ContentBox can be patched via a patch URL. This functionality is mostly used by our support customers so we can deliver on-demand patches to their ContentBox instances. You can also use this approach to deliver patches to a local intranet of ContentBox instances. Just type in the download URL and hit update!

CommandBox Updates

If you are using the contentbox module approach via CommandBox, you can easily upgrade by doing two things:

1. Issue an update command: box update contentbox. This will update the module to its latest version

2. Apply the db-only patch in your administrator

Then restart your engine.

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!

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 sign up page for 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.

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 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

This is found under the System menu in the navigation on the left. Settings is a tabbed page listing 10+ options control panels. This includes all the core settings, but is also open to module developers, to inject their own settings.

ContentBox's modular architecture, combined with the awesome power of the ColdBox MVC development framework, allows for a familiar, yet unrestricted, platform from which to develop great web applications.

If you're a Front End Developer, you'll appreciate the straightforward configuration and pre-defined ( but highly customizable! ) asset conventions.

Within the ColdBox framework, itself ContentBox is comprised of three modules:

• contentbox - Includes the the underlying libraries for content organization and presentation

• contentbox-admin - Provides the administrative interface for managing your CMS

• contentbox-ui - Provides shared libraries for the user interface which are used for presentation and which may be extended to your application requirements.

Browse through our area-specific development documentation to get started:

ContentBox CMS For Front-End Developers

ContentBox CMS for Back-End Developers

In developing your user interface, the majority of your time will be spent creating content in the admin and modifying files from within your custom theme, located in the [ContentBox Module Home]/themes directory.

With state-of-the art development tools like CommandBox to assist with scaffolding and dependency management and Coldbox Elixr, it's easy to build out your theme in a fraction of the time it might otherwise take.

Theme Directory Conventions

A typical theme directory structure might be:

MyAwesomeTheme

- includes

• css

• fonts

• js

- layouts

- templates

- views

- widgets

For more information on the theme directory structure and configuration options see ContentBox Theme Development.

Modularity

In addition, many front-end focused modules and libraries are available on Forgebox and can be installed from the CommandBox CLI and used immediately in your templates, widgets and views. For example, to install a Twitter feed widget for ContentBox, simply run box install ID=cbwidget-tweetfeed directory=widgets from your theme directory and it will automatically be available for use in the admin. You may browse the ever-growing list of Forgebox libraries and modules on the Forgebox site or run forgebox help from within CommandBox to begin exploring the available options.

Layouts Folder File Structure

• layouts (The folder that contains layouts in your theme)

  • blog.cfm (Mandatory layout used for all blog views by convention)

  • pages.cfm (Mandatory layout used for all pages by convention)

  • maintenance.cfm (Optional used when in maintenance mode, else defaults to pages)

  • search.cfm (Optional used when doing searches, else defaults to pages)

ContentBox for some time has had a ContentBox site title, keywords and descriptions. Most themes also overrode those values with Blog Post and Page Titles, and if you use the SEO tab in the editor, you can override the Keywords and descriptions too.

New SEO CBHelper Functions for your Theme

In ContentBox 3.1, we added some additional logic into the default Theme ( as a reference ) to allow even more flexibility with Title, Keywords, Meta etc. In previous versions, logic checked to see if the content was a blog, or a page, and how to determine if overrides were used or not. Now the CBHelper contains all of that logic, and you can just request the Title, Description or Keywords from CBHelper.

<title>#cb.getContentTitle()#</title>
<meta name="description"     content="#cb.getContentDescription()#" />
<meta name="keywords"          content="#cb.getContentKeywords()#" />

This is in addition to already existing functions like:

<base href="#cb.siteBaseURL()#" />

Adding Meta to your Modules

One common issue with using the theme for your module is the way Meta Tags are generated. Having your own module, its hard to set your Title, Keywords and Description. As of ContentBox 3.1, since we have added the SEO and Meta functions to CBHelper, you can actually set and retrieve that data easily. To add Meta to your modules, you can now add this to your Module Handler Events.

function index(event,rc,prc){
    cbhelper.setMetaTitle( 'My cool module' );
    cbhelper.setMetaKeywords( 'ContentBox, Ortus, Themes, Modules' );
    cbhelper.setMetaDescription( 'My new module now has Meta Data to be used my the Theme.' );
    cbhelper.prepareUIRequest( "pages" );
    event.setView( "home/index" );
}

A theme is composed of the following pieces

ThemeDirectory

• Theme.cfc (The CFC that models and configures your theme implementation)

• layouts (The folder that contains layouts in your theme)

  • blog.cfm (Mandatory layout used for all blog views by convention)

  • pages.cfm (Mandatory layout used for all pages by convention)

  • maintenance.cfm (Optional used when in maintenance mode, else defaults to pages)

  • search.cfm (Optional used when doing searches, else defaults to pages)

• views (The folder that contains views for rendering)

  • archives.cfm (MANDATORY: The view used to render out blog archives.)

  • entry.cfm (MANDATORY: The view used to render out a single blog entry with comments, etc.)

  • error.cfm (MANDATORY: The view used to display errors when they ocurr in your blog or pages)

  • index.cfm (MANDATORY: The view used to render out the home page where all blog entries are rendered)

  • notfound.cfm (The view used to display messages to users when a blog entry requested was not found in our system.)

  • page.cfm (MANDATORY: The view used to render out individual pages.)

  • maintenance.cfm (OPTIONAL: Used when in maintenance mode)

• templates (The folder that contains optional templates for collection rendering that are used using the quick rendering methods in the CB Helper. See below for additional information)

  • category.cfm (The template used to display an iteration of entry categories using coldbox collection rendering)

  • comment.cfm (The template used to display an iteration of entry or page comments using coldbox collection rendering)

  • entry.cfm (The template used to display an iteration of entries in the home page using coldbox collection rendering)

• widgets (A folder that can contain layout specific widgets which override core ContentBox widgets)

Template Folder File Structure

• templates (The folder that contains optional templates for collection rendering that are used using the quick rendering methods in the CB Helper. See below for additional information)

  • category.cfm (The template used to display an iteration of entry categories using coldbox collection rendering)

  • comment.cfm (The template used to display an iteration of entry or page comments using coldbox collection rendering)

  • entry.cfm (The template used to display an iteration of entries in the home page using coldbox collection rendering)

Functionality

The individual files included in the templates directory are a single .cfm files used by ContentBox to iterate over a collection (usually entries or categories or comments) and render out all of them in uniformity.

Please refer to ColdBox Collection Rendering for more information.

Each template receives the following variables:

• _counter (A variable created for you that tells you in which record we are currently looping on)

• _items (A variable created for you that tells you how many records exist in the collection)

• {templateName} The name of the object you will use to display: entry, comment, category

Layout Local CallBack Functions:

• onActivation()

• onDelete()

• onDeactivation()

UDF ( User Defined Functions ) are a great way to add more power to your theme, and your theme settings.

Below are some common UDFs you might want to use in your themes, or templates on how you could create some of your own.

Example UDFs

LoadHelpFile()

This is a useful method for standardizing loads HTML for the fieldHelp Modal. The fieldHelp setting using this function would look like this

loadHelpFile( 'cbBootswatchTheme.html' );

Since the helpFilePath is not passed in this example, it defaults to the Theme's includes/help/ folder.

Note: One concern when using this is relative pathing of assets, since the modal is generated in one folder, and the includes are in another folder.

/**
* loadHelpFile - helper function for loading html help into a variable for modal
* @helpFileName - the name of the file to read and return
* @helpFilePath - the relative directory for the help files. Defaulting to ./includes/help/ inside the theme.
* @return the contents of the file or empty string if the file does not exist
*/
function loadHelpFile( required string helpFileName, string helpFilePath='./includes/help/' ){
    try {
        return fileRead( arguments.helpFilePath & arguments.helpFileName );
    } catch( any e ){
        return '';
    }
}

selectMediaManagerFolder()

This function gives you an array of Media Manager folders, so you could use in a optionsUDF setting, to allow the Theme Settings form to display a dropdown box with a list of folders. This would be great for a slide show, where the users select the folder, and all of the contents of the folder could be shown in the slideshow.

function selectMediaManagerFolder(){
    var event         = getRequestContext();
    var cbSettings     = event.getValue(name="cbSettings",private=true);
    var defaultDir = expandPath( cbSettings.cb_media_directoryRoot );
    var allDirectories = directoryList( path=defaultDir, recurse=true, listInfo="query" );
    var result = [];
    for( var directory in allDirectories ){
        if ( directory.type is 'dir' ){
            var theString = replaceNoCase( directory.directory, defaultDir, "", "all" ) & '/' & directory.name;
            theString = replaceNoCase( theString, "\", "/", "all");
            theString = replaceNoCase( theString, "//", "/", "all");
            result = result.append( theString );
        }
    }
    return result;
}

getBootstrapStyles()

Bootstrap has a set of pre-defined styles, used in alerts, buttons, and many other styles you can use in your website. Having a UDF like this, allows you to create a setting that the User can select the button style type.

array function getBootstrapStyles(){
    return [ 
        "default",
        "primary",
        "success",
        "info",
        "warning",
        "danger"
    ];
}

getBootstrapSwatches()

We use BootSwatch in several Themes, because it gives the user of the theme a lot of complete styles, in one theme. This UDF shows you how you can return a list as an array, so a user could select the BootSwatch they would like to use.

/**
* Build the swatches options
*/
array function getBootSwatches(){
    return listToArray( "cerulean,cosmo,cyborg,darkly,flatly,green,journal,lumen,paper,readable,sandstone,simplex,slate,spacelab,superhero,united,yeti" );
}

By default the includes directory of your theme is used to store your static assets.

Because these assets are called from your customized theme, however, you may use any directory conventions you prefer. If you plan to use customized paths or CDN links in your template, it's best to create a setting in your Theme.cfc which will then be configured through the admin.

AddAsset() Method for CSS and JS

In the Front End of the Website, the Theme takes over the rendering. To ensure all Assets are added correctly from various modules, for every theme, we recommend using the htmlHelper's addAsset() method.

Since the SuperType ( which all ColdBox items inherit from ) implements addAsset() you can call it directly from almost any file in your application.

addAsset( "#prc.cbroot#/includes/css/#css#.css" );

You might have noticed, that even in the Admin Asset Management methods explained here, the actual implementation of the cssFullAppendList and cssAppendList use the addAsset to add the CSS to the head of the HTML page.

This applies to both CSS and JS. The main downside to this approach is that all assets added with addAsset are added to the head. The order of the assets is not strictly ( or easily ) controlled either.

Better Asset Management coming soon

We recommend using a similar approach to the admin, using an array, and outputting in the theme. We will be standardizing an approach soon, so all themes can easy implement these features, with a single line cbhelper method.

Global Variables and Functions

During the ContentBox request, common variables and super-type methods are made available to all templates and views used in that request. When developing themes and modules for ContentBox, the following methods and variables are available for use in customization:

#cb#

The cb object contains a variety of common methods for retrieving ContentBox content and settings. Below are some common methods used to retrieve and create HTML content:

Content and Settings Retrieval Methods

Settings Retreival

• cb.siteName(): retrieves the configured name of Contentbox installation

• cb.siteTagline(): retrieves the configured tagline for the ContentBox installation

• cb.siteDescription(): retrieves the configured description for the Contentbox installation

• cb.siteKeywords(): retrieves the configured global keywords

• cb.siteEmail(): retrieves the default site email

• cb.siteOutgoingEmail(): retreives the configured email used in outbound deliveries

Theme Views

• cb.quickView( viewTemplate ): Renders a view partial located in the [theme home]/views directory. A .cfm file extension is not required.

• cb.mainView( args ): Renders the main view for the handler action. A struct containing the args necessary for view rendering should be passed in. By default, this struct is available in your layout and is also named args.

Entry Retrieval

• cb.getCurrentEntries():

• cb.getCurrentEntriesCount():

• cb.getCurrentCategories():

• cb.getCurrentPage():

• cb.getCurrentComments(): Returns the published comments for the current entry

• cb.getCurrentCommentsCount(): Returns the count of published comments for the current entry

• cb.getCurrentRelatedContent(): Returns an array of content related to the active post or entry

• cb.getCurrentCustomFields(): Returns a structure of custom fields for the active post or entry

• cb.getCustomField( string fieldName, any defaultValue ): Returns the value of a custom field for the active post or entry

Content Store Retreival

• • cb.contentStore( string slug ): retrieves the HTML output of a Content Store item by its slug

• cb.contentStoreObject( string slug ): retrieves the associated Content Store object

• cb.widget( string widgetName, struct args ): executes a named widget's renderit method and returns the HTML. A structure of arguments may be passed.

• cb.getWidget( string widgetName ): retreives the associated [widget][2] object

• cb.themeSetting( string settingName, any defaultValue ): retrieves a theme setting by name. A default value may be specified

• cb.isCommentsEnabled(): returns a true|false value of whether site comments are enabled and if the current entry accepts comments

• cb.quickSearchForm(): returns the HTML of a standard ContentBox Search Form according to the SearchForm widget

• cb.getSearchResults(): returns an array of results for an active search

Link Building Methods

• cb.linkAdmin(): creates a link to the ContentBox admin

• cb.linkAdminLogin(): creates a link to the ContentBox administration login form

• cb.linkAdminLogout(): creates a link to logout of ContentBox administration

• cb.linkBlog(): creates a link to the site's blog

• cb.linksSelf(): creates a link to the current page

• cb.linkPageRSS( any categoryFilter): creates a link to the RSS feed applicable to the active request

• cb.linkSiteRSS( any categoryFilter ): creates a link to the site's RSS feed

• cb.linkCategory( string categorySlug ): creates a link to a specific category page

• cb.quickCategoryLinks( string categorySlug ): creates an HTML unordered list of category links

Path and URL Utility Methods

• cb.themeRoot(): returns the location of your currently defined theme in the application, great for assets, cfincludes, etc

• cb.siteRoot(): returns the site root location using your configured module's entry point

• cb.siteBaseURL(): returns the site's SES base URL

• cb.adminRoot(): returns the root location of the admin using your configured module's entry point

• widgetRoot(): returns the location of your widgets, great for assets and includes

Interception Points

A number of built-in interception points are avaialble within the ContentBox request, which may be run using the cb.event() method. For examples of how these are used, see the default theme layout files. Examples include:

• cb.event( "cbui_beforeHeadEnd" )

• cb.event( "cbui_afterBodyStart" )

• cb.event( "cbui_afterContent" )

• cb.event( "cbui_beforeBodyEnd" )

Development and Debugging Helper Methods:

• cb.themeName(): returns the currently active theme name

• cb.layoutName(): returns the currently active layout name

• cb.isPrintFormat(): returns true if you are in printing or exporting format

UI Utility Functions

• Easily Render Captcha Images - ContentBox supports native captcha support and now your themes can render out a nice captcha image by using the new ContentBox helper method:

  • cb.renderCaptcha() method.

[2]: /content/using/managers/widgets.html

ContentBox itself is a ColdBox application, with 3 special modules that do all of the hard work. Below you will see the shell of the ColdBox app, with the key folders expanded and bolded.

Although ContentBox has a large number of folders and files, most customization activities will be done in a few key locations. This should make navigating the ContentBox source files easier.

We recommend using modules for extending ContentBox. Modules are easy to install, and can be managed through the ContentBox admin, activating and deactivating as needed. Modules can contain widgets, interceptors, admin or front end menu items, including handlers and views.

Themes are self contained folders, within ContentBox's themes folder. Themes themselves are module like, with a few added features, which means you can include modules in your themes for truly deep and powerful themes.

Traditional ColdBox Modules can be installed outside of ContentBox's control and life-cycle with ColdBox's normal conventions.

Initial ContentBox Website Install

• coldbox ( The ColdBox core, including system and ColdBox dependencies )

• config ( The ColdBox app config folder )

• handlers ( The ColdBox app handlers folder )

• layouts ( The ColdBox app layouts folder )

• models ( The ColdBox app layouts folder )

• modules ( The ColdBox app layouts folder )

  • contentbox

    • content ( default location for the media manager - customizable through Admin settings )

    • email_templates ( Email templates for adding authors, comments, pages, blog posts and many more )

    • i18n ( i18N properties files for DE, US, SV, IT, BR currently )

    • models ( Core ContentBox Models and Services )

    • modules ( Modules here are always loaded no matter what. These are core sub-modules of the ContentBox core module )

    • modules_user ( ContentBox life-cycle controlled modules. Manually installed or downloaded from Forgebox. These Modules can be activated and deactivated through the admin )

      • Hello ( Hello World Sample Module )

    • themes ( ContentBox Themes, manually installed or downloaded from Forgebox )

      • default ( Default ContentBox Theme )

    • tmp

    • updates ( Location for downloaded and manually installed patches )

    • widgets ( Default ContentBox Widgets - Override-able )

    • Application.cfc

    • ModuleConfig.cfc

  • contentbox-admin ( ContentBox Admin - removable for security reasons )

  • contentbox-ui ( Contentbox UI Module )

• modules_app ( Home for all of your custom ColdBox modules, outside of ContentBox's lifecycle )

• views ( The ColdBox app layouts folder )

• .htaccess

• Application.cfc ( The main ColdBox Application.cfc )

• box.json

• favicon.ico

• index.cfm

• license.txt

• readme.md

• robots.txt

• server.json

ContentBox allows you to override global site settings dynamically. This approach is great for container based deployments, but also for traditional overrides for testing or staging environments.

Override ContentBox Settings via ColdBox.cfc

You can override any runtime setting for ContentBox via a configuration structure in your main ColdBox.cfc configuration file. This will allow developers to override any runtime setting for any site.

All you need to do is create the a contentbox structure in your configure() or any tier method, with the name of the site (default is the default site) and then any setting name-value pair.

contentbox = {
    // Runtime Settings Override by site slug
    settings = {
        // Default site
        default = {
            "cb_search_adapter"      = "my.search.adapter",
            "cb_media_directoryRoot" = "/docker/mount"
        }
        }
}

Override ContentBox Settings via Java Environment Variables

You can also override any runtime ContentBox setting by passing them via Docker/Java Runtime variables.

Since these are string keys we can now use our fancy structures like the settings above, so you must adhere to our recognition pattern:

contentbox_{site}_{setting}=value

Here is an example on adding a custom media root:

-Dcontentbox_default_cb_media_directoryRoot=./build/docker/contentbox/content

This will allow especially Docker environments to override settings as environments or even provide secrets. More is coming, so stay tuned to our updates.

Simplest way to access a module

To view a Module, with routing and ColdBox modules entry points, you can simply hit a url/route on your site, and the module is ready to go.

For example: http://www.yoursite.com/businessLogicScanner

That is all you have to do. You don't need to build a special widget to display the module, the module can be accessed by the entry point in the module configuration, and its as easy as that.

Views Folder File Structure

• views (The folder that contains views for rendering)

  • archives.cfm (MANDATORY: The view used to render out blog archives.)

  • entry.cfm (MANDATORY: The view used to render out a single blog entry with comments, etc.)

  • error.cfm (MANDATORY: The view used to display errors when they ocurr in your blog or pages)

  • index.cfm (MANDATORY: The view used to render out the home page where all blog entries are rendered)

  • notfound.cfm (The view used to display messages to users when a blog entry requested was not found in our system.)

  • page.cfm (MANDATORY: The view used to render out individual pages.)

  • maintenance.cfm (OPTIONAL: Used when in maintenance mode)

You can declare settings for your Themes that ContentBox will manage for you. The form itself is built from the Theme.cfc file itself.

The value is an array of structures with the following keys:

• name : The name of the setting (required), the setting is saved as cb_layoutname_settingName

• defaultValue : The default value of the setting (required)

• required : Whether the setting is required or not. Defaults to false

• type : The type of the HTMl control (text=default, textarea, boolean, select, color)

• label : The HTML label of the control (defaults to name)

• title : The HTML title of the control (defaults to empty string)

• options : The select box options. Can be a list or array of values or an array of name-value pair structures

• optionsUDF : The select box options. This points to a UDF that returns a list or array of values or an array of name-value pair structures. Example: getColors not getColors()

• group : lets you group inputs under a Group name - settings should be in order for groupings to work as expected

• groupIntro : Lets you add a description for a group of fields

• fieldDescription : Lets you add a description for an individual field

• fieldHelp : Lets you add a chunk of HTML for a Modal, openable by the User by clicking on question mark next to the field label. Recommended use is to readFiles from the ./includes/help directory, with a helper function, for example: loadHelpFile( 'cbBootswatchTheme.html' );

Example

this.settings = [
    { name="Title", defaultValue="My Awesome Title", required="true", type="text", label="Title:" },
    { name="Colors", defaultValue="blue", required="false", type="select", label="Color:", options="red,blue,orange,gray" }
];

Theme Settings Admin Form

Below is a annotated screenshot showing most of the visible elements generated in the Theme Settings Admin form from the Theme Settings configuration structure.

Where are modules located in a ContentBox 3 application

Depending on the type of module, there are different methods and locations to install the module into.

• /modules - ColdBox Modules - git ignored, controlled by CommandBox

• /modules_app - ColdBox App Modules - Your application global modules - included in your git repo

• /modules/contentbox/modules - ContentBox Always Load Modules

• /modules/contentbox/modules_user - ContentBox Admin Managed Modules

Why are there 4 locations? Which location should I use?

There are 4 locations because each location has a different set of conventions, and different behaviors. Depending on what your module is, and what it will do, helps you determine where you should install / create it. The other reason the location matters, is because of source control. If your module interacts with ContentBox's life cycle, ie adding admin menu items when the module is loaded, the module is considered a ContentBox module, and should be installed in one of the last 2 locations.

ColdBox Modules /modules

Applications can have many dependencies, and keeping them out of your repo, and managing them with package managers, like Node, Bower, CommandBox, can keep your apps clean and light. Your gitignore file can get out of hand if you are individually adding and removing modules. To make life easier, we have 2 ColdBox App locations, 1 is /modules, which is controlled by CommandBox, and should be set to ignored. This means you can install hundreds of ColdBox modules, and do not have to worry about them filling up your repo. Note:Since these files in the /modules folder are not in source control, editing these files is pointless. Your changes will never get committed, and therefore deploy to any other developers, or staging / production servers. If a module requires you to edit files inside the module to work, you should install the module to the ColdBox Apps Modules location ( below ).

ColdBox App Modules - /modules_app

This location is not ignored by git, it is a part of your source control repo. These modules can be created by you, or manually installed, or installed by CommandBox by using an alternative location ( read below for when you should do this ). There modules behave just like modules installed into the modules folder, the main difference is source control. Do you want the module to be embedded in your repo, or linked, using commandbox to resolve the module as a dependency.

Installing CommandBox modules to modules_app folder instead of the modules folder

When installing modules with CommandBox, they are usually installed to the /modules folder, but sometimes you should install modules to the modules_app folder. The main reason, if the module requires configuration changes to the files, those files need to be in source control. So the best location for that module, is inside of the modules_app folder. Not all modules need file changes to get the module working, so install those normally, but if a module requires those types of changes, a simple change to the install command will change the installation path. ? 1

box install Business-Logic-Scanner modules_app

The last parameter is the installation directory. This will install the module to that directory. Note: If you are creating a module, and you know someone will need to modify the module to get it to work, you can set the directory in your modules box.json so when commandbox installs your module, it knows it should be in that folder by default.

ContentBox Always Load Modules - /modules_app/contentbox/modules

This one is pretty self explanatory, they are ContentBox modules that always load. This location is stored for core ContentBox submodules, that are not controllable by the admin. My advice is, do not develop modules in here. Since these modules always load, trying to use a normal module in here, can have loading order issues. For example, if you design a module to add menu items to the admin, this module will have issues loading the adminMenuService@cb since the contentbox-admin module hasn't been loaded when these modules are being loaded. Its best to put those modules in the next location - ContentBox Admin Managed Modules

ContentBox Admin Managed Modules - /modules_app/contentbox/modules_user

This is where you should create modules that require the contentbox lifecycle to function correctly. A perfect example of the contentbox lifecycle, is after the core admin module has been initialized, it then loads these modules. The lifecycle fires events, that your modules can listen to, for example, onLoad and onUnload which are perfect for adding and removing menu items from the main menu item for your customer admin modules. If you module was not in this folder, your modules would not be able to intercept these events, making simple tasks, harder to do.

Another great aspect of having ContentBox managed modules, is that logged in users can activate, deactivate, or reload modules. This is the best way to extend contentbox, you can tie the module into all the internal events of Contentbox. In a future post, we'll be showing you show to make your own Admin Module where you can add menu items like the screenshot below... the last main menu item is Mapigator, which has submenu items, added dynamically by using modules in this folder.

If you are planning to build a module, a great way to get started is using Scaffolding a Module using CommandBox. CommandBox has a lot of commands, the one we will be using in this case is the ColdBox command. The ColdBox command inside of CommandBox allows you to do a lot of things, including coldbox create for all of these items:

• view

• app-wizard

• orm-virtual-service

• unit

• integration-test

• interceptor-test

• orm-entity

• orm-service

• app

• interceptor

• orm-event-handler

• model

• layout

• handler

• bdd

• module

• orm-crud

• model-test

• controller