jFormer DocumentationForm Features

Instances

Instances (component duplication) is a powerful feature that allows multiple entries to exist on a form. Giving you the ability to have optional additional items.

Usage

Instances are an option available to every component type. and work based on a preset number of instances allowed. the option used to set how many instances a component may have is 'instancesAllowed'

Optionally you may also pass a label for the add instance button and remove instance button. the add and remove instance buttons only are shown when they are available for use. if there are three instances of a single line text, and that is the maximum allowed the add instance button is not shown. and there is not a remove instance button for the 'parent' instance.

Sample Usage

	array(
		'instancesAllowed' => 5,
       	'addInstanceText' => 'Add Another',
	);

Data Format

Instances are great because it allows for a dynamic amount of components to be submitted to the form. All data sent to the server is considered a part of the same component, and presented in an array. The original instance is key [0] and each instance afterward has the next consective key eg.

  • [0] - Prime
  • [1] - First instance
  • [2] - Second instance

Instance Options

1

instancesAllowed

integer | The number of instances allowed, if not set to 1 the 'add instance' button is shown, this option may be set to zero, which allows for unlimited instances.

Add Another

instanceAddText

string | The Label for the 'Add' button may be set to whatever you want

Remove

instanceRemoveText

string | The Label for the 'Remove' button may be set to whatever you want

Next Page: Page Navigator

This page was last edited on April 25, 2011 at 1:57pm.

10 comments (add a comment)

sean on 2011-04-26 22:01:59

Component instances are quite easy to create and to save the data to your database from your initial input form. However, I have not been able to figure out how to pre-fill the component instances again from saved data to allow someone to edit what they previously entered. It is not clear how to give each instance an 'initialValue' and generate the correct number of instances, depending on how many were saved.

Ingo on 2011-05-06 04:23:46

I have the same question. I want to prefill a form with a multipe instance section, but i can't find out, how to do this.

nathan on 2011-05-30 13:52:50

in the same boat - LMK if you found anything, otherwise I will post my solution here when I work it up.

LAGRANGE on 2011-07-21 07:41:27

Have you found a issue to that "problem" ? I would like to pre-fill the component instances again from saved data ....
Thanks ;)

rob on 2011-07-25 05:08:48

Anyone found the solution to this yet?

CK on 2011-11-08 14:33:25

Not tested, but I have a theory on doing this:

IF you are re-generating the form from data pulled from a DB, I'm guessing first that the data is in some sort of array.

# of instances is easy. Count the values saved and save that value off somewhere, or if you are serializing the data from the form, then you can just get the whole array back using unserialize, and thus get a count($array) of your array.

Pre-filling is not as easy to figure out. I would use the JFormerPage onBeforeScrollTo. So, when you hit NEXT on a page before getting to the page you want to edit....or use TRIGGER based on a field changing.

Then use something like this:
PHP:
$script = '';
$compName = '#mycomponent';
for($i = 0; $i < count($dataArray);$i ){
if($i > 0){
$compName = '#mycomponent-section' . $i;
}
$script .= '$(' . $compName . ').val() = ' . $dataArray[$i] . ';';
}

Then use $script in the onBeforeScrollTo, or TRIGGER....that MAY work. Not enough time to test right now, but I can't think of anything that would prevent that method of operation.

CK on 2011-11-08 14:35:02

Oops. Messed up a line.

$compName = '#mycomponent-section' . $i 1;

emd on 2012-01-04 12:28:30

Just a couple thoughts/questions. I think jFormer is a great framework and plan to use it extensively. Well done. I've done a bit of tweaking on a couple things to make them work the way I wanted so I thought I'd mention them as suggestions for the future and to see whether anyone has other ideas of how to do them.

With instances, it seems there is always going to be at least one that exists. I've done an email application where I let the user add up to 3 attachments, but I want to start with no attachments. Is there a way to start with zero instances and then add them? I ended up defining 3 file inputs that appear or disappear with the Add and Remove buttons. So it looks just like your instancing of file inputs, just that it starts with no instances showing.

Second, I worked out a way where I could have labels to the left and the inputs/selects/etc to the right, more of a horizontal layout instead of having the labels above the inputs. Any other easier way to do that?

Thanks and keep up the great work. -Edward.

shawn a on 2012-01-19 06:22:14

This documentation is wrong.

Substitute the proper arguments as follows.
instancesAllowed = max
instanceAddText = addButtonText
removeAddText = removeButtonText

'instanceOptions' => array(
'max' => 3,
'addButtonText' => 'Add Instance',
'removeButtonText' => 'Remove Instance',
),

michka on 2012-03-10 07:56:27

Hello,

Is someone know how to catch all the variables from the multiples instances of a File component ??

I want all the 'tmp_name' of the files to upload.

Thanks