Crafter CMS: Custom Styles in Your RTE

Crafter CMS’s Rich Text Editor (RTE) applies your styles right in line.  There’s no need to save and preview before you can see your changes.  Along with that, administrators want to be able to configure what styles authors can apply.

Each RTE can be configured independently.

To configure your styles, take the following steps:

  1. Go to the Site Config console for your project.

 

To configure the RTE, within the Site Config console, select configuration and choose RTE configuration from the drop-down.

In the specific “setup” for your RTE, add the styleFormats tag with the configuration you require.  Example:

 <styleFormats>
 <![CDATA[
   [{title : 'Bold text', inline : 'b'}, 
    {title : 'Red text', inline : 'span', styles : {color : '#ff0000'}}, 
    {title : 'Red header', block : 'h1', styles : {color : '#ff0000'}}, 
    {title : 'Example 1', inline :'span', classes : 'example1'}, 
    {title : 'Example 2', inline :'span', classes : 'example2'}, 
    {title : 'Image styles'}, 
       {title : 'Circular', selector : 'img', classes : 'img-circ'},
    {title : 'Table styles'}, 
       {title : 'Table row 1', selector : 'tr', classes : 'tablerow1'}]
    ]]>
 </styleFormats>

Note the ability to create categories in the example above.  Taking time to organize the styles for authors is extremely helpful to them.

Now add style select to the toolbar

<toolbarItems1>
 formatselect, styleselect,|,bold,italic,underline,strikethrough,|,sub,sup,charmap,|,outdent,indent,blockquote,|,justifyleft,justifycenter,justifyright,justifyfull,|,bullist,numlist,|,managedImage,link,unlink,anchor,|,edithtml,|,undo,redo
 </toolbarItems1>

Once you save the configuration, open your content and test.  Your updates will be present.

Integrating Crafter CMS with GitLab for Better DevOps

Content authoring and software development are both a major part of producing today’s digital experiences. Unfortunately, development support is not something traditional CMS platforms handle very well at scale. Crafter CMS, a 100% open source CMS platform that includes a Git-based repository designed to handle not only authoring but also DevOps seamlessly.

Many development teams use cloud hosted developer platforms like GitLab to assist with their development process.   Crafter’s Git based CMS supports developers working against remote repositories like GitLab, Github, Bitbucket, and others.

By supporting this kind of architecture, Crafter provides a very simple way to flow code forward from a developer and her team all the way up through the CI/CD process to production.  We also support a very simple way for any developer or any environment to easily update itself with the latest content from production.  DevOps and CMS have never been easy — until now. Crafter CMS’s CODE FORWARD, CONTENT BACK™ process makes this process simple and allows you to leverage awesome platforms like GitLab to support your team with the tools they know and love.

In this article, I’ll show you how to create a new project in GitLab and then start a new project in Crafter CMS in a way that connects to GitLab as an upstream remote repository so that GitLab can be used to support your development process with your CMS related development! 

Create a New Project and Connect it to GitLab

Step 1: Create a Project in GitLab

Figure 1: Create a project in GitLab 

  1. Select Blank Project to create a bare project
  2. Enter your project name
  3. Provide a project description
  4. Choose your security level
  5. Click create site

Once your repository is created you will see a screen similar to the one below.  You want to make note of the Git URL for the site.  You will need this URL in the next step.

Figure 2: New Project in GitLab 

Step 2: Create Your Project In Crafter Studio

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 3: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally, set the Github repository as its upstream remote and pushes the initial project contents to the upstream repository.

Let’s walk through each part of the dialog:

Figure 4: Create Site Dialog in Crafter Studio, populating a bare upstream Git repository.

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called Sweet.com a good ID might be “sweetdotcom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1: https://gitlab.com/russdanner/sweet-dotcom.git
  5. Provide your credentials in Git Remote Repository Username and Password
  6. Choose the option: “Create site based on blueprint then push to  remote bare repository.” This means that Crafter Studio will create a new site based on the blueprint you choose, link the remote repository as an upstream and then once the blueprint is installed in the local Repositories it will be pushed automatically to the upstream remote.
  7. Choose your blueprint. There are several out of the box blueprints provided by default. Choose one of these or one of your own. For our example, we’ll choose Editorial which is the simple Article style website/project template.
  8. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and install the blueprint. Once complete it will connect to the upstream and push the contents of the Sandbox repository to the remote.

Figure 5: Site is created and the contents of the sandbox are automatically pushed to the upstream repository.

Step 3: Check GitLab to Make Sure Your Site is There

Go back to your GitLab project and refresh the screen.  You will see the contents of your CMS project in the repository.

Your project is there!  Now you are ready to set up your entire development process and CI/CD automation.  To learn more about how this is configured check out these blogs:

Creating a Project in Crafter CMS Based on an Existing GitLab Project

Let’s consider for a moment that you’re a new developer joining the team. The topology above is already set up and you just want to get a local environment up and going. Simple. Follow these instructions.

  1. Install Crafter Studio locally (Source build or Binaries bundle)
  2. Login as Admin
  3. Click Create Site
  4. Fill out the Create Site Form as in a similar fashion described in Step 2, except this time you chose the option to create your site based on an existing upstream repository. This can be your team’s branch or your own fork. The exact workflow is up to you.

Conclusion

Platforms like GitLab that support agile development and CI/CD are helping bring best practices to the enterprise with easy to use tools that make implementing these activities simple.

Crafter CMS’s Git-based repository and DevOps integration make it simple to build CMS and content related projects while adhering to DevOps best practices and leveraging today’s best development platforms.

“Code Forward, Content Back” is a trademark of Crafter Software Corporation

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