apostrophe-blocks

apostrophe-blocks allows users to alternate one-column and two-column blocks in a single page on an apostrophe-sandbox-powered website. Users may opt to have just a single one-column block, or a single two-column block, or a mix of the two.

But it actually does more than that. As the developer, you may define as many types of blocks as you wish, not just simple one- and two-column blocks. If you can do it in a regular page template, you can do it in a block template.

Installation

I assume you already have a nifty Apostrophe 2 project built with apostrophe-site. The easiest way is to start by cloning the apostrophe-sandbox project.

Add the module to your project:

npm install --save apostrophe-blocks

Configuration

In app.js, you'll need to configure the apostrophe-blocks module, just like the rest of your modules:

    'apostrophe-blocks': {
      types: [
        {
          name: 'one',
          label: 'One Column'
        },
        {
          name: 'two',
          label: 'Two Column'
        }
      ]
    }

Now add an aposBlocks call to one of your page templates:

{{ aposBlocks(page, 'main', [ 'one', 'two' ]) }}

Restart your site and... BOOM! That's it. When editing you can now add blocks as you see fit. Within each block you have the usual area-editing controls, for one area or two side-by-side areas, respectively. You can also re-order the blocks via the drag handle, or remove them.

Creating Your Own Block Templates

OK, you caught me. That's not really everything. You don't want to use my crappy example block templates. (Especially not with that nasty inline style element, am I right?)

So, let's make our own.

First create a views folder for your project's overrides of the blocks module:

mkdir -p lib/modules/apostrophe-blocks/views

Now, in that folder, create one.html and paste in:

{{ aposArea(page, prefix + 'left') }}

Much more exciting, let's create two.html:

<div class="left">
  {{ aposArea(page, prefix + 'left') }}
</div>
<div class="right">
  {{ aposArea(page, prefix + 'right') }}
</div>

See what I did there? Each block template can contain its own calls to aposArea. All you have to do is *always remember to append your own area name to prefix. If you forget to do this, all your blocks will show the same content, and you will be sad.

Also works with Singletons:

{{ aposSingleton(page, prefix + 'marquee', 'slideshow', {}) }}

"Hey, my two columns aren't showing up as columns!" Well no, of course not, I didn't write any CSS for those left and right classes on the wrapper div elements. It's your job to do that in your project's site.less file.

Limitations

Blocks cannot be edited inside the modal dialog boxes for editing blog posts, events, etc. However, you may introduce them in the show.html templates for such things.

Since blocks are inherently very much a WYSIWYG beast, we feel it would not be worth the considerable effort required to make them work in modals.

Changelog

0.5.58: when workflow: true is set globally in app.js and the apostrophe-workflow module is in use, this module now plays along, ensuring that workflow applies to adding, removing, and reordering blocks and that there are no sneaky ways to get your new text approved by changing the block type.