Apostrophe Manual
Requirements
Your project must contain the svn trunk version of apostrophePlugin, or version 1.4 stable. The 1.0 stable release of apostrophePlugin is missing necessary supporting features for apostropheBlogPlugin.
The quickest route is to check out the the sandbox project, which includes the blog plugin, in which case you can just install that according to the directions.
Installation
In a new project, creating the database tables for the blog plugin is a natural part of the usual command:
./symfony doctrine:build --all --and-load
Again, the quickest route is to check out the 1.4 stable branch (or the trunk) of the sandbox project, which includes the blog plugin, in which case you can just install that according to the directions. Then you can just do the usual doctrine:build command and you're good to go.
However, the blog plugin can be added to an existing Apostrophe Symfony project. To do so you'll need to add the relevant tables to your database without, of course, overwriting all of your existing data.
Fortunately the apostrophe:migrate task is automatically extended to support this when the blog plugin is present. Make sure you have built your model, form and filter classes and cleared your cache, BACK UP YOUR DATABASE, and then run the apostrophe:migrate task, taking care to specify the correct environment:
./symfony doctrine:build --all-classes ./symfony cc ./symfony apostrophe:migrate --env=dev
This task requires MySQL. If you are not using MySQL, use doctrine:build-sql to generate SQL commands in data/sql/schema.sql and review that file for tables beginning with a_blog.
Adding Permissions For Blog Post Editors
Those who are adding the blog plugin to older Apostrophe projects might not have the blog_admin and blog_author permissions in their sf_guard_permission table, or the corresponding entries in sf_guard_user_group_permission. For security reasons we do NOT automatically add these via the apostrophe:migrate task. However, you can add them after you have performed the above steps by visiting the permissions and groups dashboards while logged in as the superuser. Be sure to create blog_admin and blog_author permissions and add them to your admin and editor groups. To locate the dashboards, log in as the superuser, click on "Users," and then click on "Permissions Dashboard" and "Groups Dashboard" at the left.
Creating Your Engine Pages
You're almost there, but you still need to create "engine pages" where your blog posts and events will be displayed. Although there is a separate back end for editing and managing blog posts, creating and naming the front end pages is up to you.
The distinction between the back end blog administration page and the front end blog engine page can be a bit confusing. However it offers substantial benefits. The back end administration page has many navigational and editing tools that would be overwhelming if we tried to present them in the context of the front end. That's why we use separate pages for this purpose.
To create your front end engine pages for blog posts and upcoming events:
- Navigate to the home page
- Log in as admin
- Click "This Page," then "Add New Page," giving it the name "News" or "Blog" depending on your preference
- When the new page appears, click "This Page," then click the "Gear" icon
- Set "Page Engine" to "Blog"
- Click Save.
Now repeat these steps for the "Events" engine.
Note that if you do not want your blog and events engines pages to be public you can unpublish them via the page settings menu, accessed via the gear. If you anticipate inserting blog post slots into pages but don't want an "actual blog" that presents navigation to access all blog posts, this might be right for your needs.
Posting to the Blog
To post to the blog, click the "Blog" icon at the top of any page. Then click "New Post."
Give your post a title, then start adding slots, exactly as you would if you were creating a regular Apostrophe page. The body of your blog post is a full-fledged Apostrophe "area," so it can contain rich text, slideshows, video and other Apostrophe features.
Blog Post Categories
Notice that blog posts can be organized into categories. This feature is critical because it allows you to insert blog posts on the same subject via blog post slots elsewhere on the site. You can also create additional blog engine pages which are locked to a single category. To lock a blog engine page to a single category, first create the page, then switch it to the blog engine, and then select one or more blog post categories from the category selector that appears.
Blog Post Slots
apostropheBlogPlugin provides two good ways to insert blog posts into your regular pages. You can insert a single blog post with the "Blog Post" slot, or insert multiple recent blog posts with the "Blog Posts" slot.
The "Blog Post" slot invites you to search by title. Since all blog posts must have unique titles this is a very effective way to pick a post.
The "Blog Posts" slot asks how many of the most recent blog posts you wish to display, and also allows you to select specific categories. The use of categories allows you to present relevant content on any page without foreknowledge of what that content will be.
Blog Post Excerpt Options
By default, blog post slots display a short excerpt from the post along with the first image, if any, found in the post. You can adjust this behavior with the following options to the aBlog or aBlogSingle slot:
- maxImages determines the number of images extracted from the blog post. If it is greater than one, the images are presented as a click-to-advance slideshow.
- slideshowOptions can be used to override the behavior of the slideshow, using exactly the same options available to slideshow slots (see ManualDesignersGuide).
- excerptLength determines the maximum word count of the excerpt.
These options are often enough. But you can do more, including displaying the entire blog post as part of a regular CMS page. Read on for more possibilities.
Customizing Blog Post Templates
All blog posts have a blog post template that determines their basic structure. For instance, "out of the box" the blog plugin allows for one-column and two-column blog posts. The two-column posts have a narrow second column which is great for associated images and videos.
You can add additional templates to your project by overriding the aBlog settings in app.yml. Note that you must begin by copying this entire section into app.yml (of course you should merge this under your existing all heading):
all:
aBlog:
templates:
singleColumnTemplate:
name: Single Column
areas: ['blog-body']
twoColumnTemplate:
name: Two Column
areas: ['blog-body', 'blog-sidebar']
comments: false
# add_this: punkave # Username for AddThis -- http://addthis.com
aEvent:
templates:
singleColumnTemplate:
name: Single Column
areas: ['blog-body']
Once you have copied these settings to your own app.yml, you can add additional templates in addition to the one-column and two-column templates, or replace them entirely. The templates you specify will be the choices on the "Template" dropdown when creating a blog post. Please do not remove templates that are already in use for posts on your site. If you need to do that, first add your new templates and change the template setting for each existing post.
Note that you need to specify an array of Apostrophe area names that appear in your templates (the areas setting for each template seen above in this app.yml excerpt). This is used to implement the getText convenience method, which returns just the text of an entire blog post. This is not currently used in the core of the blog plugin but does come in handy in application-level code at times, so we recommend specifying a list of area names for each template.
You can customize the appearance of these templates when the blog post is seen in on the blog engine page, and even change the Apostrophe areas that make up the blog post, by overriding the aBlog/singleColumnTemplate and aBlog/twoColumnTemplate partials. And you can customize the appearance of blog posts when inserted as slots by overriding aBlog/singleColumnTemplate_slot and aBlog/twoColumnTemplate_slot. And you can override the templates for the RSS feed by overriding aBlog/singleColumnTemplate_rss and aBlog/twoColumnTemplate_rss.
Often these options are enough. However, if you are inserting blog posts on pages with different page templates and different amounts of space available, or you wish to use teasers in some cases and full-fledged blog posts in others, you'll want the subtemplate option.
When you insert a blog post slot in a page template like this:
<?php a_slot('blogpost', 'aBlogSingle', array('subtemplate' => 'inMyTemplate')) ?>
The blog plugin will append _inMyTemplate (note the underscore) to the blog post's template name, instead of the usual _slot.
That is, if the blog post is a single column post, _singleColumnTemplate_inMyTemplate.php will be used, and if the blog post is a two column post, _twoColumnTemplate_inMyTemplate.php will be used.
You can also specify subtemplates for specific blog post templates:
<?php a_slot('blogpost', 'aBlogSingle', array('template_options' => array('singleColumnTemplate' => array('subtemplate' => 'inMyTemplate')))) ?>
There are two more ways to change the template used for a blog post. You can simply force the blog slot to use the same template that the blog engine page would use:
<?php a_slot('blogpost', 'aBlogSingle', array('full' => true)) ?>
In this case, _singleColumnTemplate.php is used, exactly as it would be on the engine page.
Note that this won't work well with our out of the box blog templates, which are designed to display wide posts on the blog engine page. But it may work well with your own overrides of those templates.
The last option is to simply force the use of a specific blog post template:
<?php a_slot('blogpost', 'aBlogSingle', array('template' => 'myTemplate') ?>
This forces the use of _myTemplate_slot.php (which still must be in your application level override of the aBlog/templates folder). _slot is still appended because were are simply requiring the blog plugin to act as if this post's template was myTemplate. The usual rules for what comes next still apply.
The template option is often useful if your blog post templates are always designed in such a way that the most important area always has the same name. This is true for our standard blog post templates: the single column template and the two column template both have an area named blog-body, so you can safely substitute the former for the latter if you don't mind giving up the presumably less important information in the second column.
Working With Events
Events are slightly different from blog posts. A blog post is an article, a piece of news or other content that should be published now or on a particular future date. An event, on the other hand, has a fixed start time and end time during which it will take place.
Blog posts are traditionally presented in reverse chronological order (newest first). Events, by contrast, are typically presented in calendar order (today's events first).
apostropheBlogPlugin provides separate back end administration and front end engine pages for events, and separate slots for inserting single events and groups of upcoming events. The same features that are available for blog posts can also be used to customize the appearance and behavior of events.
As with blog posts, you must first create an engine page for events before you can add them to your site. Once you've done that, you can begin adding upcoming events to the system.
When you visit the events engine page, which typically becomes the public-facing "calendar of upcoming events" for your project, you'll see upcoming events sorted by start date and time. Again, this is different from blog posts, which are presented in reverse chronological order.
Users can still navigate to past events using the provided links to browse by year, month and day.
Managing Editing Privileges in the Blog Plugin
By default, those who are members of the editors group will be able to write blog posts, and delete and edit their own posts.
Those who are members of the admin group will be able to edit and delete the blog posts of others, and also determine which editors are permitted to assign which categories to blog posts. Admins can also grant editors the right to edit specific posts written by others.
Under the hood, the blog plugin looks for the same permissions that are used to determine which users are potential webpage editors. That is, if you are a potential webpage editor, you are a potential blog author.
Apostrophe Search and the Blog Plugin
Good news: published blog posts and events are automatically integrated into Apostrophe's sitewide search feature. If you search for something that appears in a post or event, a link to that event will be included in the results.
Adding Blog Comments with Disqus
You may wonder why we didn't implement our own system for commenting on blog posts.
In a nutshell: it's easy to implement comments badly. It's not so easy to authenticate users using their system of choice and filter spam effectively. Third party services like Disqus do it brilliantly for free. So rather than reinvent the wheel we've provided the hooks for you to take advantage of them.
(At a later date we may implement our own comment system, for instance to meet the needs of those who are blogging for an intranet audience where Disqus is not an option. Disqus will probably always be a desirable solution for most.)
We'll be making it easier to add Disqus support without overriding quite so many partials. But it's remarkably easy even now.
Here's how to set up Disqus with the Apostrophe blog plugin:
- Visit Disqus and set up an account.
- On the "Choose Install Instructions" page, click "Universal Code."
- Override the aBlog/showSuccess template at the app level. Copy the existing aBlog/showSuccess, and add the following inside this if ... endif block found at the end:
<?php if($aBlogPost['allow_comments']): ?><?php endif ?>
Should become:
<?php if($aBlogPost['allow_comments']): ?>
<?php include_partial('aBlog/disqus') ?>
<?php endif ?>
We'll be making this easier for you soon by adding an empty aBlog/postFooter partial that you can override as needed.
4. Optionally, in your blog post template overrides (aBlog/singleColumnTemplate and aBlog/twoColumnTemplate, as well as any blog templates you have added), add the #disqus_thread suffix to blog post permalinks so they can display comment counts. Change this:
<h3 class="a-blog-item-title"> <?php echo link_to($a_blog_post->getTitle(), 'a_blog_post', $a_blog_post) ?> </h3>
To this:
<h3 class="a-blog-item-title">
<?php $url = url_for('a_blog_post', $a_blog_post) . '#disqus_comments' ?>
<a href="<?php echo $url ?>"><?php echo $a_blog_post->getTitle() ?></a>
</h3>
5. Paste the "embed code" provided by Disqus into your aBlog/disqus partial (this code is provided on the Disqus site).
6. Provide yourself a convenient way to access the Disqus comment administration page for each blog post by overriding the aBlogAdmin/list_actions partial. This is a Symfony admin generator partial. You can fetch it from your Symfony cache, but we've reproduced it here for your convenience. The new code is the second line. Note that you must replace "YOURDISQUSSHORTCODE" with your disqus short code as provided by Disqus:
<?php echo $helper->linkToNew(array( 'params' => array( ), 'class_suffix' => 'new', 'label' => 'New',)) ?>
<li><?php echo link_to('Comments', 'http://YOURDISQUSSHORTCODE.disqus.com', array('class' => 'a-btn big alt', )) ?></li>
7. Add the Disqus "comment count code" just before the closing </body> tag of your layout.php. Again, this code is provided on the Disqus "universal code" installation instructions page, so you should copy the latest code given there.
Optionally, you can also put Disqus into "developer mode" by pasting this code just before the closing </head> tag of your layout.php:
<script type="text/javascript"> var disqus_developer = 1; // this would set it to developer mode </script>
8. Turn on support for allowing comments in app.yml. Note that if you have not yet overridden any of the aBlog settings you'll need to copy the entirety of plugins/apostropheBlogPlugin/config/app.yml into the all section of your application-level app.yml file. Then you can make this change:
all:
aBlog:
# Be sure to copy the rest of the aBlog settings from the plugin app.yml too!
# Now change the comments setting
comments: true
As with all changes to app.yml, don't forget the symfony cc command.
Once you have done this, blog authors and editors will be able to check the "allow comments" box for individual posts, which will then show Disqus comments.
After following these steps you should immediately have working Disqus comments on your site. Follow the documentation on the Disqus site if you wish to style Disqus to more closely match your site's style.
