WordPress.org

Plugin Directory

Simple Subscribe

Simple Subscribe is the subscribe plugin you have been waiting for. It's simple to use, yet powerful, bulletproof and developers friendly. Automa

Developer's Guide

Intro

Apart from being able to use widgets and shortcodes in your WordPress installation to display subscription and unsubscription forms, as a developer, you sometimes need more methods of controlling your content and theme behaviour. But before we jump on php examples, I'm gonna list styling used by this plugin so you can amend the look of forms and messages in the front end. There's a stylsheet with some styling for these form included in front-end of the website, if you wish to not load my stlyes, just turn them off in Subscribers > Settings. So here goes the styles:

/* General */
span.error {} // error message
span.success {} // success message

/* Widgets */
.widgetGuts {} // widget insides
.widgetGuts dt {} // odd / even rows
.widgetGuts dd {}
.widgetGuts dt label { } // label field
.widgetGuts dt label.required { } // required label field
.widgetGuts dd input { } // input fields
.widgetGuts dd textarea { } // input fields
.widgetGuts dd input.button { } // submit button

/* Shortcodes */
.shortcode,
.widgetGuts.shortcode {} // either one of them, guts of shortcode
.shortcode h3 {} // form title
.shortcode table {} // form table
.shortcode table tr {} // table row
.shortcode table tr.required {} // required
.shortcode table tr th {} // holds label
.shortcode table tr td {} // holds input / textarea
.shortcode table tr th label {} // label
.shortcode table tr td input,
.shortcode table tr td textarea {} // input fields
.shortcode table tr td input.button {} // submit button

Now when styles are out of the way, let's look at those dev examples.

Examples

Let's check what we can do, we're gonna be using class called Developers. To retrieve an object of our form we simply call:

<?php
    // get subscription form
    $subscriptionForm = \SimpleSubscribe\Developers::getSubscriptionForm();

    // or unsubscription one, whichever one you need
    $unsubscriptionForm = \SimpleSubscribe\Developers::getUnsubscriptionForm();
?>

With the form object we can do wonders, consider this code:

<?php
    // get form object
    $subscriptionForm = \SimpleSubscribe\Developers::getSubscriptionForm();

    // check if form was submitted
    if($subscriptionForm->isSubmitted()){
        // form was submitted
    }

    // check if form was submitted and was valid = that means, there were no errors
    // and subscriber was successfully added / or unsubscribed (depends on which form we have in our object)
    if($subscriptionForm->isSubmitted() && $subscriptionForm->isValid()){
        // form was submitted - and valid, saved in db show your messages.
    }

    // check if form was submitted and had erros, those can be non-valid fields,
    // subscriber with same address already in system, etc.
    if($subscriptionForm->isSubmitted() && $subscriptionForm->hasErrors()){
        // dump erorrs
        dump($subscriptionForm->getAllErrors());
        // Note: method $subscriptionForm->getAllErrors() retrieves all errors, you can list them using foreach
        // or save them, do whatever you wish to do.
    }

    // display form
    echo $subscriptionForm;

Advanced Example

That is some funky stuff isn't it. Let's create a life like example for ourselves, one used in everyday situations. Imagine that we have a website with for example a modal window, with a nice subscription form. That modal window is a hidden element that appears if some clicks on button called "Subscribe". The form shows up in a modal window, everything is great, but what happens when you send the form? Since we don't use ajax calls to submit the form, it's going to refresh the whole page thus making the modal window element hidden again with keen information about form being successfully sent or not. Now that is excactly the case where we use Developers class instead of shortcodes and widgets, and help ourselves to control that situation. Consider this code:

<?php
        // get our subscription form
        $subscriptionForm = \SimpleSubscribe\Developers::getSubscriptionForm();
        // with this we determine modal windows class, since it's hidden automatically,
        // with every submission, we should make it visible, therefore add class "visible"
        $modalWindowVisible = $subscriptionForm->isSubmitted() ? 'visible' : '';
        // just empty variable to be filled with errors / success message
        $subscriptionMessage = '';
        // is it valid or not?
        if($subscriptionForm->isSubmitted() && $subscriptionForm->isValid()){
            // it is, this is our messages
            $subscriptionMessage = 'You have succesfully subscribed, e-mail is on it\'s way!';
        } elseif($subscriptionForm->isSubmitted() && $subscriptionForm->hasErrors()) {
            // it's not! get error messages in variable
            $subscriptionMessage = print_r($subscriptionForm->getAllErrors(), TRUE);
        }
    ?>
    <style type="text/css">
        .modalWindow { display: none; }
        .modalWindow.visible { display: block; }
    </style>
    <div id="modalWindow" class="modalWindow <?php echo $modalWindowVisible; ?>">
        <?php
            // print message, if any
            echo $subscriptionMessage;
            // display form
            echo $subscriptionForm;
        ?>
    </div>
    <button onclick="displayModal()">Show Modal</button>
    <script type="text/javascript">
        function displayModal(){
            document.getElementById("modalWindow").className = "visible";
        }
    </script>

Right, let's go through this code again, it's pretty straightforward. At first, we create an instance of our form, we check if it was submitted, if it was - no matter if correctly or not, we should always display our hidden modal window, so people can see it straight away after the page reloads - we set the modal window class to "visible".

After that it's simple code, just to show working example of that logic, you can copy and paste this code or change, amend, whatever you wish to do.

Requires: 3.3 or higher
Compatible up to: 4.1.5
Last Updated: 2015-3-22
Active Installs: 10,000+

Ratings

3.4 out of 5 stars

Support

0 of 12 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
1 person says it's broken.

0,1,0
100,1,1
100,1,1
100,1,1
0,3,0 0,1,0 100,1,1
67,3,2
100,1,1
50,2,1
0,2,0
0,1,0