Apostrophe 1.5: legacy documentation

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

apostrophe People Plugin

Apostrophe People Plugin

The Apostrophe People Plugin lets you organize and display people on Apostrophe pages. You can filter, sort, and search for people and add people to ordinary webpages via the people slot. There is a robust administrative area for managing people in the system. Thanks to Symfony's excellent support for project-level overrides, you can add additional fields and relate other tables to people by extending the schema in your project.

Installation

(Please note: if you started your project with a copy of our sandbox project after December 8th, 2011, you already have the people plugin.)

1. Get the plugin. If your project is in an svn repository (an Apostrophe 1.5 best practice) then just add this line to your svn:externals for the plugins folder:

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

Then svn up and down it comes.

If you are not using svn, you can grab it this way. Relax, my use of the svn export command here just "exports" the code with no special svn magic attached.

cd plugins
svn export http://svn.apostrophenow.org/plugins/apostrophePeoplePlugin/trunk apostrophePeoplePlugin

2. Enable the apostrophePeoplePlugin in your project's projectConfiguration Class [ /config/ProjectConfiguration.class.php ]. Make sure you list it after apostrophePlugin.

3. Add the People Engine to templates and the People Slot to the slot_types in app.yml [ /apps/frontend/config/app.yml ] :

all:
  a:
    ### Apostrophe Templates
    templates:
      ...
      aPeople:
        default: People

    ...
    ### Apostrophe Slots
    slot_types:
      ...
      aPeople: People                       # apostrophePeoplePlugin Slot

4. The People Plugin requires some CSS and Javascript to fully function. Add these assets to your project level view.yml [ /apps/frontend/config/view.yml ] :

  stylesheets:
    - /apostrophePeoplePlugin/css/aPeople.less
  javascripts:
    - /apostrophePeoplePlugin/js/aPeople.js

5. Enable the People Plugin modules in your project's settings.yml [ /apps/frontend/config/settings.yml ] :

enabled_modules:
  - aPeople
  - aPeopleAdmin
  - aPeopleSlot

6. Add a button to access the people admin to the global tool bar. Our favorite way to do this is by overriding the a/globalProjectButtons partial at project level, which is initially empty (apart from the people plugin button itself in recent versions of the sandbox, which is provided as an example). Be sure to check permissions as not everyone who can see some global buttons is an admin. Our sandbox includes an example. Here's what it looks like:

<?php // This partial is loaded at the end of the list of admin bar buttons. ?>
<?php if ($sf_user->hasCredential('admin') || $sf_user->hasCredential('peopleAdmin')): ?>
  <li><?php echo link_to('<span class="icon"></span>People', 
        'aPeople_admin', array(), array('class' => 'a-btn icon a-users no-bg alt')) ?></li>
<?php endif ?>

7. Add the People Slot to an Area or Singleton Slot in a page template [ /apps/frontend/modules/a/templates/defaultTemplate.php ], or just add it to the list of slots available in a standard area if your project is derived from a recent version of our sandbox (app.yml under the a key):

all:
  a:
    standard_area_slots:                    
      ... Various other slots ...
      - aPeople

If you do not use our standardArea component or need this slot in places where you call a_area directly you can do it this way:

  <?php a_area('example', array(
    'allowed_types' => array(
      'aRichText',
      'aPeople',
    ),
    'type_options' => array(
      'aRichText' => array(
        'tool' => 'Main',
      ),
      'aPeople' => array(
        ...
      ),
      ...

8. Publish the assets of your plugins or otherwise ensure that web/apostrophePeoplePlugin points to plugins/apostrophePeoplePlugin/web or a copy of its content:

./symfony plugin:publish-assets

9. If you are integrating the people plugin into an existing project, make sure you run the apostrophe:migrate task to add the relevant tables and relations:

./symfony apostrophe:migrate

In a new project, just build your Doctrine tables in the usual way.

Exploring (and Configuring)

Installation is complete! Now we can try it out and adjust settings to get closer to what we want.

First add some people via the People button on the admin bar. Add a person and save, then click the headshot icon to add a picture.

Then add an individual or two to a regular page via the people slot. Not exciting yet- just their name (unless you copied our sandbox recently).

Let's change the default options for this slot in app.yml:

# As an example, let's use the headshot template for people slots, it's much more exciting
all:
  a:
    standard_area_extra_slot_options:
      aPeople:
        itemTemplate: headshot

(If you are using a_area calls directly, just add the same itemTemplate option to the aPeople slot in your call.)

Refresh the page and you'll see the user complete with their photo. But the photo is awfully wide. You can adjust that by setting the slideshowOptions for the aPeople slot, but that's awkward with the standardArea component, because the width of the area overrides any width options- a good thing for most slots, but headshots don't need to be as wide as a column.

Fortunately there's a way to force those options to take more suitable values for specific slots:

# These apply regardless of what the width parameter to the standard area component is
all:
  a:
    standard_area_force_slot_options:
      aPeople:
        slideshowOptions:
          width: 200
          flexHeight: true

So far we can display individuals with a bit of information but we don't have a way to access more complete information, or see a list of people. So add a new page to your site and choose the "people" type. Note that you can pick categories of people to include or allow it to just show everyone (which happens if you pick no categories). This is a nice way to show a directory of people.

Click on an individual to load their thumbnail and details. Click on "view profile" to see a standalone page about that individual.

"But I still don't see a lot of the information!" That's true. What you want to display depends very much on your project's needs. Some fields may be inappropriate to show to some users. That's why you should override the aPeople/showSuccess template in a project level templates folder for the same module name and make appropriate adjustments. You can also add columns in your project level schema.

When you're done checking out the people page, go back to the regular page where you added the people slot. Notice that each person's name is now a link to the people page that best matches their categories.

You can easily override the aPerson/defaultTemplate or aPerson/headshotTemplate at project level. You can also add your own templates. Just make sure you enable them via slot options as demonstrated above for the headshot template.

To do more, just extend the schema for these tables at project level. We routinely extend this plugin to address the particular needs of projects. It's a rare project that doesn't want to add a few columns or even relations to additional tables. That's where Symfony's deep support for project level overrides and merging columns from two different schema.yml files comes in.