RackForms v7.2.4
buckets
Site Tag Line
Latest Release: Build 928 - July 28, 2019
Contact Us  Purchase Options Purchase Options Contact Us
header-image


 
Top Link
Text Bucket


In Brief: A item for storing one or more free form elements within a larger sortable page.

Dependencies: A sortable page.

Hints & Tricks: A bucket is very useful because they always act as one element, even though they can hold many other elements. This makes showing and hiding the bucket very simple using Wrapper Classes (which is just an HTML class property attached to the bucket DIV), and makes it easier to create sortable layouts where hiding elements doesn't create large blocks of empty space.

ORDERING NOTICE: Placing items in buckets means we remove them from the linear nature of a page in sortable layout mode. This means forms submitted via Simple Email and the Entry Viewer may show a different ordering then what the forms does. The fix is to make sure we create and place items first, then drag into buckets as needed. If you already have an existing form, we can simply drag elements out of the bucket, sort as needed, then drag back into the bucket. In general, the best practice is to create items outside of the buckets when using Simple Email or Entry Viewer submission modules.

Looking to add custom JavaScript Code? Please see this explainer video for a detailed explanation and example.

Important Bucket Repeater Note: While Bucket Repeaters are very handy, one current limitation we should be aware of is we cannot require items from within the repeated items a user creates.

Options/Properties


General Usage

How to Use a Bucket
The basic idea behind a bucket is to take a sortable page layout and add a group or free-form elements to it. The elements move as one group with the bucket, but can be positioned individually within the bucket.

Using buckets as container of items is quite simple:

Simply click the bucket icon to add one to a page. We can then drag the lower right hand corner of the dashed outline to resize the bucket as needed. It's important to note the dashed outline does not appear in the final form.

To add elements to a bucket we simply click the bucket to select it, then click on the form field element we wish to add. The new form field element will be added to the bucket instead of as a new sortable element in the larger form layout.

We can then position the item in the bucket as needed in what amounts to a free form layout.

The benefit here is that we can still move the bucket around the sortable layout, resize the bucket, and so on, but we also have the ability to show and hide the bucket and its children like any other form element.

This means we now have a group of elements which can be moved as a group, but still positioned individually.

Moving Elements From One Page/Bucket To Another

We can move any valid element from one page or bucket to another. That is, if we have an element on a page that element can be dragged on top of the bucket item, even if it's from a different page.

The bucket will turn green and when we release the mouse button that item will now 'belong' to that page and bucket.

We can check the bucket ownership of any item by mousing over it. The parent bucket (if any) of that field tiem will display a blue dashed outline.

Please note that in order to prevent accidental item removal RackForms will 'stick' the form element to the edge of the bucket for about 50 pixels. Once we drag the element past that inital 50 pixels however, the item will release from the parent bucket and can be dropped as needed.

Bucket Limitations And General Hints:

  • - Buckets are not well suited for free form pages. We can create them as needed, but their behavior can be erratic. Thus, at this time it's best to only use buckets with sortable pages.
  • - We cannot drag one bucket into another.
  • - Buckets do not support multiple item drag and drop as normal free form items do. Also, items must be added to buckets one at a time.
  • Tab Order Within Buckets
  • To set the tab order of the items within a bucket, click the Enter Bucket Tab Order Mode and then click on the elements in the order you want your users to tab through them.
  • To ensure your elements tab properly, be sure to click all elements in the bucket.

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 to. 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 (though not 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.

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}

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 output on a page, add to a flat file, send to SQL, or any thing common use, 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.
  • 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 load of a page. 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 very important option controls how the bucket's elements are displayed.

Do Not Use Responsive Layout - This option, the default, means elements are positioned absolutely. That is, they lay wherever we manually position them.

Use Responsive Layout - This option is for forms that use responsive design. Key to this mode is all elements are float:left and assigned specific width. A very important implementation detail is that in order for your elements to automatically resize to the current field width (set in Custom Width, described below), we must make sure they use a % width as opposed to the default px. width. This means we will need to manually select each item in the bucket and set its Field Width property to a % value.

So long as this requirement is met, selecting this option will update the editor display to match these new layout constraints. As long as each item has a width value instead of a px., you'll notice that all elements automatically resize themselves to the parent bucket.

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.


So many features, So little time