Apostrophe Manual
Overview
Welcome to the 1.0 stable release of Apostrophe! Although this is our first official stable release, our CMS is already in regular use on a number of production sites. This release reflects the fact that our code has been stable and ready for your professional use for quite some time. So there's no need to wait; let's get started building your site.
This document has four major sections:
These are intended to be read consecutively, except for the installation section which is not appropriate if you are not installing Apostrophe yourself. Stop reading when you know what you need to know!
The installation section is intended for developers and system administrators with some knowledge of PHP and command line tasks.
The editor's guide is suitable for end users who will have administrative responsibilities on the site, such as editing and managing content. No programming skills required.
The designer's guide addresses the needs of front-end developers, discussing how to edit and manage stylesheets, page templates and page layouts.
Finally, the developer's guide explores how to extend Apostrophe with new content slots that go beyond our provided rich text and media features and new "engines" that extend the CMS with full-page content that doesn't always fit neatly into the page metaphor. Most readers will never need to refer to this section.
See the end of this document for information about community and professional support, the Apostrophe community and how to participate in further development.
Guiding Philosophy
Apostrophe is a content management system. Apostrophe is open source, and built upon the great work of other open source projects. That's why our apostrophePlugin is a plugin for the Symfony web application framework.
The philosophy of Apostrophe is that editing should be done "in context" as much as possible, keeping confusing modal interfaces to a minimum and always emphasizing good design principles and an intuitive user experience. When we are forced to choose between ease of use and a rarely used feature, we choose ease of use, or make it possible to discover that feature when you truly need it.
Before we decided to write our own CMS, we used sfSimpleCMSPlugin, and although our system is quite different you can see its influence in Apostrophe. We'd like to acknowledge that.
Who Should Use Apostrophe Today?
Right now Apostrophe is best suited to PHP developers who want to make an intuitive content management system available to their clients. Apostrophe is very easy for your clients to edit, administer and maintain once it is set up. Right now, though, Apostrophe installations does call for some command line skills and a willingness to learn about Symfony. We are working to reduce the learning curve.
Front-end developers who do not yet have PHP and Symfony skills but wish to set up an Apostrophe site by themselves should consider tackling the Symfony tutorial to get up to speed. It's not necessary to complete the entire tutorial, but it helps to have at least a passing familiarity with Symfony.
And of course we at P'unk Avenue are available to develop complete Apostrophe sites for those who see the value in a truly intuitive CMS and do not have the development resources in-house to implement it.
Apostrophe Features
Standard features of Apostrophe include version control for all content slots, locking down pages for authenticated users only, and in-context addition, deletion, reorganization and retitling of pages. When a user is logged in with appropriate privileges intuitive editing tools are added to the usual navigation, neatly extending the metaphors already present rather than requiring a second interface solely for editing purposes.
Apostrophe also introduces "areas," or vertical columns, which users with editing privileges are able to create more than one slot. This makes it easy to interleave text with multimedia and other custom slot types without the need to develop a custom PHP template for every page.
Content "slots" include plaintext, rich text, RSS feeds, photos, slideshows, videos, PDFs and raw HTML slots.
Apostrophe includes support for media management, including a built-in media library that allows you to manage locally stored photos and remotely hosted videos. When media are embedded in pages they are automatically sized to cooperate with the page templates created by the designer.
Rich text editing, of course, is standard equipment. And unlike most systems, Apostrophe intelligently filters content pasted from Word and other programs to ensure there are no design-busting markup conflicts.
Supported Browsers
Editing works 100% in Firefox 2+, Safari 4+, Chrome and Internet Explorer 7+. Editing is expressly not supported in Internet Explorer 6. Of course, browsing the site as a user works just fine in Internet Explorer 6. Although IE 6 cannot support our full editing experience, we recognize the need to support legacy browser use by the general public when visiting the site.
System Requirements
apostrophePlugin requires the following. Note that virtually all of the requirements are included in the asandbox project which you can easily check out from svn, copy from svn to your own repository as described below, or just download as a tarball.
The following must be installed on your system:
- PHP 5.2.4 or better, with a PDO driver for MySQL (PHP 5.3.x works but is still rather buggy as of this writing; this refers to PHP's bugs, not ours)
- MySQL (tested), SQLite (tested), or another relational database supported by PDO and Doctrine (a few nonessential features are MySQL-specific)
- For the media features: GD support in PHP, or the netpbm utilities. netpbm uses much less memory
- Optional, for previews of PDFs in PDF slots: ghostscript (you must also have netpbm to use this feature)
A few truly excellent hosting companies already have netpbm and ghostscript in place. If you have a Virtual Private Server (and you should, shared hosting is very insecure), you can most likely install netpbm and ghostscript with a few simple commands like sudo apt-get install netpbm and sudo apt-get install ghostscript.
If you are choosing a Linux distribution, we recommend Ubuntu. Ubuntu includes a sufficiently modern version of PHP right out of the box. If you are using Red Hat Enterprise Linux or CentOS, you will need to upgrade PHP to version 5.2.x on your own. This is unfortunate and Red Hat really ought to get a move on and fix it.
PHP Libraries
All of these are included in the sandbox project, no need to install them. We list them here for developers who want to know what we're relying on.
- Doctrine
- The Zend framework, for search
- Symfony 1.3 or 1.4
Symfony Plugins
All of these are included in the sandbox project, no need to install them. We list them here for developers who want to know what we're relying on.
- sfSyncContentPlugin
- sfJqueryReloadedPlugin
- sfDoctrineGuardPlugin
- sfWebBrowserPlugin
- sfFeed2Plugin
- sfDoctrineActAsTaggablePlugin
- apostrophePlugin
Note that if you checked out or copied our sandbox project from svn, all of the components "provided with asandbox" are provided as svn externals, which means they update automatically when you type svn update. Wherever possible we've pinned these to stable branches, not development versions.
Optional components of interest: apostrophePlugin is compatible with sfShibbolethPlugin (the 1.2 trunk version) and sfDoctrineApplyPlugin.
Mac users: want to build your site on your own computer first? Please say yes, this is the right way to avoid surprises. You can most easily meet the web server and PHP requirements by installing the latest version of MAMP. Note that MAMP's PHP must be your command line version of PHP, not Apple's default install of PHP. To fix that, add this line to the .profile file in your home directory:
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5/bin:$PATH"
Of course your production server will ultimately need to meet the same requirements with regard to PHP and PDO.
Apple's default version of PHP for Snow Leopard is theoretically capable of working with Apostrophe, but unfortunately Apple chose to ship a very bleeding-edge version and as of this writing they have not updated it to address the many PHP bugs since discovered. As of this writing we recommend the latest in the PHP 5.2.x series, not PHP 5.3.x, due to numerous hard crashes at the PHP level with PHP 5.3.x.
Yes, you can also use Apostrophe with Microsoft Windows as a hosting environment. Core Apostrophe features do not depend on Unix-specific command line tools and services.
Support, Community and News Sources
Please be sure to join the apostrophenow Google group. This is the right place to obtain community support.
Bug tracking, subversion access and a community Wiki are all available at trac.apostrophenow.org.
Professional support for Apostrophe is available from our team here at P'unk Avenue.
Also be sure to follow our Twitter account.
For bleeding-edge development news, subscribe Google Reader or your feed reader of choice to our svn commit notes:
http://www.apostrophenow.com/svn.rss
And of course, be sure to visit the Apostrophe Now site.
Please continue reading with one of the following:
