DEVEL

   1 * How to get plugged in
   2
   3 Lets explain how to create a simple GOsa plugin. The example shows a dummy plugin which is not
   4 directly related with LDAP. Independently of beeing an LDAP style or LDAP unrelated plugin, you
   5 may start a new plugin, by creating a new directory below the plugin directory structure. To be up to
   6 date, get a fresh CVS checkout:
   7
   8 Create a ~/.cvsrc with the following content:
   9 cvs -z4 -q
  10 diff -u3 -p
  11 update -dP
  12 checkout -P
  13
  14 Change to the directory which will contain your GOsa checkout.
  15 # cd ~projects
  16 # export CVSROOT=:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/gosa
  17 # cvs login
  18 # cvs co gosa
  19
  20 The gosa directory will contain your initial checkout now. In order to update from CVS
  21 you simply can call "cvs up". There's no need to set the CVSROOT directory anymore,
  22 as long as you cal all cvs commands inside the gosa directory and its subdirectories.
  23
  24 Now you've an up to date GOsa. Not that this is CVS HEAD, so there may be something
  25 broken. Continue by choosing a name and creating the directories:
  26
  27 # cd plugins/addons
  28 # mkdir dummyplug && cd dummyplug
  29
  30 GOsa expects a file named "main.inc" inside of this plugin directory. It is needed because some
  31 plugins may need no standard handling and GOsa itself may not know how to initialize the plugin
  32 classes. Here's our example:
  33
  34 ---
  35 <?php
  36         /* All page output must be placed inside the display variable. Please do not output anything
  37            from within your plugin directly. GOsa will take the display variable after things got processed
  38            and assemble the final page after that. */
  39
  40         /* print_header generates the page header including the headline and the icon, get template
  41             path looks for eventually overloaded files. You don't have to take care of this - it's only important
  42             for theming artists. Copy the icon (as .png) to the html/images directory, if you don't care about
  43             the image, just copy the personal.png to dummy.png. */
  44         $display= print_header(get_template_path('images/dummy.png'), _("A nice dummy plugin"));
  45
  46         /* All plugin objects get stored inside the PHP session. Here we create the object if it doesn't
  47             exist yet. It is recreated if "reset" is set. */
  48         if (!isset($_SESSION['dummy']) || (isset($_GET['reset']) && $_GET['reset'] == 1)){
  49                 $_SESSION['dummy']= new dummy ($config);
  50         }
  51         $dummy= $_SESSION['dummy'];
  52
  53         /* Execute plugin. This calls your plugin class and appends its output to the display variable. */
  54         $display.= $dummy->execute ();
  55
  56         /* The ignore field controls if GOsa should ignore the users tries to leave the plugin without
  57            saving. For the dummy plugin, you can leave all the time without loosing data. */
  58         $display.= "<input type=\"hidden\" name=\"ignore\">\n";
  59
  60         /* After executing the plugin, some data may have changed, so we need to put the plugin back
  61            to the session. */
  62         $_SESSION['export']= $export;
  63 ?>
  64 ---
  65
  66 The basic starter for your plugin is ready now. We're missing the plugin itself currently. To create it,
  67 you need to create a file starting with class_ and ending with .inc. These files get sourced automatically.
  68
  69 Here's the class_dummy.inc:
  70
  71 ---
  72 <?php
  73
  74 /* Create a class (name must be unique inside GOsa) which extends plugin. The plugin base
  75     class contains all methods that are used by GOsa and it provides the mechanism to load data
  76     from LDAP to local variables and prepare the save to ldap routine for you. */
  77 class dummy extends plugin
  78 {
  79
  80   /* These contain attributes to be loaded. We're not doing an LDAP plugin currently, so we don't
  81      care... */
  82   var $attributes= array();
  83   var $objectclasses= array();
  84
  85   /* The constructor just saves a copy of the config. You may add what ever you need. */
  86   function dummy ($config, $dn= NULL)
  87   {
  88         /* Include config object */
  89         $this->config= $config;
  90   }
  91
  92   /* Execute is the function all plugins need. It fills the plugin with life and produces the output. */
  93   function execute()
  94   {
  95         /* Use the smarty templating engine here... */
  96         $smarty= get_smarty();
  97
  98         /* Normally you would react to user input here. */
  99
 100         /* Let smarty fetch and process the page. Always seperate PHP and HTML as much as
 101            you can. */
 102         return ($smarty->fetch (get_template_path('contents.tpl', TRUE)));
 103   }
 104
 105 }
 106 ?>
 107 ---
 108
 109 There are two things missing now. The template file and an entry in your gosa.conf. Lets finish the
 110 work in the plugin directory, first.
 111
 112 Here is the contents.tpl file:
 113
 114 ---
 115 <p>
 116   {t}This is a dummy plugin. It really does nothing. The tags around this text do automatic translations to the desired language. Please don't include linefeeds here, or it will not work at all!{/t}
 117 </p>
 118
 119 <p class="plugbottom">
 120   &nbsp;
 121 </p>
 122 ---
 123
 124 Now add the following entry to your Addons section in gosa.conf:
 125 --
 126                         <plugin acl="dummy" class="dummy" icon="dummy.png"
 127                                 path="plugins/addons/dummy" />
 128 --
 129
 130 After logging into GOsa, you'll see your plugin in the addons section.
 131