People Goal 5 - Part 8 - Use a script parameter

Document created by Kedar on Feb 4, 2015Last modified by communitymanager on May 12, 2015
Version 15Show Document
  • View in full screen mode

 


In Goal 3, you placed buttons next to your email fields in the body of your Main Detail layout, but you hadn’t yet written the script that would actually send an email. Let's finish that now — but before you do, there’s a strategic question to address.

 

In the example solution, the Contact table includes both “Work Email” and “Personal Email” fields, so there are two email buttons. Your solution probably has the same. What’s the best scripting approach for sending emails to both of these addresses?

 

You could write two scripts, one which sends an email to the “Work Email” and another which sends to the “Personal Email”, but these scripts would otherwise be identical.  If you needed to make a change to the process, you’d have to change both scripts. This can become a burden as your scripts get more complicated.

 

Instead, let’s create a single script that can handle both addresses and associate the same script with both buttons. Each button will pass an email address to the script as a script parameter, and the script will use this parameter as the “To” address of the email.

 

What exactly is a script parameter? It’s a value passed to a script at the time the script is called, which only exists for the duration of the script itself and is reset each time the script is performed. This ability to receive an independent value can make your scripts more flexible and re-usable in different contexts.

 

This section introduces three important concepts:

 

  • Specifying a parameter when calling a script

    An optional parameter may be specified whenever a script is called (for example by a button, a trigger, or the Perform Script script step). You will specify your Work Email field or your Personal Email field when you set up your email button to perform your email script.

  • Using the Get (ScriptParameter) function.

    This function returns the value of the parameter passed to the script. It’s the only way that your script can retrieve this value.

  • Setting variables

    A variable is a place to store a piece of information temporarily while a script is running. Each variable has a name and a value. You use the name to reference the variable in order to set or retrieve the value.  You’ll use a variable to store the result of the Get (ScriptParameter) function.


In this section, we’re making the assumption that your main table contains two different email address fields (such as a work email and a personal email) and that your Main Detail layout has two email buttons.


When you’re done with this script, it should resemble “Send Email” in the example solution.



Goal:


Create a single script that can receive a script parameter, generating an email with the parameter as the "To" address. Then associate this script with buttons on the Main Detail layout, setting up the buttons to pass different email addresses when calling the script.



Steps:


Create the email script


  1. Create a new script in the Script Workspace by clicking the + button above the left panel, or by pressing Command-N (OS X) or Control+N (Windows).

  2. Name your script: Send Email [email_address]

    Note that you actually want the square brackets in this case. The “[email_address]” is a helpful naming convention to indicate that a script parameter potentially can be passed to the script. You aren’t required to use this (or any) naming convention, but in the future it can help you remember what a script does and what parameter it takes.

    Another helpful convention is to place your script parameter into a clearly named variable at the beginning of the script. Throughout your script, whenever the variable appears, you’ll immediately know what data it contains. Otherwise, you would see Get(ScriptParameter) throughout your script, which is much more abstract.

  3. Add a Set Variable script step.

  4. Click the blue gear to set the script step options.

    A "Set Variable" Options dialog box appears.

  5. Enter the Name as:  $email_address

    The dollar sign indicates that this is a local variable, which is erased from memory when the script stops running.


  6. Enter the following expression for the ValueGet ( ScriptParameter )

  7. Click the OK button.

    There’s only one more script step to add: the one that sends the email.

  8. Add a Send Mail script step.

  9. Click the blue gear to set the script step options.
    send mail options.png

  10. Leave the Perform without dialog option unchecked.

    By default, FileMaker Pro opens the email in the user’s email client, allowing them to edit it before sending. When you check this option, the email is sent automatically with no user interaction. Since your script leaves the email body incomplete, the user needs to edit the email.

  11. Click the Specify button in the Script Step Options area.

    A
    “Send Mail” Options dialog box appears.

  12. Leave the Send via: option as “E-Mail Client”

    The other option is “SMTP Server”. In the future, you may find it useful to be able to send emails directly via SMTP protocol without involving your email client.

  13. Leave the Create option set to “One email…”

    In the future, you may want to take advantage of the option of “Multiple emails…”, which allows you to send an email to every person in your found set of records.

  14. Enter the value $email_address for the To.

    If you didn’t use this variable, this is where you’d see Get(ScriptParameter) instead — not as clear.

  15. Consider where there is anything you want to enter for CC, BCC, or Subject.

    The example solution doesn’t enter values for these.

  16. Enter the following expression for the Body:

    "Dear " & Contacts::Prefix & " " & Contacts::First Name & " " & Contacts::Last Name & ",¶¶" &


    “(Type email body here)¶¶” &

    "Best Regards¶¶" &

    Get ( AccountName )

    FileMaker Pro uses the ampersand (&) to concatenate (that is, link together) pieces of text.

    This calculation combines the word “Dear “ with the Contact Prefix, First Name, and Last Name, with appropriate spaces and punctuation.

    The “¶” characters represent line breaks that will appear in the final email.

    The “Get ( AccountName )” function is intended to represent the salesperson’s name. It provides the Account Name of the person currently logged into the solution. In the “Secure Your Solution” Goal, we will recommend that you set up FileMaker user accounts that match the names of all the people using the system, which is necessary for this way of getting the current user’s name to work properly. There are other ways to do this, but they are beyond the scope of this training.

  17. Click OK to close the dialog window.

  18. Save the script by typing ⌘S (Mac) or Ctrl-S (Windows).

 

 

Change the email buttons

 

  1. View your Main Detail layout in Layout mode.

  2. Double-click on the email button next to your first email field.

  3. Change the Action to "Perform Script".

    A Specify Script dialog will appear.

  4. Select your “Send Email [email_address]” script.

  5. Change the Optional script parameter to reference the Work Email address in your main table (if this field doesn’t exist in your main table, choose an appropriate email address field).

    In the example solution, this is “Contacts::Work Email”.

    send email script parameter.png
  6. Click the OK button to dismiss the dialog.

  7. If you have a second email button, repeat steps 18 to 22 but change the Optional script parameter to reference your second email field.

    In the example solution, this is “Contacts::Personal Email”.

  8. Enter Browse mode and test your new button(s).

    Each button should generate an email where the “To” address matches the email field to the left of the button.



      

      

Attachments

    Outcomes