Collected API and feature requests 2008-10 - [fleXive]

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

Location: [fleXive] > Developer Info EDIT

Please type the word appearing in the picture.

Wiki Markup Preview

h1. 2008-10 - API and feature requests

{toc:minlevel=2}

The following suggestions are based on a recent in-house project done with \[fleXive\] 3.0.

The related forum discussion can be found [here|http://forum.flexive.org/viewtopic.php?t=105].

h2. 1. API quirks/suggestions for improvement

h4. -a) FxContent#getValue and Checked Exceptions- (fixed in 3.1)

The fact that FxContent#getValue uses checked exceptions for missing values and invalid XPaths quickly leads to cluttered code. For example, the following code checks if a String value is not empty (and will still throw a FxInvalidParameterException):

{code}private boolean isCompleted() throws FxInvalidParameterException {
    try {
        return StringUtils.isNotBlank(
            content.getValue("/confirmation/code").toString()
        );
    } catch (FxNotFoundException e) {
        return false;
    }
}{code}

Additionally, this does not work at all with optional properties when used via JBoss-EL (which allows function calls) on a JSF page.

*Suggestions*:
* Do not throw an exception for missing values. Return null or an empty FxValue instance instead.
* Throw the FxInvalidParameterException as Runtime exception. Usually the XPath is a String literal, so the program cannot react to it anyway, since it's a programmer error.
* Maybe create a "FxInvalidXPathException", since this is an error likely to occur when working with FxContents.

h4. b) -FxContent#setValue and primitive values- (fixed in 3.0)

Since #setValue only takes FxValue arguments, updating a content can get unnecessarily repetitive (especially, but not only for singlelanguage properties). For example, instead of writing
{code}content.setValue("/stringValue", new FxString(false, "value")){code}
the same effect could be expressed with
{code}content.setValue("/stringValue", "value"){code}
or for a multilanguage property with
{code}content.setValue("/stringValue", FxLanguage.ENGLISH, "value"){code}

This also improves updates for multilanguage properties because otherwise one would have to check first if a value already exists under the given XPath (which would have to be updated, unless all languages are set at once).

h4. c) -FxReference constructor for PKs- (Fixed in 3.1)

{code}new FxReference(false, new ReferencedContent(pk)){code}
and
{code}new FxReference(false, pk){code}
are equivalent, but no constructor for FxPKs is available. This is a special case because ReferencedContent extends FxPK.

h4. d) -Create/Save/Load cycle of contents- (fixed in 3.0)

Currently, creating a new content and then using it requires the following steps:
{code}FxContent content = EJBLookup.getContentEngine().initialize(...);
content.setValue("/...", new FxString("..."))
content.setValue("/...", new FxString("..."))
content.setValue("/...", new FxString("..."))
content = EJBLookup.getContentEngine().load(EJBLookup.getContentEngine().save(content))
{code}

Some syntactic sugar with support for chaining would simplify the trivial case to

{code}final FxContent content = EJBLookup.getContentEngine().initialize(...)
    .setValue("/...", new FxString("..."))
    .setValue("/...", new FxString("..."))
    .setValue("/...", new FxString("..."))
    .save();
{code}

Where save() would make the EJB call and set its own PK.

h4. e) Determining missing properties of a content instance

When saving a content instance with invalid or missing values, only the first is reported. Ideally the XPaths of all invalid values would be returned at once, which would allow fancier UI error reporting.

h2. 2. Features dearly missed

h4. a) -URL Rewriting layer- (fixed in 3.1, although UrlRewriteFilter might be replaced with PrettyFaces)

Often the page URI contains more information than just the ID of a content to be displayed. For example, the site locale ("en") followed by a tree path. Also, some pages are mapped directly to templates in the WAR file system, others are grouped and mapped to a single template (e.g. product detail pages). Writing a custom Filter is not that hard, but repetitive and it's easy to make mistakes (e.g. handling of trailing slashes).

Apparently there exists a pretty flexible URL rewriting layer similar to mod_rewrite, [UrlRewriteFilter|http://code.google.com/p/urlrewritefilter/] (also included in Seam). It also seems to solve the "pretty URLs for postbacks" issue in JSF applications.

Bugs: FX-342

h4. b) -Tree API: extract page path from URL-

(This functionality is included in 3.1's PageBean)

There is no support for dealing with the tree path found in an URL (e.g. strip locale, strip file extensions). If UrlRewriteFilter is included, it should also add support for marking the tree path section of an URL for common usecases.

h4. c) -Tree API: get content reference for current page-

(This functionality is included in 3.1's PageBean)

Likewise, there is no single call to get the content PK (or content) assigned to the current page.

h4. d) -Content API: Determine if XPath is set- (Fixed in 3.1, FxContent#containsXPath)

There seems to be no single method to determine whether a given XPath is present in a content instance, because the public methods either expect property or group paths. The following function checks if a XPath is present:

{code}public boolean containsXPath(FxContent content, String xpath) throws FxInvalidParameterException {
    try {
        // check if the given XPath points to a value
        content.getValue(xpath);
        return true;
    } catch (FxNotFoundException e) {
        return false;
    } catch (FxInvalidParameterException e) {
        try {
            // check if the given XPath points to a group
            content.getGroupData(xpath);
            return true;
        } catch (FxNotFoundException e1) {
            return false;
        }
    }
}{code}

h4. e) -Creating lists from iterators- (fixed in 3.1, added Google Collections)

Some flexive methods, like FxResultSet#getResultRows, return (with good reason) an Iterator instead of a complete list. However, to use such an enumeration in JSF it has to be converted to a List or Array.

Among other useful methods for Java 5, [Google Collections|http://code.google.com/p/google-collections/] offers Lists.newArrayList(Iterable) which does exactly that.

Bug: [FX-417|http://issuetracker.flexive.org/jira/browse/FX-417]

h4. f) FxContent: iterating over XPaths with cardinality

There is no iterator for groups or values with a cardinality greater than one. This leads to the following, non-trivial code for iterating over the instances of a group:

{code}for (FxData itemGroup : content.getGroupData("/contentGroup").getElements()) {
    final FxString label = (FxReference) content.getValue(itemGroup.getXPathFull() + "/label");
    final FxDouble price = (FxDouble) content.getValue(itemGroup.getXPathFull() + "/price");
}{code}

The same applies to properties.

*Suggestion:*
Create a XPath iterator, possibly create Value/Group iterators, e.g.
{code}
// iterate using a XPath iterator
for (String group: content.groupIterator("/contentGroup")) {
    final FxString label = (FxString) content.getValue(group + "/label");
}

// iterate using a group iterator
for (FxGroupData group : content.groupIterator("/contentGroup")) {
    final FxString label = (FxString) group.getValue("/label");
}
{code}

h4. g) -FxContent: clear all indices of an XPath- (Fixed in 3.1)

Currently, the following code is required to remove all instances of a group/property with a cardinality greater than one:

{code}try {
    while (true) {
        invoice.remove("/cartItem");
    }
} catch (FxNotFoundException e) {
    // no more items available
}
{code}

Bug: [FX-456|http://issuetracker.flexive.org/jira/browse/FX-456]

h4. -h) JSF-UI: Iterate over tree folder- (fixed in 3.1, added fx:navigation component)

Parts of a webpage are often represented in tree folders. We need at least an iterator tag that provides the PK, path and caption of each direct child of a node (identified by a path).

Bugs: FX-58

h4. i) Skeleton web app

Add a skeleton web application with tree-based navigation.

h4. j) Import/Export of entire application data

While it is relatively easy to write an export script for the content tree, there is no "one-click" solution to export the tree _and all associated contents_ (references, select lists, types).

Also, references are only exported via ID, which means that they are only resolved correctly when they have the same IDs on the target system. A complete export could solve this problem with an internal "reference mapping table" of some kind.

Minor change? (no notifications will be sent)

Comment:

Labels: EDIT

Help Tips

Notation Help: (full guide)
Text formatting:
*bold* » bold
_italic_ » italic
-strike- » ~~strike~~
+under+ » under

Headings:
h1. Large heading!
h3. Medium heading
h5. Small heading...

Lists:
* Bulleted point
# Numbered point

Linking:
[title#anchor] » Link a page
[dev:title#anchor] » In space with 'dev'
[http://host.com] » Remote link
[phrase@shortcut] » Shortcut
Note: [alias|any_of_above_links] » Custom link title

Tables:
||head1||head2||
|colA1|colA2|
|colB1|colB2|

Details and full examples are in the full notation guide »