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.

CONCLUSION

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.

Conclusion

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.

Conclusion

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!

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:

config/spring/application-context.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">


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

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>

Work Your Own Way with Crafter CMS (Series Part 1): Step-through Debugging

Most CMS platforms do a decent job of simplifying content and digital experience creation and editing for non-technical content managers.  The challenges really start once you need to innovate and development is required.  Traditionally CMS platforms have been pretty bad for developers.  They require a lot of CMS specific knowledge and don’t integrate with developer tools and process.
Here are 7 things that developers really want with a CMS:

  1. Let me work locally with my own tools like my IDE and my source code management
  2. Let me leverage my existing skills.  I want a low learning curve. Don’t make me learn a new, niche framework
  3. Let me work in teams on multiple projects at the same time without interfering
  4. Let me maintain a real development process
  5. Make the integration with the CMS seamless
  6. Don’t make me do builds
  7. Don’t make me do heavy deployments

In this installment of the Work Your Way Series we’re going to tackle item #1 (Let me work locally with my own tools like my IDE and my source code management.)   Let’s start with some background: Crafter CMS uses Git as its primary content store.  That’s the foundation of the solution for developer desire #1. A developer can mount a local clone of a Crafter CMS project directly with their IntelliJ, Netbeans, Eclipse or other IDE.  That means they can use their preferred development tools to edit and debug code and templates.  And as they work, all of the changes they make are tracked by the Crafter CMS via its native Git support.  Sounds awesome right?  Let’s learn how to get set up:

Step 1: Get a local copy of Crafter CMS running

You are going to use your IDE to update and debug your code and templates.  You’ll want a local instance of Crafter CMS running so you to execute the code and attach your debugger to.

To install and get Crafter CMS running (authoring environment) locally follow this guide:
http://docs.craftercms.org/en/3.0/getting-started/quick-start-guide.html

Step 2: Start a Crafter CMS project

Now that Crafter CMS is up and running let’s create a project so we have a place to work.  We’ll create a local project for the sake of this article, however, as we’ll learn later in this series, it’s possible to clone a remotely managed project as well.

To create your CMS project follow this guide:
http://docs.craftercms.org/en/3.0/getting-started/your-first-website.html

Step 3: Mount your IDE on top of your Crafter CMS project

For this article, I’m going to use IntelliJ.  Any IDE that allows you to connect to a remote JVM via Java Debug Wire Protocol (JDWP) should work.  Eclipse and Netbeans are other solid IDE options.

  1. Within IntelliJ, create a new project:

  • Select Create New Project

 

  • Choose Groovy

  • A: Configure your project name to something you like
  • B: Browse to the Git repo “Sandbox” under your “CRAFTER-INSTALL/data/repos/sites/PROJECTID/sandbox”
  • C: Change the module name from Sandbox to your project name

 

  • Once your project is created, open it to see all the files.  IntelliJ automatically recognizes you are sitting on top of a Git repo and will allow you to do Git operations right from the IDE.
  • Note that a Groovy project creates an “src” folder.  You can delete this.  You don’t need it.

  • Right click on your model and add a new file called “.gitignore”
  • Do not add this file to Git when prompted.

The contents of the .gitingore file should be as follows:

*.iml
.gitignore
.idea/*
  • This will tell Git and Crafter CMS to ignore your IDE project files

  • If you were to run a “git status” command in your project sandbox you would note that Git is totally satisfied and ready to rock 🙂

 

Step 4: Set up step-through debugging

Great, now that we’ve got our IDE sitting on top of our project and we’ve got the Git integration configured we’re ready to set up the step through-debugging.

  • Shut down Crafter CMS
  • Add the following lines to CRAFTER-INSTALL/bin/apache-tomcat/bin/setenv.sh (or setenv.bat)
    • Syntax in .bat will be slighly different

export CATALINA_OPTS="$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,address=localhost:8000,server=y,suspend=n"
  • Start Crafter CMS

Back in our IDE we can now configure and start our remote debugging session!

  • Go to “Run” and select “Debug”

  • Since this is a new project we’ve got to configure our debugging connection.  The next time you click Debug you’ll just select the existing configuration and click Run.

  • Click the + (plus) icon to create a new configuration
  • Select “Remote”

  • Give the debug configuration a name
  • Change the port from 5005 to 8000 (to match the value in setenv.sh)
  • Click “Apply” to accept the changes
  • Click “Run” to attach to the JVM running Crafter CMS

  • Congrats! If your JVM configuration is correct and your ports match in the debug config when you click “Run” you’ll see the “Connected” message in the console as shown above.

Step 5: Start debugging

Now that we’re connected we can start stepping through code in our Groovy Scripts.

  • Open the “Scripts” folder in your project
  • Browse down through classes, org, craftercms, sites, editorial and open SearchHelper.groovy
  • Set a breakpoint at line 56.  This method is used by the Home Page controller of the editorial website we created in step 2.
  • In a browser, open the Crafter CMS preview for the homepage of the website we created

  • When you load the homepage in Crafter Studio the rendering will pause

  • IntelliJ’s window will typically come to the foreground automatically.
  • The thread has been paused and the IDE is now in control of the thread execution.
  • You can now use the step-through debugging tools in the IDE to walk through the code.

Step 6: Magic

Found a bug?  Here’s where things get really fun.  We’re about to see the benefit of bringing Git, Groovy and your IDE together in one place.  Fixing the bug and sharing that fix with the rest of your team is a breeze:

  1. Once you understand the bug and you know what code you want to change, click Play to let the thread complete.
  2. Using the IDE, fix the Groovy code.
  3. Simply refresh the browser again to test.  Step through and verify things are working.
  4. Using the IDE to interface with Git, commit the code and push the code forward in your team mates.
  5. Find something fun to do or work on.  You have a lot more time on your hands now that you are working in a truly integrated, no-compile required, easy to code and debug CMS 🙂

 

 

Get the Names of Sites Running in Crafter Engine and Return it them as JSON

From time to time developers want to be able to get a list of tenants on a given Crafter Engine.  A tenant is equivalent to a project in Crafter.  That project may be a website, a content app, a headless content API or any one of 1000 different kinds of digital experience.  Usually, when people want to get a list of the active tenants on a server it’s to assist with some kind of DevOps automation of site creation and management.  In this example, we create a simple RESTful service that returns the list of sites running in Crafter Engine. You can find the API for the Context Manager HERE

Step 1: Create a REST Controller

  • In a Crafter Studio project, Under Scripts/rest right click and click “create controller.”
    • Enter “get-sites.get” as the controller name
  • Add the following code to the controller.
def siteContextManager = applicationContext["crafter.siteContextManager"]
def siteContextList = siteContextManager.listContexts()
def siteNames = []

siteContextList.each { siteContext ->
    def name = siteContext.getSiteName()
    siteNames.add(name)
}

return siteNames

Step 2: Execute the Service

Great Crafter CMS Webinars

Check out these free pre-recorded online events! Learn more about how Crafter CMS is built and where and how to apply it to your projects!

 

Planning a Smart Mobile App Development Strategy

Why Developers Should Care About CMS

As developers, we’ve got a strong handle on how to manage and deploy our code assets.  Yet every one of us, at some point in our application build has said, “What about this text? What about these images? Where do these belong?”  That’s pretty universal.  Nearly every single application today has content in it.  Be it a web app or a native app; it’s full of strings, images, icons, media and other classes of content.

This content doesn’t really belong in our code base — because it’s not code.  These non-code assets make us as developers pretty uneasy.  We know that at some point a business user is going to ask us to make a change to one of those strings and we’re going to spend hours of build and deploy cycles to handle a 30-second code change.  We know that at some point we’re going to need to translate that content.  We know at some point we’re going to replace this UI with another one.   We know all these things  — and we know leaving that content, even if it’s abstracted into a string table or a resource bundle is going to come back to haunt us; no matter the abstraction: it’s part of the build, developers need to update it.  Developers and Systems folks need to deploy it.  

Smart developers separate code from content.  They make sure that the content in the application is completely independent of the build and deploy cycle of the application itself.  Where appropriate they make sure non-technical business users and have access to the externalized content and can update it and publish changes at any time.

Consider the following scenario:  Your application is for an insurance company.  Along comes major regulation change.  Now your (and every other application) needs to change its language accordingly.  If the content was separate from the application the response time and cost to make changes is minimal.  It’s business as usual.  If the content is not separate you are looking at months of builds, testing and deployment that costs time, opportunity and a tremendous amount of money,

What we’re really talking about is application architecture.  Making the right decisions has significant impacts on our development teams and process and as we’ve illustrated, our organization’s responsiveness and bottom lines.

Solving the Content Problem Through Application Architecture

This problem is very similar to another problem:  Websites.  Waaaaaaaaaaaaay back in the 1990’s people built and maintained entire websites in HTML by hand.  You had to be a programmer who understood the markup and how to update it and ultimately deploy it to a server once complete.  This model didn’t work. Once business started using the web to communicate to the masses marketing departments started getting involved.  Marketers wanted constant updates. Developers wanted to write code, not update copy.  They needed a solution.  The Web Content Management System (WCM for short) was born.  WCM offered a new architectural solution to manage websites. WCM allowed the developers to put the code into templates that contained placeholders for the content and gave authors a user interface to manage and edit the content at any time.  The content is managed separately from the code (the templates) and the two are brought together to create the final product. Everyone wins.

We need the same capabilities that WCM provides but for our applications.

Why Not Use a Traditional CMS?!

Simple.  Traditional CMS platforms have the wrong underlying design. Most CMS platforms were built or are based on the same design as CMS’s that were built 20 years ago.

  • They were built to manage pages:  Most CMSs do not have a generic concept of what content is.   These systems were built to manage pages.  You might be able to contort the system to get what you want from it but it will be a hack. You need a CMS that is agnostic to the kind or type of content you need to manage.
  • They rely on the wrong type of data tier: RDBMS/SQL databases were the primary backends for data regardless of the problem and open source options like MySQL were readily available.  You need a CMS that leverages a data tier that is more distributed and flexible.
  • They are built on the wrong technology: Many CMS platforms are built in PHP.  That’s fine for certain use cases. But frankly, Java has a larger community, more library support and a lot of powerful platforms like Solr, Elastic Search, Hadoop (and many others) that plug into a Java CMS perfectly.  Why run multiple tech stacks to accomplish a single goal?
  • They aren’t secure: Most CMS platforms couple authoring and delivery together in a single database.  That means work in progress (like pending policy updates) is available in the delivery runtime to anyone who finds a way into the database.  That can spell disaster in the event of a hack. Large companies and governments have suffered expensive and dangerous leaks due to this kind of coupled, insecure architecture.
  • They don’t support multi-tenancy: Most of the CMS platforms out there are not multi-tenant.  If you’re going to back apps with a CMS you need a CMS that will let you properly segregate and secure content between apps.  No one wants to do a CMS install PER app.
  • They don’t scale:  RDBMS is hard to scale.  You either cluster or replicate.  Both have serious issues when it comes to really large, global and auto-scale type deployments.  Supporting an app with your CMS will demand scale. Design for scale from the start.
  • They don’t fit into your development tools and process: When most CMS platforms were designed the content authors were the only audience that mattered.  Today it’s different.  Developer tasks like managing templates, CSS, JavaScript, content models and other artifacts need to be just as easy — and it needs to fit in with your existing workflow.  That means Git source code management, Continous Integration (CI), Integration with your IDE, the ability to fork and support multiple teams simultaneously.

If Not Traditional CMS, Then What? A Modern CMS, That’s What!

To get different results you need a different design.  You need a modern CMS:

  1. Built with the right technologies like Java, Spring, Groovy, Solr, Git.  These are the technologies that will be easy to hire for, will fit into and integrate with any enterprise and will have the out of the box capabilities and horsepower to back any scale deployment.
  2. Decoupled architecture that cleanly separates authoring and content delivery responsibilities on to separate, independently highly securable, highly scalable infrastructures by a publishing process.  Decoupled Architectures don’t have work in progress outside the firewall.  They are much easier to scale.
  3. Built on scalable document-oriented data tiers like XML+disk/Git and Casandra and others.  Disk-based tech is much better for streaming rich content and support global distribution better because they don’t need to be clustered.  At a minimum, you want something that’s document oriented and that distributes globally better than a than a SQL backend RDBMS.
  4. Content type agnostic:  From strings to web pages, to videos and virtual reality experiences.  The CMS needs to accept any kind of content.  That comes down to how content is modeled and how it’s stored.  Does the CMS store content in a SQL database or a JCR repo?  Red flag.  Can’t provide Headless Content / APIs AND rendered content?  Another Red Flag.
  5. Is Multi-Tenant. You need to be able to support many customers/apps on a single install. Either you support it or you don’t and today it’s a must!
  6. Supports authors AS WELL AS developers and DevOps. Developers don’t want to work in some clunky CMS.  They want to work locally in an IDE, then be able to work with their team and ultimately go through the entire workflow out to production.  A modern CMS gives them this.
  7. Open Source.  Open is better than closed. The debate is over. Is it a must?  No. But you’ll get more for your money and you’ll get a lot more innovation at a faster rate if you leverage open source.

Where can I find a Modern CMS?!

Check out Crafter CMS!  Crafter CMS is a modern, 100% open source Java based CMS built on Git!  It’s easy for authors, Amazing for developers and Awesome for DevOps!  Crafter doesn’t sit on a SQL database or a JCR repo like so many CMS platforms out there.  It’s built on Git, Java/Spring, and Solr.  It brings the power Git to CMS!  Authors have true versioning.  Developers and DevOps can work they way they are used to, with the tools they are used to based on the technologies they already know.  Crafter CMS is 100% content type agnostic, highly secure, high performance and scales like nothing else.  If you’re building any kind of application or digital experience, you have content, and you NEED Crafter CMS.  Great experiences are crafted!

 

Creating and Installing Project Blueprints in Crafter CMS

What are Blueprints?

Blueprints are Crafter CMS project templates. It provides an initial structure/layout for your site containing one or more of the following: content types such as pages and components as described in Content Modeling, static assets such as images, videos, etc., and site configuration files for managing items in the blueprint such as taxonomies (categories, segments), roles, permissions, etc.

Cook Books - Blueprint AnatomyIn the blueprint that comes out of the box with Crafter CMS, Website_Editorial blueprint, it provides us with an initial structure for our site, along with the site navigation, content inheritance, taxonomies for organizing the content such as categories and segments, which was also used for targeting content, static assets such as the initial images and fonts used for the site and configuration files for managing things like the personas for targeting, the permissions for all the items in the site, the role mappings, the RTE configuration, etc. To see more of the Website Editorial blueprint, please see Your First Website where we create a site based on the Website_Editorial blueprint.

As mentioned earlier, blueprints allows us to generate sites with predefined layouts, contents and configuration. Blueprints could be a site theme or an API only site. New blueprints can be created from a site and added into Crafter CMS allowing the creation of more sites based on the new blueprint. In the section that follows, we will see how the Empty blueprint that comes out of the box from Crafter CMS and an existing site is used to create a new blueprint.

How do I make my own Blueprint?

Start by Installing and Starting Crafter CMS.

Blueprints are almost the same as a site. So, you can use a new site created from the Empty blueprint as the starting point for your blueprint. (See Your First Website but create it from the Empty blueprint).

Adapting an HTML template

If you have an existing pure HTML template (and if you don’t, you can find free ones, even with commercial friendly licenses like MIT and some flavors of Creative Commons), you can adapt it into a blueprint.

Cook Books - Template AnatomyGenerally, pure HTML templates have a file structure similar to the picture above. To start, you’ll want to copy all files except for index.html and any other .html files to your site’s static-assetslike this:

Copy folders to static-assetsHTML files will become Freemarker templates. For this cookbook, you’ll see how to adapt an index.html page, then you’ll be able to adapt other pages. Start by editing the main page’s ftl template, and replacing its contents with the index.html’s contents:

Copy index.html contents to page ftl file.You should keep <#import "/templates/system/common/cstudio-support.ftl" as studio /> at the very start, and add <@studio.toolSupport/> right before the body tag closes to have proper Studio support. Next, all resource locations are probably pointing to the wrong location. To fix this, replace every relative url that doesn’t point to a page (this would include <link rel="stylesheet" href="tags for CSS files, <script src=" for JS files, <img src=" for image files, and <source src=" for video and sound files) such that it starts with /static-assets/ and points to the corresponding file.

Modify the Rich Text Editor configuration so it uses your template’s stylesheets. See Rich Text Editor (RTE) Setup

At this point, you should have a static page that looks just how the template is supposed to look. For every other HTML page, you have to either create a new page content type and, like with index, replace its ftl template with the page’s source; or, generalize the content type, with proper content modeling, such that multiple pages share a single ftl template and vary only in the components they contain. Let’s see some tips for this.

Content Modeling

A powerful and extensible blueprint that can be used in a variety of pages and scenarios needs proper Content Modeling, so you have to be familiar with it before proceeding.

A good blueprint separates each meaningful chunk of HTML code into a component. For example, whether you implement an “Our Team” section using a repeating group or multiple “Teammate” child components, it still has to be a separate type that only contains information related to “Our Team”. Whether it is a Component or a Page, it shouldn’t contain “Product” information. Once you have identified HTML chunks with a meaning, start by moving them into their type’s template.ftl. Next, replace any information with a variable from the contentModel (and add the respective control to the Content Type). Unless they are extremely simple, most pages will contain child components, even if they are just a header and footer component provided by the Section Defaults.

There are some best practices to help you:

  • Prefix all your Content Type’s display label with either “Component – ” or “Page – ” as appropriate.

  • Make use of Section Defaults. Most sites will have a site logo that will be used all throughout the site, this is a perfect use case for Section Defaults.

    • Additionally, since Section Defaults have inheritance mechanics, a child folder that’s meant to have private pages could have it’s own Section Defaults that overrides the normal site logo with a more private looking one, signalling users that they are in the intranet.
    • You can apply this similarly for headers, footers, log in floating forms, and many more.
  • Use drag and drop but keep it to a minimum. At the moment, you can’t limit what kind of components can be dropped into a container, so this enormous amount of flexibility can make for a confusing user experience. Picture having a page with a group of sections, that each contains headers. If both sections and headers are drag and droppable, an user could accidentally drop a section inside another section without noticing instead of just reordering. It could be more comfortable that only sections are drag and droppable.

  • You can use label controls to add additional information to the content type’s form. This is useful to add tips or additional information for advanced controls.

  • Prefer repeating groups over child components. Child components are ultimately more versatile, but if you are only going to repeat text, and that text is not going to appear outside the repeating group again, it’s a better user experience to just use a repeating group.

    • Bear in mind that you can’t have nested repeating groups, so only the innermost repetition can be a repeating group.
  • You can set up folders for specific content types, and you can enforce them by using <paths> in your types’ config.xml. Use includes whenever you want to whitelist some paths, and use excludes to blacklist some paths, but do not mix them. For more examples, see Content Creation Permissions

    <paths>
        <includes> <pattern>REG_EXP_HERE</pattern> </includes>
        OR
        <excludes> <pattern>REG_EXP_HERE</pattern> </excludes>
    </paths>
    
    • You can also use this to enforce single page blueprints by using <excludes> <pattern>^/.*</pattern> </excludes> in your page type’s config.xml, effectively forbidding from creating a new page.
  • Ensure your blueprint supports In-Context Editing.

  • For most sites, you’ll have to override Studio’s default navigation menu tags. You can do this by reading Rendering navigation.

Above all, blueprints should be usable and simple.

Packaging

Suppose {CRAFTER_HOME} is the path to your Crafter installation so that it contains the startup scripts, apache-tomcat/ and data/ folders.

Blueprints reside in {CRAFTER_HOME}/data/repos/global/blueprints since Crafter 3.0. Each folder corresponds to a blueprint (You may notice the empty and website_editorial blueprint folders), you can start by copying the empty folder and renaming it to your blueprint’s name, like “my_blueprint”.

Your site exists in {CRAFTER_HOME}/data/repos/sites/your-site-name. Inside, you’ll notice 2 repos, sandbox and published. Inside of either of them, lie the site’s folders, but since sandbox contains your site as it currently exists in your Studio preview, we’ll be grabbing the files from this one. You need to move this site’s folders into an external folder named as your blueprint, but avoid copying the .git/ folder contained there, as it’s unnecessary for the final distributable package and may even contain sensitive information.

Note

Don’t merge folders, before copying any folder, delete the existing one so any renamed or deleted files don’t persist.

Copy ``scripts/``, ``site/``, ``static-assets/``, ``templates/``In the previous screenshot, we didn’t copy the config/ folder. Why? (Warnings). You can either:

  • Copy the config folder and modify permission-mappings-config.xml and site-config.xml to use {siteName} again as explained in (Warnings)
  • Keep config as is and only copy the files you’ve modified. This will likely include the whole config/studio/content-types/ folder and config/studio/preview-tools/components-config.xml for drag and drop.
  • Keep your blueprint in a VCS which will allow you to compare it against your changes and interactively see when to preserve the old version. This will also help you make any updates when blueprints get updated. You can either use git or a visual diff tool.

Now that you have merged your “site” with the Empty blueprint in the proper way, the resulting folder is ready to be distributed. To install, follow the next steps.

Installing

On Crafter 3.0

  1. Copy your blueprint folder into {CRAFTER_HOME}/data/repos/global/blueprints.

  2. Once you do, commit the change to the global repo ({CRAFTER_HOME}/data/repos/global/) by using git, and your blueprint will now start appearing when you try to create a new site.

    • Crafter 3 uses a vanilla version of Git, so regular git commands work as intended. To commit your changes so Crafter can see it, head to {CRAFTER_HOME}/data/repos/global/blueprints and git add your modified files like this

      git add <filename>
      

      for each filename. Or, to add all at once use:

      git add --all
      
    • And once you are done, commit them with the following command:

      git commit -m "<the commit’s description>"
    • No need to push, there’s no remote configured. You can also use any git client. Now, it will be available when you create a new site.

Using the Blueprint

Once you’ve installed your blueprint using it is simple!

After logging in, you’ll see the MySites screen (Below). Click on Create Site

Your First Website - Sites Screen

Give the site a friendly name for the Site Id , a description and then choose a blueprint. We’re going to be using the “Website_Editorial” blueprint. Blueprints offer you a starting point for your website. New blueprints can be created and installed in to the system. As you are entering the site id, spaces are removed and upper case letters are converted to lower case letters.

Your First Website - Create a Site

Click on Create and wait for the system to create your site based on the blueprint. It’s creating the following: configuration, site content, and permissions based on the template provided by the blueprint.

Your First Website - Creating a Site Spinner Dialog

When it’s done you will be taken to the Home Page of your site:

Your First Website - Home Page

Start an Activiti Process via Rest Script in Crafter CMS

Activiti is a powerful open source workflow engine built by Alfresco.  Incorporating a workflow engine into your customer and employee facing sites and portals is an excellent solution for automating complex workflows that cross system boundaries while providing the user with a simple to use, contextual user experience.   Working for a bank or an insurance company and need to workflow contracts with customers?  No problem. Crafter CMS (an open source Java based CMS) paired with Alfresco is a perfect solution.  It’s customer friendly, highly scalable and about as powerful as enterprise technology gets!

In this blog, I’ll demonstrate the most straightforward example of a Crafter CMS REST service being used to start an Activiti Process.

Prerequisites

  • You have Activiti (http://www.activiti.org/) installed
    NOTE:
    The authentication and process are hard coded to simplify the example

Step 1: Create a REST Controller

  • Under Scripts/rest right click and click create controller
    • Enter start-process.get as the controller name
  • Add the following code to the controller. This code assumes Activiti is deployed into the same container as Crafter Engine.
@Grab('org.codehaus.groovy.modules.http-builder:http-builder:0.7')
@Grab('oauth.signpost:signpost-core:1.2.1.2')
@Grab('oauth.signpost:signpost-commonshttp4:1.2.1.2')

import groovyx.net.http.HTTPBuilder
import groovyx.net.http.ContentType
import groovyx.net.http.Method
import groovyx.net.http.RESTClient

def http = new HTTPBuilder("http://localhost:8080")
def user = "kermit"
def password = "kermit"
def authPair = user + ":" + password
def authEncoded = authPair.bytes.encodeBase64().toString()

http.setHeaders([Authorization: "Basic "+authEncoded])

def ret = null

http.request( Method.POST ) {
    uri.path = "/activiti-rest/service/runtime/process-instances"
    // ACTIVITI ENTERPRISE URL
    // uri.path = "/activiti-app/api/enterprise/process-instances"

    requestContentType = ContentType.JSON
    body =  [ processDefinitionKey: "vacationRequest", variables:[  [name:"employeeName", value: "Russ"], [name:"numberOfDays", value: "5"],[name:"startDate", value:"10-08-2015 11:11"],[name:"vacationMotivation", value: "rest"]    ]]

    response.success = { resp, reader ->
        ret = reader
    }
}

return ret

Step 2: Execute the Service

Step 3: Verify that a new process instance has been started