xp-framework/rfc — Issue #49: Scriptlet Facades
Author: thekid
Created: 2011-10-17 15:45:30+00:00
State: closed
Labels: framework, obsoleted

Scope of Change
====
A new API will be introduced that will provide a base for common use-cases
of scriptlets - e.g. data manipulation frontends (list, new, edit, delete),
search form and paged result sets, signup processes, user-configurable
portal pages, news aggregation frontends and more.

Rationale
====
Remove the need for reinventing the wheel in many places and for boilerplate
code (EditHandler / EditWrapper / EditState, CreateHandler / CreateWrapper /
CreateState, ...).

Functionality
====
A "Facade" groups and provided functionality of multiple states and associated
handlers and wrappers together.

Use case #1: Data manipulation frontend
----
Shows a list of items, provides means to add new items, delete and edit
existing ones.

Examples:
- List of orders in a webshop administration frontend
- User administration frontend
- Mailbox display in a webmail application

RDBMS based implementation
----
The most common practice here would be to implement this based on records
from a database table, but we don't want to be limited to that.

```
Note: An implementation based on rdbms.DataSet could use rdbms.Criteria to
easily list, find, change, create and modify items. We need a way to create
specialized "facade" objects that serve the sole purpose of being displayed,
e.g. a news entry with a attributes "author.realname" and "comments.count".

```

```
Note: Simply selecting all fields from one database table and displaying
them row-wise in a table is not sufficient. This may work well for flat
database structures, but will fail if we normalize. For example, a "news"
table would contain an author_id field pointing to the "author" table.
Now for list display, we probably don't need *all* fields from the author
table but only the first- and lastname (and maybe the email address).
Also, we can't always join on everything, e.g. in a listing of news
entries we don't want all comments associated with an entry but rather
only how many exist.

```
Note: After a record is modified, some further action may need to be
taken, e.g. sending an email, triggering a SOAP service, fireing a UDP
trigger, ...

```

Other implementations
----
Beyond database access, the entries could come from and would need to
be saved to other datasources, e.g.:

- Application Server (remote API)
- LDAP
- Filesystem

```
Note: These cases seem rare to me at the moment, but I think we should
take this into account...

```

Use case #2: Search and results
----
Provides a simple entry box and a more complicated one for extended
searches. Shows search results ordered best first and paged.

Examples:
- Site search
- List search on list from use case #1

```
Note: Search results may need to be filtered before being able to
display them based on a user's settings and/or access permissions.

```

Use case #3: Configurable portal page
----
Shows a list of selected portlets in a user-defined order per page.
Offers a way to configure the shown portlets and to administer the
list.

Examples:
- Intranet portal page

Use case #4: Ordering / signup process
----
Guides the user through the process, showing forms dependant on data
currently needed (e.g., if the user is an existing user, no credit card
or bank data needs to be queried) and lets the user hop back and forth
within the process.

Examples:
- Order a webhosting package
- Signup for a blogging account

Use case #5: News aggregation frontend
----
Shows entries ordered by date, newest first, with a means to show them
grouped by topic and/or date, to browse the topics and to view and
comment entries.

Examples:
- Weblog
- Photoblog

Security considerations
====
n/a

Speed impact
====
A bit slower than directly implementing the classes because most of the
functionality will work at runtime to further ease development and to
eliminate the step of generator runs.

Dependencies
====
n/a

Related documents
====
- Ruby on Rails
http://www.rubyonrails.org/