Skip to content

Commit

Permalink
Item13003: implemented RENDERFORMDEF
Browse files Browse the repository at this point in the history 
... for DataForm definition insights in wiki apps
  • Loading branch information
@MichaelDaum
MichaelDaum committed Aug 28, 2014
1 parent 418483e commit 287a32a
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 6 deletions.
41 changes: 36 additions & 5 deletions data/System/FlexFormPlugin.txt
View file
Expand Up @@ -4,10 +4,10 @@

%TOC%

This plugin leverages the internal capabilities to render an interface for %SYSTEMWEB%.DataForms.
This API is part of the =Form= class of Foswiki and is called =renderForEdit()=. It takes
a form definition and creates an appropriate edit interface for the given !DataFrom. This
feature is actually very handy to write custom EDIT_TEMPLATEs and VIEW_TEMPLATEs in wiki applications.
This plugin leverages the internal capabilities to render an interface for %SYSTEMWEB%.DataForms
and adds insights to the acutal !DataForm definition itself as used internally.
This API is part of the =Foswiki::Form= and =Foswiki:Form::FieldDefinition= classes of Foswiki
now available when writing custom EDIT_TEMPLATEs and VIEW_TEMPLATEs in wiki applications.

The %<nop>RENDEFFOREDIT and %<nop>RENDERFORDISPLAY macros allows wiki application authors
to customize interfaces to !DataForms while not losing the flexibility of defining a !DataForm
Expand All @@ -22,6 +22,10 @@ to render the input form in a more dynamic way while still customizing the overa
In addition, !FlexFormPlugin facilitates the extraction of field default values (such as valid schema options) from
!DataForm. See http://foswiki.org/Development/MacroForRetrievingFieldDefaultValues for background.

While %<nop>RENDERFOREDIT% and %<nop>%RENDERFORDISPLAY render forms for the net data using a !DataForm
the %<nop>RENDERFORMDEF= macro renders information about the !DataForm definition itself identpendent of
any topic actually using it. This may be used to provide more defailed insights into the !DataForm definition.

---++ Usage
---+++ RENDERFOREDIT
| *Parameter* | *Description* | *Default* |
Expand Down Expand Up @@ -92,7 +96,8 @@ In addition, !FlexFormPlugin facilitates the extraction of field default values

If all three =format=, =header= and =footer= are undefined a =foswikiFormSteps= block will be rendered as illustrated in the example below.

The =format= parameter may contain the following pseudo-variables:
The =format= parameter may contain the following variables:

* =$attrs=: attribute string as given in the !DataForm definition
* =$description=: formfield description in !DataForm
* =$edit=: the HTML form element as specified by the !DataForm definition, that is a input field, a textarea, a select box, whatever
Expand All @@ -109,6 +114,31 @@ The =format= parameter may contain the following pseudo-variables:
* =$origvalues=: list of all allowed values; for =+value= formfields this is the original _unmapped_ value of the formfield
* =$default=: this is the default value if no value is specified in the topic itself

---+++ RENDERFORMDEF

| *Parameter* | *Description* | *Default* |
| "..." or form="..." | the topic holding the !DataForm definition | current topic |
| field="..." or fields="..." | a comma separated list of fields to render information about | all fields |
| include="..." | regular expression a field name must match to be listed | |
| exclude="..." | regular expression a field name must not match to be listed | |
| header | header string prepended to the result | |
| format | format string for each field to be rendered in the result | |
| separator | separator between lines when field information is rendered | |
| footer | footer string appended to the result | |

The =format= parameter may contain the following variables:

* =$name=: field name
* =$title=: field title
* =$type=: field type
* =$size=: field size
* =$attributes=: field attributes
* =$description=: field description
* =$definingTopic=: topic where allowed values are defined
* =$value=: default value of the field

Note that the actual results may vary depending on the formfield type of the !DataForm.

---++ Examples

<verbatim>
Expand Down Expand Up @@ -156,6 +186,7 @@ The =format= parameter may contain the following pseudo-variables:
| Release: | %$RELEASE% |
| Version: | %$VERSION% |
| Change History: | <!-- versions below in reverse order -->&nbsp; |
| 28 Aug 2014: | added new feature %<nop>RENDERFORMDEF |
| 03 Mar 2014: | work around different styles of inconsistencies in =renderForDisplay= across foswiki core releases |
| 07 Nov 2013: | properly render =checkbox+buttons= formfields |
| 13 Jul 2013: | added =revision= parameter to access non-top revisions; \
Expand Down
5 changes: 5 additions & 0 deletions lib/Foswiki/Plugins/FlexFormPlugin.pm
View file
Expand Up @@ -40,6 +40,11 @@ sub initPlugin {
return Foswiki::Plugins::FlexFormPlugin::Core::handleRENDERFORDISPLAY(@_);
});

Foswiki::Func::registerTagHandler('RENDERFORMDEF', sub {
init();
return Foswiki::Plugins::FlexFormPlugin::Core::handleRENDERFORMDEF(@_);
});

$doneInit = 0;
return 1;
}
Expand Down
64 changes: 63 additions & 1 deletion lib/Foswiki/Plugins/FlexFormPlugin/Core.pm
View file
Expand Up @@ -65,6 +65,68 @@ sub getTopicObject {
return $topicObj;
}

##############################################################################
sub handleRENDERFORMDEF {
my ($session, $params, $theTopic, $theWeb) = @_;

my $formName = $params->{_DEFAULT} || $params->{form} || $theTopic;
my ($formWeb, $formTopic) = Foswiki::Func::normalizeWebTopicName($theWeb, $formName);

my $theFormat = $params->{format};
$theFormat = '$name' unless defined $theFormat;

my $theHeader = $params->{header} || '';
my $theFooter = $params->{footer} || '';
my $theSep = $params->{separator} || '';
my $theFields = $params->{field} || $params->{fields};
my $theExclude = $params->{exclude};
my $theInclude = $params->{include};

my $form = new Foswiki::Form($session, $formWeb, $formTopic);
return '' unless $form;

my @selectedFields = ();
if ($theFields) {
foreach my $fieldName (split(/\s*,\s*/, $theFields)) {
$fieldName =~ s/\s*$//;
$fieldName =~ s/^\s*//;
my $field = $form->getField($fieldName);
writeDebug("WARNING: no field for '$fieldName' in $formWeb.$formWeb") unless $field;
push @selectedFields, $field if $field;
}
} else {
@selectedFields = @{$form->getFields()};
}


my @result = ();
foreach my $field (@selectedFields) {
next unless $field;
next if defined $theExclude && $field->{name} =~ /$theExclude/;
next if defined $theInclude && $field->{name} !~ /$theInclude/;

my $line = $theFormat;

$line =~ s/\$name/$field->{name}/g;
$line =~ s/\$title/$field->{title}/g;
$line =~ s/\$type/$field->{type}/g;
$line =~ s/\$size/$field->{size}/g;
$line =~ s/\$attributes/$field->{attributes}/g;
$line =~ s/\$(description|tooltip)/$field->{tooltip}/g;
$line =~ s/\$definingTopic/$field->{definingTopic}/g;
$line =~ s/\$value/$field->getDefaultValue/ge;

push @result, $line;
}

return '' unless @result;

my $result = $theHeader.join($theSep, @result).$theFooter;
$result =~ s/\$form/$formName/g;

return $result;
}

##############################################################################
sub handleRENDERFORDISPLAY {
my ($session, $params, $theTopic, $theWeb) = @_;
Expand Down Expand Up @@ -267,7 +329,7 @@ sub handleRENDERFORDISPLAY {
}

next if $theHideEmpty && (!defined($fieldValue) || $fieldValue eq '');
$fieldValue = $fieldDefault unless defined $fieldValue;
$fieldValue = $fieldDefault unless defined $fieldValue && $fieldValue ne '';

next if $theInclude && $fieldName !~ /$theInclude/;
next if $theExclude && $fieldName =~ /$theExclude/;
Expand Down

0 comments on commit 287a32a

Please sign in to comment.