Development

nahoWikiPlugin

You must first sign up to be able to contribute.

nahoWikiplugin - Wiki for symfony

Overview

This plugin allows you to embed a wiki within your symfony application with the following features:

  • Create/edit pages with full versionning
  • Basic permissions management
  • Basic security features
  • History of changes
  • Graphical and unified diff between two given revisions
  • Preview changes before saving
  • Internal links, supporting namespaces
  • Interwiki links
  • Automatically generated table of contents
  • Breadcrumbs
  • Configurable
  • Fully extendable
  • A bunch of helpers to provide total integration in your application

Most features have been inspired from DokuWiki (e.g. namespaces and Interwiki work the same way).

It is not aimed at replacing full-featured wiki packages, but offers a lightweight alternative for when you build a website that has to contain a simple wiki. It is very easy to configure and adapt, so it should fulfill most basic wiki requirements.

Please note that this plugin is in active development. If you want to help and improve it, please contact Nicolas Chambrier (naholyr at yahoo dot fr).

Screenshots

Screenshot (sample page) Screenshot (list of changes, graphical diff) Screenshot (index by title)

Requirements

The prerequisites for using the nahoWiki plugin are:

  • As the plugin doesn't contain a user management module, the project where you install it must have a table managing authors, or users (whatever the name), and the related Propel class must have a __toString() method. Both these conditions are satisfied by the sfGuardPlugin, so installing this plugin is a good choice.
  • You need the [http://trac.symfony-project.com/trac/wiki/sfMarkdownPlugin sfMarkdownPlugin] which will provide the ability to convert from wiki syntax to XHTML contents.

Installation

PEAR Install

To install the plugin for a symfony project, the usual process is to use the symfony command line: 

$ php symfony plugin-install http://plugins.symfony-project.com/nahoWikiPlugin

SVN Install

If your project is not under subversion yet, you can simply checkout the plugin in your plugins directory: 

$ svn co http://svn.symfony-project.com/plugins/nahoWikiPlugin/trunk plugins/nahoWikiPlugin

If your project is under version control, you can use the svn:externals property: 

$ svn propedit svn:externals plugins

and add the following line: 

nahoWikiPlugin http://svn.symfony-project.com/plugins/nahoWikiPlugin/trunk

After you installed nahoWikiPlugin this way, you must copy (or symlink) plugins/nahoWikiPlugin/web to web/nahoWikiPlugin.

General instructions

Rebuild the model as you are used to, to create the new tables needed by the plugin. 

$ php symfony propel-build-all # Be careful, this command will erase all the existing tables of your model

Clear the cache to enable the autoloading to find the new classes: 

$ php symfony cc

You can load the included fixtures to start using the forum with test data. 

$ php symfony propel-load-data frontend plugins/nahoWikiPlugin/data/fixtures

Enable the new nahoWiki module in your application, via the settings.yml file. 

// in myproject/apps/frontend/config/settings.yml
all:
  .settings:
    enabled_modules:        [..., nahoWiki]

Start using the plugin by browsing to the frontend module's default page: 

http://myproject/frontend_dev.php/nahoWiki

Slots

The templates of the nahoWiki module define some slots that you can use inside your layout:

  • wiki_page_actions : For the current page actions
  • wiki_page_name : Name of the current page
  • wiki_breadcrumbs : For the wiki breadcrumbs

If you want to insert the actions menu or the breadcrumbs in your layout at the place you exactly want, simply disable the auto-inclusion of it (see app.yml configuration) and include the corresponding slot in your layout.

Here is an example layout (in this example, options include_page_actions and include_page_name have been disabled in app.yml): 

...
<body>

<div class="my-menus">
  <?php include_slot('wiki_page_actions') ?>
</div>

<h1><?php include_slot('wiki_page_name') ?></h1>

<?php echo $sf_data->getRaw('sf_content') ?>

</body>
</html>

Configuration

Schema customization

If you install the sfPropelAlternativeSchemaPlugin, you can customize this plugin's schema by creating a nahoWikiPlugin_schema.custom.yml file under your project's config/ directory. This allows you to customize the connection name, table names, etc… Refer to the README file for more information.

Extending model, actions, or templates

If you want to extend a class of the model, just create an empty file lib/model/nahoWikiClass.php, which will contain: 

<?php

class nahoWikiClass extends PluginnahoWikiClass {

  // Here I add my own features, or override existing ones

}

If you want to extend the actions, the process is similar: create a file named modules/nahoWiki/actions/actions.class.php in your app's directory: 

<?php

// autoloading for plugin lib actions is broken as at symfony-1.0.2
require_once(sfConfig::get('sf_plugins_dir'). '/nahoWikiPlugin/modules/nahoWiki/lib/BasenahoWikiActions.class.php');

class nahoWikiActions extends BasenahoWikiActions
{

  // Here I add my own features, or override existing ones

}

To override a template file named plugins/nahoWikiplugin/modules/nahoWiki/templates/theTemplate.php, just copy it to modules/nahoWiki/templates/theTemplate.php in your app's folder, and then edit the copied file: it will be the one used by Symfony to render the pages. In most cases, you will want to override _page_actions.php or _breadcrumbs.php, or _toc.php. Templates have been smartly exploded, you should be able to customize the rendering with a few efforts.

Using another Wiki renderer

The default engine is Markdown (if sfMarkdownPlugin is not installed, no conversion at all is done). If you want to use another engine, just override the method nahoWikiContentPeer::doConvert($content).

Create a file named lib/model/nahoWikiContentPeer.php: 

<?php

class nahoWikiContentPeer extends PluginnahoWikiContentPeer {

  public static function doConvert($content)
  {
    // Return converted $content from Wiki-syntax to XHTML
    // Default behaviour is : return sfMarkdown::doConvert($content)
  }

}

app.yml

Some of the features of the plugin can be altered by configuration. To do so, add some of the following lines to your application's app.yml: 

all:
  nahoWikiPlugin:
    # General config
    start_page:             index         # Default start page
    pagename_format:        "a-z0-9\-_"   # Pagename authorized characters (format compatible with PCRE)
    ns_separator:           ":"           # Namespace separator character
    max_breadcrumbs:        5             # Maximum number of links stored in the breadcrumbs
    breadcrumbs_separator:  " » "         # Separator between breadcrumbs items
    include_breadcrumbs:    on            # Include breadcrumbs slot (disable if you include the slot in your layout) ?
    include_actions:        on            # Include actions list slot (disable if you include the slot in your layout) ?
    include_pagename:       on            # Display page's name when viewing content ?
    include_toc:            on            # Display Table of Contents at top of every page
    routes_register:        on            # Enable embedded routing rules ?
    wrap_class:             nahoWiki      # All pages are wrapped into a <div class="..."> tag. This is its class name.

    # Rendering for internal links, you may need to customize the *_model options if you change rendering engine
    internal_links:             ["[[%name% %title%]]", "[[%name%]]"]
    internal_link_model:        "[%title%](%link%)"
    internal_link_broken_model: "[%title%(?)](%link%)"
    interwiki_links:             ["[[%key%>%name% %title%]]", "[[%key%>%name%]]"]
    interwiki_link_model:        "[![%alttext%](%image%) %title%](%link%)"

    # Regular expressions replacements *before* conversion
    replace_before:     []
      # - { from: "/a pcre mask/i", to: "something" }  # replace "a pcre mask" with "something"

    # Regular expressions replacements *after* conversion
    replace_after:     []
      # - { from: "/a pcre mask/i", to: "something" }  # replace "a pcre mask" with "something"

    # Strip some tags (and their contents) for security (this comes after conversion)
    strip_tags:  [script, embed, object]

    # Permissions
    credentials_edit:      []           # Credentials required to be able to edit a page
    allow_anonymous_edit:  no           # Are anonymous (not authenticated) users able to edit a page ?

Routing rules

The plugin comes with the following default rules. You can prevent those routes to be added by disabling the option routes_register, and add your own routing rules.

Here are the default rules: 

wiki_home:
  url:   /wiki
  param: { module: nahoWiki, action: index }

wiki_view:
  url:   /wiki/view/:page
  param: { module: nahoWiki, action: view }

wiki_view_revision:
  url:   /wiki/view/:page/:revision
  param: { module: nahoWiki, action: view }

wiki_edit:
  url:   /wiki/edit/:page
  param: { module: nahoWiki, action: edit }

wiki_edit_revision:
  url:   /wiki/edit/:page/:revision
  param: { module: nahoWiki, action: edit }

wiki_history:
  url:   /wiki/history/:page
  param: { module: nahoWiki, action: history }

wiki_diff:
  url:   /wiki/diff
  param: { module: nahoWiki, action: diff }

wiki_index:
  url:   /wiki/index
  param: { module: nahoWiki, action: browse }

Look and Feel

The nahoWiki module comes with a default stylesheet. You can choose to use your own stylesheet instead of the default one. To do so, you must create an empty nahoWiki module inside your application with just one config/view.yml file in it, with the following content: 

all:
  stylesheets: [-/nahoWikiPlugin/css/default.css, myCustomStylesheet]

nahoWiki specific features

Helpers

nahoWiki provides a bunch of helpers to help you integrate the wiki in your application.

You can insert links to wiki pages, anywhere in your application :

  • link_to_diff($text, $page_name, $rev1, $rev2, $mode = 'inline')
  • link_to_raw_diff($text, $page_name, $rev1, $rev2, $mode = 'unified')
  • url_for_wiki($page_name, $revision = null)
  • link_to_wiki($text, $page_name, $options = array(), $revision = null)
  • url_for_wiki_user($username, $revision = null)
  • link_to_wiki_user($text, $username, $options = array(), $revision = null)
  • url_for_wiki_discuss($page_name, $revision = null)
  • link_to_wiki_discuss($text, $page_name, $options = array(), $revision = null)

You can even insert the content of a wiki page using include_wiki :

  • include_wiki($page_name, $revision = null, $options = array())
  • get_wiki($page_name, $revision = null, $options = array())

The last two helpers are just shortcuts to use nahoWiki component.

Interwiki

nahoWiki provides basic support for Interwiki.

The main syntax is [[Key>PageName Title]], and it outputs a link to the page "PageName?" of the wiki named "Key", preceded by a nice icon telling the user this is an Interwiki link.

If the file named web/nahoWikiPlugin/images/interwiki/key.gif exists (or .png or .jpg) it will be used, else we use the generic interwiki.png [[Image(source:plugins/nahoWikiPlugin/trunk/web/images/interwiki.png, image/x-trac-wiki)]]

To add a new Interwiki, just create a file named interwiki.yml in your app's folder, and add the key you want : 

all:
  Key: "http://UrlOfTheWiki?page="

The page name provided in the link is just added to the corresponding URL.

The syntax for internal links is [[PageName Title]].

Page names support namespaces.

If an internal link points to a unexisting page, it's show to the user, using different models : internal_link_model for links to existing pages, internal_link_broken_model for links to unexisting pages.

Namespaces

Namespaces work just the same way than DokuWiki

TODO

  • User manual for advanced features (mainly namespaces and interwiki)
  • Add admin modules
  • Add ACL (fine grained permissions management)
  • Support multilingual versions of a page

Contact

If you have any comment, feeback, question or idea, please use this dedicated thread on the forum.

Active tickets

Closed tickets

Attachments