1 | # apostrophe-blocks
|
2 |
|
3 | `apostrophe-blocks` allows users to alternate one-column and two-column blocks in a single page on an [apostrophe-sandbox](https://github.com/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.
|
4 |
|
5 | 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.
|
6 |
|
7 | ## Installation
|
8 |
|
9 | *I assume you already have a nifty Apostrophe 2 project built with [apostrophe-site](https://github.com/punkave/apostrophe-site). The easiest way is to start by cloning the [apostrophe-sandbox](https://github.com/apostrophe-sandbox) project.*
|
10 |
|
11 | Add the module to your project:
|
12 |
|
13 | npm install --save apostrophe-blocks
|
14 |
|
15 | ## Configuration
|
16 |
|
17 | In `app.js`, you'll need to configure the `apostrophe-blocks` module, just like the rest of your modules:
|
18 |
|
19 | ```javascript
|
20 | 'apostrophe-blocks': {
|
21 | types: [
|
22 | {
|
23 | name: 'one',
|
24 | label: 'One Column'
|
25 | },
|
26 | {
|
27 | name: 'two',
|
28 | label: 'Two Column'
|
29 | }
|
30 | ]
|
31 | }
|
32 | ```
|
33 |
|
34 | Now add an `aposBlocks` call to one of your page templates:
|
35 |
|
36 | {{ aposBlocks(page, 'main', [ 'one', 'two' ]) }}
|
37 |
|
38 | 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.
|
39 |
|
40 | ## Creating Your Own Block Templates
|
41 |
|
42 | 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?)
|
43 |
|
44 | So, let's make our own.
|
45 |
|
46 | First create a `views` folder for your project's overrides of the blocks module:
|
47 |
|
48 | mkdir -p lib/modules/apostrophe-blocks/views
|
49 |
|
50 | Now, in that folder, create `one.html` and paste in:
|
51 |
|
52 | ```twig
|
53 | {{ aposArea(page, prefix + 'left') }}
|
54 | ```
|
55 |
|
56 | Much more exciting, let's create `two.html`:
|
57 |
|
58 | ```twig
|
59 | <div class="left">
|
60 | {{ aposArea(page, prefix + 'left') }}
|
61 | </div>
|
62 | <div class="right">
|
63 | {{ aposArea(page, prefix + 'right') }}
|
64 | </div>
|
65 | ```
|
66 |
|
67 | 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.
|
68 |
|
69 | Also works with Singletons:
|
70 |
|
71 | ```twig
|
72 | {{ aposSingleton(page, prefix + 'marquee', 'slideshow', {}) }}
|
73 | ```
|
74 |
|
75 | "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.
|
76 |
|
77 | ## Limitations
|
78 |
|
79 | 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.
|
80 |
|
81 | 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.
|