This release we're focusing on feedback from ContentBox 3.x customers and the ability to containerize ContentBox. Building on top of the SEO updates in ContentBox 3.1.0, we're continuing to make ContentBox more SEO friendly, Search Engine Friendly and Social Media Friendly. This update has a tremendous amount of updates and bug fixes for your current installations. So let's start investigating all the major areas of improvement:

New Installation Slugs

ContentBox has been partitioned into three installation slugs from ForgeBox in this version going forward:

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

2. contentbox-site - Installs a new ColdBox site enabled for ContentBox with a dependency on contentbox for its module.

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

This new schema and re-organization allows us better flexibility when updating ContentBox and installing ContentBox under docker containers. First of all, updating ContentBox will now be a matter of two simple steps:

1. Run box update contentbox in the root of the site

2. Apply the contentbox-db patch in the admin

We are trying to leverage CommandBox much more for updates and also for ease of use of installation.

Container Based Updates

On our move to greater containerization we have made several improvements and re-structuring in ContentBox.

Override ContentBox Settings via ColdBox.cfc

You can now override any runtime setting for ContentBox via a configuration structure in your main ColdBox.cfc configuration file. This will allow developers to override any runtime setting for any site (yes multi-site is coming).

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

contentbox = {

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

Override ContentBox Settings via Java Environment Variables

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

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

contentbox_{site}_{setting}=value

Here is an example on adding a custom media root:

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

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

UI AdminBar

We have added a new Admin Bar that can help you manage and edit content from the front end website. This Admin Bar can be enabled/disabled from the ContentBox Settings panel and will only show up if it meets the following rules:

1. You are logged in

2. You have ANY of following permissions: CONTENTBOX_ADMIN,PAGES_ADMIN,PAGES_EDITOR,ENTRIES_ADMIN,ENTRIES_EDITOR

The admin bar will give you the following features:

• Visit admin

• Edit visited content

• Edit custom fields

• Edit SEO data

• View content history

• View Hits

• View page layout

• Visual Draft Mode

• Visual Publish in Future

Hopefully, this admin bar can help you manage and edit content in a more visual manner.

Media Manager Image Editor + UI Updates

Thanks to our good friend Francesco Pepe (@tropicalista), we now have a full-fledged image editor in ContentBox Media Manager. The new Image Editor has the following capabilities:

• Visual Image Information

• Image Resizing

• Image Cropping

• Image Manipulation: Rotation, Flip and much more.

The media manager also sports better dialogs, context menus and better visualization. You can now also do multiple select via the use of the ctrl key.

i18n Editor Integration

The ContentBox editors now accept a new markup for retrieving localized content from any resource bundle in the ColdBox application. You can now use the following markup:

// Retrieve a key from the default resource bundle
${i18n:resourcekey}

// Retrieve a key from a named bundle
${i18n:resourceKey@bundleName}

This will allow you better localization in any page, blog entry or content store item.

i18n Caching Updates

All the UI front-end caching mechanisms have been updated to incorporate the user's language locale via the i18n module included in ContentBox. This means that you can localize any content now by using the getFWLocale() method included in the i18n module.

Updated Dashboard

The ContentBox dashboard gets some love with two new reports:

• Future Published Content - Shows top 10 content that publishes in the future.

• Expired Content - Shows the top 10 expired content.

The Latest Edits widget also shows hit counts for the pages as a mini-report.

Revamped Admin Global Search

The admin global search has been completely revamped. The UI has been updated to reflect the different types of context searches: pages, contentstore, entries and authors. It also allows you to edit or open directly to the site if available. We have also introduced that ability to scope your search context with the following search prefixes:

• author:{text}

• page:{text}

• contenstore:{text}

• entry:{text}

You can replace the {text} with whatever you want to search for and ContentBox will search only the context you applied.

Global Search Interceptors

You can add your own search contexts and search contributions by listening to the following two events:

• onGlobalSearchRequest

• onGlobalSearchDisplay

Content Store Ordering

The content store hierarchy has now been introduced to ordering digits. This means that instead of retrieving content store collections ordered by their natural keys, you now have full control of ordering hierarchies. This will allow you to create ordered collections for things like photo galleries, metadata, etc.

On Demand Sitemap Generation for Search Engines

In an effort to make ContentBox work better with search engines, we have added a Sitemap Generation Module for Search Engines. You can now upload your XML sitemaps to Google, Yahoo, Bing and any other search engine you would like to work with.

The Sitemap generation is available on demand, and available in several formats. Following Google's convention, we have implemented the following url patterns:

• /sitemap.xml

• /sitemap.txt

• /sitemap.json

• /sitemap.html

• /sitemap - which defaults to html

Google recommends XML, but supports txt as well. XML allows for more information, including:

• loc - location / url of the content

• lastmod - last modified

• image

  • image:loc - image location / url

If you use the featured image with your pages and blog entries, the image will be included in the site map, and the last modified date as well.

The site maps shows all pages and blog entries that are published, and not hidden via the show in search bit. If you disable the blog, all blog posts are removed from the site map.

Info The HTML version of the sitemap does not take into consideration any of the hierarchy of your site. It simply outputs all visible content into a list. This can be used for a crawl-able site page, but it not intended for your website visitors, at this time.

Sitemap Options

You can turn on/off the sitemap features of ContentBox via the Settings Panel.

Sitemap.txt support requires manual step

To support sitemap.txt, you will need to edit your config/routes.cfm file. Inside that file you will find a line:

setValidExtensions('xml,json,jsont,rss,html,htm,cfm,print,pdf,doc');

For the .txt extension to work inside of ContentBox ( and ColdBox the framework underneath ContentBox ), you will need to append txt to the list of existing supporting file extensions.

setValidExtensions('xml,json,jsont,rss,html,htm,cfm,print,pdf,doc,txt');

Once you have made this change, reinitialize the site, the easiest way is to log into the admin, and then click the Setting Cog and click Reload Application. Once this is done, the /sitemap.txt will function in addition to the xml and json formats.

Opengraph support for Facebook and Twitter

CKEditor Updates

CKEditor has been updated to its latest stable release with its new skin which looks fantastic within ContentBox.

Update of all JavaScript libraries + Widgets

All internally used JavaScript libraries and widgets have been updated to their latest stable versions.

Release Notes

Bugs

New Features

Improvements

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

ContentBox Modular CMS - v3.7.1

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

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

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

ContentBox Modular CMS - v3.7.1

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

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

This release has a major focus on security, authentication, containers, testing and automation. Below you can find the major changes and updates for this release and our full release notes.

Container Updates

Our ContentBox docker image has been updated to support this release and we have added two new areas of improvements for containerization:

Portable Datasource

You can now create a config/runtime.properties.cfm file with your database information and ContentBox will leverage it dynamically. No more registering of datasources on the CFML engines if you do not need to. This can allow you to leverage dynamic datasources for multiple environments and container deployments.

Author Sessions Cache & Distribution

In a world now of containers and distributed computing, we have added the ability for logged in sessions to be tracked by the ColdBox Cache Storages and CacheBox. This means that you can leverage in-memory sessions or distribute to any Cache provider CacheBox can talk to and distribute your sessions easily. It will also allow you to use the geek settings to monitor and manage the session objects of your users. You can even clear them all, expire them or choose a-la-carte.

The new cache provider region is called sessions and you can find its definition in the config/CacheBox.cfc file.

// 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"
    }
}

Make sure that your config.Coldbox.cfc file contains in configure function

        // ContentBox relies on the Cache Storage for tracking sessions, which delegates to a Cache provider
        storages = {
            // Cache Storage Settings
            cacheStorage = {
                cachename   = "sessions",
                timeout     = 60 // The default timeout of the session bucket, defaults to 60
            }
        };

Security Updates

Two Factor Authentication

This is one of our biggest features for ContentBox is our two factor authentication framework. That's right, we built a two factor module framework that will allow you to build or use any two factor or multi-factor authentication mechanism. We have included one in the core which is Email verification.

Please refer to the developing two factor authentication providers in order to get an in-depth look of how to build your own two factor authentication provider modules.

Two Factor Events

The following are the new interception points for two factor authentication

• cbadmin_onTwoFactorSettingsPanel - Shows on the two factor global settings panel

• cbadmin_onAuthorTwoFactorOptions - Shows on the options for two factor auth in the author editor

• cbadmin_onAuthorTwoFactorSaveOptions - Fires when the options are being saved

• cbadmin_beforeTwoFactorForm - Shows at the beginning of two factor form challenge

• cbadmin_afterTwoFactorForm - Shows after the two factor form challenge

• cbadmin_onInvalidTwoFactor - Fires when an invalid challenge has been made

• cbadmin_onValidTwoFactor - Fires when a valid challeng has been made

Global Settings

An admin can force two factor authentication for all users in the system and even provided a trusted device registry so ContentBox can track their devices and challenge only after a few days.

User Settings

The user can also setup two factor authentication for their account if so desired.

Login Options

An administrator now can control login options and enhance the logging experience of their users.

Permission Groups

We have introduced the ability to create and organize permissions not only in roles but in our new permission groups. This will allow you to create more complex and robust permission schemas and be able to assign multiple permission groups to users. The entire permissions tab for authors has been revamped to allow you better visualization of rules and permissions.

Improved Rate Limiting

The rate limiting module has been revamped to help with Denial of Service attacks or even just pesky scrapers. You can now configure more options for fine-tuning including relocation URLs, custom messages and improved logging.

Password Enhancements

There have been many updates on both the UI and the security of user passwords.

Password Meter

We have introduced the concept of a visual password meter, which can guide users when changing, resetting or setting passwords:

Password Length Options

You can now also as an admin decide on the minimum length of user passwords.

Password Reset Options

As an administrator, you can now reset user passwords a-la-carte or for every single user in the system. This will issue a notification to the user with instructions on resetting their system password. User password reset workflow has now been improved with our new password reset screens instead of bulky double email validation mechanisms.

New Interception Events

Here are the new interception events you can listen on for password reset workflows:

• cbadmin_onGlobalPasswordReset

• cbadmin_onPasswordReset

• cbadmin_onInvalidPasswordReset

Author Updates

New Author Wizard

We have introduced a new approach to creating authors in ContentBox. You will now be presented with the new author wizard which will allow you to pre-fill author details in a secure manner. A notification will be sent to the new author's email address with a password setup token so they can secure their account.

Improved Author Listings

The author listings have been improved with tons of new filters, reporting and even sorting options. Go admin like a mad man!

Improved Author Snapshot

The Author Profile Snapshot has been updated to include a better UI, better visualization and a new action toolbar for direct Author actions and Author exporting.

Content Updates

Markdown Support++

We introduced markdown support for all content in many versions before. This update includes a brand new markdown engine with table support, code syntax highlighting and much more. We also made several settings and author specific details available as markdown content. In other words, viva markdown!

Markdown Editors

We have also updated our markdown UI editor and it can be used everywhere in the admin were markdown is allowed.

Publishing Workflows

We have added a new two-step workflow for publishing any piece of content. This will allow you better visibility when working with drafts or live content. The new flow will also assist users that do not have any publishing capabilities.

Content Hierarchy Navigation History

We have improved the navigation of the content store and the sitemap by taping into the browser history API and providing history support for hierarchy navigation. Never again loose your place in the hierarchy.

Full Release Notes

Bugs

New Features

Improvements

ContentBox 3 is a collection of more than 150 tickets resolved. It has been a massive undertaking with some great results. We have divided all the major updates in this release by category below:

ContentBox 3.1.0 is a minor release with over 40 issues, improvements and new features addressed. Below you will find the detailed release notes about this release but also the major areas of improvement and new features introduced. Enjoy!

Upgrading to 3.1.0

Travis Integration

Travis is now building and publishing ContentBox to ForgeBox.io. We will also be able to accept pull requests with satisfaction that they do not break the builds. So pull away my friends!

Updated JDK/JRE + Lucee Engines

All express versions have been updated with the latest JRE/JDKs and Lucee CFML engines.

Easily Render Captcha Images

ContentBox supports native captcha support and now your themes can render out a nice captcha image by using the new ContentBox helper method: cb.renderCaptcha() method.

SEO Enhancements

We have also devoted time to enhance the SEO capabilities of ContentBox not only in the ContentBox helper object but in the updated default theme. The new helper methods are:

• getContentTitle() : Retrieve the assigned title for a rendered page

• getContentDescription() : Retrieve the assigned description for a rendered page

• getContentKeywords() : Retrieve the assigned keywords for a rendered page

Title Discovery

Please note that the title for a page now comes in the following discovery hiearchy:

1. Override set by custom modules

2. SEO Panel title

3. Page name

Description Discovery

Please note that the description for a page now comes in the following discovery hiearchy:

1. Override set by custom modules

2. SEO Panel description

3. Excerpt

4. Dynamic Excerpt (160 characters) from content

Keywords Discovery

Please note that the keywords for a page now comes in the following discovery hiearchy:

1. Override set by custom modules

2. SEO Panel keywords

3. Global Site Keywords

SEO Module Overrides

If you are building custom modules with views that render in a site's theme, you can now also set SEO content for title, description and keywords by leveraging the following methods in the ContentBox Helper:

• setMetaTitle()

• setMetaDescription()

• setMetaKeywords()

Static Site Generator

ContentBox 3.1 now supports the generation of static sites from your content and even your blog. This is a great addition to ContentBox as now you can produce static versions and workflows, deploy to CDN networks, secure your content and much more. Once you click on the Start Generation button, ContentBox will go over your entire site and produce a static archive for you in the associated theme. It will also announce two interception points for you during the process:

• cbadmin_preStaticSiteExport : Receives all the export options in the intercept data so you can alter the export behavior.

• cbadmin_postStaticSiteExport : Receives all the export options and also a results structure with the following keys: exportLog:builder, exportDirectory, exportArchive. This is a great way to listen for the export and send to S3 for archiving, etc.

Warning Dynamic elements like commenting, searching, etc must require a JavaScript implementation. So make sure you have a static export strategy in place.

Module Enhancements

This release sports many enhancements to support module development authors in order for them to seamlessly build high impact applications using ContentBox.

Author Object Availability

The logged in (or not) author/user of ContentBox is now globally available in the ColdBox private request collection as prc.oCurrentAuthor. This will allow module developers to have easy access to the current object that would represent a logged in Author or User of the ContentBox instance.

File Manager UI Updates

The File Manager / Media Manager is an important part of a Content Management System, and we have fixed several UI bugs, and added a few smaller features. The Context Menus are more accurate, and function on the selected item. The file location breadcrumb is now clickable, to allow you to move about your file structure easier.

Release Notes

Bug

New Feature

Improvement

The following are major system architecture updates we have done in ContentBox 3.

ColdBox 4

We have updated the entire core to leverage ColdBox 4 and modularity. We have completely re-architected all modules to adhere to ColdBox 4 standards and rely on CommandBox CLI for package management and resolutions. This update in itself is worth noting as it not only modularized even more ContentBox, but gave it a source code reduction and performance boosts.

Oracle + PostgreSQL Support

Oracle and PostgreSQL are now fully supported.

BCrypt Support

Password Policy

A new password policy is now in place for ContentBox for new and current users, which must be greater than 8 characters with at least one:

• Lower case character

• Upper case character

• Digit

• Special character

Login Tracker

The ContentBox administrator module now comes with a login tracker which if enabled can track invalid logins and be able to block individual ip addresses from brute-force attempts. We even track all valid logins into the new ContentBox Security Audit Log.

Rate Limiter

ContentBox now comes with a rate limiter module that can limit count and duration and very configurable. This can stop denial of service attacks or just penetration hacking attempts.

Core Settings

Introduction of core and user based system settings. This allows for the distinguishing of what are ContentBox core settings and custom user or module settings when managing them from the geek panel.

Settings Cluster Storage

You can now decide in which caching engine to store global ContentBox settings. This provides the way to fully scale ContentBox in any cloud provider.

SSL Support +

SSL support can now be found everywhere in ContentBox for both the UI and admin modules. Users can even select specific pages for users to transition into or out of SSL for richer eCommerce or secure experiences.

Internationalization

The majority of all modules have been now translated into English, Spanish, Italian, German and French. There is still work to do to localize the entire source, but it is coming.

ContentBox Express with JRE

Our entire build process has been revamped and now we can produce ContentBox Express editions with included Java runtimes for Linux, Mac OS X and Windows.

Automated Asset Pipeline

We have completely re-architected our asset pipeline and ContentBox now comes with an integrated development pipeline for front-end development. All assets are now tracked via bower and npm. We have created a developer guide for anybody working with the admin assets and collaborating.

CommandBox Integration

All development is now done with CommandBox and all dependencies are tracked via CommandBox. This provides a smoother update processes for users and also a great workflow for collaboration.

DocBox API Docs

DocBox now generates all API docs with much better documentation and readability.

We have also updated the theming engine in ContentBox with ColdBox 4 goodness and extreme modularity. Here you can find the major updates for the theming engine.

Themes not Layouts

Themes is our new mantra. We have transitioned layouts to what we now call ContentBox Themes. They have been revamped to support ColdBox 4.

New Theme.cfc

The theme descriptor CFC is now named Theme.cfc. Backwards compatibility still remains, but now the new descriptor will provide a nice way for editors and tools to target.

Theme Setting Groups

You can now create theme setting groups in the theme descriptor Theme.cfc and the new admin UI will present them in a categorized and ordered format. This is a great way to visualize theme settings.

Theme Modules

Themes can now include ContentBox modules in a new folder convention called modules. This allows you to ship your theme with 1 or a billion modules.

New Theme Events

The theme life-cycle now presents several new events:

• cbadmin_preThemeSettingsSave - Before saving theme settings

• cbadmin_postThemeSettingsSave - After saving theme settings

• cbadmin_onThemeSettings - When displaying theme settings in the admin UI

• cbadmin_onThemeInfo - When displaying theme information on the admin UI

New ContentBox Theme

We have a new official UI theme that you will come to love. It has over 10 different skins and configurations that will give you a plethora of configuration patterns for your site. It is based on bower and grunt assets, so you can easily fork and customize.

RESTFul Response Formats

The UI module now allows you to be able to export your pages, or blog entries in many response formats by adding the formats as extensions to the URL or using a ?format=XXX URL variable.

• json

• XML

• PDF

• word

The JSON and XML support means you can now build alternative UI modules based on modern JavaScript or other language frameworks. This is a game changer for ContentBox as it will provide you with the ability to export any piece of content or blog in a tranportable RESTFul format. You can get a response format from any page, blog entry, blog archive, and blog filters.

JSON Output

XML Output

New Rendering Cache Headers

A new header will be sent to the browser if a content page is cached: x-contentbox-cached-content. This can provide proxies or cache engines the ability to tell when a page is cached by ContentBox.

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

If you already have a ContentBox 2.X installation you will have to follow this guide in order to update your installation. Please note that ContentBox 3 is a major upgrade and will require some manual steps on your part in order to have a seamless upgrade.

Step 1: Backup

Like with any automated process, there is room for error. So backup your files and database, we will not be held responsible for any mishaps.

Step 2: Download CBCMS3 Updater

Step 3: Install CBCMS3 Updater

Unzip the download and copy over the folder to your current ContentBox installation in the modules folder. Make sure the folder is called cbcms-updater-v3. It should be placed alongside the other ContentBox modules.

Step 4: Restart Application

In order for the module to take effect, you must restart your application or even better your server.

Step 5: Visit Module

Now open your application and visit the module by using the /CB3Updater URL entry point. Here is an example: http://mysite.com/cb3updater

The module will be active and it will tell you to upgrade your application's config/ColdBox.cfc that you must do so manually according to the instructions presented. Once you have done this manual step, then save your file and click on the Continue button.

Step 6: Automation

Now you will be in step2 of the module wizard. It will show you an updated Application.cfc according to your old Application.cfc on disk. If there are any custom changes that are not reflected, then update as you see fit. Once done, then click on the continue and save button. This will start the upgrade process, grab a cup of coffee and wait for the installer to show you the finalization screens.

Step 7 : WINDOWS ONLY

If you are on a Windows machine, unfortunately, you will have to have an extra step due to the fact the OS creates file locks on certain files. This means that the upgrader will not be able to upgrade the coldbox folder in its entirety. You will have to stop the ColdFusion/Java server, and remove the following folder: coldbox/system/core/javaloader manually. Once removed, restart the server and click on the button that says Continue so you can finalize the process.

Step 8: DELETE UPDATE MODULE FROM DISK

If all went well, then you should see the screenshot above. You can now log in to your new application and site. We would recommend a final server restart if possible as well. IMPORTANT: Now you must delete the module from disk

Below is a listing of all the major updates in the administration modules.

Admin UI

The administration module sports a completely re-designed responsive UI. Our goal was to think mobile first and build from there. So you will see tons of great additions for working on mobile devices, new editors, new fullscreen mdoes and much much more. Below is a nice image gallery of all the changes in the administration module. Please note that every single screen has changed.

Markdown Native Support

ContentBox now sports native Markdown support for writing all content objects. You can even choose markdown on a per-user level as your preferred writing style.

New Code Editor

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. It also sports realtime previews and side-by-side editing in full screen. Your editing experience is about to get a whole lot better now.

Editor Auto Save

We have introduced local storage auto saving capabilities for all editors in ContentBox. No matter the implementation, we will provide auto-save capabilities. This is a great way to know that silently your work is secure.

Editor Escaping Markup Translations

You can now use the <escape></escape> syntax in any content editor to escape ContentBox translations for settings, markdown, etc.

Editor Responsive Previews

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

Editor UI Updates

The content editors have completely been re-designed for mobile first paradigm. They sport new tabbed interfaces for history, comments, custom fields and editing. You also have much more real estate when editing and even full screen editing support.

New Dashboard

The dashboard now supports a cleaner interface for visualizing the latest content edits, drafts, comments and news.

Media Manager Updates

Improved UI to match the new admin UI with responsive updates. It also has a smoother uploading and drag and drop uploading capabilities.

Admin Fullscreen Mode

We have added HTML5 fullscreen mode capabilities for the admin UI. This will allow you to go full screen to edit, create and manage in a gorgeous huge display.

Configurable RSS

RSS feed options and caching options can now be customized via settings.

Content Featured Images

All content objects now have the ability to set natively a featured image alongside the content.

Author Edit Panels

The author details now sports two new panels to showcase their latest edits and latest drafts. It will make it much easier for authors or administrators to discover what they are working on.

CBHelper Updates

The CBHelper sports some new methods:

• getPrivateRequestCollection() - Get the ColdBox private request collection

• isHomePage() - Verify if the current rendered page is the home page

• prepareUIRequest() - Use in any ColdBox module to prepare rendering under the ContentBox theme

New Admin Interception Points

Here is a collection of all the new admin interception points:

• onGlobalSearchRequest - When a global search is made

• onGlobalSearchDisplay - When the global search is displayed

• cbadmin_beforeLoginForm - Before the login form renders

• cbadmin_afterLoginForm - After the login form renders

• cbadmin_preThemeSettingsSave - Before saving theme settings

• cbadmin_postThemeSettingsSave - After saving theme settings

• cbadmin_onThemeSettings - When displaying theme settings in the admin UI

• cbadmin_onThemeInfo - When displaying theme information on the admin UI

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

There are several ways to install ContentBox. You can:

• Leverage the ContentBox.war to any Java enabled server

• Run an express self-contained version

• Run as a docker container

So let's get started.

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 4.5). You can use an embedded database or connect the embedded server to any database server as well. 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
server start

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

Note You can install the bleeding edge of ContentBox by using the contentbox-install@be identifier in the install command. Basically, you can add any @be to any ID and CommandBox will try to retrieve the latest bleeding edge.

This will install the latest stable ContentBox and run an embedded server (Lucee 4.5) for it. After this you will get the ContenBox 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 4.5
server start

# lucee 5
server start cfengine=lucee@5

# Adobe CF11
server start cfengine=adobe@11

# Adobe 2016
server start cfengine=adobe@2016

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

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

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 requires ColdBox 4.3+.

Step 1 : Dependencies

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

This will install the ContentBox module with all of its dependencies under the /modules/contentbox folder and update your box.json with the appropriate dependency. That's it, next step!

Step 2 : Copy Over Installer (Optional)

Note We will create another installer approach in the future for this portion.

Step 3 : Application.cfc Updates

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

Mappings

ORM Settings

Step 4 : ColdBox.cfc Settings

We now move to the last step, open your application's ColdBox.cfc and you will add the following settings:

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

Danger Make sure you have the datasource created in your ColdFusion administrator or inline in your Application.cfc

Step 5 (Optional) : UI Route

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

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

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

Or you can visit www.ortussolutions.com/products/contentbox for all the available download patches.

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

The login URL to use to access the contentbox administration 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.

Playing around

Note The command above is using && to concatenate the two commands which will work under *unix. If you are in windows, replace && with ; in Powershell, replace && with & in Cmd, or run the two commands separately

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 user-uploaded assets. 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 default storage location for the CMS user media assets is set to /app/includes/shared/media. Let's mount both of those volume points, so that our database and user-uploaded assets persists between restarts:

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

Custom Database Configuration

Because the express flag produces a ContentBox installation which runs on a file-based, in-memory H2 database, it's really suitable only for testing or low-traffic containers. For scalability, we would want to connect to an database server, which would allow us to connect from multiple containers in a distributed fasion (MySQL, Oracle, MSSQL, etc)

By convention, the datasource name expected is simply named contentbox.

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

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

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

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

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

Granular Environmental Control

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

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

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

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

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, 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 1 minute intervals with 5 retries and a timeout of 30s.

In The Real World

Playing around with the image is great, but what does this mean for you as a developer? Effectively it means that you can develop and deploy customized CMS applications with only a single theme directory (and, possibly, a customized config/Coldbox.cfc file).

The image location for the themes directory in ContentBox is /app/modules/contentbox/themes. Any theme mounted in to this directory can be configured in the run of the container, which means you no longer have to commit an entire ContentBox installation to your repository. You can mount only those files and folders ( e.g. - custom modules ) necessary for your application to do its thing. In addition, you also have power to reconfigure ContentBox settings on-the-fly using environment variables prefixed with contentbox_{site}_{setting}={value}.

Let's start an image with a custom theme, and a ColdBox module, persisting our assets, while using a MySQL database with the installer:

Customizable Volume Paths

Please note the following customizable paths for custom assets.

• /app/includes/shared/media - ContentBox Media Manager

• /app/modules - CommandBox managed modules

• /app/modules_app - Custom ColdBox modules

• /app/modules/contentbox/themes - Custom ContentBox Themes

• /app/modules/contentbox/widgets - Custom ContentBox Widgets

• /app/modules/contentbox/modules_user - Custom ContentBox Modules

There are more geek settings and paths that we have time to go in to in this post but, suffice it to say, you will be able to control nearly every aspect of your site settings on the startup of your Docker container.

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.

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

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

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

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

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

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

• Shows if your post has been published

• Shows the numbers of views

• Shows the number of comments

And you also have quick actions:

Where you can check the info related to each individual post

And entry actions

Developers are getting more and more familiar with Markdown, and its 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.

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.

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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

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.

In this section you will install ContentBox by using the source download option.

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

Caution Due to a bug in some CFML engines, DO NOT use the subfolder name contentbox, use cbox or site or whatever you like if you will be deploying under a subfolder.

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!

Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in. {Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator

In this section you will install ContentBox by using the war download option and deploying it to any Java 1.7+ servlet container.

Step 1: Download WAR

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

# bleeding edge
wget http://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!

Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in. {Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator

This release was all about improvements to the core, localization and internationalization for sites, many bug fixes, UI improvements and updates to our containerization strategy. Please see below the major areas of improvement and our full release notes.

New Installer Module

The installer module is now available as a standalone module using the slug contentbox-installer-module. This will improve our container and your container strategy as now you can bring in the installer on demand via CommandBox.

install contentbox-installer-module

Ability to contribute CSS to CKEditor

Thanks to the Computer Know How guys you can contribute your own CSS files to the CKEditor instance so the content has your theme's look and feel. Please note, this is mostly usable for theme developers and module developers.

The event is called cbadmin_ckeditorContentsCss and it will receive a struct with one key called contentsCss which is an array. You can then append CSS style sheets to that array that CKEditor will showcase.

function cbadmin_ckeditorContentsCss( event, interceptData ){
  // Add css
  interceptData.contentsCss.append( "/path/theme.css" );
}

Site Localization Updates

Thanks to the Computer Know How guys, this release sports many i18n improvements.

Changing Site Locales

A ContentBox application depends on the ColdBox i18n module which gives you the ability to serve any content in any language, use resource bundles and use the resource utilities. However, we have now exposed the ability natively for users to change locales via the UI module using our URL of: http://site.com/__changelang/en_US. The route expects an ISO valid language code in the format of code_variant.

Note By default, visitor locale's are stored in the cookie scope. You can change this via the config/Coldbox.cfc configuration CFC.

Generating Locale Links

The CBHelper object can now produce these links for you in your layouts, themes and views by leveraging the following method:

/**
 * Link to the __changeLang route, this is where the fwLocale is changed
 * @lang The iso language code
 */
function linkLanguageChange( string lang = "en_US" ) {
    return getRequestContext().buildLink( '__changeLang/' & arguments.lang );
}

Locale Content Caching

All caching strategies have now been updated to allow for locale to determine its key. This way, every visitor's language will be cacheable and performant.

Release Notes

Bugs

New Features

Improvements

The roles menu is located under the User menu in the navigation bar to the left of the screen.

In this menu you will see a list of roles available to assign users, which will allow you to define their access to the site. You can use the quick search function if you are looking for specific roles, otherwise you can look in the main body of the page.

You will see 5 headings across the page

• Role - This will be the name given to the role

• Description - This will explain the role and access

• Permissions - This will tell you how many permissions have been assigned to the role.

• Authors - This will tell you how many users are assigned to this role

• Actions - There are 2 options:

  • Green Icon - Manage the Permissions

  • Blue icon - Role Actions has 3 options

    • Edit Role

    • Export as JSON

    • Export as XML.

*You can only edit permissions if you yourself have permission to make changes.

Create Role

You can create new roles by selecting Create Role. A box will appear and you enter the Name and Description. Once this is done you can add abilities to the new role by managing the permissions (see below).

Edit Role

Edit Role only allows you to edit the Name and Description, like the Create Role Form. You will spend more of your time with Roles, managing the Permissions.

Manage Permissions

In the Manage Permission menu it will show the Available Permissions & Active Role Permissions.

Available Permissions

Available Permissions are shown in a dropdown box. You will be able to add permissions to a role by selecting the permission and clicking Add Permission.

Active Role Permissions

In the Active Role Permissions below are the permissions that are currently available to this role. You can also remove permissions available to the role by click the red X next to the permission in the active role section.

Bulk Actions

In the top right section of the page, you will see a Bulk Actions button next to Create Role. 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 roles on one site, and then export them, and import them into the other sites you manage.

For safety reasons, when you Import Roles, by default you will not override any content. If you have existing roles, 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 ).

ContentBox 3.1 now supports the generation of static sites from your content and even your blog. This is a great addition to ContentBox as now you can produce static versions and workflows, deploy to CDN networks, secure your content and much more. Once you click on the Start Generation button, ContentBox will go over your entire site and produce a static archive for you in the associated theme. It will also announce two interception points for you during the process:

• cbadmin_preStaticSiteExport : Receives all the export options in the intercept data so you can alter the export behavior.

• cbadmin_postStaticSiteExport : Receives all the export options and also a results structure with the following keys: exportLog:builder, exportDirectory, exportArchive. This is a great way to listen for the export and send to S3 for archiving, etc.

Warning Dynamic elements like commenting, searching, etc must require a JavaScript implementation. So make sure you have a static export strategy in place.

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

The express version of ContentBox is a fully integrated running server powered by Lucee, an open source CFML engine, and Tomcat. It comes bundled with a JRE for your operating system or one without a JRE.

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!

Caution We recommend that after you install ContentBox that you remove the installer and datsource wizard modules from disk. You can do so manually or via the Dashboard once you log in. {Root}/modules/contentbox-installer and {Root}/modules/contentbox-dsncreator

Changing the Default Port

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

Just update the port to whatever you desire.

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

• PostgreSQL

• Hypersonic

• H2

• Apache Derby

IMPORTANT: Dialect Choice

Example Code

Dialects We Support

• Derby

• PostgreSQL

• MySQL

• MySQLwithInnoDB

• MySQLwithMyISAM

• Oracle10g

• MicrosoftSQLServer

Tip If you are using the H2 or Hypersonic Databases, just leave the dialect empty or use the MySQL dialects for compatibility purposes.

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"