Bucket Repeater

What is a Repeating Bucket?
A repeating bucket is one that allows our forms users to click a button to add or remove instances of the bucket and all its items at runtime. This is a very handy feature for times when we may not know exactly how many of some group of fields we need.

For example, a forms allows a user to fill in an address, but we want to allow for several distinct addresses if needed. This could of course be handled by creating a bucket, duplicating it, then using conditional show/hide logic with a checkbox. However, with repeating buckets we simply say make this item able to be duplicated, and then leave it up to the user to decide how many addresses they wish to add (though we can of course set a maximum number of buckets the user can create).

As useful as this is, their is one potential drawback you should be aware of before using repeating buckets: they usually increase the complexity of your data store if using a custom database via SQL+.

This increase in complexity isn't too harsh, but is usually means the extra instances of data we want to store will need to be sent to a second database table which is then related, via a key, to the 'main' entry table the rest of the form fields belong too. This means we'll now have two SQL+ items in our form, as well as when pulling data back out, the ability to write SQL JOIN statements to relate the two tables.

In short then we could consider using bucket repeaters an "advanced" feature, as the data requirements usually mean greater sophistication in terms of saving and retrieving data. Thus, it always pays to consider the alternative, which is as noted above, just using conditional logic to show and hide the extra instances of the bucket items we need.

That said if we do not need SQL+ and instead wish to use Simple SQL or Simple Email, using bucket repeating logic can be a much faster route to include dynamic fields than conditional logic.

Processing Bucket Repeater Output In Emails, SQL, PHP, Etc.

Due to the complex nature of Bucket Repeaters, both in terms of basic logic and security issues, we usually include output from them in slightly different ways, depending on the output method.

Using Automated (Simple) Methods For Database Work

The easiest and quickest way to save bucket data to a custom database is to use the SQL+ Automator with no elements selected in your form, and then choosing the Table And Add SQL+ Insert Item, or Entire Job + Index Table options. This will create all needed table not only for the buckets, but all elements in the form as well.

Warning: Our form must have at least one item outside of a repeating bucket to use this mode. That is, a text field, a select item, basically any form field item that also writes to the database.

Using Manual Tokens

RackForms has two main classes of tokens that deal with Bucket data. The BI and BUCKET tokens for dealing with only repeated rows in simple and complex display/processing situations, and the B token for accessing all rows of a bucket in raw processing code. We also have several options when considering the method we wish to access our data. Displaying bucket data in Email's and text display fields is usually best handled via the BUCKET token, SQL+ using the special Bucket processing mode, and so on.

SQL+ Specific Considerations

For SQL+ items the preferred method is to use the SQL+ items Bucket Repeater Processing Mode option, as described here. In this method we tell the SQL+ item which Bucket we'd like to process, and RackForms handles the rest for us.

Simple Email

Simple Email items require no extra processing, any Bucket Repeater items we add to the page are shown in the email body.

Email+

Email+ items require the use of a token, of which we have two to choose from:

First, we can use the BI token, which stands for Bucket Indexed. We use this token when we wish to access specific items within a bucket repeater data set. The token takes the form of:

BI{bucket_name|index|field name}

The downside to this is we do not know, at run time, how many rows have been filled out. Thus, it's best to use the second token, or use the Bucket API in a text field to know how many items we have.

The second main token for Email+ items is:

BUCKET{bucket_name}.

This token will take all repeater rows (including the first row), and display it in a simple HTML table. This is a "fully automated" approach, as we do not need to know anything about the number of rows of fields before hand.

The B token.

The BUCKET and BI tokens are meant to be used inline with Email+, display fields, and so on. We may, however, want to gain direct access to our bucket data. This is where the B token comes in.

The B token specializes in delivering direct code access to our bucket data in an associative array, raw HTML, or TAB delimited data.

Accessing each of these output modes is determined by the format of the token. Used by itself, we get a raw PHP array. Used with a pipe (|) and TAB or HTML, we get that type of output. Please see below for details on each. In each case, the result of the B{} token is a PHP variable called $bucket_data, which we can either process when using the B token with no options, or issue a PHP echo to display its content when using the HTML or TAB option.

One final note: Unlike the BI and BUCKET tokens, the B token delivers ALL rows of data, even unrepeated ones, aka, the first row.

The Bucket Indexed Raw Token

In some instances we'll need to pull the value of a Bucket field in a PHP Code block or when using a Web Servcie (HTTP Call). In those cases we'll want to use the "raW" form of the Bucket Indexed token, which is the same as the standard bucket token only with an additional R at the end: BIR{bucket_name|index|field name}

For exmaple, to build a web service parameter list we can use: Bucket0Name=BIR{bucket1|0|Name}&SR=SR{Sample}

Raw PHP

To get our raw bucket data as an associative array, we use the B token with no options as in:

B{Bucket_Name}

This creates a PHP variable named $bucket_data, which is an associative array in the form of:

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [EmailField] => Array
                        (
                            [value] => info@rackforms.com
                            [label] => Email
                            [row-number] => 1
                        )

                )

            [1] => Array
                (
                    [AgeField] => Array
                        (
                            [value] => 38
                            [label] => Age
                            [row-number] => 1
                        )

                )

        )

    [1] => Array
        (
            [0] => Array
                (
                    [EmailField-bucket-f761b3c669b67a82e6ccac4bbc6ab18b] => Array
                        (
                            [value] => steve@yahoo.com
                            [label] => Email (1)
                            [row-number] => 2
                        )

                )

            [1] => Array
                (
                    [AgeField-bucket-731ac0112347483e07999920e7b7589d] => Array
                        (
                            [value] => 67
                            [label] => Age (1)
                            [row-number] => 2
                        )

                )

        )

    [2] => Array
        (
            [0] => Array
                (
                    [EmailField-bucket-b5f76452ff2b58d748bab5a74b485597] => Array
                        (
                            [value] => tom@hotmail.com
                            [label] => Email (2)
                            [row-number] => 3
                        )

                )

            [1] => Array
                (
                    [AgeField-bucket-8dee599e3297510e69c2d6feb9586dcb] => Array
                        (
                            [value] => 34
                            [label] => Age (2)
                            [row-number] => 3
                        )

                )

        )

)

              

As noted above, please keep in mind that unlike the BI and BUCKET tokens, this array contains all rows of data, even the first, non-repeated row. This makes the B token an excellent choice for creating a comprehensive view of our bucket data.

HTML Display

We may want to display a bucket's contents as HTML on a page. To do so we'll use the B token with a sub-property of |HTML, as in:

B{Bucket_Name|HTML}

It's key to note this token works slightly different from others, in that instead of using the token to generate and display content in one step, this token only generates raw HTML code. See below for how we access the generated value.

This creates a table-based HTML block containing all related rows for that bucket. Please note this token is identical in functionality to BUCKET{Bucket_Name} with one exception, the BUCKET token only displays repeated rows, this token displays all rows.

To place this HTML output on a page, add to a flat file, send to SQL, and so on, simply add a Code Block, SQL+ item, or text field directly below where the token was placed, and issue:

<?php echo $bucket_data; ?>

Tab Delimited Data

We can output the result of a bucket repeater as tab-delimited data using the B token with a sub-property of TAB as in:

B{Bucket_Name|TAB}

This is very handy for times when we need to export data to Excel, Google Sheets, and so on. The same basic use for the HTML output applies here as well. To access this raw data simple issue a call to:

<?php echo $bucket_data; ?>

Please Note These Important Bucket Repeater Limitations:

• At this time bucket repeaters do not support file upload items.
• As a workaround, whe SQL+ item offers a way for us to easily populate a database table with repeater elements via the Bucket Repeater Processing Mode option.
• Bucket Repeaters do not support dynamic or SQL driven items for select, radio, and checkbox items. The only items a repeated element will contain are static, hand-entered values. This also applies to dynamic code generation, which means features like the PHP range() Expression are not allowed.
• The fields within a Bucket Repeater cannot be populated using raw text or G{} tokens. However, we can use the S{} token to supply default values to our fields.
• Bucket Repeaters do not validate on the client side, only server side.

Managing Bucket Repeater Item Order

One tricky aspect of Bucket Repeaters will be the ordering your items display in Email items. Specifically, the order in which you create and place items will usually not match the visual display in the form editor.

Repeating Bucket Logic Enabled?

This feature allows us to say this bucket and its contents can be duplicated by the user at run time.

Repeating Bucket Control Visibility?

When enabled, the repeating bucket displays controls next to each item. This is generally what we want, but as of Build 885, we have an alternative -- hide these controls and instead control buckets via API calls.

Bucket JavaScript API

This is an option as we now have a new method of controlling repeating items: with a simple JavaScript call. Assuming our bucket has a Name/Value of seriesbucket, we can call:

bucket_repeater.populate_to('seriesbucket', this.value);

We'll generally want to wrap this in an event call in an items Extra Attribute(s), JS, Event Code, etc block:

onkeyup="bucket_repeater.populate_to('seriesbucket', this.value);"

When used in this way, the user no longer needs to click a control to create new items, they simply input the number of items they desire in a text box, from a select menu, and so on.

Limitations: While this is a handy control, we currently have a few items to be aware of: First, this logic only works on the initial page load. Thus, this is only useful for single page forms. Second, this feature is still in beta, and may exhibit bugs. Please use at your own risk.

Numbering Logic

As of Build 885 Bucket Repeaters have gained a useful function: If our repeating bucket contains of of these keywords followed by a space and then a number(which must start from 1), RackForms will automatically tag any repeated items with the next number in sequence:

Week, Day, Year, Month, Item, Number.

As of Build 897, we will also process:

Person, Action, Incident, Ticket, Reservation, Invoice

For example, we can add this text to a Body Copy item:

Week 1

And any bucket repeaters applied to that item will, upon incrementing that field, display the subsequent value as:

Week 2

And so on. Please note that just as with Repeating Bucket Control Visibility, this feature is still in beta, and may exhibit bugs.

Treat As An HTML Fieldset Element?

This option, when enabled, will turn the standard DIV code a bucket uses into an HTML fieldset element. This can be handy for styling tasks, as the fieldset element wraps the containing elements in a border.

To make these styling tasks easier, RackForms adds a class name of fieldset to all fieldset enabled buckets.

Fieldset Legend

If we've enabled Treat As An HTML Fieldset, this will be the legend property of the fieldset. This is a block of text resting at the top left part of the fieldset. It's key to note this text "breaks" the border the rest of the fieldset in enclosed in to maximize readability.

Responsive Layout Mode

This option controls how the Bucket's elements are laid out on the page.

Do Not Use Responsive Layout - The default mode for Buckets is this option, and is that way because the default page layout type in RackForms, sortable doesn't allow for items to lay side-by-side. While we cannot place items in random places at the page level the benefit is our layout automatically resizes itself when dynamic content is active on the form. For example, if we had a checkbox that displayed a textfield when checked we'd want to make sure hiding that same content didn't create an empty space on the form.

Of course we'll still need to have some fields laying side-by-side and that's where this option comes in. This option means Bucket elements are positioned absolutely (meaning elements lay wherever we manually position them). Thus, when a Sortable layout is combined with a Bucket, contained elements will show in any layout we choose but still live within a larger, sortable layout that properly resizes in response to dynamic content. In fact, a common design pattern is to show and hide entire Buckets, as this way we can have the best of both layout modes.

While convenient this mode has a major drawback when our forms are on a responsive page, or the Bucket itself contains dynamic show/hide elements. In those cases the Use Responsive Layout Mode should be used.

Use Responsive Layout - This option is for forms that use responsive design or have Bucket elements that show and hide in response to user input. Key to this mode is all elements are float:left, meaning elements aren't placed in random positions but rather stacked from left to right.

Critical implementation details for this mode are:

• All fields within the Bucket must use a % width instead of px.
• A "row" of content is created when the combined % values for one or more items equals 100%

This means we'll need to manually select each item in the bucket and set its Field Width property to a % value. For example, if we wanted to have two items on a single row, we'll set each items Width properly to 50%. For 3 items 33%, and so on.

So long as this requirement is met this option will update the editor display to more closely (though not exactly) match these new layout constraints. As long as each item has a width value instead of a px., you'll notice elements automatically resize themselves to the parent bucket using the column % rules you define.

Finally, it's very important to note a bucket will only be responsive if the Custom Width property, again, described next, is set to a % width as well.

Custom Width

This field is used in conjunction with the Responsive Layout Mode option to create buckets where content is fully responsive, that is, automatically and appropriately resizes. As noted above, for a bucket to be fully responsive, this value must be a positive integer % value.

By default this field is blank, which means we use the set px. width as defined by manually resizing the bucket.

Custom Bottom Margin Px.

When using a responsive layout, this is how much bottom padding each row of items contains. The default value of 15 is usually a good compromise between readability and efficiency.

Repeating Bucket JavaScript Library

The library we use to process the repeating bucket. The default is jQuery, and should almost always be left as is. Please note jQuery is required if we use Custom JavaScript Code.

Entry Limit

Entry Limit sets how many times a bucket can be duplicated.

Entry Limit Message

If the entry limit is exceeded, this is the message shown to the user alerting the user.

Add Animation
The animation effect to play when adding the bucket item.

Remove Animation
The animation effect to play when removing the bucket item.

Custom JavaScript Code

This field allows us to define custom JavaScript code to run against the current repeated row. Please note this feature requires us to use jQuery as our Repeating Bucket JavaScript Library.

In almost all cases this should be a function called rjs(). This is because only functions called rjs will have unique names applied by the RackForms bucket creation and copy process. Any additional calls will simply be duplicated as is, leading to multiple function calls with the same name.

Thus, a typical value for this field to add together two fields named a and b and place the result into a field called c using jQuery will be:

function rjs(){

$('#c').val( parseInt($('#a').val()) + parseInt($('#b').val()) );

}

Please note this restriction may be relaxed at some point.

Please also note the JavaScript code we use in this block should match the library selected in the buckets Repeating Bucket JavaScript Library property. Thus, if we have jQuery selected, our code should use jQuery syntax.

Please see this explainer video for a detailed explanation and example of this field.

Custom JavaScript Events For Add/Delete Actions

When a user clicks the add or remove buttons on a bucket a custom event is fired. We can monitor this event and react to it using our own custom JavaScript event handler code. At minimum, we'll need to listen for this event with the following code:

Adding a new Bucket Item:

$(document).on( "bucket:add", function( event ) {
console.log(event);
});

Removing a Bucket Item:

$(document).on( "bucket:remove", function( event ) {
console.log(event);
});

We can also modify these event triggers by opening and modifying the file:

rackforms/app/movefiles/bucket-repeater/process-bucket-jquery.js

Search for the text: bucket:add and bucket:remove. There you'll find the event trigger code, which can be extended to include any other parameters your logic requires.

Advanced Bucket Topics

Accessing bucket repeater count: One common need is to see how many rows were added beyond the standard first item. We can access this value by taking the prefix:

fb-bucket-repeater-

And adding the bucket name to the end in an F{} token. For example, a bucket with the name of bucket1 would be:

F{fb-bucket-repeater-bucket1}

This will be blank if no items have been added, and then indexed 1 per item added. In other words, this is not the total number of buckets, but the total minus 1. It doesn't count the first bucket item, only ones the user has added.