Apostrophe 1.5: legacy documentation

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

A2 Migration Guide

Migration to  Apostrophe 2 is a smart goal for Apostrophe 1.5 projects that are undergoing a significant redesign. Apostrophe 1.5 is a mature and reliable system with many good features, but the performance and development ease of Apostrophe 2 and node.js cannot be denied. Migrating to A2, though, is definitely a significant undertaking. So we encourage you to set aside adequate time for the project.

Here's a quick overview of the major steps in the A2 migration process:

1. Mastering Apostrophe 2, of course.  Clone our sandbox project and spend some quality time carrying out familiar tasks with it, as a user and as a developer.

2. Copying the sandbox to a new project and repository of your own (very easy to do; see the  sandbox README). This is much easier with git and A2.

3. Migrating your content. We encourage doing this early in the process so that you are working with a realistic data set.

4. Rewriting your PHP-based page templates in nunjucks. Nunjucks, like Symfony 2's Twig, is a port of Jinja, a popular template language from the Python world. So Symfony developers who have experimented with Symfony 2 should feel at home. See the  Jinja syntax guide.

5. Rewriting any custom modules in A2. In most cases you'll want to add new subclasses of the A2 snippet module (this is what our A2 blog module does, and the reason it can be so short). Apostrophe 2 page loader functions are commonly used as well to muster data so that it can be made available to templates before templates start running; unlike PHP code, Nunjucks code cannot and should not invoke any model code directly. You may also want to add some Express routes (akin to Symfony actions) directly to your project for interactions that don't involve pages or provide back end APIs for browser-side JavaScript?.

6. Creating new LESS CSS styles to suit your new design.

7. Training your users on A2. A2 is significantly easier and more powerful than A1.5, but of course there is a need to introduce your users to the new experience in a friendly way.

8. Relaunching the project.

"Great, but how do I migrate my content?"

We've released a highly useful plugin for your Apostrophe 1.5 project, apostropheA2ExportPlugin, which allows you to export your site to an Apostrophe 2 project. This plugin is rapidly maturing and already imports the majority of content.

Assuming you've already created an Apostrophe 2 project, using the plugin is straightforward.

EVERY RUN OF THIS PLUGIN'S TASK ERASES THE CONTENT OF YOUR NEW A2 PROJECT, COMPLETELY REPLACING IT, UNLESS YOU USE THE --mount OPTION. The content of your 1.5 project is NOT erased.

MAKE SURE YOU HAVE MONGODB CLIENT SUPPORT IN PHP. See " install the PHP driver" on the MongoDB site.

MAKE SURE YOUR PROJECT IS RUNNING APOSTROPHE 1.5 AND IS FULLY UP TO DATE WITH ALL OF OUR CORE PLUGINS, especially apostrophePlugin. We have made fixes in svn that are necessary for this migration task to work.

Add the plugin to your project:

svn propedit svn:externals plugins

apostropheA2ExportPlugin http://svn.apostrophenow.org/plugins/apostropheA2ExportPlugin/trunk

Enable it in config/ProjectConfiguration.class.php in your plugins list.

Now run the task, passing the MongoDB database name and filesystem path of your new A2 project:

./symfony apostrophe:export-a2 apostrophe-sandbox /Users/boutell/src/apostrophe-sandbox

The MongoDB database is assumed to be on your own machine. You can move it to another machine later by any method of your choice.

By default this task will switch pages to the default template unless they currently have the home or default template. You can change this behavior using the --whitelist-templates and --default-template options. The --whitelist-templates option takes a comma separated list of template names.

Similarly, this task will append all content slots and areas found in a page to the body area unless they are currently in the body or sidebar area. You can change this behavior using the --whitelist-areas and --default-area options.

By default, the content imported from A1.5 completely replaces the A2 site's content, if any. If you wish, you can import all of the content as a subtree of the new site instead, with the --mount option. If you choose this approach, you may merge the old content with new content already under construction.

Also, if you use the --mount option, you may make several migration attempts or practice runs; each new run will drop all previously imported content but leave the non-imported content alone.

We do, however, recommend backing up your new site with mongodump first if you have built A2 content you are fond of.

Here is an example of a fancy command line from a real-world project:

./symfony apostrophe:export-a2 moore /Users/boutell/src/apostrophe-sandbox --whitelist-templates=default --default-area=migration --mount=/legacy

Here's another command line with even more fancy options:

./symfony apostrophe:export-a2 moore /Users/boutell/src/moore --whitelist-templates=default,videoPortfolio --whitelist-areas=body,sidebar,portfolio --default-area=migration --template-map=videoProgramNav:videoPortfolio,videoDefaultNav:videoPortfolio,video:videoPortfolio --reusable-slideshow-snippet-type=gallery --reusable-slideshow-widget-type=galleries  --reusable-slideshow-snippet-area=thumbnail --area-map=default-banner:marquee

Note that in all cases "aBlog" and "aEvent" engine pages will be given the page types "blog" and "events" so that they are functional. Similar exceptions are made for people pages (from apostrophePeoplePlugin).

The import of media can take a long time. If you need to run the task more than once because of issues on the first try, and you are certain that you have already completed that part successfully, you can add the --skip-copy option:

./symfony apostrophe:export-a2 apostrophe-sandbox /Users/boutell/src/apostrophe-sandbox  --skip-copy

When the task completes, it will remind you that you need to run several Apostrophe 2 tasks to complete the data migration. Those commands, to be run in your a2 project folder, are:

node apos.js apostrophe:migrate
node apos.js apostrophe:search
node apos.js apostrophe:rescale

The rescale task takes considerable time. You can skip it if you are also skipping the copying of media files with --skip-copy.

Once these tasks are complete, you can visit your A2 site and see your glorious content! As of this writing the import is not 100%, but you will get your tree of pages, including blog and events pages and people pages, and blog posts, events and people themselves. Users with accounts in A1.5 become unpublished people with login rights in A2, and their passwords continue to work. Rich text, slideshows, "reusable" slideshows, buttons and videos are imported.

Many other slot types still await inclusion in the migration task. But this set of features is often enough to get the site's editors to a place where they can do the rest manually in the course of adapting their content to the new design.

A number of Symfony events are posted by the migration task, making it easier for you to integrate custom project-specific migrations into the process. See the notify method, the various calls to it, and the various public methods of the task all of which may be invoked from your event handler. ]