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

ContentBox Modular CMS - v4.x

Versioning

<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

• Copyright by Ortus Solutions, Corp

• ContentBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

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

Intro

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:

cbadmin/{module-entry-point}/${Full URL Route}

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.

+ modules
  + contentbox
    + content
    + themes
    + modules_user
    + widgets

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.

+ modules_app
    + contentbox-custom
        + _content (media libary)
        + _modules (custom modules)
        + _themes (custom themes)
        + _widgets (custom widgets)
        ModuleConfig.cfc

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.

docker run -p 8080:8080 \
    -e express=true \
    -v `pwd`/contentbox-db:/data/contentbox/db \
    -v `pwd`/contentbox-custom:/app/modules_app/contentbox-custom \
    ortussolutions/contentbox

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

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

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:

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:

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

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

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

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

<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

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

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

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

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

Playing around

docker pull ortussolutions/contentbox &&
docker run -p 8080:8080 \
-e EXPRESS=true \
-e INSTALL=true \
ortussolutions/contentbox

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:

docker run -p 8080:8080 \
-e EXPRESS=true \
-e INSTALL=true \
-v `pwd`/contentbox-db:/data/contentbox/db \
-v `pwd`/contentbox-custom:/app/modules_app/contentbox-custom \
ortussolutions/contentbox

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.

docker run -p 8080:8080 \
-e EXPRESS=true \
-v `pwd`/contentbox-db:/data/contentbox/db \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

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:

docker run -p 8080:8080 \
-e 'INSTALL=true' \
-e 'CFCONFIG_ADMINPASSWORD=myS3cur3P455' \
-e "DB_CONNECTION_STRING=jdbc:mysql://mysqlhost:3306/contentbox_docker?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true" \
-e 'DB_CLASS=org.gjt.mm.mysql.Driver' \
-e 'DB_USER=contentbox_user' \
-e 'DB_PASSWORD=myS3cur3P455' \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

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

docker run -p 8080:8080 \
-e 'CFENGINE=adobe@11' \
-e 'INSTALL=true' \
-e 'CFCONFIG_ADMINPASSWORD=myS3cur3P455' \
-e 'DB_DRIVER=MSSQLServer' \
-e 'DB_HOST=sqlserver_host' \
-e 'DB_PORT=1433' \
-e 'DB_NAME=contentbox_docker' \
-e 'DB_USER=sa' \
-e 'DB_PASSWORD=myS3cur3P455' \
-v `pwd`/contentbox-media:/app/includes/shared/media \
ortussolutions/contentbox

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.

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

• 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

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

So let's get started.

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

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.

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

What does RC and PRC mean:

• RC - Request Collection

• PRC - Private Request Collection

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

Syntax

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

${rc:name}

This will output the name variable from the RC scope.

Accessing URL Variables

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

mydomain.com/?name=Gavin Pickin

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

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

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

Escaping Dynamic Output

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

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

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

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

Settings

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

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

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

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

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.

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

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

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

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

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

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

• Delete Selected

• Import

• Export All as JSON

• Export All as XML

Add a new Category

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

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

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

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

Edit Category

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

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

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

Delete a Category

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

Deleting a single Category

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

Deleting Multiple Categories

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

Deleting a Category with associated Pages or Entries

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

Export Categories as JSON/XML

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

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

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.

Media Manager

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

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

Icons

Refresh Listing - Refreshes the current folder location

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

Create Folder - Create a new folder in the current location

Rename - Rename the currently selected File or Folder

Delete - Delete the currently selected File or Folder

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

Download - Download the currently selected file.

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

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

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

File / Folder Context Menus

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

Folders have the following context menu items

Status Bar

The Status Bar has useful quick view information.

• Full file path breadcrumbs

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

Libraries

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

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

Media Manager Settings

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

Directory Root:

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

Media Providers

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

CF Content Media Provider ( default )

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

Forward Media Provider

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

Relocation Media Provider

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

Provider Caching Headers:

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

Default: true

FileBrowser Options

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

• Allow Creation

• Allow Deletes

• Allow Downloads

• Allow Uploads

Accepted Upload File Mime Types

HTML5 Uploads

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

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

Quick View Image Width ( Pixels )

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

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

Theme Settings

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

Default Theme Settings

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

Colors:

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

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

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

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

Header

Logo URL:

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

Show Search form field in Header.

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

Footer

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

HomePage

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

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

Blog Sidebar Options

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

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

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

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

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

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

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

What are modules

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

ContentBox is built on Modules

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

ContentBox

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

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

On the permissions page you will see 4 headings.

• Permission - This is the name of the permission

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

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

• Actions

  • Green Icon - Edit the permission

  • Red Delete Icon - Delete the permission.

Creating Permissions

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

• Permission ( commonly known as a slug / name )

• Description

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

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

Bulk Actions

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

• Import

• Export All as JSON

• Export All as XML

Import

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

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

Export as JSON / XML

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

Whether you have a website with a lot of traffic, or not, it pays to have a test / staging site setup to test out changes to your website. One of the biggest problems with having a staging and production website, is moving data from one environment into another. This need inspired the Content Import and Export features in ContentBox.

The Import and Export tools are located in the Admin menu under Tools.

From this panel you can choose to export your entire site or parts of it as a *.box archive package.

You have 2 options, Export everything, and Mr Picky, where you can pick and choose.

As you can see in the pick and choose, there are lots of options. Pages, Entries, Categories, ContentStore, Authors, Roles, Permissions, Security Rules, Settings and much more. This makes it easy to pick and choose the content you need to move.

When you are ready, you can click Export Preview to see exactly what will be exported ( see below ).

Once you are happy with your selection, click Start Export

Once complete, you will be prompted to save your cbox file.

Once you have exported your content into a cbox file, you can import it to the installation of your choice, through Tools > Import

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)

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

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

Charitable Proceeds

Shalom Children's Home

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

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

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

Step 1: Download WAR

# stable
wget https://www.ortussolutions.com/parent/download/contentbox?type=war

# bleeding edge
wget https://www.ortussolutions.com/parent/download/contentbox?type=war&version=be

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:

/{appcontext}/lucee/admin/server.cfm

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!

Luis Fernando Majano Lainez

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

# stable
wget https://www.ortussolutions.com/parent/download/contentbox?type=installer

# bleeding edge
wget https://www.ortussolutions.com/parent/download/contentbox?type=installer&version=be

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

unzip contentbox_{version}.zip

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

wget https://www.ortussolutions.com/parent/download/contentbox

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

wget https://www.ortussolutions.com/parent/download/contentbox?type=site

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!

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:

mkdir mysite --cd
install contentbox-installer

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

this.ormSettings = {

    dialect = "MicrosoftSQLServer"
    
}

Start the Server

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

server start

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.

http://localhost:{port}/lucee/admin/web.cfm

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:

# default Lucee 5.x
server start

# Latest Adobe 2018
server start cfengine=adobe
# Adobe 2016
server start cfengine=adobe@2016
# Adobe CF11
server start cfengine=adobe@11

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.

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" );
}

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

New Features

Improvements

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:

// Artifacts Server
https://downloads.ortussolutions.com/

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!

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!

Step 1 : Download

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.

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

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:

install contentbox,contentbox-installer-module

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

// LOCATION MAPPINGS
this.mappings[ "/contentbox" ] = COLDBOX_APP_ROOT_PATH & "modules/contentbox";
// THE LOCATION OF THE ORM MODULE
this.mappings[ "/cborm" ] = this.mappings[ "/contentbox" ] & "/modules/contentbox-deps/modules/cborm";

ORM Settings

// ORM SETTINGS
this.ormEnabled = true;
this.ormSettings = {
    // ENTITY LOCATIONS, ADD MORE LOCATIONS AS YOU SEE FIT
    cfclocation=[ "models", "modules", "modules_app" ],
    // DO NOT REMOVE THE FOLLOWING LINE OR AUTO-UPDATES MIGHT FAIL.
    dbcreate = "update",
    // FILL OUT: IF YOU WANT CHANGE SECONDARY CACHE, PLEASE UPDATE HERE
    secondarycacheenabled      = false,
    cacheprovider        = "ehCache",
    // ORM SESSION MANAGEMENT SETTINGS, DO NOT CHANGE
    logSQL             = false,
    flushAtRequestEnd             = false,
    autoManageSession            = false,
    // ORM EVENTS MUST BE TURNED ON FOR CONTENTBOX TO WORK
    eventHandling         = true,
    eventHandler        = "cborm.models.EventHandler",
    // THIS IS ADDED SO OTHER CFML ENGINES CAN WORK WITH CONTENTBOX
    skipCFCWithError    = true
};

Step 3 : ColdBox.cfc Settings

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

// ORM Module Configuration
orm = {
    // Enable Injection
    injection = {
        enabled = true
    }
};

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:

// Register all the custom named caches you like here
caches = {
    // Named cache for all coldbox event and view template caching
    template = {
        provider = "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
        properties = {
            objectDefaultTimeout = 120,
            objectDefaultLastAccessTimeout = 30,
            useLastAccessTimeouts = true,
            freeMemoryPercentageThreshold = 0,
            reapFrequency = 2,
            evictionPolicy = "LRU",
            evictCount = 5,
            maxObjects = 5000,
            objectStore = "ConcurrentSoftReferenceStore" //memory sensitive
        }
    },
    // ContentBox Sessions
    sessions = 	{
        provider = "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
        properties = {
            objectDefaultTimeout = 60,
            objectDefaultLastAccessTimeout = 0,
            useLastAccessTimeouts = false,
            freeMemoryPercentageThreshold = 0,
            reapFrequency = 2,
            evictionPolicy = "LRU",
            evictCount = 5,
            maxObjects = 1000, // Can support up to 1000 user sessions concurrently.  Modify if needed. 0 = unlimited
            objectStore = "ConcurrentStore"
        }
    }
}

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:

// YOUR SES URL ENTRY POINT FOR CONTENTBOX, IF EMPTY IT WILL TAKE OVER THE ENTIRE APPLICATION
// IF YOU WANT TO SECTION OFF CONTENTBOX THEN FILL OUT AN SES ENTRY POINT LIKE /site OR /content
// BY DEFAULT IT TAKES OVER THE ENTIRE APPLICATION
this.entryPoint    = "";

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

Whether you have used ColdBox before or not, using Modules with ContentBox and ColdBox is fairly straightforward, in fact, I think its a great way to dip your toes into using both technologies. Working with Modules is like everything else in ColdBox, you work with conventions, but you have control.

As stated in our Module Conventions page, we showed you how there are 4 locations for modules in ContentBox. Depending on how your module will work, you should choose the appropriate location. In this example, we're going to build a custom ColdBox module, which it not managed by ContentBox Admin's Module Manager.

Module Build Location

We'll be working in modules_app folder. These modules we create are for developers eyes, and will not show up in the 'Manage Modules' administration menu. These are modules that you wouldn't want someone accidentally turning on / off, for example, a key part of the website.

When you install a module from the 'module manager' in the admin, ContentBox installs those modules into another location.

Module Building Basics

There are a few ways to build a module, including CommandBox scaffholding, where you are asked a few questions, and then it generates a module, with all of the folders you need and some you might want.

In this example, we will start simple, and add more files as we build. First, we need to know a few things about the module to get started... your folder name, and then some details to add into your Module Config file.

Folder Name for the Module

This is the folder you put the module in. It does not have to match anything else with the module, so you can use something meaningful... you can set the entry point / link / route manually in the Module Config file.

Entry point - What link / route would you hit to pull up this module?

In my example, I want to be able to go to /customModule and be able to pull up this module. I have created modules for /profile and /pay and /help in the past.

Namespace for the Module

This is a namespace for any models initialized in this module. Say you have a UserService.cfc in your module, you would ask for this service from wirebox with userService@customModule if that is the namespace you would like to use. I usually make the entry point and namespace and the folder all match, unless the entry point should be shorter or different, for whatever reasons.

CFMapping for the Module

This is an automated mapping for the module. I usually have this match the folder, and namespace.

Version

Start at 1.0.0, you can bump it up as you go, but this is usually not vital unless you're planning to publish on Forgebox or something. We can look at that in a future post.

Our new Module - CustomModule

For my example, lets keep it super simple, and call the app customModule, and we'll keep everything the same, folder, entrypoint, namespace, mapping.

Create Folder

Lets create a folder /modules_app/customModule/

Create ModuleConfig.cfc

Next, lets create a file called ModuleConfig.cfc - this is the config file that ColdBox loads to setup the module, and get it ready to use. It can setup a lot of things, including the mapping, entry point, and a lot more. We'll start simple, here is a gist for my bare bones moduleConfig file.

Once you have your folder, and your moduleConfig file, you can reinit your app, and then try hitting your entrypoint.

Error - so lets see what we need next to be able to get this Module Working.

If you read the error message, you'll see that the event customModule:home.index is not a valid registered event.

What does this mean? This means the entry point worked, and found your module, but its looking for an event to run. If you look in your routes in your config, you'll see some basic routes setup for you.

Module Routing

// SES Routes
routes = [
// Module Entry Point
{ pattern= "/", handler="home" , action="index" },
// Convention Route
{ pattern= "/:handler/:action?" }
];

These routes are children routes of the entrypoint.

So /customModule/ is added to the apps main routing table, by setting the entry point above. These children routes build on top of that.

So if someone hits the child route / then its the same as /customModule/ - and if that pattern is matched, that route says we want to use the 'Home" handler, and the "index" action. That is why you see the error looking for that, its because this is the default event for this module. You will also see there is another route pattern below, /:handler/:action - this includes placeholders. So this will match anything with 2 or more values, and then it will use the first value as the handler name, and the second piece as the action.

• /customModule/profile/view/ would be the customModule with the profile handler and the view action.

• /customModule/product/add/ would be the customModule with the product handler and the add action.

We could change our default to be something else, but for now, lets keep it simple. Home Handler and Index action.

So how can we create this event?

This is where ColdBox conventions really shine. You might think you have to create a Handler folder, and create the handler named Home.cfc and then put a function inside of it called index... which is correct but you don't HAVE to. ColdBox's conventions requires less than that to create an event. In fact, the lowest point of entry for creating an event, is just to create a view.

Lets make a folder called views ( the convention for where your views live ) /modules_app/customModule/views/

To create the view for home.index, we need to create an index.cfm. Conventions tell us, to make a folder inside views to match the handler, and then place the action's view in that folder. So lets create /modules_app/customModule/views/home/index.cfm We'll put in an <h1>My Custom Module</h1> and see what happens when we hit the entry point now.

Amazing, just 2 files, and we have a working module. You could paste in your legacy spaghetti code right in here, and it would work. Of course, we probably want to dress it up a little more, and add some more functionality, so lets look at the layout first. If we view the source, you'll see there is more than just the h1 tag we added.

Where is all of that coming from? Layouts

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.

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.

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

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

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

Menu Data

• Title: The name of the Menu

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

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

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

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

Item Types

• Content

• Media

• Submenu

• URL

• JS

• Free

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

Common Attributes (Shared by all Item Types)

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

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

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

Type: Content

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

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

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

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

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

  • _self

  • _blank

  • _parent

  • _top

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

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

Type: Media

Refers to Media from the Media Manager

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

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

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

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

  • _self

  • _blank

  • _parent

  • _top

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

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

Type: Submenu

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

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

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

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

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

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

Type: URL

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

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

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

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

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

  • _self

  • _blank

  • _parent

  • _top

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

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