BrowserCMS Code Snippets

Andrew Zelenets edited this page Nov 4, 2013 · 11 revisions
Clone this wiki locally

This page is meant to just be a collection of issues we've run into whilst developing on bcms and some snippets / tips of how to get around these until future releases address them.

Using Ckeditor and Updating Styles

BCMS 3.5.x+ (aka using the asset pipeline)

First, add in a file into your /app/assets/javascripts folder, and name it whatever you want, something like ckeditor_custom_config.js. Then add the code below to get started.

// This is a custom configuration file that will be used by BrowserCMS to load instances of 
// the CKEditor.
// As per http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig using a custom config
// avoids the need to 'mask' the core default config.js file that CKEDITOR comes packaged with.

CKEDITOR.config.toolbar_CMS = [
  ['Source','-','Cut','Copy','Paste','PasteText','PasteFromWord','-','SpellChecker','Scayt','-','Undo','Redo','Find','Replace','RemoveFormat','-','NumberedList','BulletedList','Outdent','Indent','HorizontalRule'],
  '/',
  ['Link','Unlink','Anchor','Image','Table','SpecialChar','-','Bold','Italic','Underline','JustifyLeft','JustifyCenter','JustifyRight','JustifyFull','-','TextColor','Format']
];

CKEDITOR.config.toolbar_CMSForms = [
    ['Source','-','Cut','Copy','Paste','PasteText','PasteFromWord','-','SpellChecker','Scayt','-','Undo','Redo','Find','Replace','RemoveFormat','-','NumberedList','BulletedList','Outdent','Indent','HorizontalRule'],
  '/',
    ['Link','Unlink','Anchor','Image','Table','SpecialChar','Bold','Italic','Underline','JustifyLeft','JustifyCenter','JustifyRight','JustifyFull','TextColor','Styles'],
    '/',
    ['TextField','Select','Checkbox','Radio','Textarea','Button','ImageButton','HiddenField']
];

CKEDITOR.config.width = 598;
CKEDITOR.config.height = 400;
CKEDITOR.config.toolbar = 'CMS';

There are a lot of configurations you can set here, and a lot of settings you can change in the Toolbar as well. The main one configuration you might want to add would be custom CSS: CKEDITOR.config.contentsCss = '/assets/wysiwyg.css';. This is referencing another stylesheet you can add to redfine styles in the WYSIWYG editor if you want to. Obviously, /assets/wysiwyg.css is just an example, you would still need to create this file in your project.

Next, open your /config/application.rb file and add this:

# Determines which ckeditor file will be used to configure all instances.
# There should be at most ONE of these, so use manifest files which require the below one to augement it.
config.cms.ckeditor.configuration_file = "/assets/ckeditor_custom_config.js"

And replace ckeditor_custom_config with whatever you named your file. Lastly, exit out of your app, and run rake tmp:clear to clear out the asset pipeline. Then when you restart your app, the necessary files will have been recreated to point to the correct config file.

Add-in HTML Templates

Adding in templates is pretty much the same as before, first just add this button to your editor settings in ckeditor_custom_config.js by adding 'Templates' to whereever you want this to appear. Then add in the following to your ckeditor_custom_config.js file:

CKEDITOR.config.templates_files = ["/assets/dropdown_templates.js"];

Then create the dropdown_templates.js file (or whatever you want to call it) in your /assets/javascripts folder. You can then use the same content as below, but update path for the images to assets in this case. You don't need to add in this file, Ckeditor has built-in templates if you enable the button.


Pre-BCMS 3.5 (aka non-asset pipeline)

For those sites using ckeditor and a client wants the editor to be styled like the output content on the site, here is what you need to do:

  • First, create a /bcms folder and a /ckeditor folder inside of it. Then create a config.js file inside this folder and add the following to it:
CKEDITOR.config.toolbar_CMS = [
  ['Source','-','Cut','Copy','Paste','PasteText','PasteFromWord','-','-','Undo','Redo','Find','Replace','RemoveFormat','-','NumberedList','BulletedList','-','JustifyLeft','JustifyCenter','JustifyRight','JustifyFull','Outdent','Indent','HorizontalRule'],
  '/',
  ['Link','Unlink','Anchor','-','Image','Table','SpecialChar','-','Format','Bold','Italic','Underline','-','Templates','Maximize','SpellChecker','Scayt']
];

CKEDITOR.config.toolbar_CMSForms = [
    ['Source','-','Cut','Copy','Paste','PasteText','PasteFromWord','-','SpellChecker','Scayt','-','Undo','Redo','Find','Replace','RemoveFormat','-','NumberedList','BulletedList','Outdent','Indent','HorizontalRule'],
  '/',
    ['Link','Unlink','Anchor','Image','Table','SpecialChar','Bold','Italic','Underline','JustifyLeft','JustifyCenter','JustifyRight','JustifyFull','TextColor','Styles'],
    '/',
    ['TextField','Select','Checkbox','Radio','Textarea','Button','ImageButton','HiddenField']
];

CKEDITOR.config.width = 598
CKEDITOR.config.height = 400
CKEDITOR.config.startupOutlineBlocks = true;
CKEDITOR.config.contentsCss = '/stylesheets/wysiwyg.css';
CKEDITOR.config.toolbar = 'CMS'
CKEDITOR.config.templates_files = [ '/javascripts/dropdown_templates.js' ]; 
CKEDITOR.config.tabSpaces = 3;
CKEDITOR.config.fillEmptyBlocks = false;
CKEDITOR.config.templates_replaceContent = false;
  • Next, inside the /stylesheets folder, create a wysiwyg.css file and add in all the styles you'd like to be included in the editor.
  • Finally, if you want to give the client templates for image uploading and captioning, add a file in the folder /javascripts and call it dropdown_templates.js. In here, you can add whatever you like, but here is an example of the syntax:
// Register a templates definition set named "default".
CKEDITOR.addTemplates( 'default',
{
    // The name of sub folder which hold the shortcut preview images of the
    // templates.
    imagesPath : CKEDITOR.getUrl( '/images/' ),

    // The templates definitions.
    templates :
        [
            {
                title: 'Image and Caption - Right',
                image: 'template1-right.gif',
                description: 'One main image with a caption underneath aligned to the right side of the page.',
                html:
                    '<div class="figure-right">' +
                        '<img height="100" alt="" width="100" src="/images/template1.gif" />' +
                        '<p>' +
                        'Type the caption here' +
                        '</p>' +
                    '</div>'
            },
            {
                title: 'Image and Caption - Left',
                image: 'template1-left.gif',
                description: 'One main image with a caption underneath aligned to the right side of the page.',
                html:
                     '<div class="figure">' +
                        '<img height="100" alt="" width="100" src="/images/template1.gif" />' +
                        '<p>' +
                        'Type the caption here' +
                        '</p>' +
                    '</div>'
            }
        ]
});

This should help get the editor to be a lot more similar to what the end content rendered out will be. Of course, it might not look the same due to CSS inheritance based on elements only on the actual site, but it should still suffice for the client needs.

Using Fckeditor and Updating Styles & Templates

After adding bcms_fkceditor to your project, move the /site folder in the /public folder into the /bcms folder. Inside here is a file named customconfig.js; here's where we'll be defining the new files for the new styles and templates. Add the following snippet to this file, and edit the name of the subsequent files to whatever your project is.

FCKConfig.EditorAreaCSS = '/stylesheets/wysiwyg.css';
FCKConfig.StylesXmlPath = '/bcms_config/fckeditor/[project_name]_fckstyles.xml';
FCKConfig.TemplatesXmlPath = '/bcms_config/fckeditor/[project_name]_templates.xml';

Then, in the /bcms_config folder, there should be a /fckeditor folder. In here, there should be one file already: fckstyles.xml. Rename this to whatever you called in the customconfig.js folder. * This is a bug in bcms right now where this has to be changed to override the default Fckeditor styles. Then, add a new file named [project_name]_templates.xml.

In the [project_name]_fckstyles.xml file, you can edit the styles as you see fit. However, adding new elements to be styled is not very easy. So, the easiest way to do this is to add these in via custom templates. Add the following snippet and then edit as you see fit for your project.

<?xml version="1.0" encoding="utf-8" ?>
<Templates imagesBasePath="/images/">
  <Template title="Custom Container" image="template1.gif">
    <Description>Custom container for headline and bulleted copy.</Description>
    <Html>
      <![CDATA[
        <div class="helpful-info cf">
            <h3>Enter A Title</h3>
            <ul>
                <li>Enter Text</li>
            </ul>
            <ul>
                <li>Enter Text</li>
            </ul>
        </div>
      ]]>
    </Html>
  </Template>
  <Template title="Custom Blockquote">
  <Description>A custom blockquote template.</Description>
    <Html>
      <![CDATA[
        <blockquote>
            Enter a blockquote here.
            <p>Enter the cited person/place here.</p>
        </blockquote>
      ]]>
    </Html>
  </Template>
</Templates>

Lastly, you need to edit the 'FCKConfig.ToolbarSets["CMS"]' part of the /bcms/fckeditor/fckconfig.js file. After the last definition 'Style', just add in ,'Templates' and this will enable the templates button in the editor.

NOTE: you can apply these toolbar edits directly in the customconfig.js file. Just copy and paste FCKConfig.ToolbarSets["CMS"] snippet into here, and it should work; saving you one step.