Text Size

Doculicious

Dynamic Element Text in Doculicious

Version 3.5 of Doculicious, our online tool to help anyone create fillable pdf forms, was released a few weeks ago, and in addition to some performance enhancements a great new feature was added which we are calling "Dynamic Element Text". Basically, this lets you display the text value from a field in your form elsewhere in the final PDF. So if you ask for someones First Name and Last Name on page 1 of the form, you can then show those values later in your final PDF, without having to ask the user to fill them in on every page you need them. Details on how to use this feature can be found here on the Documentation site.

We also made many performance enhancements in this release, which will give improvements across most functions of Doculicious, but especially the entries page when viewing report of your data and for deleting data from your entries or trash. The PDF upload conversion tool has been tweaked to create nicer looking templates from uploaded PDF files. Previously the text could look a little jaggy, but now it is very smooth and looks much nicer. 

Enhanced page movement features in Doculicious

We've had a lot of requests from users for more advanced functions for adding pages to templates in Doculicious, our tool to help anyone make web generated PDF files, so we thought we'd add these in the latest release. Previously you could only add new pages at the end of a template, but now we've added the ability to add pages anywhere, as well as move pages around to anywhere within the template too. The new interface looks like this:

 

The page column lists all the pages in your template. You can click on this link to change to that page for editing. Clicking on the red (x) will delete the page. Be careful with this feature, as you cannot get a deleted page back. To move pages you can choose the new page number in the dropdown. So to make page 3 the first page, you sould choose "to Page 1" in the drop down next to page 3 and then click the move button. This would move page 3 to page 1, and push page 1 and 2 down so that they would become page 2 and 3.

Doculicious PayPal IPN

<?php
        //CONFIGURATION OF DEFAULT VARIABLES
        //Your PayPal Seller email address (Change to your PayPal sandbox email for testing)
        $paypal_email = "chris@digitalcarpenter.com.au";
        
        //The currency you use for your PayPal buttons
        $currency = "USD";
        
        //The cost of your form. Make sure you add the cents
        $cost = "10.00";
        
        //The email address used to send you notification emails
        $from_email = "email@YOURDOMAIN.com";
        
        //The email address used to receive notification emails on success or failure
        $notification_email = "notifyme@YOURDOMAIN.com";
        
        //Your API access ID and Security key from the API link on the dashboard 
        $api_access_id = "xxxxxxxxxxxxxxxx";
        $api_security_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
        //Send this back to PayPal to validate the fields
        $req = 'cmd=_notify-validate';
        
        //Add each field to a value we will post back to PayPal
        foreach ($_POST as $key => $value) 
        {
                $value = urlencode(stripslashes($value));
                $req .= "&$key=$value";
        }
        
        //Post back to PayPal
        $header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
        $header .= "Content-Type: application/x-www-form-urlencoded\r\n";
        $header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
        
        //PayPal Production
        $fp = fsockopen ('ssl://www.paypal.com', 443, $errno, $errstr, 30);
        
        //PayPal Development - uncomment for testing
        //$fp = fsockopen ('ssl://www.sandbox.paypal.com', 443, $errno, $errstr, 30);
        
        if (!$fp) 
        {
                //Send an email on failure with the error message (errstr) from paypal
                $from = "From: " . $from_email;
                $to = $notification_email;
                $subject = "HTTP ERROR";
                $body = $errstr;
        
                mail($to, $subject, $body, $from);      
        }
        else
        {
                fputs ($fp, $header . $req);
                while (!feof($fp)) {
                        $res = fgets ($fp, 1024);
                        if (strcmp ($res, "VERIFIED") == 0) 
                        {
                                //These are only the fields required for this simple purchase. See the following page for all variables you can get at:
                                //https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_html_IPNandPDTVariables
        
                                //The custom field contains the unique Doculicious Document ID of the completed form and the item_number contains the Template ID.
                                $item_number = $_POST['item_number'];
                                $document_uid = $_POST['custom'];
                                
                                $item_name = $_POST['item_name'];
                                $payment_status = $_POST['payment_status'];
                                $payment_amount = $_POST['mc_gross']; 
                                $payment_currency = $_POST['mc_currency'];
                                $txn_id = $_POST['txn_id'];
                                $receiver_email = $_POST['receiver_email'];
                                $payer_email = $_POST['payer_email'];
 
                                //Check that all the variables are valid        
                                if (($payment_status == 'Completed') &&                 //check the payment_status is Completed
                                        ($receiver_email == $paypal_email) &&           //check that receiver_email is your Primary PayPal email
                                        ($payment_amount == $cost ) &&                  //check they payed what they should have
                                        ($payment_currency == $currency))               //check that payment_amount/payment_currency are correct 
                                {                                                       
                                        //OK, everything is fine, so now process their order.
                                        
                                        //We are going to get the completed PDF from Doculicious and save it to our website and then send the purchaser an email with a link to where they can download it.                                     
                                        //The full authorization string - needed for the header. API access and security codes are set at the top of the page
                                        $auth = "authorization:DCS " . $api_access_id . ":" . $api_security_key;
                                        
                                        //This is the URL to get completed the completed PDF for a specific entry. 
                                        $resource_uri = "https://api.doculicious.com/entries/" . $item_number . "/" . $document_uid . ".pdf";
                                        
                                        //Initialize curl and set URL and other appropriate options
                                        $ch = curl_init();
                                        curl_setopt($ch, CURLOPT_URL, $resource_uri);
                                        
                                        //Send the authorization details in the header
                                        curl_setopt($ch, CURLOPT_HTTPHEADER, array($auth));
                                        
                                        //This tells curl to return the actual result of the API call (ie, the PDF or XML error message). Returns False if HTTPS get fails.
                                        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE );
                                        
                                        //SSL Settings
                                        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
                                        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
                                    
                                        //Execute the API call
                                        $output = curl_exec($ch);
                                        
                                        if(!curl_errno($ch))
                                        {
                                                $info = curl_getinfo($ch);
 
                                                //Use this for debugging if needed
                                                //echo("<pre>" . var_export($info, true) . "</pre>");
                                                //die();
                                                
                                                //200 means success.
                                                if($info['http_code'] == 200)
                                                {       
                                                        //Save the PDF file to our website
                                                        $my_file = "/YOUR/WEB/ROOT/customer-files/" . $document_uid . ".pdf";
                                                        $fh = fopen($my_file, 'wb') or die("can't open file");
                                                        fwrite($fh, $output);
                                                        fclose($fh);
                                                        
                                                        //Create the URL where the customer can download their PDF
                                                        $download_url = "http://www.YOURDOMAIN.com/files/" . $document_uid . ".pdf";
                                                        
                                                        //Send an email to the purchaser with a link to download the PDF file
                                                        $from = "From: " . $from_email;
                                                        $to = $payer_email;
                                                        $subject = "Your PDF form is ready.";
                                                        $body =  'Thank you for your purchase. Please use the link below to download your PDF file:' . PHP_EOL . PHP_EOL .  
                                                                         $download_url . PHP_EOL . PHP_EOL .  
                                                                         'Regards,' . PHP_EOL .
                                                                         'YOUR NAME' . PHP_EOL;
                                                                
                                                        mail($to, $subject, $body, $from); 
                                                }
                                                else //there was an error, so output the content
                                                {
                                                        header("Content-type: " . $info['content_type']);
                                                        echo $output;
                                                };
                                        }
                                        
                                        // close cURL resource, and free up system resources
                                        curl_close($ch);
 
                                        //Send an email to yourself with details of the purchase
                                        $meFrom = "From: " . $from_email;
                                        $meTo = $notification_email;
                                        $meSubject = "PayPal order completed.";
                                        $meBody =  'Someone just purchased a PDF document using our Doculicious form. Here are the details:' . PHP_EOL . PHP_EOL .  
                                                           'Item Name: ' . $item_name . PHP_EOL .  
                                                           'Item Number: ' . $item_number . PHP_EOL .  
                                                           'Document UID: ' . $document_uid . PHP_EOL . 
                                                           'Price: ' . $payment_amount . PHP_EOL . 
                                                           'Transaction ID: ' . $txn_id . PHP_EOL . 
                                                           'Purchaser Email: ' . $payer_email . PHP_EOL;
                                                
                                        mail($meTo, $meSubject, $meBody, $meFrom);           
        
                                }
                                else
                                {
                                        //Something went wrong, so email yourself with the details
                                        $meFrom = "From: " . $from_email;
                                        $meTo = $notification_email;
                                        $meSubject = "PayPal IPN failed.";
                                        $meBody =  'Something went wrong with a PayPal order. Here are the details of the transaction:' . PHP_EOL . PHP_EOL .  
                                                           'Item Name: ' . $item_name . PHP_EOL .
                                                           'Item Number: ' . $item_number . PHP_EOL .   
                                                           'Document UID: ' . $document_uid . PHP_EOL . 
                                                           'Price: ' . $payment_amount . PHP_EOL . 
                                                           'Transaction ID: ' . $txn_id . PHP_EOL .
                                                           'Payment Status: ' . $payment_status . PHP_EOL . 
                                                           'Currency: ' . $payment_currency . PHP_EOL . 
                                                           'Receiver Email: ' . $receiver_email . PHP_EOL . 
                                                           'Purchaser Email: ' . $payer_email . PHP_EOL;
                                                
                                        mail($meTo, $meSubject, $meBody, $meFrom);
                                }
                        }
                        else if (strcmp ($res, "INVALID") == 0) 
                        {
                                //Paypal didn't like what we sent.
                                $meFrom = "From: " . $from_email;
                                $meTo = $notification_email;
                                $meSubject = "PayPal - Invalid IPN";
                                $meBody = "We have had an INVALID response. Check that PayPal hasn't changed their IPN API.";
                                mail($meTo, $meSubject, $meBody, $meFrom);
                        }
                }
                fclose ($fp);
        }
?>

Doculicious PayPal Form

<html>
        <head>
                <title>PayPal Form</title>
        </head>
        <body>
        <?php 
                
                //Check that the doculicious URI is set - It should be
                if(isset($_GET['dclcs_entry_uri']))
                {
                        $uri = $_GET['dclcs_entry_uri'];
                        
                        //Put all the parts of the URI into an array
                        $uri_parts = explode("/", $uri);
                        
                        //Get the last item in the array. This is the uniqeID of the submitted form 
                        $document_id = array_pop($uri_parts);
                }
        ?>
                <!-- Display a message to the customer. -->
                <div style="width: 450px; margin: 0 auto;">
                        <p>Thank you for using our service. Please click the button below to pay for your form using PayPal. Once confirmed we will send through a link where you can download the completed PDF file.</p>
                        
                        <div align="center">
                                <form action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post">
                                        <input type="hidden" name="cmd" value="_s-xclick">
                                        <input type="hidden" name="hosted_button_id" value="957FC8G74KTR4">
                                        <input name="custom" type="hidden" value="<?php echo($document_id);?>" />
                                        <input type="image" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
                                        <img alt="" border="0" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/scr/pixel.gif" width="1" height="1">
                                </form>
                        </div>  
                </div>  
        </body>
</html>

How To - Sell your PDF files by integrating Doculicious and PayPal

We've had a lot of requests for payment integration with Doculicious, and this is something we've thought about adding. One issue is that Doculicious is a little different than other form builders - a lot of the time the people who contact us want to sell the output of the form itself and not use the form as just an order form. People are selling Visa applications, Government forms, Award certificates and a range of other forms using Doculicious. Integrated payment within Doculicious will be a while away, so I thought the next best thing was to write a comprehensive tutorial on how to integrate Doculicious and PayPal.

This tutorial will explain how you can sell a PDF form on your website using Doculicious and PayPal, but the concepts here can easily be used to gather payment for any other type of order. After going through the tutorial, you will be able to create a process that is something like this:

  1. Customer fills in your Doculicious form from your website;
  2. When complete, they are redirected to a sales page where they can purchase the completed form for $10;
  3. They click through to PayPal and enter their payment details;
  4. They return to a Thank you page on your site;
  5. PayPal sends you an "Instant Payment Notification" informing you of the payment success or failure;
  6. On success, you send the customer a link to the completed PDF form.

This is going to be a fairly long post, so I've split it into sections and included a table of contents to make it easier to navigate. I'm going to go through the whole process - from how to set up a PayPal sandbox account for testing, to using the Doculicious API to retreive a submitted entry. So feel free to skip bits you don't need.

Table of contents

  1. Setting up a PayPal testing environment
  2. Creating a PayPal "Buy Now" button
  3. Create and configure the Doculicious form
  4. Set up your PayPal purchase form
  5. Create the PayPal IPN page
Setting up a PayPal testing environment

There are a couple of ways to test your PayPal buttons and integrations. The first, and easiest, is to use your normal business account and take advantage of the 60 day refund option that PayPal provides. This lets you cancel a transaction and all the fees will be refunded. PayPal lets you have 2 accounts - one business and one personal. So you just use your personal account to purchase from your business account and then refund after the transaction. Easy, but messy. After a small while it gets pretty annoying to keep refunding.

The second way is to use the PayPal testing environment ("the PayPal Sandbox") where you can create multiple buyer and seller accounts to test your buttons. This is much cleaner, and is pretty easy to set up.

First, go to the PayPal Developer web site and sign up for an account. Use a different email address than your other PayPal accounts. Once you are signed up, log in.

The PayPal sandbox let's you pretend to be a buyer and a seller, and create fake accounts with essentially play money and credit cards. For our purposes, we are just going to create one buyer and one seller account. Click on the "Create a preconfgured account" link.

You will then be shown a form like the following one. Select the account type as "buyer", choose an email address and make a note of the password. Make sure you add some money to the account balance.

Once created, go and do the same again, but make this one a "Seller" account. When you're done, you should have 2 accounts in your sandbox, like so:

We can now use these accounts to simulate our purchases, and also create buttons for testing without worrying about breaking our production setup. It's a good idea to write down both the email addresses and the passwords you noted down when creating them. Do this in notepad so you can access them easily later.

Remember, you need to be logged into the PayPal sandbox to use the mock buyer and seller accounts.

Whenever you make a purchase, you need to use the full buyer email address created for you. When you sell, you need to use the seller email address. Paypal also let you see all email communications. We won't be using that too much, but it is useful to know.

In the next section you need to create the button for selling your PDF, so enter the sandbox site using your pretend seller account. Click on the radio button next to the seller, and press on the "Enter Sandbox Test Site" button. A new window will display where you can log in using the password noted earlier. You are now inside the PayPal sandbox, and should recognize this as similar to your normal account screen.

Creating a PayPal "Buy Now" button

To sell our Doculicious PDF form, we are going to use a PayPal "Buy Now" button. You do this within the PayPal site by clicking on the "Merchant Services" tabk at the top, then click on the "Buy Now Button" link near the top. There are 3 steps to create your button:

Step 1 - Choose the button type and enter details

We need the Template UID here because later it is used when we call the Doculicious API.

  • The Item Name can be anything you want. 
  • The Item ID needs to be the Unique ID of your Doculicious Template. You can find this from the Doculicious Dashbord by clicking on the orange "api" link, and looking for the text labeled "Template UID".
  • Enter a Price
  • Enter the Currency
  • Continue on to Step 2

Step 2 - Track inventory, profit and loss

This step is pretty small, just make sure the check box to save the button at PayPal is clicked. You don't need to do this, but it makes it easier to edit later. When done, continue to Step 3

/p>

Step 3 - Customize advanced features

This step lets you add some advanced features, one of which is what we use to have PayPal notifiy us when a purchase is made. This is called the "Instant Payment Notification" and we can set up the URL that PayPal will notify here. There are also a few other things we can turn off, as they are not really needed, such as shipping address and customer message. If you would like this information, feel free to keep them turned on.

The IPN is how PayPal notify us of a successful payment. We don't send the completed PDF until we receive this, and it's valid!

  • Enter a URL for when customers cancel their checkout. This should be a page on your website with some information on how they can continue their purchase.
  • Enter a URL for then customers finish their checkout. This should be a page on your website that informs the customer of what they just purchased and when you will deliver it. We will go into more detail about this later when we create these pages.
  • In Advanced Variables, make sure the checkbox is clicked, and add the following line:

    notify_url=https://www.YOURWEBSITE.com/paypal/ipn.php

    (You can use HTTP here instead of HTTPS if you dont have an SSL certificate for your site, but you should really get one for security purposes.)

  • When done, click on the Create button at the bottom.

The next page will display the code that you need to put onto your website for this button to work. Make sure you copy and paste this into a text file for later. We need to make a couple of small changes before this goes onto your site. These will be outlined in a later section of the tutorial.

Create and configure Your Doculicious form

Click here to learn how to build a Doculicious form

If you are reading this tutorial, you most likely have a Doculicious form that you want to sell or integrate with a Payment gateway. If not, you can use one of the examples from the "Template Gallery" or create a new form first. You don't need anything fancy to follow this tutorial, you could even just create a basic test form to get everything working first. Once your form is created within Doculicious, you need to activate it which will automatically add it to your Doculicious Dashboard.

The Dashboard is where you can change the settings for your form. Below we explain what changes to make and why they are made. Below this is a quick summary (for those that don't like to read :)

Disable PDF download

You don't want the user to be able to download the PDF file once they have completed the form, so checking this will disable that feature.

Clicking on Disable PDF download will automatically check the Save Entries box. 

Optionally set notifications

When Save Entries is turned on, the system will allow you to set notifications. On premium accounts, you can also attach the completed PDF to the notification email, or use custom notifications to send the PDF to different email addresses depending on choices made on the form. This is a good time to set any notifications you may want to receieve. Don't use this to send the user their PDF file, as they wouldn't have paid at this point in time.

Turn on Redirect 

Please note that Redirect is a premium feature, and will not be available on free accounts.

After your user completed the Doculicious form, you want to redirect them to your payment page. So you need to check the Redirect box and enter the URL to your payment page. We will edit this page at a later step of this tutorial to add the PayPal button you created earlier, so now you can just put in the URL where you are going to put that page. It may be a good idea to create that page now so that you can test the redirect working. 

Summary

Ok, fo all you non-readers out there ... this is the quick summary of what we just did to configure the Doculicious form for PayPal integration:

  1. Turned on Disable PDF Download
  2. Turned on Redirect
  3. Entered a Redirect URL to a page with the PayPal button on it
  4. Turned on Save Entries (Optionally, added notifications.)
  5. Clicked Save
Set up your PayPal purchase form

We now need to create the page that people are redirected to after they complete your Doculicious form. This is pretty easy, and the main thing you need on this page is the PayPal button code that you copied earlier. However, we are also going to add another field which contains our unique entry ID of the submitted form. 

So, open up the page you set as the Redirect URL from the earlier step, and past in your PayPal button code. It should look similar to this:

1
2
3
4
5
6
<form action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post">
    <input type="hidden" name="cmd" value="_s-xclick">
    <input type="hidden" name="hosted_button_id" value="957FC8G74KTR4">
    <input type="image" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
    <img alt="" border="0" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

Now we need to add a small bit of PHP code before the PayPal button code. This gets the Unique ID of the entry just made so that we can send this to PayPal.

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php 
    //Check that the doculicious URI is set - It should be
    if(isset($_GET['dclcs_entry_uri']))
    {
        $uri = $_GET['dclcs_entry_uri'];
 
        //Put all the parts of the URI into an array
        $uri_parts = explode("/", $uri);
 
        //Get the last item in the array. This is the uniqeID of the submitted form 
        $document_id = array_pop($uri_parts);
    }
?>

Ok, we have the $document_id variable with the unique ID in it, so we can add a hidden field to the PayPal button code that contains this using the custom PayPal variable, which will ultimately be passed to the IPN code:

1
<input type="hidden" name="custom" value="<?php echo($document_id);?>">;

Add this line in between 2 of the hidden fields of the PayPal button.

This page will just have a PayPal button and nothing else, so you should add some more text above the button explaining things to your customer. Something like:

Thank you for using our service. Please click the button below to pay for your form using PayPal. Once confirmed we will send through a link where you can download the completed PDF file.

The completed code for the PayPal form page can be viewed here.

Create the PayPal IPN page

Ok, this is the final step - creating the PayPal IPN page. This is what links everything together to provide the PDF to your customer, and tells you that the payment was successful. You will remember that we provided PayPal the address of this page when creating our custom button, and it was something like this:

1
notify_url=https://www.YOURWEBSITE.com/paypal/ipn.php

You now need to create or edit that page and put in the PHP code which will talk to PayPal to verify the payment, then talk to Doculicious to get the completed PDF and finally email your customer with the details on how they can download the file. I will go through the file line by line explaining what we are doing. Top help you follow along, you can download an example containing all the code here.

In the first part of the IPN page we declare some default variables that are used later on in the script. This is where you customize the script with your details. The inline comments will explain what all the settings are for.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//CONFIGURATION OF DEFAULT VARIABLES
//Your PayPal Seller email address (Change to your PayPal sandbox email for testing)
$paypal_email = "chris@digitalcarpenter.com.au";
 
//The currency you use for your PayPal buttons
$currency = "USD";
 
//The cost of your form. Make sure you add the cents
$cost = "10.00";
 
//The email address used to send you notification emails
$from_email = "email@YOURDOMAIN.com";
 
//The email address used to receive notification emails on success or failure
$notification_email = "notifyme@YOURDOMAIN.com";
 
//Your API access ID and Security key from the API link on the dashboard 
$api_access_id = "xxxxxxxxxxxxxxxx";
$api_security_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
//Send this back to PayPal to validate the fields
$req = 'cmd=_notify-validate';

 

The following lines are to verify with PayPal the values that are being sent. PayPal is doing a POST to this IPN page with all the details of your transaction. What you are doing here is sending those details back so that PayPal can verify you have the right information. This is to help ensure that people can't post to your IPN page and tell you about fake transactions.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//Add each field to a value we will post back to PayPal
foreach ($_POST as $key => $value) 
{
        $value = urlencode(stripslashes($value));
        $req .= "&$key=$value";
}
 
//Post back to PayPal
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
 
//PayPal Production
$fp = fsockopen ('ssl://www.paypal.com', 443, $errno, $errstr, 30);

 

Next we check if there was a failure communicating with the PayPal servers, and if there was send an email to the notification address you defined earlier with the details:

 

1
2
3
4
5
6
7
8
9
10
11
if (!$fp) 
{
 
        //Send an email on failure with the error message (errstr) from paypal
        $from = "From: " . $from_email;
        $to = $notification_email;
        $subject = "HTTP ERROR";
        $body = $errstr;
 
        mail($to, $subject, $body, $from);      
}

 

If we got a result from PayPal, we then check if it is "VERIFIED", and if so get the POSTed values that PayPal has sent us:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
else
{
    fputs ($fp, $header . $req);
    while (!feof($fp)) {
        $res = fgets ($fp, 1024);
        if (strcmp ($res, "VERIFIED") == 0) 
        {
            //The custom field contains the unique Doculicious Document ID of the completed form and the item_number contains the Template ID.
            $item_number = $_POST['item_number'];
            $document_uid = $_POST['custom'];
                        
            $item_name = $_POST['item_name'];
            $payment_status = $_POST['payment_status'];
            $payment_amount = $_POST['mc_gross']; 
            $payment_currency = $_POST['mc_currency'];
            $txn_id = $_POST['txn_id'];
            $receiver_email = $_POST['receiver_email'];
            $payer_email = $_POST['payer_email'];

 

We need to check if some values are what we expect them to be. Payment Status should be "Completed", the price should match what we have configured, as well as the currency and reciever email address:

 

1
2
3
4
if (($payment_status == 'Completed') &&      //check the payment_status is Completed
    ($receiver_email == $paypal_email) &&    //check that receiver_email is your Primary PayPal email
    ($payment_amount == $cost ) &&           //check they payed what they should have
    ($payment_currency == $currency))        //check that payment_amount/payment_currency are correct <span _fck_bookmark="1" style="display: none; "> </span>

Once we confirm that all that is good, we can now use the Doculicious API to get the PDF and save it to our website somewhere. To do this, we are going to use CURL. First we need to set the parameters for this:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//The full authorization string - needed for the header. API access and security codes are set at the top of the page
$auth = "authorization:DCS " . $api_access_id . ":" . $api_security_key;
 
//This is the URL to get completed the completed PDF for a specific entry. 
$resource_uri = "https://api.doculicious.com/entries/" . $item_number . "/" . $document_uid . ".pdf";
 
//Initialize curl and set URL and other appropriate options
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $resource_uri);
 
//Send the authorization details in the header
curl_setopt($ch, CURLOPT_HTTPHEADER, array($auth));
 
//This tells curl to return the actual result of the API call (ie, the PDF or XML error message). Returns False if HTTPS get fails.
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE );
 
//SSL Settings
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
 
//Execute the API call
$output = curl_exec($ch);

The last line of the above snippet of code executed the cUrl request, the next bit of code will process the response we receive from Doculicious. First we check that there were not any cUrl errors, then we get information about the cUrl response so we can check if Doculicious sent us what we wanted.

The 200 result means everything went OK. If Doculicious couldn't find the PDF we asked it for, we would have gotten a 404 response, and the code below would have printed out an error message.

If everything is OK, we save the file to our website, and email the customer with a URL to where they can download it.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
if(!curl_errno($ch))
{
        $info = curl_getinfo($ch);
 
        //200 means success.
        if($info['http_code'] == 200)
        {       
                //Save the PDF file to our website
                $my_file = "/YOUR/WEB/ROOT/customer-files/" . $document_uid . ".pdf";
                $fh = fopen($my_file, 'wb') or die("can't open file");
                fwrite($fh, $output);
                fclose($fh);
 
                //Create the URL where the customer can download their PDF
                $download_url = "http://www.YOURDOMAIN.com/files/" . $document_uid . ".pdf";
                
                //Send an email to the purchaser with a link to download the PDF file
                $from = "From: " . $from_email;
                $to = $payer_email;
                $subject = "Your PDF form is ready.";
                $body =  'Thank you for your purchase. Please use the link below to download your PDF file:' . PHP_EOL . PHP_EOL .  
                                 $download_url . PHP_EOL . PHP_EOL .  
                                 'Regards,' . PHP_EOL .
                                 'YOUR NAME' . PHP_EOL;
       
                mail($to, $subject, $body, $from); 
        }
        else //there was an error, so output the content
        {
                header("Content-type: " . $info['content_type']);
                echo $output;
        };
}

The rest of the file contains some error handling, basically sending notifications when things go wrong.

The completed code for the Doculicious PayPal IPN can be seen here.

Doculicious 3.1 - Custom emails, validation and more

Another release of our web form and PDF builder - Doculicious 3.1. It's late and I'm tired, so not going to write much, but I created a new doculicious form that explains it all. The biggest change is the Custom Emails. Now you can use fields in your form to determine who gets an email with the PDF attached. Either let people type in their email address (doculicious will validate it too) or use a drop down list to determine who gets an email (or both. Yes, you can set 2 custom email options for each form). Great for when you need to send the form to different people within your company depending on some chosen field.

So, here's the sample form. If you want to see the final PDF, make sure you put in your email address and click one of the new submit buttons (which are another great feature . use your own images and turn off our default submit buttons if you don't like them). Enough talk. Sleep.

Automatically create web forms from PDF forms

I love this photo ... it sort of sums up how I feel after releasing the latest version of our online PDF web form tool, Doculicious.com: happy, a little delirious and looking to relax on the beach after a hard bit of work. Sydney's getting cold now though, so I'll probably just stay in and program some more cool features.

Anyway, this latest release has something which has been on the drawing board for a while. The ability to upload a PDF file with fields and have it converted into a web form has been requested by many of our users, and I'm happy to say that our first version of this is ready to go. Our goal with this release was to enable someone with a bunch of PDF forms to upload them and have them automatically converted to web forms. This means that if you have a PDF file with fields, you will have a working web form in minutes after uploading it to Doculicious. If the original file doesn't have fields, the system will still help, but there will be some manual work to do. I'll give some tips on re-creating a form like this very quickly, so don't worry ... if your PDF files don't have fields, this new feature will still cut the time it takes to create a form by at least half.

PDF's are messy

PDF files are not nice ordered documents that make it easy to extract text. However, they print very well, and will pretty much look the same when sent to any printer. This gave us a clue as to how to implement the form conversion. We take the uploaded PDF and generate screenshots of each page by printing to an image file. We then create a new Doculicous template and use the images of each page as a background for that page. If the PDF has form fields, we re-create each one in the correct place, ensuring that drop down lists are filled with the right options, checkboxes and radio buttons are created and using the right groups and that some of the same formatting is applied, such as text alignment. Doculicious has a great feature that will scale images to load faster when viewed on the web, but will use a larger image when output as PDF. This lets converted forms stay small for the web form, but still print nice when downloaded.  Ok, enough background, here is the detail.

Converting your PDF to a web form

Doculicious makes this really simple. Just follow these steps:

Step 1 - Go to "Your templates" and click on the "Upload form" button

This will show the "Choose file" or "Browse" button , depending on your web browser. 

Step 2 - Click to choose a file to upload

You can choose a PDF file, postscript file or image files. Only PDF have form fields, but postscript can have multiple pages, and can be useful to convert a MS Word form into a web form. Images can be used to create single page templates, and are great if your source form is a scan of a paper form.

Step 3 - Wait for the PDF to Web Form conversion to complete

It should only take a few seconds, but PDF's with many pages could take a while. When completed, refresh the page to see your new template at the top.

Step 4 - Web form goodness! You're ready to rumble

That's it. If your PDF form had fields, they should be converted properly into Doculicious elements, so all you should need to do now is load up the template and check that everything looks ok, then press publish and activate it on your dashboard. Some things you may want to consider is turning on number validation for numeric only fields and checking that each form element has a nice name or your CSV downloads may be hard to decipher. Also, you may find that some elements may not line up perfectly with the background image. In my experience text boxes all work fine, but radio buttons and check boxes may be off by a few pixels. A small nudge using the arrow keys will fix this up in no time.

My PDF doesn't have fields, what do i do?

Don't worry, atleast 50% of your form is complete. You just need to add the text boxes and move them into position. Luckily you have a nice background image that will help you do this, and Doculicious' keyboard shortcuts will help you get this done fast. We'll soon be posting a video capture of how to do this really quick, but for now make sure you use the "c" for clone keyboard shortcut. Most text fields on a PDF form are the same width, border style, font style etc. You just need to create one text field, put it in place, and then press "c" select the new element and place in the right position, then press "c" and move the new one down to the right position, then press "c" ... you get the idea. Forms that use to take 60 minutes to re-create can be done in about 10 minutes or less!

Doculicious update 3.0

This weekend we completed testing on the new version of  Doculicious, our PDF web form creator and have released it to the production site. This version is the 3rd major revision of the site, and includes a few visible changes, but also a lot of internal changes that are required for the continuing updates that will be released this year.

The visible updates released this weekend are a PDF form upload and conversion function, which allows users to upload an existing PDF form with fields, and have it converted into a Doculicious web form, ready to be used for gathering information almost straight away (depending on the original form :) I'm hugely excited about this feature, and have been playing with it for days. It's great to get a PDF file with a bunch of fields and have it automatically converted into a web form using Doculicious. It feels almost magical ... (even though I know the amount of work that went into making it happen). I'll be writing a post just on this feature with some details on how you can use it to convert your existing PDF forms to be web enabled.

The second update includes a new validation framework which saw alot of work going on in the background to allow future additions. The visible part of this release is Numeric validation for text fields and List options for text fields, allowing drop down list entry.

We plan a bunch of releases this year, and here's a teaser of some of the things we have on the drawing board:

  1. Nicer editing within the Template Workshop with things like snap to grid and multiple selection and editing of elements.
  2. Numeric calculations on text elements.
  3. Updates to the form display, including submission buttons and page controls at the bottom of forms.
  4. Ability for users to come back and edit forms before submission via the use of a password and unique URL for thier form entry.
  5. Routing of email notifications based on a list field within the template.
  6. File uploads as data within a template.

I'll try to expand on these in future blog posts.

Doculicious adds required fields and radio buttons

Doculicious, our online application that lets you generate a PDF file from a webform now lets you flag fields as required, and has a new field type, the Radio Button.