MyCustomWidget

What does this Plugin do?

“MyCustomWidgets” provides a powerful alternative to the wordpress standard “text”-widget-template. After activating this plugin you will be able to create own widgets and to include them into your wordpress theme by using the wordpress administration interface. Inside of your CustomWidgets you can use html- and php-code. By using filters (which you can define freely as well) you can define where your CustomWidgets should show up.

UPDATE: It is now possible to place “CustomWidgets” outside of the sidebar by using custom tags.

Update: The plugin was tested up to WP 3.0!

Where can I download it?

Current Version: MyCustomWidget 2.0.5 – » download latest version

Why is there so much text below?

Because the author of another cool widget hates cool plugins that are badly documented.
In addition to that, there have been some questions how to use the plugin. Therefore I added this documentation. If you have a question about the plugin please first make sure you refer to the latest version of the plugin and the question is not answered on this page or in the comments section of the plugin homepage.

Table of Content

1. Introduction
   1. Motivation
   2. Features
   3. Concept of MyCustomWidget
   4. Registering Widgets with WP 2.8
   5. Tutorial
2. Installation
   1. Requirements
   2. Installing the Plugin
   3. Upgrade from previous versions
   4. Deactivating the Plugin
   5. Uninstalling the Plugin
3. Usage
   1. Using MyCustomWidget
   2. Configuration
      1. Filter Section
      2. Miscellaneous Section
      3. Layout Section
      4. Administration Section
   3. Create CustomWidget
      1. Add/Change
      2. Preview
      3. Debugging mode
      4. Assign Plugin
4. About Security
5. Troubleshooting
   1. Incompatibilities to other Plugins or Themes
   2. Limitations
   3. Reporting Bugs
   4. Test to assert Plugin functionality
6. FAQ – Frequently Asked Questions
   1. Why does the plugin fail with an eval() error when executing my code?
   2. How can I just print out PHP code and don’t execute it?
   3. How can I include PHP files?
   4. Whole site crashes because of error in my_custom_widget_classes.php

Introduction

Motivation

While building up my WordPress blog I changed the code of my sidebar several times. Whenever I used a new plugin that should offers content in a sidebar I had to change the coding again. When WordPress offers the ability of widgets I liked to use this functionality as well. Unfortunatelly this would have meant to loose all changes I had made in the past. Of course there is the WordPress build-in text-widgets and several plugins that you can use to create own widgets. Nevertheless I was not happy with these solutions because:

• I’d like to put php- and html-code in my widgets
• I’d like to define own names for my widgets (Who want’s to use widgets like „Text Widget 1“ to „Text Widget 99“?)
• I’d like to use filters because not all widgets should be available on all pages

Back in 2007 I decided to write a small plugin that allows me to put these additions in small widget-pieces. Long story short: I improved this pugin and decided to release it under GNU Public Licence (GPL).

Features

• Define own widgets through powerfull widget-configuration-panel
• Define filters through plugin-option-page
• Deinstallation routine to delete all data that has been created by this plugin
• Backup routine for widget data and plugin options
• Preview functionality for all CustomWidgets
• Debugging functionality to locate coding errors (beta-version)
• apply_filter-functionality can now be activated within CustomWidgets
• Widgets are also available through custom tags such as <!–MyWidget–> and can therefore be used outside of the sidebar as well (apply filter)
• Dublicate/copy existing widgets

Concept of MyCustomWidget

Technically MyCustomWidget executes code inside of <?php ?> tags by just wrapping your whole text into ?> <?php tags and hand it over to the PHP eval() function. By that no parsing of your code needs to be done by the plugin itself. It is not recommended to use the plugin in WordPress installations with untrusted users.
All widget-data is stored in the wordpress option table.

Registering Widgets with WP 2.8

In general a widget has to be registered/announced before it can be added to a sidebar. With WP 2.8 the concept of creating and registering widgets changed. Instead of registering a single function that generates the widget content, the developer of a widget has to declare a class (that extends a predefined class of WP2.8) that represents the widget.

While WP 2.7.X added the widget to a sidebar, WP 2.8 generates an new instance of the widget-class whenever a widget is added to a sidebar. This means: Within WP 2.8 the same kind of widget can be added several times.

If you take a look at the Widget “MCW 2.0 Addon” (the code is located in file my_custom_widget_addon.php) you will find a pure WP2.8-Widget as it has to be (according to the WP-developers).
Unfortunatelly it was not possible (yet/for me) to re-implement all functionalities of MCW 1.9 by using this new technique (e.g. Backup, Preview, making widgets available outside of a sidebar, downward compatibility).

That’s why the plugin just generates the class definitions on-the-fly whenever the widgets are saved. The result is stored in file my_custom_widget_classes.php.

Other plugins
Nowadays there are a lot of similar plugins around which are doing similar work as this plugin. If MyCustomWidgets functionality does miss some feature you are desperatly seeking, you may want to take a look on one of the various WordPress plugin databases or drop a feature request.

Tutorial

Creating a simple widget:

Installation

Requirements

You need the following software to be installed on your webserver in order to run the Exec-PHP plugin:

• A running installation of WordPress 2.0 or higher
• A WordPress theme that allows to use widgets.*
• The MyCustomWidget plugin

* If your theme does not support widgets yet, you can adjust your theme like described here »

Installing the Plugin

If you have ever installed a WordPress plugin, then installation will be pretty easy:

• Download the MyCustomWidget plugin archive and extract the files.
• Copy the mycustomwidget directory into /wp-content/plugins/
• Activate the plugin through the ‘Plugins’ menu of WordPress

Upgrade from previous versions

Usually if not specifically mentioned on this page you can upgrade from a previous version of this plugin by simply deactivating the plugin through the ‘Plugins’ menu of WordPress, replacing the content of /wp-content/plugins/mycustomwidget and reactivating the plugin again. An upgrade should not migrate settings of an older plugin version.

Deactivating the Plugin

Deactivating the plugin will cause your CustomWidgets to disappear. Don’t panic! Your widget content will not be erased until you deinstalled the plugin.

Uninstalling the Plugin

For uninstalling the plugin you should start the deinstallation routine on the plugin-option screen and simply delete the MyCustomWidget directory from the /wp-content/plugins/directory afterwards. You even don’t need to deactivate the plugin in the WordPress admin menu.

Usage

Using MyCustomWidget

With MyCustomWidget you can create widgets that contain php and html-code. All other features are listed in the correspondend section written above. The following section will descripe how to use these features.

Configuration

The plugin comes with its own option menu that is accessible through ‘Options / My Custom Widget’s. The option menu is only accessible for users that do have the ‘edit_plugins’ capability. This is usually only assigned to the Blog Administrator. If you have disabled Javascript you will not see or only see parts of the Plugin Option menu.
The option menu is divided into four parts:

• the filter section
• the miscellaneous
• the layout section and
• the administration section

Filter Section

In this section you can define filters which you can use in your CustomWidgets.
You will have to define at least one filter to make your widget visible. Therefore several default values have been defined. The most important filter should be ‘all’.
The whole filter-handling is quite easy. A filter is defined by a name and a php-code snipped which can be interpreted as a bool-value (true or false). Please visit the official WordPress-side (Conditional Tags) if you want to know which values can be entered here. If you have added a new filter the filter will be available for all CustomWidgets immediately.

If you are new to PHP and you do not even know what I am writing you should use the default filters and leave this section as it is.

Miscellaneous Section

In this section you can define several default values that will be used by the plugin. Currently there are 4 options available:
With release 1.1 I added information which should explain the options that are available. These information become visible when you click on the small question sign on the very left.
The addition HTML-code option will give you access to an additional code-box. All code in this area will be interpreted as pure html code. This box is a legacy from a former version of this plugin. If you do not have to you should deactivate this option. I think I will delete this additional code-box within one of the next releases. The other options are improvements suggested by wordpress-users.

To save any changes in this section you will have to press the save-all-button which is situated under the layout section.

Layout Section

In this section you can define several layout parameters. As always I added a short description of the functionality inside the plugin. Therefore I think these options are self-explanatory.

Administration Section

In this section you can Reset the default plugin settings, create or restore a backup and start the deinstallation routine. Due to the fact that these buttons should be used very carefully there is an additional checkbox which should be ticked to commit any actions.

A backup will create a new database record in the WordPress option-table.

Create CustomWidget

To create an own CustomWidget is quite easy. Just proceed as follows…

Create/Change Widget

First you should ask yourself what the widget should do.

1. What should be the widgets name?
2. Do you want to add HTML or PHP code?
3. Where should the widget be available?

1. The widgets name should be unique. If the widget has the same name as another existing one the custom or the other widget will not be shown. The plugin checks wether the name is unique regarding other widgets created with MyCustomWidgets. (I did not want do force a prefix like “mcw_”. Nevertheless you should think about that and use a name which is not used by another plugin-specific widget.

2. You can use both: HTML and PHP code. You can even combine both kinds by using the normal php-tags <?php and ?>. If a code works somewhere else on your side it should works within your CustomWidget as well. Just choose if your code should be interpreted as HTML or PHP-code.

3. Not all widgets should show up on each page. Below the code area all available filters are listed. If you do not know what these filters will mean or if you need to create your own filters you should visit the filter section of the plugin option page. Please keep in mind: You have to create the filter first and tick it afterwards. You can tick several filters. The widget will be displayed if one (or more) of the selected filters is true.

Preview Widget

Once you created and saved the plugin you will be able to start the preview by clicking on the lens-symbol.
The widget-code and the widget-content will show up on the very bottom. Please be aware that the stylesheets that are used inside of the admin panel is different to the one used on your WordPress blog. Therefore the layout can be different.

Debugging mode (beta)

The debugging mode works as follows: It splits the widget code into HTML- and PHP-pieces and lists this code. As a matter of fact if-statement that include html-code will not interpreted correctly. Therefore the debugging-mode is not a all-in-one device suitable for every purpose. To start the debugging mode you will have to tick the debugging-checkbox and click on the preview icon (the lens) afterwards.

Assign Widget

Once you saved the widget a new widget entry will appear under Presentation –> Widgets. Just add the widget to your sidebar via Drag’n'Drop.

About Security

By using this plugin a user can use the full PHP API and WordPress API. There are no restrictions to execute only certain subsets of functionality. Allowing your users to create or change CustomWidgets will mean to allow executing PHP code and will expose your WordPress installation in specific and your server installation in general. By that a user can easily take over your blog and your server. If in doubt do not install this plugin as long as there are no additional security features available.

Troubleshooting

Incompatibilities to other Plugins or Themes

Currently there are no known incompatibilities to other plugins or themes.

Limitations

Most likely the debugging functionality will not work if you are using if-statements. Apart from this there are no known issues.

Reporting Bugs

You can post bug reports to the comments. Before doing this make sure your PHP script is running properly in a separate file. If it does, assure that you did not hit the “Globals” issue. If you still think it’s a bug, keep in mind that WordPress’ commenting system is not build to write unescaped code, so better convert it to the correct XHTML entities before commenting here, point to the code using an external link or get in contact with me by email (wordpress@this-domain-name.de).

Test to assert Plugin functionality

Following is a list of tests that were made by the author of the EXEC-PHP-Plugin to assert his plugins functionality. On the left side the PHP code taken directly from the tests is written. On the right side the live output generated by the Exec-PHP plugin is shown. If you view this documentation as a static HTML file obviously the PHP code isn’t executed and will look messy. Because of the content of this test, this page will not verify as XHTML. If you think, your favorite PHP plugin is better than this one, try out all the tests below and see if this works correctly.

<?php ?>

<?php echo "a?>1"; ?>

<?php echo 'b?>1'; ?>

<?php echo "a?>2"; ?>

<?php echo 'b?>2'; ?>

<?php?>

<?php echo"a?>3";?>

<?php echo'b?>3';?>

<?php echo"a?>4";?>

<?php echo'b?>4';?>

<?php echo "c";?>1";?>

<?php echo 'd';?>1';?>

<?php echo "c';?>2";?>

<?php echo 'd";?>3';?>

<?php
echo "impressive\n '";
echo 'string\' "';
echo "\n\thandling\"";
?>

<?php if (1) { ?>
<b>Handle THIS!</b>
<?php } else { ?>
<i>Handle THAT!</i>
<?php } ?>

FAQ – Frequently Asked Questions

Why does the plugin fail with an eval() error when executing my code?
If you experience a PHP error message like ‘Parse error: syntax error, unexpected '?' in /www/htdocs/wp-content/plugins/mycustomwidget/my_custom_widget.php(504) : eval()'d code on line 1 ‘ then it’s time to repair your PHP code. If you are unsure where your code breaks you can use the debugging functionality or run it in a separate file to punch out all bugs and afterwards copy the code into your article or widget.

How can I just print out PHP code and don’t execute it?
If you just want to print out code and don’t want to execute it, e.g. like it is done here on this page, you have to make sure to convert your code to the correct XHTML representation. To do so you have to escape your whole code or at least change your tags from <?php ?> to &lt;?php ?&gt;.

How can I include PHP files?
If you want to include a php-file you should be aware of the fact that each relative path will start in the root directory of this plugin which is ‘/wp-content/plugins/mycustomwidget/’.
instead of using a relative path you should use a statement like
<?php require_once(get_option(‘home’). ‘/example.php’); ?>

How can I support this plugin?
First of all you can rate this plugin on wordpress.com. But of course you can also make a donation.

Whole site crashes because of error in my_custom_widget_classes.php
If you receive an error such as Parse error: syntax error, unexpected T_STRING, expecting ‘{’ in /wp-content/plugins/mycustomwidget/my_custom_widget_classes.php on line 10 there was an error
during the generation of the widget-specific classes. This might happen when you use prohibited characters in your widget name. Please delete the content of my_custom_widget_classes.php and rename you CustomWidget. Of course you should contact me (e.g. by leaving a comment). Usually I try to catch all prohibited characters.

Donation