WordPress.org

Download the zip and extract the files to a subdirectory, called tdo-mini-forms, of your plugin directory. i.e. /path_to_wordpress/wp-content/plugins/tdo-mini-forms.

It is currently assumed that the "wp-load.php" of your Wordpress install can be accessed from the tdo-mini-forms folder using the relative path: ../../../wp-load.php

Also make sure that the files in the root of tdo-mini-forms can be accessed from the web as they are used to enable post submission.

Once you've got it installed, active the plugin via the usual Wordpress plugin menu. Make sure you then configure it via the main TDOMF menu in the Wordpress Administration backend.

You must assign a user as the "Default Author". This user must not have rights to publish or edit posts, i.e. they should be of the subscriber role. When posts are submitted from unregistered users, this "Default Author" user is set as the author of the post to keep Wordpress happy. The TDOMF options menu can automatically create a dummy user to set as the Default Author. This is the recommended approach.

On the options menu, there is a button to automatically create a page with the necessary tag to display your form. There are also other options to help integrate with your theme on this page. For more information on Theme integration, please refer to the Frequently Asked Questions of this readme.

Upgrade Instructions from versions previous to 0.7

Before installing the new version of TDO Mini Forms, delete the TDOMiniForms from your .../wp-content/plugins/ folder. Now simply follow the installation instructions above. You will need to re-configure the plugin again, however previously submitted posts and other user information will be retained from your previous installation of the plugin.

Configuration

Please check the Frequently Asked Questions for answers to many of the common issues that arise.

If you are using the wp-cache or wp-super-cache plugins, please make sure that any page that uses a TDO Mini Forms form are not cached. If you cache the form it'll may contain an old "key" and will cause "Bad Data" error messages and also you will not be able to preview or see admin messages.

If you are using any plugins that will execute PHP code within post content/title or custom field, it is recommended to disable them or at the very least make sure that moderation is enabled and all submissions are scanned for malicious code. PHP code and Javascript tags can be submitted as part of input to any part of the form, in some cases Wordpress will strip them out. But custom fields, especially, will not be filtered automatically (this can be desirable, for example if you want people to post snippets of javascript code).

Creating a Form

To start, go to "Options" menu under the main "TDO Mini Forms" menu in your admin dashboard. Make sure you've set a valid Default Author (who does not have publish rights). Go through the general options and make sure everything is okay.

By default, TDO Mini Forms must have at least one form. You can have multiple forms, with various different options in your configuration. You can even copy an existing Form. When you visit any of the Form specific menus, the forms are listed at the top of this menu, so choose go to "Form Options" and select Form 1 if this is the first time you have configured TDO Mini Forms. Read through the options and configure as appropriate. You can automatically create a page on your blog to hold the form from here.

Now move on to the "Create". From here you can configure what is on the Form and how it is processed by dragging and dropping "widgets" from the "Available Widgets" pool to "Your Form" and then configuring the widgets by clicking on the left icon for the widget. It is important to remember that widgets are processed from top down, so they will appear on your form in that order and they will be executed in that order when the form input is previewed, validated and submitted. This can mean that one widget can overwrite a submitted posts settings from another widget (for example multiple Categories widgets can overwrite the default category and themselves). At this stage, try using the form and making sure it works the way you want.

If you're happy with the generated Form and the submitted posts it creates, then you are finished. However if you want to tweak stuff, change some of the messages, re-arrange fields you can move onto the Form Hacker. You must be careful with the Form Hacker as it is quite powerful and there is very little debugging or error reporting going on. You can totally change how your Form appears and even behaves using the Form Hacker. See the following section "Using the Form Hacker" for more on using the Form Hacker.

Using the Form Hacker

With version 0.12, the Form Hacker was added to TDO Mini Forms. Previously a lot of people would modify the source code of TDO Mini Forms to modify a single piece of text used in the form or re-arrange the fields in your form.

Currently the Form Hacker does not allow you to modify the Error message, the Upload Files widget and inline Form and the Custom Field widget preview (FYI: you can do this from within the Custom Field widget configuration).

What Form Hacker does allow you to do is to completely modify the code displayed for a Form. Parts of the Form are often generated on the fly; the Form Hacker gives you access to modifying that actual code as it supports using PHP code within. It is quite powerful but can also be very easy to screw up, so be careful. It also allows you to modify any of Form's general messages such as permission or throttling messages. To use PHP code is fairly easy, for example:

<?php echo get_bloginfo('title'); ?>

This will display your blog's title in the form.

The Form Hacker has a number of "macros". These are special strings that are automatically expanded when the Form is displayed. Some of these macros are used to automatically generate the Form Key (which is used for security). The %%WIDGET:widget-name%% macro can be used to let individual widgets do their thing while you hack everything else. A list of macros can be found by clicking on "Show Help" link at the top of the page.

Please be aware that if you use the Form Hacker and you later change the setings of your form (modify widgets or options), these changes are not reflected automatically in the Form Hacker. You must re-edit the hacked form to pick up the new changes.

Getting even more out of your Form

You can now attach additionally PHP code to your form using the "Append to Content" widget. If you drag and drop this widget to your Form, you can use it to add anything you like to the post content, however you can also insert PHP code that will get called when the submission is being processed (and any outputted info gets added to the post content).

For some examples, on the support forums, the Append to Content widget has been used to use the value set in Custom Field as the Title and to use the Submitter's username as Title