Platform Architecture

Understanding DonorPoint’s architecture helps you know which customization approach is right for any given need — and how much effort each requires.

Code Generation: What It Means

DonorPoint is built on the giftwrap framework, a code-generation platform that produces the entire admin application automatically from the data model. Every entity in DonorPoint (Contact, Campaign, Fund, PurchaseOrder, etc.) automatically gets:

• A backing bean (EntityHome) managing CRUD operations, validation, and lifecycle hooks
• A list view (EntityList) with sorting, filtering, and pagination
• A search/autocomplete bean (EntitySelector) for selection dialogs
• Full admin XHTML pages: list, edit, dialog, and edit-facet views

This means that adding a new field to the data model automatically makes it appear in the admin UI, in reports, in imports, and in the API — with no additional code.

Three Layers of Customization

Every customization need falls into one of three layers. The key question is: how much effort does it require, and who can do it?

Layer 1: Runtime Configuration (No Rebuild)

Who: System administrators in the DonorPoint admin UI
Examples: Custom field definitions, Event Handlers, Workflows, ScriptModules, Entity Actions, Scheduled Jobs, Campaign Templates with createEL/persistEL, externalized text (Messages), page templates

These are stored in the database and evaluated at runtime. No code change, no deployment, no rebuild. Changes take effect immediately.

This is the layer that makes DonorPoint’s configurability possible. Most business rules, field labels, lifecycle actions, and scheduled tasks belong here.

Layer 2: FTL Hook Customization (Rebuild Required)

Who: Developers with access to the giftwrap source
Examples: Custom XHTML injected into entity edit pages (rhs sidebar, tab content, body headers), custom Java logic in entity lifecycle (create, persist, update, revert, duplicate)

The giftwrap code generator includes custom FTL template files at named injection points throughout the generated Java and XHTML. There are ten Java lifecycle hook points and thirteen XHTML injection points per entity. Adding a new hook file triggers a rebuild of the admin application.

Because these hooks are included via <#attempt>/<#recover>, missing files are silently ignored — you can add any hook for any entity without touching any other code.

Layer 3: Model Annotation (Full Framework Rebuild)

Who: Developers with access to the giftwrap entity model
Examples: Changing which fields exist on an entity, adding a new entity type, changing UI widget types (@EditType), setting rendering conditions (@Rendered), initialization values (@Initialization), read-only rules (@ReadOnlyRule)

Java annotations on entity getter methods control how the code generator produces the admin UI. Changes here require a full rebuild and deployment of the giftwrap platform.

What This Means in Practice

When you get a request to change how DonorPoint behaves, use this decision tree:

Can it be done with a Custom Field, EL expression,
ScriptModule, Event Handler, or Workflow?
  → YES: Do it in the admin UI. No rebuild needed.
  → NO ↓

Can it be done with a new FTL hook file
(sidebar button, new tab, form field injection)?
  → YES: Write a .ftl file. Rebuild admin only.
  → NO ↓

Does the entity model need to change
(new field, new entity, new annotation)?
  → YES: Change the model. Full platform rebuild required.

The vast majority of customizations requested by implementation partners fall into Layer 1 or Layer 2.

The EL Runtime System

The Expression Language (EL) system is the technical foundation of Layer 1. It allows JavaScript and JSF EL to be stored in the database and executed at runtime against any DonorPoint object. See EL Expression Reference and Scripting Guide for full details.

Deployment Architecture

DonorPoint is deployed as a multi-tenant SaaS application. All accounts share the same deployed codebase. Layer 1 customizations are always account-scoped — your custom fields, scripts, and event handlers are visible only to your account. Layer 2 and Layer 3 changes go through the DonorPoint release process and apply to the shared platform.