sfAlohaPlugin documentation

Introduction

This symfony 1.4 plugin makes it very easy to turn any HTML element within a template into an editable WYSIWYG field using Aloha Editor. Aloha plugins are included to save the content and upload pictures. The plugin can therefore be used to turn a symfony application into a very basic CMS.

Features and main benefits of using Aloha Editor

• Very easy integration of Aloha Editor using a helper
• Intuitive way to edit web site content in a real WYSIWYG way: the styles in the editor (headers, lists, ...) are the one of the real website.
• Define you own styles in a stylesheet file. The user will therefore not have the possibility to change too much the content's style and change the website "according to his tastes"
• Save content in database (with versioning enabled)
• System to implement several content saving backends (see configuration), using the DataMapper design pattern
• Upload images

Installation

• Go to your symfony project's root directory

• Install the plugin (via a package)

  ./symfony plugin:install --stability=beta sfAlohaPlugin
  

• Or install the plugin (via Git, which is the preferred way):

  git clone git@github.com:michaelperrin/sfAlohaPlugin.git plugins/sfAlohaPlugin
  

• Activate the plugin in config/ProjectConfiguration.class.php

  class ProjectConfiguration extends sfProjectConfiguration { public function setup() { $this->enablePlugins(array( 'sfDoctrinePlugin', 'sfAlohaPlugin', '...' )); } }

• Activate module in your app's settings file (e.g apps/frontend/config/settings.yml)

  all: .settings: # ... enabled_modules: # ... - sfAlohaContent

• Rebuild the model

  ./symfony doctrine:build-model
  ./symfony doctrine:build-sql
  

• Update database tables (Beware! All tables will be deleted and created again from scratch):

  ./symfony doctrine:insert-sql
  

• Publish plugin assets

  ./symfony plugin:publish-assets
  

• Clear symfony cache

  ./symfony cc
  

Configuration

Default configuration values are defined in the the plugin's config/app.yml file:

all:
  aloha:
    defaultPlugins:
      - common/format
      - common/list
      - common/link
      - common/highlighteditables
      - common/block
      - common/undo
      - common/contenthandler
      - common/paste
      - common/commands
      - common/table
      - common/align
      - sfAloha/save
      - sfAloha/image-upload

    # Tells whether new content can be automatically created or not
    autoAdd:                              true

    image_upload_dir:                     aloha-images
    backend:                              sfAlohaBackendDoctrine

    security:
      edit:
        # Tells whether only authenticated users can edit content or not
        authenticated:                    true

        # Tells whether only users with the given credential(s) can edit content or not
        # ~ for no specific credentials, a table for several allowed credentials (e.g. [admin, writer]), string for only one
        credentials:                      ~

You can override these parameters in your application app.yml file (e.g. in apps/frontend/config/app.yml):

• defaultPlugins: tells which Aloha plugins to load when calling the aloha_init_page helper function

• autoAdd: tells whether new empty content should be automatically created when it doesn't exist yet

• image_upload_dir: tells in which subfolder of the web/uploads folder images will be uploaded

• backend (default value: sfAlohaBackendDoctrine): defines the backend used to save content (i.e. how Aloha content is persisted)

• security: options to allow edit for specific users based on the their authentication status or credentials

• authenticated (true or false): tells whether only authenticated users can edit content or not

• credentials (~, string, array): tells whether only users with the given credential(s) can edit content or not (e.g. [admin, writer])

Add editable content to a page

With autoAdd

• In a template, render the content

• If the "My content" element is already existing in the database, an editable div element will be rendered with the existing content inside, or it will be created with empty content

Without autoAdd

• Execute ("My content" is an arbitrary name that will be used to easily identify content. It's like a title which won't be displayed)

  ./symfony aloha:create-content "My content"

• In a template, render the content

• Now you can test your page, hover the mouse cursor on the div element, edit it, and click the save button in the Aloha editor toolbar :)