Content Inheritance Basics in Crafter CMS

Crafter CMS support content inheritance out of the box and supports it via a pluggable mechanism that allows developers to augment or override what’s out of the box.  In this article, we’ll dig into the basics of this functionality.

What is Content Inheritance

Content inheritance is the ability of the CMS to centrally manage content values.  Updating this content in one place automatically updates the value everywhere else.  This goes far beyond simple “shared components” in the sense that, as far as the system is concerned, the inherited values, in fact, belong to the content in question.  In general, with inherited content you may:

  • Centrally define default values
  • Override previously inherited values (from some other level of the graph)
  • Delete or mute previously inherited values (from some other level of the graph)

Content inheritance is useful for a wide range of use cases including translation support, microsite management and common values (hotel count, employee count, CEO name, etc) that you want to use throughout the content but want to manage centrally.

Content Inheritance Basics

Content objects in Crafter CMS are essentially structured markup, XML by default, and house data authored via Crafter Studio by content authors. Content objects are typically structured as a tree which naturally suits the notion of inheriting from a parent (not to say that the inheritance mechanics are limited to that topology). Inheritance works as follows:

Assume we have two objects, one called Parent and one called Child and they’re set up as follows:

Parent: Below you’ll see a typical level descriptor which will be the parent of another object. You’ll note the level descriptor defines multiple elements that are common to everything at this level in the hierarchy and below it. This level descriptor defines a primary CSS file main.css, a common header component default-header.xml and a common footer component default-footer.xml.

    <?xml version="1.0" encoding="UTF-8"?>
            <createdDate>2/7/2016 19:40:03</createdDate>
            <lastModifiedDate>10/8/2016 19:58:30</lastModifiedDate>
                            <value>Default Header</value>
                            <value>Default Footer</value>
            <lastModifiedDate_dt>10/8/2016 19:58:30</lastModifiedDate_dt>

Child: Below is the XML file of a page residing under the above level descriptor and is setup to inherit from it. You’ll note the definition of the merge-strategy as inherit-levels, this invokes the level-based inheritance mechanics that require Crafter CMS to look at current and higher levels for files named crafter-level-descriptor.level.xml (this is configurable). You’ll also note that this page doesn’t specify the CSS file/group of files to include, nor will it need to specify the header nor footer components.

    <?xml version="1.0" encoding="UTF-8"?>
            <title>Child Page</title>
            <description>This is the Child page.</description>
            <createdDate>7/31/2016 16:52:39</createdDate>
            <lastModifiedDate>8/1/2016 18:55:09</lastModifiedDate>
                    <h1>Hello World</h1>

Crafter CMS will invoke the inheritance mechanics implemented in the merge strategy inherit-levels to merge the page and the level descriptor and the merge strategy will pull in the elements defined in the level descriptor into the child page before handing the new model (XML) to the rendering system. This means that when the page renders, the model will automatically contain the meta-data defined in the parent level descriptor. In our example above, the page will automatically inherit the meta-data fields cssGroupdefaultHeader, and defaultFooter.

When an element is defined by the level descriptor and then subsequently defined by a child, the child’s definition overrides the level descriptor.

This mechanism allows you to define meta-data that flows down the information architecture of the site such that an entire site can have defaults and those defaults can be overwritten by sections individual page. Some examples of real-life use of inheritance:

  • Site logo
  • Global stylesheet and JS includes
  • Global headers and footers
  • Section meta-data (flows to all pages/subsections)

The inherit-levels mechanism allows you to set level descriptors at various levels of the information architecture with lower levels overriding upper levels.

What we discussed thus far is a single inheritance strategy implementation, inherit-levels, the code to which is available here: There are more inheritance strategies implemented out of the box with Crafter CMS and you can build your own to suit your needs.

Out of the Box Strategies

No content should be inherited.
Content from Crafter level descriptors (crafter-level-descriptor.xml)
in the current and upper levels should be inherited.
The parent descriptor to inherit is specified explicitly in the XML
tag parent-descriptor.
The page will be merged with other pages in a targeted content
hierarchy, including level descriptors. For example,
/en_US/about-us will generate the following merging list:

How To Change the Ports on Your Crafter CMS Installation

One of the most common questions I get from developers is:  “When I download Crafter CMS it runs on port 8080.  How do I change that?”  They are not simply looking to put Crafter on port 80 or 443.  They want to move it to port 9080 or some other port because they are already running something on port 8080.

To make things easy, let’s look at a standard development installation — which consists of the following microservices:  Crafter Studio, Crafter Engine, Crafter Search, Solr and Crafter Deployer.

In the diagrams above you will note the black arrows between components.  These are HTTP connection to (typically) localhost and the port specified on the target component.    Let’s review each of these connections:

A. Developer/consumer goes to Crafter Studio application (/studio).  Crafter Studio IFrames Crafter Engine rendering.
B. Crafter Studio queries Crafter Search when users do a search inside the CMS
C. When rendering Crafter Engine can leverage Crafter Search to perform content queries and searches.
D. Crafter Search applies platform-specific business rules and makes query requests to Solr via connection D
E. When content, code or configuration is saved via Crafter Studio or directly via Git it is picked up by the preview deployer and published to Crafter Search.  Crafter search performs inserts updates and deletes on Solr via connection D
Crafter Studio maintains/caches project/user and operational metadata (workflow state, dependencies) about content locally in an embedded MariaDB.

Configuration for Tomcat ports:

  • Impact: Ports for Crafter Studio, Crafter Engine, and Crafter Search
  • Location: INSTALL_DIR/bin/apache-tomcat/conf/server.xml
  • Configured ports: There are several ports listed in this XML file.
    • 8005 (shutdown port),
    • 8080 (HTTP connector)
    • 8443 (HTTPS connector)
    • 8009 (AJP connector)
  • INSTALL_DIR/bin/ / crafter.bat
    • Linux: export TOMCAT_HTTP_PORT=8080
    • Windows: SET TOMCAT_HTTP_PORT=8080

Once you change the Tomcat ports you must update the configuration for the communication between microservices to Crafter Search:

  • Impact: Crafter Studio Connections
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
  • Configured Ports:  There are several ports to update when Tomcat’s connector ports are changed:
    • studio.preview.engineUrl
  • Impact: Crafter Engine
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/engine/extension/
  • Default Ports:  Update the crafter search port
  • Impact: Crafter Deployer
  • Location: INSTALL_DIR/bin/deployer/config/classes/crafter/engine/extension/base-target.yaml
  • Default Ports:  Update the crafter search port
    • target/search/serverUrl

Configuration for Deployer ports:

  • Impact: Configures the ports for the deployer, impacts Studio
  • Location: INSTALL_DIR/bin/deployer/config/application.yaml
  • Configured Portsport
  • INSTALL_DIR/bin/ / crafter.bat
    • Linux: export SET DEPLOYER_PORT=9191
    • Windows: export DEPLOYER_PORT=9191

Once you change the Deployers ports you must update the configuration for the communication between Crafter Studio and the deployer

  • Impact: Crafter Studio’s communication with deployer
  • Location: INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
  • Configured Ports:  There are several ports to update when the deployer ports are changed:
    • studio.preview.defaultPreviewDeployerUrl
    • studio.preview.createTargetUrl
    • studio.preview.deleteTargetUrl

Configuration for Solr ports:

  • Impact: Crafter Search’s communication with Solr
  • Location: INSTALL_DIR/bin/ / crafter.bat
  • Configured Ports:
    • Linux: export SOLR_PORT=8694
    • Windows: SET SOLR_PORT=8694
  • Impact: Crafter Search’s communication with Solr
  • Location:INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/studio/extension/
  • Configured Ports:

Five Reasons Why You Should Use a Git-based CMS (Part 5 of 5)

In our previous posts we looked at Crafter CMS and its Git-based versioning (part 1), distributed repository (part 2), dug in to Git’s underlying mechanics to see how it benefits deployment (part 3) and we looked at how the support for branching (part 4) can help your organization dramatically speed up development and deployment activities. In this post, we’re going to wrap the series up with one final reason.

There are so many advantages to the way that we’ve leveraged Git; It’s hard to pick just 5 things to talk about. Because I’ve arrived at our last reason, #5, I want to use this item to speak to something non-technical: familiarity.

Reason #5: Familiarity

Throughout this series, you have heard me talk about a “Git-based” CMS.  That’s intentional and I want to elaborate on why that’s important.  The entire series isn’t just about a better mousetrap.  We’ve tried to take a hard look at the kind of problems that remain in the CMS space and the needs that modern organizations have in terms of innovation at a competitive level with respect to ease, speed and scale of continuous delivery.  It turns out that, yeah, some of the biggest bottlenecks go all the way down to the core of today’s CMS platform: They way we store and manage content and code.

The features I spoke to in this series are the first steps in truly making a real and major difference. What we’re saying is, we need a repository with a specification that enables these kinds of capabilities.  Developers and DevOps should not have to dance around the technology to get their jobs done.  That said, the functional specifications of features and how you implement them are different things. We could have focused on a system with “Git-like” rather than “Git-based” functionality. We chose to do the latter. We did that on purpose.

Leveraging Git rather than re-inventing it has nothing to do with code-reuse or ease of implementation. If you look around, you will find a number of projects that enable non-technical content editing and publishing (basic CMS functionality) for statically generated static websites that leverage Git.  Developers and DevOps familiar with Git, already recognize many of the benefits of leveraging Git for these kinds of needs.  However, implementing a full enterprise-class CMS designed to support modern, dynamic and personalized multi-channel experiences isn’t as simple as sticking Git under your CMS. The full range of WCM authoring, development and DevOps use cases are much different and more complex than what you see with simple editing and publishing of statically generated websites and standard source code management.  There are a lot of decisions to make and problems to solve.  A Git-based implementation is important for a much bigger reason another reason:

Familiarity matters. Familiarity covers both adoption and integration. Git is used all over the world. It’s proven. Moreover, developers and operations teams know how to use it. A Git based CMS is part of the broader Git ecosystem — which means your existing Git-friendly toolchain natively works with the CMS.

“Git-like” is not enough. Its got to be Git-based. Familiarity matters.


Crafting great digital customer experience is a complex, multi-step, multi-environment and multi-disciplinary practice. Today, a CMS must be as good for development and operations/process as it is for the content authors that are traditionally thought of as the primary users.  Today’s contemporary CMS platforms still sit on a basic architecture that was designed over 20 years ago when needs were different.  To meet today’s challenges a new kind of CMS is required with a new architecture that starts at the root of the platform, the repository.  Today’s needs call for a distributed repository that supports branching, advanced content/code flow scenarios and a versioning model that is multi-file.  These are Git-like features.   While the functional specification of a modern CMS repository is “Git-like” a solution that is “Git-based” leverages the power and track record of the worlds most popular source code management platform and plugs into a vast ecosystem of developers and DevOps in a way that no other solution can. 

Crafter CMS is an open source CMS project and the world’s first enterprise-class CMS based on Git. Crafter CMS is on a mission to bring content authors, developers, and operations teams together in a single platform that makes innovation easy, fast and fun.

Check out the other articles in this series:

Five Reasons Why You Should Use a Git-based CMS (Part 4 of 5)

In our previous posts we looked at Crafter CMS and its Git-based versioning (part 1), distributed repository (part 2) and deployment mechanics along with its decoupled architecture (part 3)  In this post we’ll take a deeper dive into a feature of Crafter’s Git-based CMS that provides unparalleled support and speed for innovation: branching.

Imagine a single train track that stretches from Washington D.C. to New York.  How many trains can run simultaneously on this track?  How fast can the trains go? How much control over the order of arrival do you have?

  • You can run as many trains as you have room for on the track.
  • Anyone train can only go as fast as the train in front of it.
  • The trains always arrive in the order they departed in.
  • If a train breaks down or gets put on hold, it’s nearly impossible to reorder.

With only one track, the railroad’s ability to deliver success is throttled by the amount of volume they can handle and even when capacity is not an issue, they are completely dependent on good luck with respect to order and unplanned changes and breakdowns. With railroads, the solution to this problem is implemented with switches and sidings. Sidings are branches in that single track that allow a train to pull off the main line giving the controller the ability to regulate the order, speed, and quantity of trains on the main line.

The same problems of bandwidth, throughput, and order you see in the railroad example exist with projects that need to go through your traditional CMS.  Traditional CMS platforms have no ability to branch the content and code base. They are just like that single track from DC to New York.  This means you have very little control over the order, speed, and capacity of your development. Your CMS needs branching. Let’s explore this further.

Reason #4: Branching

Nearly every CMS still sits on an architecture and repository that was devised 20 years ago.  Back then innovation was important but the world moved a lot slower.  A single pipeline of features got the job done and the CMS was less of a bottleneck.  Today, in contrast, digital channels are at the core of many organizations’ strategy for serving the customer better and beating the competition.  The organization who moves the fastest often wins.  Agility is key.

Meanwhile, infrastructure costs have gone down while development costs continue to rise.  Balancing costs with volume and speed of innovation is a major challenge of our day.  Today it’s all about great DevOps. To make DevOps really work with CMS you need to be able to branch.

Traditional software development process has included branching for eons. Developers and DevOps have long since figured out that they need to be able to work in teams, isolate work and control the order in which work is merged into the critical path for go-live. The CMS track runs right alongside the traditional development track, and at some point, it merges and the last few steps require the CMS.  It’s only now that the demand for the speed of innovation has increased that the connective tissues between development and the CMS have been put under so much stress that they are completely failing.  The fact is that today, we need that same agility all the way through the CMS and right up to the very last step of production deployment.

Even if the majority of your development is outside the CMS you still need to integrate. Consider the following example:

Because the website needs to integrate with, and ultimately deliver the functionality of the microservice, we need to perform development.  We also need to support daily content edits and continuous publishing. With traditional CMS we have no option but to use multiple CMS environments to support this scenario.  Does this approach give us multiple tracks and control over my releases?  Yes, technically it does.  But practically speaking?  No.  Not at all.

As we learned before, moving content and code between CMS environments with traditional CMS architecture is extremely difficult. The process of spinning up environments and loading code and content into them is so difficult and time consuming for any DevOps team that most won’t even consider it unless absolutely forced to.  Even then the size of the team may not support the need. The rate of innovation crawls to a near stop.

To address this problem, we built Crafter CMS v3 on top of a Git-based repository. As a result, the Crafter CMS platform is built on repository store that not only branches but also is fully distributed.  Not only are you able to easily control the order and rate of work, but it’s a snap to move work from one environment to another.

Moreover, branching not only supports DevOps and but it makes development easier.  Developers and authors can experiment, work on major features and other site enhancements in the safety of branch-based sandboxes that keep them from stepping on each other’s toes.


If you want to quickly innovate with your website, mobile app and other content-rich digital experience apps, you will need multiple teams working on different features at the same time. You need control of who is working on what and the order in which projects will be delivered.  Having the capability to manage these concerns with agility is the key to innovating quickly.  Traditional CMS platforms don’t support the basic feature set that enables this. Moving most of the development outside the CMS only gets you so far. You need a CMS that supports your DevOps process with features like branching and distributed repository if you truly want to be able to move fast.

Stay tuned for our next blog entry to learn another major reason why you should use a Git-based CMS!

Five Reasons Why You Should Use a Git-based CMS (Part 3 of 5)

Most CMS technologies are what we would call a “coupled CMS.”  The content authoring and content delivery environments are usually part of the same stack. The act of “going live” with new content or a feature is essentially based on the act of marking a true/false in a database field. There are a lot of problems with coupled CMS platforms around security, performance, scalability, and flexibility (you can learn more here.)

For these reasons and many others, Crafter CMS is built as a decoupled CMS. With a decoupled CMS you author content in one system and publish to another separate system. For platforms like Crafter CMS that are decoupled, when correctly implemented, the architecture provides great solutions for the issues mentioned above. That said, nothing is without its challenges. Decoupled systems, by their nature, are typically very scalable and can have many instances all over the world. Security, scalability, and distribution are no longer issues that only concern the Internet’s biggest players like Google and Amazon.  Security and distribution impact customer experience, safety and help reduce operating costs.  Every brand-conscious and customer-forward organization in the world is focused on these tactical issues.

Once you have a decoupled, distributable deployment model, the challenge becomes making certain that the content on the servers all over the world is the same — everywhere. Every decoupled solution has an approach for this. Some better than others. That said, few if any of the approaches offered out of the box by today’s traditional CMS platforms “mathematically” ensure every remote instance is 100% up to date and in sync with every other instance. If there are bugs in the deployment code or there is trouble in the environment you may get out of sync.

In our previous posts, we looked at Crafter CMS and its Git-based versioning (part 1) and distributed repository (part 2).  In this post, we’ll take a deeper dive into how Crafter CMS leverages Git mechanics to provide a better, more consistent distributed publishing mechanism.

Reason #3: Distributed, scalable, consistent publishing

Crafter CMS uses Git mechanics to publish content to its decoupled delivery space. When Git reports that its repository is set at a specific version that means that every file is guaranteed to be present and in the proper state for that version, it is. Fact. It’s provable.

The reason it’s provable is due to the fact that the Git mechanics that underlie Crafter CMS’ content repository are based on Git’s purely functional data structures. “The main difference between an arbitrary data structure and a purely functional one is that the latter is (strongly) immutable” (Wikipedia).  What this means is that as commits happen within the repository an entirely new immutable data structure is created containing the changes for the commit. No action is taking on the previous data structure(s.)  Nothing you ever change can be lost or corrupted by an operation once the change has been committed.  Moreover, in Git, the ID for the commit is essentially a SHA1-hash of metadata and the content in the directory tree. By definition, if a single bit changes anywhere in the tree a new SHA1-hash must be generated.


While this explanation is an oversimplification of Git’s algorithm, it is essentially the model of how it works. The point is that two repositories on two different machines with the same commit ID are mathematically guaranteed to be the same. That’s an extremely useful mechanism for versioning but it also is a very large helping hand in publishing. Crafter CMS publishes (replicates) content based on Git commits. If you want to know if an endpoint on the other side of the world is the same as what you expect, you only have to compare the commit ID(s).

In today’s elastically scalable, globally distributed world you can have any number of servers.  You need a means to make sure they are all in sync. As you can see above, Git’s internal mechanics give us just that.  Crafter CMS is the first decoupled CMS with the capacity to scale geographically across an elastic cloud and at the same time make 100% certain that remote instances are consistently running the same version of content and code.


Decoupled CMS platforms provide push-based publishing, offer greater architectural flexibility and are much easier to scale elastically and distribute globally.  Along with this increased power and flexibility comes a need to ensure that all remote endpoints are in sync with one another and are up to date.  While this problem is solvable, few of today’s decoupled CMS platforms provide a solution for this that is 100% guaranteed and mathematically verifiable.  Crafter CMS and its Git-based repository leverage Git mechanics for publishing and replication to remote nodes.  Calculating changesets and verifying that an endpoint is in a particular state is based on the proven algorithms and data structures that back Git, the world’s most powerful and popular distributed source repository.
Stay tuned for our next blog entry to learn another major reason why you should use a Git-based CMS!

Five Reasons Why You Should Use a Git-based CMS (Part 2 of 5)

Since the birth of content management system (CMS) technology, well over 20 years ago, platforms have been leveraging “obvious backends” like SQL databases as a store for the content. Not because it’s the best or right store for the job, but because SQL databases are a commonly available, simple to use technology that (kinda) gets the job done. By the early 2000s, it was clear with many implementations that directly leveraged SQL and similar database stores do not provide the full range of features like versioning that a CMS requires. They can’t. They were not built to do it. The Java Content Repository (JCR) and other similar technologies entered the scene. The implementations of these technologies sit on top of the same old database stores and add a layer of capability to fill the gaps. This is good but not good enough. Ultimately, the fact that they sit on top of a database comes back to haunt them.

In Part 1, we looked at what kind versioning model is needed to support modern digital experiences. Today we focus on another critical capability that is missing in traditional CMS solutions: a distributed repository. More specifically, distributed versioning and workflow.

Reason #2: Distributed repository

Most databases are not easily distributable from a geographic sense, and more importantly, they are not distributable from a versioning and workflow sense.

I could spend a lot of time talking about how scaling and distributing a database geographically matters in the context of CMS and why it’s so difficult. I don’t have to. If you have the need for a CMS with high availability and global distribution you already know why it matters. If you have tried to make this work with a CMS based on a traditional database or a JCR repository, you already know it’s a difficult and sometimes impossible errand.

What is distributed versioning and workflow? The easiest way to get at this is by example. In the software development space, we’ve had Source Code Management (SCM) systems for a long time. These SCM systems allow teams of developers to work on a single code base as a team without stepping on each other’s toes by checking out work locally, working on it and then checking back in edits. Hint: This is not much different from what a CMS provides to content authors behind its UI.

Back to developers: In the past, we had CVS, SVN along with many others. These SCM systems provided basic version management as well as branching and tagging but fundamentally the system was a centralized model. With such solutions, there is a single central store and source of truth for the code base.

This SCM model worked well for smaller teams and smaller code bases but for large projects like the Linux operating system, it failed completely. Linux has so many developers spread out all over the world, working on many separate but related projects. A single, centralized system simply does not scale (in several ways) to meet this need. To make a long story short (collapsing a lot of history and detail), Linus Torvalds created Git as a lightning fast, open source solution to solve this problem. Git allows developers to have their own local and intermediary repositories that are all born from a parent repository. This makes distributing developers easy, it makes concurrency simple and most importantly to us, it distributes the versioning and workflow which makes “flowing” code to and from these independent repositories possible, fast and easy. Yes!

In the CMS space, for more than 20 years all the way up to this day, we’ve had repository solutions of various capabilities and quality. All of these solutions have no real, workable solutions for moving content back from production to lower environments like Staging, QA, Development, Load Testing and local developer machines. Yes, you can do it. But it’s a nightmare. You end up doing an export/import process and it’s not easy. Some systems are easier than others but they all stink. CMS consumers rig up all kinds of replication and publishing workarounds to try and deal with this problem. It’s all a hack. There’s no technical solution in the CMS space that was built to handle the problem specifically. For this reason and many others, development, and operations teams HATE the CMS options available today. They do nothing to help the team work — worse, they fight them in almost every way. The technical members of the team put up with CMS technology because their business counterparts need content creation and editing capabilities. That’s all.

Moreover, today we understand that to some degree, in the digital experience space, “code is content.” Just as we need to be able to move content back to environments, we also must be able to move code (templates, javascript, CSS, etc.) forward through the environments. Developers have processes that they use to ensure quality and performance. With traditional CMS, moving code forward through environments is even harder than moving content back. Wholesale export/import doesn’t work!

Because Crafter CMS is Git-based and because we’ve specifically built capability in Crafter CMS to handle these needs, the world finally has a CMS that solves this problem. The same approach developers use to make and promote source code changes with Git is used by Crafter CMS to move code forward and content back.

Every organization that uses a CMS for more than simple edits and blog posts know exactly what I am talking about. Today, it’s understood that customer experience is one of the biggest competitive advantages an organization can have. Further, beyond the human element, digital enablement and innovation is the most important component of delivering great customer experience. Because content and code are inseparable from customer experience, the CMS is a mission-critical component of any and all customer experience solutions. Here’s the kicker: nearly the entire world is using a CMS technology that not only fails to enable the organization to innovate faster — it actually fights them!

The Git-based distributed capabilities in Crafter CMS allow your organization to have many environments that are all related to one another — syncing and moving objects between them is natural and part and parcel to the technology itself. This means it’s easy to move content back and code forward.

Because the system is distributed and Git-based, developers can work locally and still be part of the CMS. That means they can use the tools they know and like, and they are not working on an island. The best way to make a developer love the CMS is to let them work with the CMS without having to work _in_ the CMS. Organizations that want to win, need to innovate without impedance.


Today’s CMS systems are rooted in 20-year-old architectures and technologies. As the demand for greater amounts of innovation and digital experience has grown and organizations are under pressure to deliver more at ever increasing rates CMS platforms have become more of a hindrance than a help. Crafter CMS, with its Git-based approach, not only solves these fundamental problems but also integrates very well with developer process and tools that innovation moves even faster. Finally, a CMS approach that accelerates development instead of blocking it.

Stay tuned for our next blog entry to learn another major reason why you should use a Git-based CMS!

Five Reasons Why You Should Use a Git-based CMS (Part 1 of 5)

Crafter CMS is a revolutionary open source digital experience platform based on Git. Crafter CMS solves problems from scalability and performance to ease of innovation that has existed in the CMS space for more than 20 years. What makes Crafter CMS so unique is its technical approach and underlying architecture. From its repository layer to its content delivery technology, Crafter CMS is designed to handle today’s most difficult content management challenges associated with creating and managing omnichannel digital experiences.

While there are many architectural advantages of Crafter CMS, in this series we will focus your attention on Crafter’s underlying repository technology: Git. Crafter CMS is the first and only enterprise-class CMS based on Git. We’ve based our CMS on Git for many reasons, and throughout this series, we’ll explore five of the most important.

Reason #1: Event-based multi-object versioning

Traditional CMS platforms like Drupal, WordPress, Adobe Experience Manager, Sitecore, and most others either have severely limited versioning or provide basic versioning capabilities that track single object graphs or maintain clunky data structures to track relationships.

Figure 1: Single file versioning model. Each object has its own version tree. How and whether relationships are tracked between objects differ from one system to the next.

Such simplistic approaches work for basic content management needs like blogs or boring websites but largely fall down in the face of managing today’s multi-object, multi-asset digital experiences. Today’s content models are component-based, and they have many relationships and dependencies. Further, there is often a relationship between the content and the code (CSS, Javascript, templates, etc.) that needs to be considered. Tracking the edits of any one specific object in isolation is simply not enough.

While simple object versioning does support basic editing, simple review, and basic reversion, these use cases are only the tip of the iceberg in a real-world environment. Scenarios like legal audits, company re-branding, and concurrent feature development drive the need for much more sophisticated CMS capabilities like a “time-machine” preview, multi-object reversion and content/codebase branching.

Instead of the single file versioning we see in the CMS space, what’s needed is a multi-object versioning approach like we see in the programming space. We require an approach that tracks “the entire state of the universe on each change.” With this level of version detail, a system can provide real previews at any point in time, make intelligent decisions about what must be reverted and support a host of branching and workflow needs.

Figure 2: Multi-object (“striped”) versioning model. Each event tracks the state of the entire repository at the time of the event.  

This type of solution already exists in the enterprise software development space. With software, one source file is often related to many others. Versions between objects matter. Modern Source Code Management (SCM) has evolved to support this need. Git is today’s most popular and widely used source code management system. It’s clear that the content and technical components of today’s digital experiences share many of the same needs that we see in the software development space. Rather than re-invent Git to achieve the same versioning capabilities in the context of content management, we’ve based Crafter CMS on Git’s versioning mechanics.

Because Crafter CMS is based on Git, every content change event is tracked with an event ID known as a “Commit ID.” Using this ID, it is possible to know the state of every content object in the system at the time of the event. For the sake of simplicity, we can say that we’ve created a version “stripe” across the entire repository at a given moment in time. The system does not make a copy of every object on every edit. That would be too slow and cost too much in terms of storage. Instead, this is done in a very efficient and effective manner by leveraging Git’s own proven versioning mechanics.

Moreover, because of the way Git stores and manages versions, traversals to any point in time are extremely fast. Performance is very important when it comes to the types of use cases we discussed earlier. Let’s take, for example, an auditing scenario: legal needs to see what the site looked like 46 days, 2 hours and 42 minutes ago. With most CMS platforms, this scenario is impossible to support. At best a systems group can attempt to restore a backup from that date and staff can be diverted to give the lawyers what they need. Even if your CMS claims to support this kind of review, the speed at which it can be provided is of key importance. If it’s too slow it won’t be practical. I’ve seen demos of CMS platforms that take minutes to render a previous version of a dynamic site. That’s too slow when you are doing a triage. It’s worse if you are traversing for editorial reasons. Crafter CMS simply doesn’t have this issue. Because of the way Git stores versions, traversal of versions n our Git-based CMS is extremely fast.

Finally, Crafter’s Git-based versioning approach itself hints at another important and related characteristic of Crafter CMS: content is managed in a document-oriented, file-based store. In short, content is stored as XML. Git is a file-based versioning system. Storing content as files are not only necessary, but the file-based approach has several major advantages. Because we’re dealing with files, content is easy to move among environments (Dev, QA, Prod, etc.) and migrate between systems. It’s much easier to integrate the content with other 3rd party systems, such as for language translation, e-commerce, and marketing automation. And because we store content in an XML format, it’s multi-byte character set friendly and totally extensible.


Most CMS’s lack the sophisticated versioning mechanics that are needed by today’s multi-disciplinary teams who are creating modern digital experiences. Today’s sophisticated digital experiences call for a much richer set of versioning mechanics similar to those we see in the software development space with Source Code Management Systems (SCMS.)  Git is today’s most powerful and popular SCMS. Because it’s based on Git, Crafter CMS is able to deliver the versioning needs for today’s most sophisticated needs and use cases.

Stay tuned for our next blog entry to learn more reasons why you should use a Git-based CMS!

Working with url interceptor/servlet filters in Crafter CMS

A filter in Crafter is a Groovy-based controller that allows you to intercept inbound requests for content and API responses and dynamically apply rules, modify the request or transform the response.  A Crafter Filter has the same interface and mechanics as a Java J2EE Servlet Filter.  Some examples of filter use are:

  • Apply security rules: Check for SAML2, Site Minder or other security tokens before allowing the request to proceed.
  • Active Record: Example: before serving the requested resource, look up and load the user’s profile into the request so it is available to all components of the system.
  • Apply compression: Gzip all of the data returned by the requested resource (page, API, etc)

In this article, we’ll learn the specific mechanics of creating and configuring a filter in Crafter CMS.

Step 1: Create the controller

Let’s start simple.  We’ll create a controller that prints a message before processing the request (or subsequent filters in the chain) and a message after control is returned to the filter.

Here’s the code."Handling the request")

filterChain.doFilter(request, response)"Control returned to filter/controller")

Yep, that’s it!  It’s that simple. The key is that you can put code before and after doFilter.  That code can do just about anything.  Typically it’s actions like inspecting the request and making decisions, modifying the request for further downstream processing wrapping the response object.

Step 2: Install the filter in the CMS

Now let’s install the controller into the CMS/project.  With developer or user role your CMS sidebar should contain a folder called scripts:

2.1:  Right-click on the scripts folder and click “Create Folder.”  Enter “filters” as the folder name.

2.2: Right-click on the new filters folder and click “Create Controller”  Enter “MyFilter” as the name and click “Create”

2.3 Add the code from above and click “Update.”

At this point, you should see your filter in the Sidebar and we’re ready to configure it to run when a user requests a resource.


Step 3: Configure the filter to execute

Now we need to tell the filter which resources to execute for by configuring the order of execution, the URL resource patterns it should execute on and the request method types that it should apply to.  To do this we modify the Crafter Engine /Config/site.xml

3.1 Add the following filters tags to your site.xml.  This will run your filter on every kind of request for all URLs.

<?xml version="1.0" encoding="UTF-8"?>

Once the Engine config is updated we have to tell Crafter Engine to reload it. To do this execute this simple API: http://localhost:8080/studio/preview/#/?page=/api/1/site/context/rebuild.json

Step 4: Test

Since our simple example prints messages into the log, you will need to “watch” your log files. The log is located at INSTALL_DIRECTORY/logs/tomcat/catalina.out.

4.1: In the console, watch the logs by printing it out in as it is appended:

tail -f ./logs/tomcat/catalina.out

4.2: Simply reload a page: http://localhost:8080/studio/preview/#/?page=/

4.3: You should see your log entries in the log file every time you view a page or access any other resource.

Create Spring Beans in Your Site with Crafter CMS

Crafter CMS supports scripting in Groovy.  It’s awesome.  It’s lightweight. It’s fast. It’s easy.  That said when solutions start to become more sophisticated developers need ways to manage the complexity.  Spring bean factory is an inversion of control implementation that has become a standard for wiring components of a system together.  Crafter CMS lets you create classes in Groovy and wire them together as spring beans that can be used by other scripts in the system.

Step 1: Create your classes

Put your classes under scripts/classes/groovy
I.E., scripts/classes/groovy/mysite/AddressBook.groovy

Note: In older versions of Crafter (2.5.x) The path for classes is outside of the scripts folder.  For these older versions, the path is: classes/groovy/YOUR_PACKAGE/YOUR_CLASS.groovy

package mysite

import java.util.Map

public class AddressBook {

   def addresses  // map
   def label

   public int getAddressCount() {
      return addresses.size() 

Step 2: Wire your Spring beans

Place your Spring bean configuration at the following path:


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""

  <bean id="myAddressStoreMap" class="java.util.HashMap">
  <bean id="myAddressBook" class="fastenal.AddressBook">
    <property name="label" value="Russ's Address Book" />
    <property name="addresses">
      <ref bean="myAddressStoreMap" /> 

Step 3: In a Controller, get a hold of the bean and use it

templateModel.addressBook = applicationContext.get("myAddressBook")

Step 3.a Show the count in a template

<h1>Address Book: ${addressBook.label}</h1>
<h2>Entries: ${addressBook.addressCount}</h2>

Match Highlighting for Search in Crafter CMS

Highlighting search terms in search results is a common requirement for many websites.  Crafter CMS builds on top of Apache Solr and make implementing rich search and other query-driven experiences super simple.

In this tutorial, we’ll create a simple article search backend that highlights the search terms that were used within the results returned to the user.

Step 0: Prerequisites

If you haven’t gotten Crafter CMS set up and built your first site you can follow this tutorial to get started: Working with Your First Crafter CMS Web site.

Step 1: Build a content model for articles

The next thing we need is content to query against.  The first step in supporting content creation is defining the Content Type.  The Content type is the definition of the structure of a particular type of content.  In our example, we want to define the structure of an Article.

A simple article should have:

  • A Url
  • A title
  • An author name
  • A body

To define this we use Crafter’s Content Type management console:  Below you can see the example model including the fields and their types.

You can learn more about content modeling here Content Modeling in Crafter CMS.

Step 2: Create content

Now that you have your article content type defined you can create articles.  To create an article open the pages folder (we modeled the article as a page with a URL) in the sidebar and right click on the home page:

Step 3: Create a REST script to return highlighted results

Now that you have content you can write a RESTful controller and test it.  Let’s create a simple GET based REST controller.

  1. Open the Sidebar and locate the Scripts folder.
  2. Open the Scripts folder and navigate to “rest” folder.
  3. Right click on it and choose “Create Controler
  4. In the script name dialog, enter “search.get” and click Create.
  5. Enter the following code:
// build a query
def keyword = params.q 
def queryStatement = "content-type:\"/page/article\" " 
 if(keyword) {
      queryStatement += " AND $keyword"
 def query = searchService.createQuery()
 query.addParam("hl", "true")
 query.addParam("hl.fl", "body_html")
 query.addParam("hl.simple.pre", "<b>")
 query.addParam("", "</b>")
 // execute the query
 def executedQuery =

def matches = [:]
matches.found = executedQuery.response.numFound
matches.articles = executedQuery.response.documents
matches.highlights = executedQuery.highlighting

return matches

Step 4: Execute the Script

In a browser, go to http://SERVER:PORT/api/search.json?q=AWORDTHATEXISTSINRESULTS

example: http://localhost:8080/api/search.json?q=bacon