Apostrophe 1.5: legacy documentation

Still using Apostrophe 1.5? Check out Apostrophe 2 for your future projects.

Upgrade

Apostrophe Manual

Up to the Overview

Upgrading Apostrophe

Overview

Patchlevel upgrades (1.4.1 to 1.4.2, etc.) can be undertaken with little worry. If they do involve schema changes, they will be additions. There will not be radical changes to markup, CSS philosophy, etc.

Usually this is true for minor versions (1.0 to 1.4, for instance). However, the upgrade from 1.4 to 1.5 was relatively significant and is not trivial to carry out. The good news is that we provide migration tools that do a very significant chunk of the work for you. Nevertheless you can expect to have to deal with schema changes that may affect your code especially if you have defined additional relations on our tables. It's a good idea to refer to the source code of the apostrophe:migrate task to learn about the schema changes and table updates that are involved.

From time to time we issue upgrades for Apostrophe, more specifically for the open source Symfony plugins apostrophePlugin and apostropheBlogPlugin. For the more part this process is all but automatic within the Apostrophe 1.x series. However, sometimes a major change does justify a few manual steps to allow new features to be implemented. We'll add notes on these issues to this page over time to ensure that an upgrade path is available, just as we did during the transition from pkContextCMS to apostrophePlugin.

Standard Upgrade Steps

  • If you are installing Apostrophe via the plugin:install task or downloading Symfony plugin tarballs directly from the Symfony plugins site, then of course you'll need to download the new version. If you used plugin:install you should be able to use plugin:upgrade to install the latest version of apostrophePlugin. Remember that you should upgrade the blog plugin at the same time. With Apostrophe 1.5 you must switch to sfDoctrineGuardPlugin 5.0.0. Apostrophe's apostrophe:migrate task can take care of the necessary schema changes after you do this.
  • If you used svn you will need to switch to the 1.5 branch of both plugins, and also switch to the trunk of sfDoctrineGuardPlugin. We strongly recommend checking out the 1.5 sandbox project and looking at the svn:externals settings there as a reference. This command is handy:
svn propget svn:externals plugins
  • Always run the symfony cc task after upgrading.
  • When moving to 1.5, you must add a published_at column to your pages.yml fixtures file, otherwise your pages will not be visible at all to users who cannot edit them. For an easy way to get this accomplished, see data/fixtures/pages.yml in the 1.5 sandbox project, which you should check out as a reference. Of course if you are not rebuilding your site from fixtures you can skip this but it may surprise you later.
  • Always run the apostrophe:migrate task after upgrading, and also the doctrine:build --all-classes task. For instance, on your development computer, you would type:
./symfony doctrine:build --all-classes
./symfony apostrophe:migrate --env=dev
./symfony cc
./symfony apostrophe:rebuild-search-index --env=dev

These tasks rebuild Doctrine base classes (this does not affect your own code), update database tables (including upgrades to BIGINT IDs if coming from 1.4 or earlier), clear the Symfony cache, and rebuild the search engine index. apostrophe:migrate will perform schema changes when upgrading from an earlier release such as 1.4, so back up your content first.

Version-Specific Upgrade Notes

Be sure to consult these when migrating from an older version up to or beyond the version mentioned.

Version 1.5

First make sure that apostropheBlogPlugin is enabled AFTER apostrophePlugin in your config/ProjectConfiguration.class.php file. Do NOT use enableAllPluginsExcept for this purpose. Enable the specific plugins you want, with the blog plugin listed after the main Apostrophe plugin. Otherwise certain class files will not be found beginning in version 1.5.

Developers: if you have created custom slot types, either on your own or by using the apostrophe:generate-slot-type task, you will need to make a small change to the normalView partial of your slot.

Beginning in version 1.5, the slot parameter must be added to the list of parameters to the simpleEditButton partial. For example:

<?php include_partial('a/simpleEditButton', array('pageid' => $page->id, 'name' => $name, 'permid' => $permid, 'slot' => $slot)) ?>

If you are using simpleEditWithVariants you won't need to change anything. If you are not using a standard edit view at all (many slots, such as our slideshow slot, do not need one), then you don't have to worry about this change.

Also, your layout must call the new a/globalJavascripts partial at the end of the body:

<?php include_partial('a/globalJavascripts') ?>

This is necessary to bring in the JavaScript? calls automatically collected and reduced to a single block of JS code by Apostrophe 1.5's a_js_call helper.

Your layout should also have a page-header Symfony slot, allowing the media repository to insert material at the appropriate point:

<?php if (has_slot('a-page-header')): ?>
  <?php include_slot('a-page-header') ?>
 <?php endif ?>

We strongly recommend reviewing the new layout.php in the 1.5 sandbox.

You should also call the new a_include_javascipts and a_include_stylesheets helpers in preference to the standard Symfony helpers in order to take advantage of the new minifier features, although this item is optional. See the installation guide for notes on how to activate the minifier which greatly reduces page load time and bandwidth usage.

CSS changes from 1.4 to 1.5

Note that you must have an up to date version of Doctrine 1.2.x (at least 1.2.2 in our tests). We rely on a bug fix that appeared in version 1.2.2. You do not have to upgrade to an incompatible version, just the latest patchlevel in the 1.2.x series. If you are distributing Symfony 1.4 with your project via svn:externals then this is already happening automatically.

In Apostrophe 1.4, the majority of the CSS lived in a single stylesheet a.css. This stylesheet contained everything from Eric Meyer's reset CSS to Apostrophe UI and even the basic styles needed to make the Sandbox project look and feel like a functioning website.

In Apostrophe 1.5 we made some significant changes to the structure of our CSS to make it easier to:

A. We made is easier to override our styles removing all of the #ID based selectors from the CSS. We also removed the use of !important wherever possible.

B. We removed the reset stylesheet from the plugin itself. It now lives in the sandbox main.css file. This allows you to choose if you want to use the CSS Reset for your project or not.

C. We have begun name-spacing the Apostrophe interface elements with the class name a-ui and we have a name-spaced reset styles for only the UI. Previously in Apostrophe 1.4, the CMS interface elements were too easily impacted by the project's styles and vice versa. Implementing the a-ui class insulates the interface somewhat from the project styles.

D. The philosophy of Float Nearly Everything is slowly getting removed from the plugin where possible. This could potentially have an impact on your project level styles if you were relying on the floats to be present. When upgrading from 1.4 to 1.5, it may be necessary to reapply float at the project level.

E. We introduced .clearfix into the Apostrophe. The clearfix CSS that we are using comes from the HTML5 Boilerplate  http://html5boilerplate.com/.

F. LESS support. We haven't begun implementing LESS into the Apostrophe plugin yet but it is available to you to use.

G. Opt-in and out of using portions of our styles all together. We broke our styles out into separate stylesheets. With a simple app.yml parameter, you can turn off individual stylesheets in favor of using your own project level styles. This means that you do not have to write complex selectors at the project level to "forcefully" override any unwanted styles included with Apostrophe. Minification and Gzip for CSS -- there is no price paid for having many stylesheets. It allows us to toggle individual stylesheets off and on, combining them into a single file on the production server.

Apostrophe 1.5 Stylesheets

a-admin.css -- Admin Generator styles for the Apostrophe 'aAdmin' Theme.

a-area-slots.css -- Styles for the area and slot interfaces as well as some light formatting for individual slots.

a-buttons.css -- Apostrophe button framework contains CSS for all of the button types used in Apostrophe, including the sprites.

a-colors.css -- bundled colors for the sandbox were collected and put into a single stylesheet for easy overriding.

a-components.css -- contains all of the complex interface elements for Apostrophe: pptions menu, history browser, global toolbar, taggable widget, etc.

a-engines.css -- contains all styles relating to our bundled Apostrophe engines: media library, blog, and events.

a-forms.css -- a basic form framework that we use throughout Apostrophe assumes we are using the mark-up defined by our formFormatter

a-ie.css -- general IE stylesheet is included for IE6,7,8 for any plugin fixes

a-reset.css -- a-ui scoped reset

a-utility.css -- basic utility classes for Apostrophe, .a-overlay, .a-spinner, .a-hidden, .a-disabled, and the Clearfix.