[user-submitted-posts]

Arabic                - usp-ar
Bengali               - usp-bn_BD
Czech                 - usp-cs_CZ
German                - usp-de_DE
Greek                 - usp-el
Spanish (Spain)       - usp-es_ES
Persian               - usp-fa_IR
French (France)       - usp-fr_FR
Irish                 - usp-ga
Hebrew                - usp-he_IL
Hindi                 - usp-hi_IN
Italian               - usp-it_IT
Japanese              - usp-ja
Korean                - usp-ko_KR
Dutch                 - usp-nl_NL
Norwegian             - usp-no
Punjabi               - usp-pa_IN
Polish                - usp-pl_PL
Portuguese (Brazil)   - usp-pt_BR
Portuguese (Portugal) - usp-pt_PT
Romanian              - usp-ro_RO
Russian               - usp-ru_RU
Slovenian             - usp-sl_SI
Serbian               - usp-sr_RS
Swedish               - usp-sv_SE
Turkish               - usp-tr_TR
Urdu                  - usp-ur
Chinese (Simplified)  - usp-zh_CN
Chinese (Traditional) - usp-zh_TW

Installation

How to install the plugin

1. Upload the plugin to your blog and activate
2. Configure your options via the plugin settings
3. Display the form via shortcode or template tag

More info on installing WP plugins

How to use the plugin

To display the form on any WP Post, Page, or widget, add the shortcode:

[user-submitted-posts]

Or, to display the form anywhere in your theme, add the template tag:

<?php if (function_exists('user_submitted_posts')) user_submitted_posts(); ?>

Customizing the form

There are three main ways of customizing the form:

• Plugin settings, you can show/hide fields, configure options, etc.
• Custom form template (see “Custom Submission Form” for more info)
• By using USP action/filter hooks (advanced)

USP Hooks:

Filters:
usp_post_status
usp_post_author
usp_form_shortcode
usp_mail_subject
usp_mail_message
usp_new_post
usp_input_validate
usp_require_login
usp_default_title

Actions:
usp_submit_success
usp_submit_error
usp_insert_before
usp_insert_after
usp_files_before
usp_files_after

Check out the complete list of action hooks for User Submitted Posts

More info about WordPress Actions and Filters

Custom Submission Form

Out of the box, User Submitted Posts provides a highly configurable submission form. Simply visit the plugin settings to control which fields are displayed, set the Challenge Question, configure submitted images, and much more.

There are situations, however, where advanced form configuration may be required. In order to allow for this, USP makes it possible to create a custom submission form. Here are the steps:

First, copy these two plugin files:

/user-submitted-posts/resources/usp.css
/user-submitted-posts/views/submission-form.php

Then, paste those two files into a directory named /usp/ in your theme:

/wp-content/themes/your-theme/usp/usp.css
/wp-content/themes/your-theme/usp/submission-form.php

Lastly, visit the plugin settings and change “Form style” to “Custom Form + CSS”. You now may customize the two files as desired; they will not be overwritten when the plugin is updated. For help with making basic changes to the custom form, check out the USP FAQs at Perishable Press.

Alternately, you can set the option “Form style” to “HTML5 Form + Disable CSS” to use the default USP form along with your own CSS. FYI: here is a list of USP CSS selectors.

Or, to go further with unlimited custom forms, check out USP Pro 🙂

Displaying submitted posts

User-submitted posts are handled by WordPress as regular WP Posts. So they are displayed along with your other posts according to your theme design. Additionally, each submitted post includes a set of Custom Fields that include the following information:

• is_submission – indicates that the post is a user-submitted post
• user_submit_image – the URL of the submitted image (one custom field per image)
• user_submit_ip – the IP address of the submitted-post author
• user_submit_name – the name of the submitted-post author
• user_submit_url – the submitted URL
• usp_custom_field – configurable Custom Field

There are numerous ways to display these Custom Fields. The easiest way is to visit the plugin settings and configure the options available under “Auto-Display Content”. There you can enable auto-display of submitted email address, URL, and images. Note that submitted images also are uploaded to the WP Media Library.

For more flexibility, you can use a variety of WP Template Tags (e.g., get_post_meta()) to display Custom Fields. Here are some tutorials for more information:

• WordPress Custom Fields, Part I: The Basics
• WordPress Custom Fields, Part II: Tips and Tricks

And here are some tutorials that may help with custom display of submitted images:

• Display all images attached to post
• Display images with links

Also, here is a Helper Plugin to display Custom Fields. It originally is designed for use with USP Pro, but also works great with the free version of USP.

Auto Display Images

To automatically display submitted images on the frontend, visit the plugin settings, “Images Auto-Display” and select whether to display the images before or after post content. Save changes.

Featured Images

To set submitted images as Featured Images (aka Post Thumbnails) for submitted posts, visit the plugin settings, “Image Uploads” and check the box to enable “Featured Image”. Save changes.

Shortcodes

User Submitted Posts provides a set of useful shortcodes. Check out the “Display the Form” panel in the plugin settings for examples and more information.

[user-submitted-posts]                        : displays the form on any Post or Page
[usp-login-form]                              : displays a login/register/password form
[usp_display_posts]                           : displays list of all submitted posts
[usp-reset-button url="https://example.com/"] : displays a button to reset the form
[usp_access cap="read" deny=""][/usp_access]  : limits access to specific user capability
[usp_visitor deny=""][/usp_visitor]           : limits access to visitors (not logged in) only
[usp_member deny=""][/usp_member]             : limits access to logged-in users

Here is more info about these shortcodes:

[user-submitted-posts]

Displays the post-submit form. This shortcode does not accept any attributes.

[usp-login-form]

Displays the login/register/password form. This shortcode does not accept any attributes.

To add Google reCaptcha to the form, you can use any good reCaptcha plugin. Here are a few examples:

• reCAPTCHA Lite
• Smart Captcha (reCAPTCHA)
• reCaptcha by BestWebSoft

These are not endorsements for these plugins. They have been tested and work with the USP login/register/password form.

[usp_display_posts]

Displays a list of all submitted posts. This shortcode accepts two optional attributes, “userid” and “numposts”. Examples:

[usp_display_posts]                           : default displays all submitted posts by all authors
[usp_display_posts userid="current"]          : displays all submitted posts by current logged-in user
[usp_display_posts userid="1"]                : displays all submitted posts by registered user with ID = 1
[usp_display_posts userid="Pat Smith"]        : displays all submitted posts by author name "Pat Smith"
[usp_display_posts userid="all"]              : displays all submitted posts by all users/authors
[usp_display_posts userid="all" numposts="5"] : limit to 5 posts from all users

So the shortcode attributes can be used to customize the post list as desired. Note that the Pro version of USP provides many more options for the display-posts shortcode.

[usp_gallery]

Note: This shortcode works only when added to a submitted post. It does nothing when added anywhere else.

Displays a gallery of all submitted images for the current post. Customize via the following attributes:

$size   = image size as thumbnail, medium, large or full -> default = thumbnail
$before = text/markup displayed before the image URL     -> default = {a href='%%url%%'}{img src='
$after  = text/markup displayed after the image URL      -> default = ' /}{/a}
$number = the number of images to display for each post  -> default = false (display all)
$postId = an optional post ID to use                     -> default = false (uses global/current post)

Notes: 
    Use curly brackets to output angle brackets
    Use single quotes in before/after attributes
    Can use %%url%% to get the URL of the full-size image
    Check out the source code inline notes for more info

[usp-reset-button]

Displays a button to reset the form. Accepts the following attributes:

class  = classes for the parent element (optional, default: none)
value  = link text (optional, default: "Reset form")
url    = the URL where your form is displayed (required, default: none)
custom = any attributes or custom code for the link element (optional, default: none)

Note that the url attribute accepts %%current%% for the current URL (useful when the form is displayed in the sidebar).

[usp_access]

Limits access to specific user capability. Example:

[usp_access cap="read"]
    Content for users that have "read" access
[/usp_access]

The cap attribute specifies the required capability or capabilities (comma-separated). This shortcode also accepts an optional deny attribute. The deny attribute displays a message to users who are denied access. Tip: to include markup in the deny message, you can use {tag} to display <tag>. Check out the “Display the Form” panel in the plugin settings for examples and more info.

[usp_visitor]

Limits access to visitors (not logged in) only. Example:

[usp_visitor]
    Content for for users who are not logged in
[/usp_visitor]

This shortcode accepts an optional deny attribute. The deny attribute displays a message to users who are denied access. Tip: to include markup in the deny message, you can use {tag} to display <tag>. Check out the “Display the Form” panel in the plugin settings for examples and more info.

[usp_member]

Limits access to logged-in users. Example:

[usp_member]
    Content for for users who are logged in
[/usp_member]

This shortcode accepts an optional deny attribute. The deny attribute displays a message to users who are denied access. Tip: to include markup in the deny message, you can use {tag} to display <tag>. Check out the “Display the Form” panel in the plugin settings for examples and more info.

Template tags

User Submitted Posts provides a set of useful template tags:

/*
    Display the Post-Submission Form
    Usage: <?php if (function_exists('user_submitted_posts')) user_submitted_posts(); ?>
*/

user_submitted_posts()


/*
    Display the Login/Register/Password Form
    Usage: <?php if (function_exists('usp_login_form')) usp_login_form(); ?>
*/

usp_login_form()


/*
    Display a configurable list of submitted posts
    Usage: <?php if (function_exists('usp_display_posts')) echo usp_display_posts(array('userid' => 'all', 'numposts' => -1)); ?>
*/

usp_display_posts()


/* 
    Check if post is a submitted post
    Returns true or false
    Usage: <?php if (usp_is_public_submission()) return true; ?>
*/

usp_is_public_submission()


/* 
    Get all image URLs
    Returns an array of image URLs that are attached to the current submitted post
    Usage: <?php $images = usp_get_post_images(); foreach ($images as $image) echo $image; ?>
*/

usp_get_post_images()


/* 
    Display all images
    Outputs a set of <img> tags for images attached to the current submitted post
    Usage: <?php usp_post_attachments($size, $beforeUrl, $afterUrl, $numberImages, $postId); ?>
    Parameters:
        $size         = image size: thumbnail, medium, large or full -> default = full
        $beforeUrl    = text/markup displayed before each image URL  -> default = <img src="
        $afterUrl     = text/markup displayed after each image URL   -> default = " />
        $numberImages = number of images to display for each post    -> default = false (display all)
        $postId       = an optional post ID to use                   -> default = uses global post
*/

usp_post_attachments()


/* 
    Display submitted author name and URL
    This tag displays one of the following:
        - The author's submitted name as a link (if both 'User Name' and 'User URL' fields are included in the form)
        - The author's submitted name as plain text (if 'User Name' is included in the form, but 'User URL' is not included)
        - The author's registered username as a link to the author's post archive (if 'User Name' is not included in the form)

    Usage: <?php usp_author_link(); ?>
*/

usp_author_link()


/*
    Get an array of image URLs, wrapped in optional HTML
    Syntax: <?php if (function_exists('usp_get_images')) $images = usp_get_images($size, $before, $after, $number, $postId); ?>  
    Usage: <?php if (function_exists('usp_get_images')) $images = usp_get_images(); foreach ($images as $image) echo $image; ?>
    Parameters:
        $size   = image size as thumbnail, medium, large or full -> default = thumbnail
        $before = text/markup displayed before the image URL     -> default = {img src="
        $after  = text/markup displayed after the image URL      -> default = " /}
        $number = the number of images to display for each post  -> default = false (display all)
        $postId = an optional post ID to use                     -> default = false (uses global/current post)

    Notes:
        For $before/$after parameters, use curly brackets instead of angle brackets, for example:
        usp_get_images('thumbnail', '{img src="', '" /}'); 
        // results in each image URL wrapped like: <img src="[image URL]" />

        For $before/$after parameters, use %%url%% to get the URL of the full-size image, for example:
        usp_get_images('thumbnail', '{a href="%%url%%"}{img src="', '" /}{/a}'); 
        // outputs for each image: <a href="[full-size image URL]"><img src="[image URL]" /></a>
*/

usp_get_images()

These template tags should work out of the box when included in your theme template file(s). Keep in mind that for some of the tags to work, there must be some existing submitted posts and/or images available.

The source code for these tags is located in /library/template-tags.php and shortcode-login.php.

Upgrades

To upgrade User Submitted Posts, remove the old version and replace with the new version. Or just click “Update” from the Plugins screen and let WordPress do it for you automatically.

Important! The /custom/ directory is deprecated. If you are using a custom form template, please move it to /wp-content/your-theme/usp/. For more information, check out the “Custom Submission Form” section under Installation.

Note: uninstalling the plugin from the WP Plugins screen results in the removal of all settings from the WP database. Submitted posts are NOT removed if you deactivate the plugin, reset default options, or uninstall the plugins; that is, all submitted posts must be removed manually.

Restore Default Options

To restore default plugin options, either uninstall/reinstall the plugin, or visit the plugin settings > Restore Default Options.

Uninstalling

User Submitted Posts cleans up after itself. All plugin settings will be removed from your database when the plugin is uninstalled via the Plugins screen. Submitted posts are NOT removed if you deactivate the plugin, reset default options, or uninstall the plugins; that is, all submitted posts must be removed manually.

Pro Version

Pro version of USP now available! USP Pro includes many more awesome features and settings, with unlimited custom forms, infinite custom fields, multimedia file uploads, and much, much more.

• Check out USP Pro for virtually limitless form-building action »
• Read what users are saying about USP Pro »

Like the plugin?

If you like USP, please take a moment to give a 5-star rating. It helps to keep development and support going strong. Thank you!