fahad19

I have been writing documentation for Croogo for the past few weeks in markdown format. The more I use it, the more I like it. It is really very nice to write in plain text and be able to convert it to proper (X)HTML when it is finally shown in the browser. So I decided to write a plugin for converting markdown to html. It can be used in Croogo for writing content, as well as manually in your CakePHP applications.

What is Markdown?

Markdown is a text-to-HTML conversion tool for web writers by John Gruber. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Learn more about markdown here: http://daringfireball.net/projects/markdown/.

I have used the PHP Markdown_Parser class by Michel Fortin for this plugin.

Download

Get the plugin from GitHub: http://github.com/fahad19/markdown.

How to use this plugin with Croogo?

Read the wiki for information on how to upload and activate the plugin. Once active, you can start writing content in markdown format.

You don't need to convert your already existing content (in HTML) into markdown because it is aware of what is already in HTML and won't convert them twice. It is recommended that you deactivate any WYSIWYG editors (like TinyMCE) before using this plugin.

Using the plugin in CakePHP applications manually

After placing the plugin at /app/plugins/markdown, let you Controller know to load the plugin's Helper:

<?php
class PostsController extends AppController {

    pubic $helpers = array('Markdown.Markdown');

}
?>

<?php
    // will output in HTML format
    echo $this->Markdown->transform($textInMarkdownFormat);
?>

If you are a CakePHP developer, you must know about DebugKit plugin by Mark Story already. It provides a debugging toolbar and enhanced debugging tools for CakePHP applications. As far as I remember, it is the first plugin I tried in my applications and this may be the case for most developers too.

So why am I posting it here again? Just to demonstrate how it can be used with Croogo's plugin/hook system. A few weeks ago, I forked DebugKit and made it Croogo ready so anyone can upload it from the admin panel and start using it without having to worry about editing php files (app_controller.php here) manually.

All I did was add two files under a new directory 'config' to this awesome plugin, and done! First was an YAML file and the other was a PHP file. The file structure looks like this:

• /app/plugins/debug_kit/
  • config (the new directory)
    • debug_kit_bootstrap.php
    • plugin.yml
  • controllers/
  • models/
  • views/
  • ...
  • debug_kit_app_controller.php
  • debug_kit_app_model.php

The YAML file

plugin.yml file is used for storing basic information about the plugin like it's description, author's name, website, etc. It can also contain information like it's dependencies. But we don't need anything like that for this plugin now:

name: DebugKit
description: DebugKit plugin

author: Mark Story
authorEmail:
authorUrl: http://mark-story.com

The plugin's bootstrap file

debug_kit_bootstrap.php is loaded every time the application bootstraps (only when the plugin is active). It handles configuration so DebugKit's Toolbar component is loaded in every controller.

<?php Croogo::hookComponent('*', 'DebugKit.Toolbar'); ?>

If you wanted the component to load only in, say, Users controller:

<?php Croogo::hookComponent('Users', 'DebugKit.Toolbar'); ?>

That wasn't too difficult, right? Now you can log in to Croogo's admin panel and activate the plugin from Extensions > Plugins page and you will see the toolbar at top right of your browser immediately. You can also deactivate it once you are done with debugging.

To learn more about how plugins work in Croogo, read the wiki.

Download

Get the modified version of DebugKit from http://github.com/fahad19/debug_kit.

Let's call this version Plugins-Are-Awesome version! I have spent more time thinking than actually coding about how plugins can integrate themselves with the whole application more easily without having to touch the core. And I believe, I have been able to take the right direction. Still a long way to go. This release consists of 55 commits resolving 18 tickets, and fixing a number of bugs.

Download

Download the latest version from GitHub: http://github.com/croogo/croogo/downloads.

Changelog

See all commits for this release on GitHub, and tickets on LightHouse.

New and improved plugin/hook system

The major change in this release is how plugins work in Croogo. Previously, administrators were given the ability to activate/deactivate a helper or a component (hook) individually, which is bad because it expects the administrator to know about CakePHP development. But now you activate/deactive a plugin as a whole only, which is easier to understand for non-developers. And it is from the plugin's own bootstrap file that you decide which items to hook (let it be a component, helper, behavior or routes). The administrator doesn't need to know what happens there.

Upgrading existing Croogo installations

There has been no change in the database schema since the last release. A simple 'git pull' should update everything smoothly (like my blog). If you have developed plugins utilizing the hook system of Croogo, you should read the Developers section of the new wiki.

Site is up with documentation!

Yes, I know I have been very slow (may be lazy) with documentation. One of the reasons is that things were continuously being improved for more flexibility and ease of use. But the API is getting pretty stable now, and there is no reason for not writing documentation. Check out the site here at http://croogo.org. I will be writing for the next few weeks constantly, and once the wiki is in a decent shape, I will turn it into a git/markdown based wiki so user contribution and translation becomes easier.

What's next?

Next release will be all about user experience (aka UX). There will be a more usable and accessible (and of course, good looking!) admin panel. I lack skill in designing area, so if any of you want to share your experience and send suggestions, please post on Google Group. Submitting screenshots highlighting the good parts of other existing solutions would help too. Mockups would be highly appreciated!

If the project progresses at the current speed, I am positive that a stable version will be available in the next three releases. But don't expect a label of 'stable' unless there is decent test case coverage.

Extensions

An extensions directory could be up soon. And it largely depends on the number of community contributed plugins and themes. I can see a number of plugins being developed already, but there aren't many theme designers interested in Croogo yet. So if your friend is a designer, make sure you recommend Croogo to him/her!

Enjoy and Happy Baking!