1Workflow::Action::InputUFsieerldC(o3n)tributed Perl DocuWmoernktfaltoiwo:n:Action::InputField(3)
2
6 Workflow::Action::InputField - Metadata about information required by
7 an Action
8
10 This documentation describes version 1.09 of this package
11
13 # Declare the fields needed by your action in the configuration...
14 <action name="CreateUser">
16 <field name="username"
17 is_required="yes"
18 source_class="App::Field::ValidUsers" />
19 <field name="email"
20 is_required="yes" />
21 <field name="office"
22 source_list="Pittsburgh,Hong Kong,Moscow,Portland" />
23 ...
24
26 A workflow Action can declare one or more input fields required to do
27 its job. Think of it as a way for the external world (your application)
28 to discover what information an action needs from it. The application
29 can request these fields from the workflow by action name and present
30 them to the user in whatever form appropriate for the application. The
31 sample command-line application shipped with this distribution just
32 cycles through them one at a time and presents a query to the user for
33 data entry.
34 For instance, in the above declaration there are three fields,
36 'username', 'email' and 'office'. So your application might do:
37 my @action_fields = $wf->get_action_fields( 'CreateUser' );
39 foreach my $field ( @action_fields ) {
40 print "Field ", $field->name, "\n",
41 $field->description, "\n",
42 "Required? ", $field->is_required, "\n";
43 my @enum = $field->get_possible_values;
44 if ( scalar @enum ) {
45 print "Possible values: \n";
46 foreach my $val ( @enum ) {
47 print " $val->{label} ($val->{value})\n";
48 }
49 }
50 print "Input? ";
51 my $response = <STDIN>;
52 chomp $response;
53 $wf->context->param( $field->name => $response );
54 }
55 $wf->execute_action( 'CreateUser' );
56
58 Public Methods
59 new( \%params )
60 Typical constructor; will throw exception if 'name' is not defined or
62 if the property 'source_class' is defined but the class it specifies is
63 not available.
64 You will usually not need to use or override this method unless you
66 derive your own input field class (see class in "Properties" below).
67 For example, suppose you need to add extra properties to all your
68 fields like "index", "disabled", etc.
69 In your actions definition XML file, you can just add them and the
71 parser will pick them up. Pay close attention the custom InputField
72 "class" property.
73 <actions>
75 <type>foo</type>
76 <action name="Bar"
77 class="your::action::class">
78 <field index="0" name="id" type="integer" disabled="yes"
79 is_required="yes" class="your::custom::inputfieldclass"/>
80 </action>
81 But you need to give them life by creating the accessors for these
83 extra properties. Just derive your custom fields class like so:
84 package your::custom::inputfieldclass;
86 use warnings;
88 use strict;
89 use base qw( Workflow::Action::InputField );
91 use Workflow::Exception qw( workflow_error );
92 # extra action class properties
94 my @EXTRA_PROPS = qw( index disabled );
95 __PACKAGE__->mk_accessors(@EXTRA_PROPS);
96 sub new {
98 my ( $class, $params ) = @_;
99 my $self = $class->SUPER::new($params);
100 # set only our extra properties
101 foreach my $prop (@EXTRA_PROPS) {
102 next if ( $self->$prop );
103 $self->$prop( $params->{$prop} );
104 }
105 warn "INDEX IS NOW WORKING:".$self->index;
106 warn "AND SO IS DISABLED:".$self->disabled;
107 return $self;
108 }
109 1;
111 is_required()
113 Returns 'yes' if field is required, 'no' if optional.
115 is_optional()
117 Returns 'yes' if field is optional, 'no' if required.
119 get_possible_values()
121 Returns list of possible values for this field. Each possible value is
123 represented by a hashref with the keys 'label' and 'value' which makes
124 it easy to create dropdown lists in templates and the like.
125 add_possible_values( @values )
127 Adds possible values to be used for this field. Each item in @values
129 may be a simple scalar or a hashref with the keys 'label' and 'value'.
130 init
132 Init is a dummy and just returns no special actions are taken
134 Properties
136 name (required)
137 Name of the field. This is what the action expects as the key in the
139 workflow context.
140 label (optional)
142 Label of the field. If not set the value for "name" is used.
144 description (optional)
146 What does the field mean? This is not required for operation but it is
148 strongly encouraged so your clients can create front ends to feed you
149 the information without much fuss.
150 type (optional)
152 Field types are implementation dependant are they should be
154 intrinsically implemented by validators. In other words, you can use
155 any mnemonic value for your convinience like "integer", "text", etc.
156 but it won't affect anything unless you use a validator to validate
157 your action data. By default it is set to 'basic'.
158 requirement ('required'|'optional')
160 If field is required, 'required', otherwise 'optional'.
162 source_class (optional)
164 If set the field will call 'get_possible_values()' on the class when
166 the field is instantiated. This should return a list of either simple
167 scalars or a list of hashrefs with 'label' and 'value' keys.
168 source_list (optional)
170 If set the field will use the specified comma-separated values as the
172 possible values for the field. The resulting list returned from
173 "get_possible_values()" will have the same value for both the 'label'
174 and 'value' keys.
175 class (optional)
177 You may specify a custom InputField class. It should "use base qw(
179 Workflow::Action );" and probably override the new() method which
180 should call SUPER::new($params). See "new( \%params )" above for an
181 example.
182
184 Workflow::Action
185
187 Copyright (c) 2003-2007 Chris Winters. All rights reserved.
188 This library is free software; you can redistribute it and/or modify it
190 under the same terms as Perl itself.
191
193 Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current
194 maintainer.
195 Chris Winters <chris@cwinters.com>, original author.
197perl v5.30.1 2020-01-30 Workflow::Action::InputField(3)