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!

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.

 logger.info("Handling the request")

filterChain.doFilter(request, response)

logger.info("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"?>
<site>
    <filters>
        <filter>
            <script>/scripts/filters/MyFilter.groovy</script>
            <mapping>
                <include>/**</include>
            </mapping>
        </filter>
    </filters>
</site>

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:

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>

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.setQuery(queryStatement)
 query.addParam("hl", "true")
 query.addParam("hl.fl", "body_html")
 query.addParam("hl.simple.pre", "<b>")
 query.addParam("hl.simple.post", "</b>")
 
 // execute the query
 def executedQuery = searchService.search(query)

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

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

Working with Content as XML/DOM in Crafter CMS

In a previous article (Querying Content in Crafter CMS) we talked about how you can query content in Crafter using content and search services. Under the hood, Crafter CMS saves all of the content you create through the authoring interface (Crafter Studio) as XML.  This XML is published from Crafter Studio to dynamic delivery engines (Crafter Engine) and is available through the content services and is also indexed in Solr and thus available through Crafter’s search services.  There are times in the rendering engine (Crafter Engine) when you may want to get access to values in the XML directly and work with the content as an XML Document Object Model (DOM) API.

In the example below I will show you how you can:

  1. Load a content object
  2. Get access to its DOM
  3. Query for DOM elements within the parent object
  4. Process the results

To illustrate this let’s imagine that we have a use case where content authors need to manage values like CEO name or Number of Offices throughout a site that might change.  They want to pepper these values throughout the site but want to update them quickly from a single place.    To do this we would use a macro/placeholder type approach in the content where the author would enter content with macro/placeholder in the place where the value should go.

Example:

Acme Anvil Co has [Office_count] offices throughout the world.

To manage the Macro/Value pairs we’ll give the authors a content type:

Once you have your macro type defined you can create a content object based on that type:

Now that we have created an author managed list of macros and their corresponding values.  Let’s create a basic controller (some assumptions to keep things simple) to process the content in a component and replace the macros found in the content with the value.

Controller example:

// Load the content object containing the macros key values
def macroItem = siteItemService.getSiteItem("/site/components/5ef8d326-3e85-9f67-e8d6-47fb5dfba21d.xml")

// Get the unprocessed content
// Here we'll put some assumptions in the code.  In reality you may want 
// to process all the content fields in the content.
def content = contentModel.queryValue("content_html")
def contentUpdate = content
// Query the macros and iterate over them performing the replace. 
// this is where we get the DOM and leverage the DOM API
def macros = macroItem.getDom().selectNodes("//item")
macros.each { pair ->
 def macro = pair.valueOf("./macro")
 def value = pair.valueOf("./value")
 contentUpdate = contentUpdate.replace("["+macro+"]", value)
}

// Make the processed content available to the template
templateModel.content_html = contentUpdate

 

You can easily tie this controller into any template by adding it to the top of the template:

<@controller path="/scripts/controllers/macro-controller.groovy" />

Most of the time with Crafter CMS, there is no reason to access the DOM directly.  From time to time you may find it more convenient or necessary.  Now you know how!

Working with Your First Crafter CMS Website

This article assumes that you have followed the steps in the Cafter CMS Quick Start Guide to get Crafter CMS installed and logged in to Crafter Studio. We will be using an out-of-the-box blueprint, called “Website_Editorial” to create your first website.

Let’s get started building your first website!

Creating your website from out of the box blueprint Website_Editorial

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

Your First Website - Sites ScreenGive 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 into 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 SiteClick 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 DialogWhen it’s done you will be taken to the Home Page of your site: (need to update image below)

Your First Website - Home PageYour site is setup, we can now start adding/editing content! To edit content you see on the page, click on Edit at the top (see above). This will open a form (see below) where you can edit the page content. To see other ways of editing page content, see Editing a Page.

Your First Website - Editing Content

Adding a new article page to the site

We’ll be adding a new article to the site. To add a new article (or a new page), navigate to the level and location within the site navigation tree in the Sidebar where we want to create the new page. In this case, we are adding an article under articles -> 2017 -> 3. Right click, then select New Content (need to update image below)

Your First Website - New ContentWe’ll then select the page template we want. Since we are adding a new article to the site, we will be selecting the template Page – Article

Your First Website - Select Page TemplateWe’ll start filling out the form for our new article, “Where to find cherry blossoms in Virginia”. For the Page URL, replace spaces with dashes. You can write the Internal Name and Title however you like as long as it is 50 characters or less as indicated on the right of the input boxes. For the Headerand Sidebar, we will be using the default provided by the template.

Your First Website - Page PropertiesThe next section on the form is the Metadata section, where we can select the category for our article, the targeted segments of the article and whether our new article should be added to the Featured section. Our new article, will be under Entertainment for the Categories and the targeted segments is Gal. We will also be placing our new article in the Featured section.

Your First Website - Page Metadata SectionFinally, we add our blurb in the Content section of the form. Here, we fill out the SubjectAuthorDateSummaryImage and Section, which contains the content of our article.

Your First Website - Page Content SectionHere’s the site, with our newly created article in the featured section.

Your First Website - Newly Created Site Home PageYou can add more pages or modify/remove the existing pages from the blueprint, depending on your needs. To remove or edit an existing page, navigate to the location of the article you want to edit/remove. Right click on it, then select the action you would like to do on the page.

Your First Website - Edit a Page

Updating the Contact Us section in the sidebar

Another thing that we may want to modify from the blueprint, is the left rail. For this example, we are going to modify the Contact Us section in the left rail (contact widget). To edit items in the sidebar, click on the pencil on the top right of your screen to enable in-context editing. Pencils should appear on sections editable on the page. Go to the top left of the left rail and click on the pencil there.

Your First Website - Edit the Left RailA form with all the editable content of the left rail will appear. Go to the Widgets section of the form, select Contact Widget and then click on the Edit button on the right of the list of widgets.

Your First Website - Left Rail FormA form containing all the editable fields in the Contact Us section will appear. Modify the fields that you want to change.

Your First Website - Contact WidgetHere’s the sidebar with the Contact Us section updated.

Your First Website - Updated Contact Us Section

Editing the features section, “Erat lacinia”

We will now edit the features section in our blueprint. The features in this section has been configured as components, as you will see in the images below. There are multiple ways of editing the features section in the blueprint.

Your First Website - Add Features through Drag and DropWe’ll start out by adding a feature using the pencil at the top of the features section (In the image above, we will use the pencil captioned “Edit the whole features section”). Click on the pencil at the top of the features section. A form will open containing the content of the section. As you can see in the image below, there are currently two features in the section.

Your First Website - Edit by Clicking on the PencilIn this form, you can add another feature, by clicking on the Add button, which will give you a menu to Create New – Features or Browse for Existing – features

We will add a feature by selecting Create New – Features as seen on the image above. This will open a form, where we will now enter our content.

Your First Website - New FeatureYour First Website - New Feature AddedWe will now add another feature, by selecting Browse for Existing – Features, after clicking on the Add button. This will bring up a form containing a list of existing features in the blueprint. Select one, then click on Add & Close or, click on the radio button of your selection, then click on Add Selection. This will add your selected existing feature to the features section of the page.

Your First Website - Browse for Existing Features ComponentWe will again add another feature, this time by opening the Preview Tools panel, and then clicking on Page Components. A Components panel will open where the Preview Tools panel used to be, containing components that you can drag and drop onto the drop zone highlighted on the page. To click and drag a new feature onto the drop zone, click and drag Feature, under the general heading. This will then open up a form for you to add your new feature content. To click and drag an existing feature onto the drop zone, click on Browse Features. This will then open up a form containing a list of existing features that you may choose from. Make your selection, the form with the list will then close and now you can drag and drop your selected existing feature onto the drop zone.

Your First Website - Drag and Drop ZoneFrom inside the drop zone, you may also re-arrange the features by clicking and dragging on a feature and placing it in your desired position. Notice the positioning of the newly added feature and the existing features, which have been re-arranged compared to the previous image. To delete/remove a feature from the drop zone, just click on the X as show in the image below.

Your First Website - Drag and DropTo edit a feature, select a feature from the list and click on the Edit button on the right of the list. Edit the fields you would like to modify, then click on Save and Close or Save Draft to save your changes or click on Cancel to discard all changes in the form. You can also edit a feature by clicking on the pencil next to the feature when In-Context Editing is enabled.

Your First Website - Edit FeatureTo remove a feature, select a feature from the list and click on the X button on the right of the list. Or, from the drag and drop zone when you click on “Page Components” in the Preview Tools panel, click on the X next to the feature.

Your First Website - Remove Feature

Publishing Your New/Edited Page

Your site is published after creating the site from the Website_Editorial blueprint. If you make edits to any of the pages or created new pages, it will need to be published for your site visitors to see the changes. There are a couple of ways to publish your page edits. The first thing you need to do is to navigate to the page you want to publish in the Site Navigation Tree (Enabled by clicking on Sidebar on the right of the Crafter CMS logo on the upper left hand corner of Studio). After navigating to the page you want to publish, there are two ways to publish:

  • Click on the page you want to publish. In the context menu, click on Approve & Publish
  • Right click on the page you want to publish from the Site Navigation Tree, then click on Approve & Publish

Your First Website - Publish Your New ContentYou will then prompted whether you want to publish the page now (Items should go live now), or publish the page at a later date and time (Items go live on a specific date & time).

Your First Website - Publish OptionsFor more information on content authoring, please see the documentation section: Content Authoring