You are currently browsing
the website for symfony 1

Visit the Symfony2 website

« Back to the Plugins Home


Plugin Information Installation
Plugin image


This plugin is designed to work with the Apostrophe CMS by P'unk Ave. It allows developers to add an srPageChooserWidget to forms, for use with choosing links in slots, and also in the rich text slot.

Plugin Contents

The srPageChooserPlugin contains a number of classes that work together to allow easy choosing and managing of local site hyperlinks on an Apostrophe website.

  • srPageChooser: The module that displays a page tree for selecting the link, based on the Reorganize page tree built into Apostrophe.
  • srWidgetFormPageChooser.class.php: The best part about the srPageChooserPlugin is that it gives the developer a standard symfony form widget that can be dropped into a form like any other widget.
  • _includeFormAssets.php: A partial which must be included for the widget to work if it is being loaded by Ajax. This loads the necessary JavaScript and CSS for the form, as defined by $form->getJavaScripts() and $form->getStyleSheets(). For an Apostrophe slot, the majority use case, this partial should be included in the _editView.php of the appropriate slot.


The recommended method of installation is as an svn external. To do this, starting in the your symfony project directory, navigate to your plugins directory:

$ cd plugins

Then add in the externals definition to the plugins directory.

$ svn pe svn:externals .

This will bring up your default text editor, perhaps populated with any existing svn:externals you're using. If you're using the asandbox as a starting point, the externals definition for the plugins directory will look like this:


To the bottom of this list, add:


And save the file. To download the plugin files, do an SVN update in your plugins directory:

$ svn up

We're done installing the plugin files. Now, change back to your symfony project directory:

$ cd ..

Next, you must add srPageChooserPlugin to the list of enabled plugins in /config/ProjectConfiguration.class.php.

Then, you have to enable the srPageChooser module in your application's settings.yml file. If the name of your application is, for example, frontend, then open apps/frontend/config/settings.yml, find the enabled_modules parameter, and add srPageChooser to the list.

Next, clear your cache:

$ ./symfony cc

And publish the plugin's assets, so the JavaScript and CSS files are available to the frontend.

$ ./symfony plugin:publish-assets

The srPageChooser is now ready to be used.

Using With Apostrophe Slots

So now that it's installed, how do we use it in our Apostrophe slots? Great question! The first step is to create a new slot type that will utilize our fancy new widget, using the handy generate-slot-type task. Let's start by creating a very simple slot that displays a link.

$ ./symfony apostrophe:generate-slot-type --application=frontend --type=SimpleLink

Now, you must follow the steps outlined by the "WHAT COMES NEXT" text of the symfony task:

  1. Generate your Doctrine classes: ./symfony doctrine:build --all-classes

  2. Enable your new slot type's module, SimpleLinkSlot, in settings.yml

  3. Add your new slot type name, SimpleLink, to the a_slot_types list in app.yml

  4. ./symfony cc

Let's add the new slot into a template so we can use it.

Assuming we're starting from a fresh asandbox installation, we need to copy defaultTemplate.php from the a module of the apostrophePlugin directory into our application-level a module. Skip this step if you already have a template in your apps/frontend/modules/a/templates directory.

$ cp plugins/apostrophePlugin/modules/a/templates/defaultTemplate.php apps/frontend/modules/a/templates/

Add in the new slot SimpleLink into the allowed_types array of one of the areas in the template of your choice.

Now, let's edit the form for the SimpleLinkSlot to add in an srWidgetFormPageChooser widget. Open up the file apps/frontend/lib/form/SimpleLinkForm.class.php and change the following lines from:

$this->setWidgets(array('text' => new sfWidgetFormTextarea()));
$this->setValidators(array('text' => new sfValidatorString(array('required' => false, 'max_length' => 100))));


  'text' => new sfWidgetFormTextarea(),
  'link' => new srWidgetFormPageChooser(),
  'text' => new sfValidatorString(array('max_length' => 100)),
  'link' => new aValidatorSlug(array('allow_slashes' => true, 'require_leading_slash' => true)),

Take note that srWidgetFormPageChooser begins with sr, not sf --- sr stands for [](SunRun, Inc.), the sponsor of this plugin and the nation's leading residential solar company.

Next (and this is an important, easy-to-forget step), we need to add in a line of code into the _editView.php partial of SimpleLinkSlot that will ensure that the necessary JavaScript and CSS files for the srWidgetFormPageChooser are loaded. Bring up apps/frontend/modules/SimpleLinkSlot/templates/_editView.php in your text editor and change it from:

<?php // Just echo the form. You might want to render the form fields differently ?>
<?php echo $form ?>


<?php // Just echo the form. You might want to render the form fields differently ?>
<?php echo $form ?>
<?php include_partial('srPageChooser/includeFormAssets', array('form' => $form)) ?>

Load up a page that has the SimpleLink slot available to it, click Add Slot, and then choose Simple Link. Click Edit and you will see two fields, a textarea labeled Text and a button labeled Link with the text "Select a Link". Clicking this button displays an iframe showing the site's page tree. Click on one of the pages to select it as the target for the link. This populates the link form field with the slug of the page. For example, if you click on a page titled "Contact" in the page tree, the link field will be populated with "/contact". Plus, the title of the page and the slug will be displayed near the "Select a Link" button so you can know which page it points to.

Finally, let's edit the _normalView.php template to display our newly selected link. Open up apps/frontend/modules/SimpleLinkSlot/templates/_normalView.php and change the code from:

<?php include_partial('a/simpleEditButton', array('name' => $name, 'slot' => $slot, 'pageid' => $pageid, 'permid' => $permid)) ?>
<?php if (isset($values['text'])): ?>
  <h4><?php echo htmlspecialchars($values['text']) ?></h4>
<?php endif ?>


<?php include_partial('a/simpleEditButton', array('name' => $name, 'slot' => $slot, 'pageid' => $pageid, 'permid' => $permid)) ?>
<?php if (isset($values['text']) && isset($values['link'])): ?>
  <a href="<?php echo $values['link'] ?>"><?php echo htmlspecialchars($values['text']) ?></a>
<?php endif ?>

And that's it!

Using with FCKEditor and aRichTextSlot

Having the ability to graphically insert links using the Rich Text slot, without ever having to type a URL, is one of the most useful features of this plugin. Luckily, it's super easy to implement once the plugin is installed. You just need to replace one FCKEditor HTML file with the version included in this plugin.

By default, asandbox is setup to use the fckeditor files bundled with apostrophePlugin, which are located at:


The file we are particularly interested in is:


Replace this with the version included with this plugin, located at:


If you would like to keep the FCKEditor files bundled with apostrophePlugin intact (recommended), copy the FCKEditor files it bundles into your own web directory, like:

$ cp -R web/apostrophePlugin/js/fckeditor web/js/

You'll also want to delete the SVN stubs in this new folder if you plan to commit it to your repo:

$ cd web/js/fckeditor/
$ find . -name .svn | xargs rm -rf
$ cd ../../..

Now, if you haven't already, copy in the srPageChooserPlugin version of fck_link.html into this new directory:

$ cp plugins/srPageChooserPlugin/web/js/fckeditor/editor/dialog/fck_link.html web/js/fckeditor/editor/dialog/

Finally, to tell Apostrophe to use our custom FCKEditor files, change the rich_text_fck_js_dir setting in apps/frontend/config/settings.yml to reflect the new location:

rich_text_fck_js_dir:   js/fckeditor

Clear your cache, and that's it!

$ ./symfony cc

If you don't see the changes, make sure to clear your browser's cache!

Contact the developer at ocelot [a] gmail.

Copyright (c) 2010 SunRun Inc.