Dynpi Documentation

DynPI home

Installation


Installing DynPI is just as easy as installing any other EE module. After you downloaded the zip file and extracted it, copy the dynpi folder to your installation’s modules folder and copy the lang.dynpi.php language file to your installation’s language folder. The standard supplied language file is in English.

Next, login to the Control Panel and go to the modules screen. DynPI should now be visible. Install the module and that’s it, you’re done.

Creating your first plugin


DynPI does not come with any standard plugins, so if you navigate to its homepage, you’ll end up with a notice that no plugins are installed. There are two ways to fix this: the first way is to upload a file with the .dynpi extension by using the upload form box in the bottom of the screen. This option will upload and automatically install the new DynPI plugin for you. The second option is to create a fresh plugin yourself. And that is what we’ll be doing here.

Step 1: creating your plugin


Click the “Create a new dynamic plugin” button which resides on the right side of the modules homepage. You will presented with a screen that allows you to specify necessary plugin parameters, such as its name and usage description. All input fields and explanations of what they mean are listed below.

For our example we’ll create a plugin that checks of a certain category ID exists. It then generates some conditional logic that we can use in our templates. But first, let’s check out the fields.

Full (long) name of plugin
This is the full name of the plugin, which should be something that is easily readable. This field is required. For our tutorial we’ll use the name Category Checks.

Short name of plugin (no spaces or special characters)
As the label suggests, this is the short name of your plugin, which you will use to refer to from your templates. Do not use any special characters or DynPI will go bonkers. For our example, type in category_checks. Also, do not start your plugin name with a number. PHP does not appreciate that.

Plugin version
The version of this plugin. Since we’re building a new one, we’ll type in 1.0.

Author
The name of whoever made this plugin. In this case, yours.

Plugin website URL
This is just for informing people where to go to find more information on the plugin. Just leave it blank or type in whatever URL you like.

Automatic update URL for plugin
This is currently not in use yet, so again, just leave it blank or go crazy.

Usage information for this plugin
Here you tell people how to use your plugin. Keep it short and simple and for now, just type in something like documentation

That’s the basic information needed. Click the “Save plugin” button to, indeed, save your plugin. You can go back to the plugin setup screen at any time by clicking the appropriate “Edit this plugin” link from the main page.

Step 2: creating a method


Plugins are useless without methods. Methods connect your templates to your PHP snippets and because of that, you’ll need at least one method for your plugin to do something. In our example, we’ll make a method to check if a certain category id exists. From the main DynPI screen, click on “Edit this plugin’s methods”.

This will present you with a big empty screen. On the left is a select box showing this plugin’s methods and since we have none yet, it’s empty. The big empty place to the right of the select box will be filled as soon as you click the “Add new method”, so please do so.

The empty place is now filled with a form containing three fields:

Method name
This is the name of your method, which you will use in your templates to call it. For our example, type in exists.

Method arguments
Method arguments are not used when you just want your method to communicate with your template directly. Arguments are used for helper methods you’d like to have in a certain plugin. For example, if you’d like your plugin to be able to do some calculations, you could add a method called “add” and type $a,$b into the method arguments field. From your other methods, you will then be able to call this method by typing $this->method_name($a, $b).

Method code
This is where you type your code. Just consider this an extremely simple PHP editor. Note that you can use the tab button like you would in any other editor, so you can nicely format your PHP snippets.

Type in the following code: 

$tagdata = $TMPL->tagdata;
$category_exists = FALSE;
$category = $TMPL->fetch_param('input');
if (!$category) return 'Please set the "input" parameter';
$sql =
"SELECT * FROM exp_categories WHERE cat_id='{$category}'";
$query = $DB->query($sql);
if ($query->num_rows == 0) $category_exists = FALSE;
else $category_exists = TRUE;
$cond = array();
$cond['category_exists'] = $category_exists;
$tagdata = $FNS->prep_conditionals($tagdata, $cond);
return $tagdata;

If this code scares you, relax. I picked an example that wasn’t too basic just to show the capabilities of DynPI. Most plugins hardly ever use stuff like prep_conditionals, so you yourself might not ever use it. To explain what this code does: it checks for an input parameter and returns an error if it wasn’t set. After that it checks to see if the input supplied to the plugin actually represents an existing category. If that is the case, a conditional variable named {category_exists} is created and set to TRUE. If that is not the case, this variable is set to, you guessed it, FALSE.

That’s it. Click the “Save method” button to save your creation.

Testing your creation


You are now ready to test your freshly created plugin. Go to your Templates tab and create a template that will allow you to test your creation. Open the template and add the following:

The plugin and method parameters are used by DynPI. You can use any custom defined parameters you want, as long as you don’t use EE parameter names like “parse”. In our example, the input parameter is a custom one.

Now call this template from your webbrowser. You can of course change the {segment_2} part to any number you’d like, but let’s suppose you have the value 1 in segment two of your URL. Your newly created plugin will check if that id exists and returns a variable {category_exists} that you can then use to base logic on. In our example, we just return a message, but you could of course do anything you’d like.

In most cases a category with the id will probably exist and the plugin will return a positive statement. Now change the value from 1 to for example 123456789 and refresh your page. You should most likely get a negative response now, or you actually have a lot of categories.

And that’s it! You’ve created your first plugin and (hopefully) tested it succesfully. Nice!

Exporting a plugin


If you have a created a plugin that you would like to share with friends of perhaps even clients, DynPI will let you do so very easily. Once you decided your plugin is ready to be distributed to other Expression Engine websites, just open up the main DynPI screen where all your plugins are listed. Click the “Export this plugin” link and DynPI will pop up a window asking you where to download the file. Just save it to wherever you like and you’re done. This file can now be used by any EE website running DynPI. Take a look at the following paragraph for more information.

Importing a plugin


Importing a DynPI plugin is very easy too. Navigate to the main window, click the “Browse” button in the “Upload and install a plugin installation file” form box, pick a file with the .dynpi extension and upload it. If everything is ok, you’re new plugin will now be installed and ready to be used. If you already had a plugin with the same short name, DynPI will not install the plugin until you first remove the currently present version.

Deleting a plugin


Deleting a plugin is as simple as clicking the “Delete this plugin” link from the main DynPI window. You will receive a confirmation request and if you answer in a positive manner, the plugin will be deleted. Be careful not to delete plugins that are actually still used in your site because this will generate a whole bunch of errors and you cannot undo the delete process.

Programmer’s notes


No need to global EE objects
As you perhaps noticed in the example on this page, you don’t need to global objects like $TMPL or $IN. DynPI takes care of that for you.

Special $DYNPI object
There’s also a special DynPI object named $DYNPI that can - for example - be used to store private properties and it also has a neat functionality which allows you to use its contents in different DynPI plugins in one page, just as long as you consider when a particular plugin is loaded. But this is more advanced stuff that most users will hardly ever use.

Be careful
Don’t just install any .dynpi file you can get your hands on if you don’t know its source. Plugins can access your entire system and destroy your website.

Methods with the same name
In the IDE it is possible to have methods with the same name, since this allows for easy testing of methods by merely switching their names. However, if you try and use a plugin that has methods with the same name, get ready for some very bad PHP errors or even a website that stops functioning.

designed by: 6bit Under