Advanced Customization using Scripting

Content in Pages and Emails can be customized dynamically to include relevant data:

  • prompting a logged in donor with giving history and a personal message
  • co-branding a page or email for a related organization
  • adding campaign-specific contact information

Dynamic content of this nature is created using Scripting. Scripting in DonorPoint refers to embedding Java Server Faces Expression Language (EL) and JavaScript code in content. When that content is rendered - like a page in a browser or when the server creates a specific email from a template, that script is executed and its results are inserted into the template content. Scripting is also used to perform actions before a page is rendered, and after a transaction is complete. Scripting is also used by some objects in DonorPoint forms to take action - for example having a Custom Property rendered conditionally on a page.

When DonorPoint renders a Page or creates an email, the server keeps a Context associatd with it. This Context contains variables specific to the Page or email, and allows access to common scripting functions.

What you can do with scripting:

  • conditionally render objects on Page Templates and Pages, initially or in response to user input
  • change objects in memory
  • create objects in database after processing
  • send additional emails from templates
  • create rdis

The most prominent areas where Contexts are used are:

  • In PageTemplates during Page rendering
  • In Pages during initialization, rendering, data entry and postprocessing
  • In Items during initialization, rendering, data entry and postprocessing.
  • In PaymentMethods on Pages during initialization and data entry
  • In Custom Properties on Pages during initialization and data entry
  • In Autoresponders when they are sent
  • In Reports and Dashboards when they are rendered The relevant variables are documented in the documentation for pages and autoresponder templates.

Contexts

In DonorPoint a Context refers to the data in memory at the current time that a script is run.

For example the context when in a form includes the current transaction being created, the form’s design, paramteres etc.

When a receipt email autoresponder is being sent, the context includes the email template, addressee and transaction being receipted.

When an OrderItem post-process script is processed after a transaction, the context includes the OrderItem.

Contexts are where Java Server Faces (JSF) EL Script and Javascript find variables that they reference. Additional server objects can be called into the current context via EL script. The most commonly used server objects are:

commonRenderer - library of JSF EL Script processing, JavaScript processing and HTML formatting. The evalJS function executes JavaScript. queryService - library for querying the database elProcessor - access to context variables and to execute script

In addition a number of server objects named {class name}Service exist for finding and saving DonorPoint objects in the database.

Custom Property Values

When referring to custom prty values or integration codes on objects, there are two steps to getting their value.

The get(custom property name) function returns the custom property value on an object for the given custom property. However this is not the value itself, it is an object that contains the value. By default the property value on the custom property value object will contain the value. However for some custom property values this is not the case:

  • for Custom Property Textareas, the value is located in the text property
  • for Custom Property File and Image, the data is located as follows: – fileName - the name of the file – size - the size of the file – contentType - the MIME type of the file – data - the file contents – value - in the case of files and images, the value property returns a URL to access the file

** Because the get() function returns an object, note that if you want to check whether a value exists in JavaScript, you cannot use standard JavaScript shortcuts to determine whether it has a value. You need to test both that the objects exists and its value exists. **

	If (contact.get('UWAID')) {  //  will not work to test for UWAID undefined or empty string
	If (contact.get('UWAID') != null && contact.get('UWAID').value != '')  { //  this will work, note that casting to String will get the value as expected

References

The Java Server Faces EL documentation can be found here

The JavaScript language reference can be found here

The DonorPoint API reference is located [here])(https://docs.donorpoint.com/javadoc)