Introducing Gdn_PScaffold a plugin scaffold/mini framework for your convenience

x00

I'm releasing Gdn_Scaffold shortly on an MIT licence, which is a utility/script which will help your organise, often cluttered plugins.

https://github.com/x00/Gdn_PScaffold

Requires php >= 5.2 to run

For those that already have IDE templating and automation regimes, you probably don't need this. You might want to look at the utility methods though.

What it is NOT for:

• Plugins that only have one or two files and a few lines of code (as it will create extra files).
• Plugns that already have a more specific organised structure

You can use on a plugin that needs some organisation, or a new project.

It is a scaffold it does not make your plugin automatically work, you need to implement along the lines suggested.

Treat it like beta software. It does backup within the plugin file, but it is not substitute for an external backup regime.

This is a tool/helper, don't trust it to be perfect.

x00

Without further ado an explanation

ABOUT

A utility/script for the Vanilla / Garden Framework, which will help your organise, often cluttered plugins.

SETUP

To make cd to Gdn_Scaffold and run $ php make.php As go through all the steps You can make a link/shortcut in a convenient location e.g. $ ln -s gdn_ps.php ~/gdn_ps

GENERAL USAGE

To run $ php ~/gdn_ps --bklimit=3 --dir='/path/to/plugin' optional bklimit is the amount of backup history you want to keep (the default is 3) dir is the path to you plugin directory if the directory doesn't exist, creation will be attempted. You can also cd to the plugin folder and run $ php ~/gdn_ps If you wish to refactor (add or remove from the class chain) $ php ~/gdn_ps --refactor On Windows do the equivalent... for help run $ php ~/gdn_ps --help

EXAMPLES

How to make

How to run

Scaffold existing plugin

Refactor an existing plugin

Demo of scaffolding and refactoring

File examples

• class.utility.php
• class.api.php
• class.settings.php
• class.ui.php
• class.existingpluginplugin.php

Also provided is additional readme's in how to implement the various resources in each directory

HELP

NAME gdn_ps.php - Garden Plugin Scaffold (Gdn_PScaffold) SYNOPSIS php gdn_ps.php [--refactor] [--bklimit=num] [--dir=path] DESCRIPTION Gdn_PScaffold creates a scaffold or mini-framework for the purpose of organizing you code. It is a loose methodology for the Garden Framework https://github.com/vanillaforums/Garden It is designed to be as unobtrusive and minimal as possible The general structure of a scaffolded plugin is as follows: ./class.yourplugin.php OR ./default.php ./class.ui.php [optional additional abstract classes] ./class.settings.php ./class.api.php ./class.utility.php ./views ./design ./js ./library ./models ./icon.png ./readme.markdown You have suggested directories, but specifically a chain of abstract classes that extend Gdn_Pluign culminating in your plugin file. You can then keep your plugin file lean and shallow and move much of the logic to appropriate files in the chain and still be derivative of Gdn_Pluign. This program will generate the structure for you although if the plugin file exists, it will not change it, except to refactor the class declaration to be at the top of the chain of inheritance. However it can only try to do this. Please check that your plugin class extends YourPluginUI If it exist, you will be given the option for an example folder to be created, full of suggestions. gdn_ps will also create any file structure not there, plus a generated backup each time you run gdn_ps. It DOES NOT automatically move your code for you. It isn't that smart. The files contain suggestions, use them for guidance. You can remove the backup and examples folder when appropriate. The 'framework' extends Gdn_Pluign with an abstract YourPluginUtility which will automatically contain a handful of methods that can be useful in developing plugins Notably: Autoload - which will load all models matching models/class.*.php, and all class.*.php in the base of the plugin. HotLoad - which will load a setup each time the plugin is updated. You MUST implement abstract method PluginSetup which should be friendly to hot loading. Typically this contains your db structure declaration and any other necessary setup. MiniDispatcher - works like the mini dispatcher that comes with Gdn_Plugin except it is pluggable meaning other plugins can create additional methods for the pseudo-controller. What's more you are not limited to one pseudo-controller you can set a local and pluggable prefix, therefore implement the dispatcher multiple created methods. ThemeView - gets a view location, checking first in the enabled theme, then in the plugin views enabling folk to copy the views across to their theme. If you want additional files in the chain you can "refactor" which gives the option to add or remove abstract classes. The convention is the name is prefixed with the Plugin's index or class name and gdn_ps works on that basis, so will not know what to do otherwise. The plugin file itself extends YourPluginUI. You would not be able to add a class before this using gdn_ps You will also not be able to add a class before YourPluignUtility which as it is extending Gdn_Plugin Other than that you can add a class anywhere along the chain if it makes any difference to you. You can insert any number of classes, or remove those in between YourPluignUtility and YourPluignUI In each directory that it implements as part of the scaffolded plugin it provides a readme suggesting how to implement such resources. OPTIONS --dir=path Specifies a path to a plugin. If the plugin folder doesn't exist it will try to create it. --bklimit=num Allows you to specify how many copies of backup is kept, if you are using gnd_ps often by default the 3 last copies are kept. --refactor will give you options to refactor the class chain in an existent scaffolded plugin. --help will bring up this help file AUTHORS Paul Thomas COPYRIGHT Copyright (C) Paul Thomas 2013 all rights reserved. This script is released under the MIT License shown in the LICENCE file.

x00

Don't forget to implement required method PluginSetup in your plugin file even if empty.

x00

pluggability should now work in the mini dispatcher

So not only can you do stuff like

 protected function Name_PseudoController($Sender, &$Args){
    $this->AddCssFile($this->GetResource('design/somestyle.css', FALSE, FALSE));
    $this->AddCssFile($this->GetResource('js/somescript.js', FALSE, FALSE));
    $this->MiniDispatcher($Sender,'PseudoController','PseudoController');
 }

 public function PseudoController_Index($Sender){
    $Sender->Render($this->ThemeView('index'));
 }

 public function PseudoController_Browse($Sender){
    $Sender->Render($this->ThemeView('browse'));
 }

but in another plugin you can do

 public function PseudoController_AllNewMethod_Create($Sender){
    ....
 }

if you need the updated class.utility.php class grab the latest copy of Gdn_PScaffold, make, remove the old and run gdn_ps

x00

I have added a new utility method DynamicRoute

  /**
   *  @@ GDN Plugin Scaffold @@
   *  
   *  Add a route on the fly
   *  
   *  Typically set in Base_BeforeLoadRoutes_Handler
   *  
   *  @param string &$Routes loaded
   *  @param string $Route RegExp of route
   *  @param string $Destination to rout to
   *  @param string $Type of redirect (optional), default 'Internal' options Internal,Temporary,Permanent,NotAuthorized,NotFound 
   *  @param bool $OneWay if an Internal request prevents direct access to destination  (optional), default FALSE
   *  
   *  @return void
   */

  protected function DynamicRoute(&$Routes, $Route, $Destination, $Type = 'Internal', $Oneway = FALSE)

You can add a new route like so (note due to $OneWay = TRUE direct access to destination is blocked).

  public function VanillaController_SomePage_Create($Sender){
     exit('hello world!');
   }

   public function Base_BeforeLoadRoutes_Handler($Sender, &$Args){
     $this->DynamicRoute($Args['Routes'],C('Plugins.TestPlugin.SomePageURI', 'somepage'),'vanilla/somepage','Internal', TRUE);
   }

I've made gdn_ps's --dir argument friendlier, it should be able to use absolute, relative urls and does posix tilde expansion.

x00

I have created a --light to create stripped down plugins

• ./class.yourplugin.php
• ./class.ui.php
• [optional additional abstract classes]
• ./class.utility.php
• ./icon.png
• ./readme.markdown

lifeisfoo

I'll try it for my next plugin.

x00

cool what OS do you develop on?

lifeisfoo

On Ubuntu 12.10 (to be updated to 13.04 in some weeks, maybe...).

x00

ok that should work

x00

a few gremlins with the path and mini dispatcher to be expected....

x00

If there are going to be a lot of utility functions, it would make sense to put them in a special plugin that loads that class to keep things DRY.

Then they could be overridden in YourPluginUtility if necessary.

The problem is that, this is released MIT, which fine as it is standalone generation function, but it uses templates.

The code generated, and the templates, I don't want it to be too restrictive for those that use it. I'm going to make a new post concerning the continue lack of clarity extension licensing.

In parallel, where this plugin would be primarily a garden extension, so I don't think would an issue, however GPl complicates things more than people like to admit.

Also is this going to be annoying, or you think it is fine, requiring such a plugin? It would mean it would automatically require it to be there. It won't have to be enabled.

At the moment it is just a handful of convenience methods, so it probably isn't worth doing.

lifeisfoo

Are there any plugin that use this? (from yours plugins @x00)

I'll trying it but with a working example everything should be easier. Thank you.