Build-On Tutorial:


Receipts: Lesson 1

Create a Receipt for a Donation

Lesson Overview

In this lesson you will create a script that generates a PDF receipt for a donation. Users will be able to print a receipt from the details of a Donation by using a "Create Receipt" button.

You will build onto the Donations table that already exists, creating a new print layout and a new script for the receipt. A new button will link the script to the existing Donation Card layout.

Step 1 - Create a campaign name calculation field

Create a new field in the Donation table that will concatenate the name of the campaign, if there is one, with some additional text. This will be used in a later step on the donation receipt.

  1. Open the Manage Database dialog (File > Manage > Database...) and activate the Fields tab.
  2. Select the Donation table from the Table drop-down menu
  3. Select the zz_Name_Display field and click on Duplicate to make a copy of that field.
  1. With the new field highlighted, rename the field to “Receipt_Campaign_Text” by typing that as the Field Name: and then clicking Change.
  1. Click on the Options... button to edit the calculation formula.
    1. Set the Calculation Result is drop-down to Text.
    2. Specify the following expression as the field's formula:

If ( not IsEmpty( ID_Campaign ) ; " for the " &
donation_CAMPAIGN::Name & " campaign" ; "" )

  1. Still in the Specify Calculation dialog, click on Storage Options … and select the option
    Do not store calculation results - - recalculate when needed.
  1. Confirm the storage options by clicking OK, close the calculation dialog by clicking OK, and click OK to exit the Manage Database dialog.

Step 2 - Create the Donation Receipt layout

Next, you will create a new layout that will be used for printing a donation receipt.

  1. Enter Layout mode using the Edit Layout button in the status toolbar.

    Note: You can also enter Layout mode using the View > Layout Mode menu item, or the keyboard shortcut Command-L (MacOS) / Control-L (Windows).
  2. Create a new blank layout by clicking the New Layout / Report button in the status toolbar.

    Note: You can also use the Layouts > New Layout/Report… menu item, or the keyboard shortcut Command-N (MacOS) / Control-N (Windows)
  3. In the New Layout/Report dialog, specify layout options as follows:
    1. Set Show Records from: to the DONATION table occurrence.
    2. Set the Layout Name: to "Donation Receipt".
    3. Choose Computer, then Form for the layout format.
  1. Click Finish to complete the new layout.
  2. Delete the Header and Footer parts from the new layout by selecting the Layouts > Part Setup… menu item. In the Parts Setup dialog, remove those parts using the Delete button and then click Done.
  1. Make sure the Inspector is enabled by clicking the right of the two Show/Hide Panes buttons in the status toolbar.

    Note: You can achieve the same result by selecting the View > Inspectors > Inspector menu item or by using the keyboard shortcut Command-I (macOS) / Control-I (Windows).
  1. Activate the Position tab of the Inspector.
  1. Adjust the layout size by following the steps below.

    Note: If the units in the Position tab are currently displayed as in (inches) or cm (centimeters), click on a unit label repeatedly to toggle through the units until pt (points) is displayed.
    1. Enter 576 in the Width box.
    2. To adjust the layout height, select the Body part by clicking on the box with the label "Body" on the left side of the layout, and enter 730 in the Height box.
  1. In order to add field objects to the layout, make sure that the Fields tab of the Objects pane is enabled by clicking the left of the two Show/Hide Panes buttons in the status toolbar.

    Note: You can achieve the same result by selecting the View > Objects > Fields Tab menu item.
  2. Make sure the Drag Preferences for the Labels are set to Place labels above fields when dragged to the layout.
  1. Select the _GLOBAL table occurrence from the drop-down list in the Fields tab. This is an unrelated table occurrence, but as it only contains global fields, its value will display.
  1. Click the g_Logo container field in the Fields tab and drag it onto the layout.
  2. Use the Position and Styles tabs of the Inspector to place and style the g_Logo field:
    1. Style the logo on the Styles tab to container Minimal style.
    2. Delete the “g_Logo” label by clicking on the label and pressing delete.
    3. Place the g_Logo field in the top left corner by setting the Position to Left: 16pt and Top: 8pt on the Position tab
    4. Resize the container field to the Size: Width: 56pt, Height: 56pt.
  3. Next, add a text box containing {{Current Date}} as merge text:
    1. Click anywhere in the Body part.
    2. Select the Insert > Date Symbol menu item.
    3. Position it beneath the logo field.
  4. Click the Text tool in the status toolbar to activate it.
  1. Click in the Body part and begin typing the main message body of the receipt. On the Styles tab, make sure to apply the style Label Left and then switch the style back to Default style. This will prevent the Default style from being modified.

      Dear <<donation_MEMBER::Member_Name>>,

      Thank you for your donation on <<Date_Donation>> in the amount of $<<Amount>><<Receipt_Campaign_Text>>. We appreciate your support!

      Please keep this letter as proof of donation.
  2. The text between the double angle brackets “<<>>” is a merged field. You can manually type the brackets and field name in the text block, or you can Insert it.
    1. Select the Insert > Merge field… menu item.
    2. Select any field to insert from the dialog. As needed, select other table occurrences in the drop-down above the field list.
  1. In the Styles tab of the Inspector, ensure both text boxes are set to the Default style.
  2. Select the {{Current Date}} object, and in the Data tab of the Inspector scroll down to Data Formatting. Select the Date icon, then set the Format to 12/25/2014 and set the Leading Character to Zero for both day and month numbers.
  3. Select the main message text object. You will apply formatting so the dates and currencies print correctly within the body of the letter. In the Data tab of the Inspector scroll down to Data Formatting. Select the Date icon, then set the Format to December 25, 2014.
  1. In the Data Formatting section, select the Number icon. Set the Format to Currency, and check the box to Use thousands separator.
  1. Your layout should now look similar to this:
  1. Enter Browse mode (View > Browse Mode, or Command-B (macOS) / Control-B (Windows)) to save and review your work.

Step 3 - Create a script to print the receipt

Now that you have the print layout ready, you can add the workflow to automatically print a receipt from a donation.

  1. Open the Script Workspace by using the Scripts > Script Workspace… menu item.

    Note: You can also use the the keyboard shortcut Shift-Command-S (MacOS) / Shift-Control-S (Windows).
  2. Create a new script by duplicating the Template Script, located in the "Example Scripts" folder.
    1. Rename the script “Donation - Create Receipt” (Scripts menu > Rename Script).
    2. Move it into the Member folder by dragging it into that folder.
    3. Right-click the Member folder, and select the option to Exclude from Scripts Menu (if needed).

      Note: Any time you create a new script or copy an existing one, be sure to amend the comments at the top to fit your current script.
  3. Add the highlighted steps to your new script.

    NOTE: See the next step for detailed information about the Save Records as PDF step. For the Print Setup step, make sure to choose Portrait mode for printing.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Freeze Window

Perform Script [ Specified: From list ; “Try To Commit or Halt” ; Parameter: ]

Go to Layout [ “Donation Receipt” (DONATION); Animation: None ]

Print Setup [ Restore; With dialog: Off]

Set Variable [ $path; Value: Get ( TemporaryPath ) & "certificate.pdf" ]

Save Records as PDF [ Restore ; With dialog: Off ; “$path” ; Automatically open ;Current record ; Create directories: Off ]

Go to Layout [ original layout ; Animation: None ]

Exit Script [ Result: $null ]

  1. For the Save Records as PDF step:
    1. In the Specify Options dialog, select the option to save the Current Record.
    2. In the Specify Output File dialog, enter $path as the output file and select the option to Automatically open file.
  1. Close the Script Workspace and save your script when prompted.

Step 4 - Add a button to the Donation Card layout

  1. Go to Layout mode.
  2. Navigate to the Desktop > Donation > Donation Card layout on the layout drop down menu.
  3. Select the Button tool in the status toolbar.
  1. Use your cursor to draw a button on the upper right of the Body part of the layout. Do not worry if it the style does not look right yet; you will format the button later on.
  1. In the Button Setup dialog:
    1. Set the name of the button to "Create Receipt".
    2. Set the Action: to Perform Script.
    3. Set it to run the Donation - Create Receipt script.
    4. Leave the other options as their default values.
  1. Using the Styles tab of the Inspector, set the button's style to btn Minimal.Blue.Next.
  2. Using the Data tab of the Inspector, set a hide condition for the button by entering the following formula under Hide object when:

    IsEmpty( DONATION::Amount )
  3. Your layout should look something like this:
  1. Return to Browse mode to save and review your work.

Step 5 - Review your work

  1. When you view the details of a donation using the Donation Card window, you should be able to create a PDF of the receipt. 
  2. The Create Receipt button should only appear if a donation amount has been entered.