=== Plugin Name === Contributors: the_dead_one Donate link: http://tinyurl.com/yvgcs9 Tags: anonymous, posting, users, post, form, admin, submit, submissions, unregistered users, uploads, downloads, categories, tags, custom fields, captcha, custom posting interface, plugin, custom, widget, akismet, ajax Requires at least: 2.3 Tested up to: 2.5.1 Stable Tag: 0.12 This plugin allows you to add custom posting forms to your website that allows your readers (including non-registered) to submit posts. == Description == This plugin allows you to add highly customisable forms to your website that allows non-registered users and/or subscribers (also configurable) to submit posts. The posts are kept in "draft" until an admin can publish them (also configurable). It can optionally use Akismet to check if submissions are spam. **Version 0.12 introduces the Form Hacker which allows admins the power to modify the form code from within the plugin as opposed to hacking the plugin source code. Nearly all messages to the user are configurable now.** TDO Mini Forms has been used to turn Wordpress into a [Forum](http://thedeadone.net/software/tdo-forum-wordpress-theme/) and a [Contact Manager](http://www.slipfire.com/wp-crm-58.htm)! The plugin provides an extensive moderation view so administrators and editors can see posts awaiting approval and publish or delete them. Administrators can also ban specific users and IPs from using the form. Administrators can also "Trust" specific users. This means that when they use the form, their posts are automatically published. This does not give them any other rights or permissions using the Wordpress software, it only affects usage of the form. This applies to user and IP bans as well. There is even an option to automatically trust users after so many approved submissions. (It should be noted that submissions from users that can already publish using the normal Wordpress UI, will be automatically published.) Administrators can configure the forms using drag and drop "widgets". They are based on the same model as Wordpress' built-in Theme widgets and it is possible to write your own. With 0.7, more options are available and it is now much easier to integrate with your theme. You don't even need to modify your theme any more to display submitter information and you can even add a form as a sidebar widget to your form. Registered users have access to a "Your Submissions" page which lists their current submissions awaiting approval and links to their approved submissions. * [Demo Site]( http://thedeadone.net/forums ) = Features = * Integration with Akismet to prevent Spam * Highly customisable: Create your forms using a Widget interface and then hack it to make it work how you like! * Create as many forms as you like. * Put a form in your sidebar using a widget for your Theme. * Submit pages instead of posts. * Simple Question and/or Image Captcha. * Add Custom Fields to your Forms. * QuickTags support for Forms. * Upload Files and can be attached to posts. Uses Wordpress' core to create thumbnails if applicable. * Submitters can be notified if post approved or rejected. * Allow users to select category and tags. * Ban users and IPs. * Control what roles can access the form. * Can automatically create a page with form for you. * Can automatically modified author template tag with info about submitter. * Can, optionally, automatically allow submissions to be published. * Throttle number of submissions by user and/or IP * Optionally Queue published posts * Numerous widgets for your theme, including a list of the top submitters * And many more... The Import/Export feature has been temporarily disabled in this release due to incompatibility with the Form Hacker. **Verision 0.11 provides intregration with Akismet, Submission Throttling, Import and Export of Form settings, Queuing Approved Post, Top Submitter theme widget and numerous bug fixes!** **With version 0.10.3, "Bad Data" errors and register_global issues should be a thing of the past!** **Version 0.10.2 provides compatibility with Wordpress 2.5!** **Version 0.10 is a big upgrade. You will not be able to roll back to previous versions after this install** **Version 0.7 is a major reworking of the code. Make sure to follow the upgrade instructions if you are using a version prior to this!** == Installation == 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`. 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 is **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. = Creating a Form = To start, go to "Form Manager and 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. The forms are listed at the top of this menu, so choose 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 Form Widgets. 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 acts 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: `` 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. == Frequently Asked Questions == = Where do I get the latest updates and news on TDO Mini Forms? = [TDO Mini Forms News]( http://thedeadone.net/index.php?tag=tdomf ) and here is the [RSS Feed]( http://thedeadone.net/index.php?tag=tdomf&feed=rss2 ). = Where is the best place to get support for this plugin? = You can use the [TDOMF Support Forum]( http://thedeadone.net/forum ) or you can post on [Wordpress.org's Support Form]( http://wordpress.org/tags/tdo-mini-forms#postform ). = How do I add a form to a page or post? = You can use the button in the options menu to create a page automatically. Or instead you can add: `[tdomf_form1]` to any post or page. The plugin will replace this with your Form 1. If you have multiple forms, each form has an ID. Just replace the '1' with the correct form ID. You can add it to your template directly using this template tag: `` = How do I display the submitter info? = There are options to automatically modify the the_author tag with submitter information if available and also to append submitter information to the end of the post. If thats not good enough for you, you can use the template tag: `` = What template tags are available? = (Replace '1' with the ID of the form you are interested in) ` Link to form ` `` `` These tags must be used within the loop: `` `` `` The tdomf_get_the_submitter_email template tag can be used to get the gravatar icon for a submitter. = I want to add custom fields! = With v0.9, you can! There is now a Custom Field widget avaliable to add to your form. Currenly only text fields and text areas are supported but future versions will support check boxes, drop down lists, radio groups, etc. = I want to allow my readers to attach a image to a submission? = With v0.8, you can allow users to upload files. You can specify what files can be uploaded and how big. You can also optionally have the upload files automatically added to the post as an image, link or a Wordpress attachment. To add the option to upload files, as admin, go into the TDOMF menu and then the widgets menu. On that page you can drap and drop widgets. Just drag and drop the "Upload Files" widget. = I want to allow only certain people to access the form = The best way to do this is to use Wordpress roles. Create a role using the [Role Manager Plugin](http://redalt.com/Resources/Plugins/Role+Manager "Role Manager Plugin"). This plugin has nothing to do with me. Make sure it is not the default role and that it can't `edit_other_posts` or `publish_posts`. Then you can use the TDOMF options page to set that as the only role that can access the form. If you don't want people to have to register, you might try looking at this plugin: [Wordpress OpenID Plugin](http://verselogic.net/projects/wordpress/wordpress-openid-plugin/ "Wordpress OpenID Plugin"). This plugin has nothing to do with me. This plugin allows people to use an OpenID identity to login to your Wordpress site. If the user has an account on Wordpress.com, LiveJournal, Yahoo and numerous other sites, they can log in using that account and once they have logged in, you can assign them to the right role. Another suggestion, but much less secure and not recommended, is to have the page where you have the form, password protected and only send the page link and password to the people you want to access the form. = I want submissions, even from unregistered users, be published automatically! = You can disable moderation in the options menu for a specific form and all posts will be published. However such posts get passed through Wordpress' kses filters automatically to remove nasty scripts. = When people submit posts with YouTube embedded code, it gets stripped! = Enable moderation and it'll work. If you disable moderation, posts get passed through kses to remove nasty scripts before being published. This removes YouTube code. If you have to approve posts, you can make sure no-one has snuck in something tricky. Alternativily you can use a custom field. Add the Custom Field widget to your form, set it as a URL and ask your submitters to add the URL of the YouTube video they want to include. Then in your theme, you can use the Custom Fields template tags to automatically display the YouTube video underneath the submitted post. Or you can use another plugin that gives you tags to support YouTube and have the Custom Field append the YouTube link with the tags to your post. = Can we use TinyMCE, FckEditor, Niced for writing posts? = I have spent some time exploring the use of TinyMCE (and to a lesser degree FckEditor) for TDO Mini Forms. Both libraries provide a WYSIWYG or "Rich Text" editors in place of your bog-standard text area. Wordpress' write screen using a heavily modified version of TinyMCE. I haven't settled on the right method to do this yet. However you can easily integrate TinyMCE without modifying any of TDO Mini Forms. Grab the latest copy and installed it somewhere on your website and then follow the directions on how to replace a text area with TinyMCE. This can be used to even change your comment input field. = I want to add add tags to QuickTags such as embed video, etc.? = Right now there is no user interface for adding your own tags to quicktags. Feel free, however, to modify `tdomf-quicktags.js.php` to add any tags you want. = I want to display some information about the upload files? = In later versions, proper template tag support will be added. However, for the moment you can use: `// Gets the name of the first uploaded file for post $post_ID get_post_meta($post_ID, "_tdomf_download_name_0"); // Gets the type of the first uploaded file for post $post_ID get_post_meta($post_ID, "_tdomf_download_type_0"); // Gets the download count of the first uploaded file for post $post_ID get_post_meta($post_ID, "_tdomf_download_count_0"); // Gets the path to the first uploaded file for post $post_ID get_post_meta($post_ID, "_tdomf_download_path_0"); // Gets the command output for the first uploaded file for post $post_ID (if avaliable) get_post_meta($post_ID, "_tdomf_download_cmd_output_0"); // Gets the name of the second uploaded file for post $post_ID get_post_meta($post_ID, "_tdomf_download_name_1"); // And so on...` = Uploading a bmp file causes errors! = If you have the options for attachments and thumbnail generation turned on for Upload Files and you try to upload a *.bmp (bitmap) image, you'll get an error like this: `Warning: imageantialias(): supplied argument is not a valid Image resource...` Wordpress does not support bitmaps for thumbnails so you cannot use bitmaps for thumbnail generation. = I can't upload files! : safe_mode and open_basedir issues = First step, make sure you can upload with the normal Wordpress admin UI. If you can't then your not going to be able to upload with TDOMF until that is sorted. If you do and you get an error with something like this `Warning: mkdir() [function.mkdir]: open_basedir restriction in effect` or `Warning: mkdir(): [function.mkdir]: SAFE MODE Restriction in effect` Then you host has restricted where you can create and upload files. Safe mode is particularly bad because it'll fail in unexpected ways. Ultimately the best solution is not to use safe mode or open_basedir but you may not have the option to do that. The best solution is to use a folder to store uploads that does not break safe mode. If you can upload with the normal wordpress interface then you can use something like /wp-content/uploads. Remember also that you cannot use symbolic links in your path to get around open_basedir restrictions. You can enable extra log messages from the options screen to see more detailed messages about file uploading. You can also check your "phpinfo()" from the main TDOMF page. = Having submitted posts not included on your main page = This is outside the scope of TDOMF as TDOMF only enables people to submit posts. However you can use a plugin like [Advanced Category Excluder Plugin](http://wordpress.org/extend/plugins/advanced-category-excluder/ "Advanced Category Excluder Plugin"). This plugin has nothing to do with me. You could have posts submitted to a specific category that is excluded from your main blog. = I'm getting "Bad Data" errors when I submit posts = * Make sure you disable any caching plugins on the form page. * Try changing the Form Verification Options to "Wordpress nonce" (or "None" if you are really desperate) * Try changing the Form Session Method to use the database = Getting TDO Mini Forms to work with WordpressMU = [Installing TDOMF plugin on WordPress MU](http://www.newlife.com.ua/blog/2008/04/29/installing-tdomf-plugin-on-wordpress-mu/) = Credits = I've used code in TDOMF that I've found in the wild so some credit is due to these authors for making their source code avaliable for re-use. PHP Function to create a random string based on (http://www.tutorialized.com/view/tutorial/PHP-Random-String-Generator/13903) PHP Function to validate an email address based on (http://www.ilovejackdaniels.com/php/email-address-validation/ ) PHP Function to turn a file size in bytes to an intelligable format based on (http://www.phpriot.com/d/code/strings/filesize-format/index.html) Quicktags Javascript script taken from (http://www.alexking.org/) Freecap (PHP Image capatcha) taken from (http://puremango.co.uk/) Customfield Select Box javascript based on (http://www.mredkj.com/tutorials/tutorial006.html) PHP Function to display a human readable time interval based on a function I found here (http://ie2.php.net/time) Checkbox support in the Categories Widget initially added by [Sillybean](http://www.sillybean.com) == Screenshots == 1. The Form as displayed to non-registered users 2. The Moderation page (v0.6) (Wordpress 2.3) 3. "Your Submissions" page for registered users (Wordpress 2.3) 4. The Moderation page (v0.7) for approved submissions (Wordpress 2.3) 5. The overview page (Wordpress 2.3) 6. Constructing your form using "widgets" (Wordpress 2.3) == Known Bugs == * An issue with having the latest MoreFields plugin (v0.6.7) and TDO-Mini Forms (v0.10.2) has been reported. Not yet investigated. (http://thedeadone.net/forum/?p=212) * If you deactivate the plugin at a later date, links to uploaded files will break (as they use a wrapper in the plugin). However with v0.9.3, you can set an option in the "Upload Files" widget to use direct links instead of the wrapper. In v0.10.3, the default is to use direct links but you can switch back to the handler if this does not work correctly for you. * Uploading a bmp image with attachment and thumbnail options turns on causes an error. Wordpress does not support bitmaps for thumbnail generation. * Form does not validate as XHTML. I'll fix this soon I swear! :) * An clash with using the WP-United plugin and TDO-Mini Forms (v0.10.4) has been reported. Not yet investigated. (http://thedeadone.net/forum/?p=266) * The queuing functionality may get the time wrong if period set to greater than an hour == Version History == = v0.12: 13th June 2008 = * AJAX (with fallback support) * Small bug in that validation widgets were not being called properly if they use the action "tdomf_validate_form_start" (such as any multiple instant widgets like 1 Question Capatcha and the Image Capatcha. Same also for preview. * Redirect to published post option * Initial implementation of Form Hacker * Text Widget now uses Form Hacker macros * Log now has size limit! * Categories Widget now supports radio buttons and checkboxes * Fixed a minor bug in the widgets panel where you had to reload the page after you saved a change in the number of any of the multiple widgets * Append widget * Upgrade notice * New Template Tags: tdomf_get_the_submitter_email and tdomf_the_submitter_email = v0.11.1: 23rd May 2008 = * Using a dollar sign plus a value in a input field would cause the first two digits to disappear - now fixed. * Fixed a mistake in the post scheduling, GMT offset would kick in if time greater than an hour * Added times and list of scheduled posts to Your Submissions * Corrected some formatting mistakes on the options page * Added a pot file and removed the po file. = v0.11: 22nd May 2008 = * Fixed a small behaviour issue in generate form where it would keep the preview, even after reloading the page! * Integreted with Akismet for Spam protection * Fixed an issue with "get category" widget where it would forget it's settings occasionally * Increased the number of tdomf news items and added an list of the latest topics from the forum to the overview page * Published Posts can now be automatically queued! * Fixed "Your Submissions" links for users who are not-admin such as Editors * Can add throttling rules to form * Can now view tdomfinfo() in text and html-code formats * Import and Export individual Form settings * Top Submitter Theme Widget = v0.10.4: 17th April 2008 = * Fixed a bug that made TDOMF incompatible with PHP5 (see uniqid) * Fixed a bug where some widgets were not making it to the form when the form is generated. This was a mistake in the "modes" support added in v0.10.3. = v0.10.3: 16th April 2008 = * Fixed a bug in the random_string generator: it did not validate input and I've been using a value that's too big (which meant it could return 0) * Widgets now support "modes" which means widgets can be filtered per form type. Right now that means widgets that don't support pages will not appear, if the form is for submitting pages. * Can now choose how to verify an input form: original, wordpress nonce or none at all * Implemented a workaround for register_global and unavaliablity of $_SESSION on some hosts * Fixed double thumbnail issue in WP2.5 = v0.10.2: 2nd April 2008 = * Fixed a bug if you reload the image capatcha, it would not longer verify * Added a flag `TDOMF_HIDE_REGISTER_GLOBAL_ERROR` in `tdomf.php` that can be set to true to hide the `register_globals` errors that get displayed. * WP2.5 only: Can now set a max width or height for widgets control on the Form Widgets screen. * Compatibily with Wordpress 2.5 = v0.10.1: 13th March 2008 = * Fixed a bug when if you inserted an upload as an attachment it would overwrite the contents of the post. * Fix to categories widget where widget on other forms than the default would forget it's settings at post time. * Custom Field widget was ignoring append format for multi-forms = v0.10: 12th Feburary 2008 = * Suppressed errors for is_dir and other file functions just in case of open_basedir settings! * Use "get_bloginfo('charset')" in htmlentities in widget control. Hopefully this will finally resolve the issues with foreign lanaguage characters * Multiple Form Support * Widgets that validate know if it's for preview or post. Certain validation should only occur at post like captcha and "who am I" info for example. * Option to specify the max number of instances of a multi-instant widget per form * Can now set a form to submit pages instead of posts. * Fixed a bug where customfield textfield would submit empty values for the custom field if you had magic quotes turned off. * Update the "Freecap" Image Captcha so that the files get included in the release zip Wordpress creates. = v0.9.4: 7th January 2008 = * Added "Set Category from get variables" widget * If moderation turned off, when post published, redirect to published post page. * Fixed Custom Field widget javascript. Now works properly in Firefox (why does Firefox break on code that works in Opera and IE all the time?) * Image Captcha Widget * Updated all text fields input (and output) to use htmlentities. Hopefully this will cure foreign character input/output issues and weird re-encoding issues with widget settings. * Word count or character limit on post content * Theme Widget that displays the form! * Add "credits" to readme.txt for various places I pull source and other stuff from * Added a "Read More..." `` tag to the quick tags * Fixed Bug when multiple notifications to submitter when post is edited after approval = v0.9.3: 1st December 2007 = * Fixed customfield textfield control radio group in Firefox * Fixed customfield textfield ignoring size option * Fixed customfield textarea putting magic quotes on HTML * Fixed customfield textfield not handling HTML and quotes well. * Fixed customfield textfield not handling foreign characters well. * Fixed customfield textarea quicktag's extra button only working on post content's quicktag's toolbar * Updated customfield to optionally can automatically add value to post with a user defined format * Removed any "short tag" versions (i.e. use "