Child Form

A child form is displayed under an active Profile Tab with its contents solely dependent upon the specific Profile's topic or title.

Note: The information within constitutes the Child Form, not the button or icon that displays the form.

A child form is a list of records or information that are dependent upon a specific "parent" title or topic. This terminology is derived from a typical "parent-child" relationship you would find in a home and their intrinsic dependency on each other, for example the "parent" Individual (Profile Page) has child forms displaying multiple "child" records for Individual Addresses, Individual Phone Numbers, Event Registrations, etc.

On the left is a simple child form showing a committee and the active members that currently belong. From a child form, an end user may add new child records, or edit, delete or go to existing child records, by clicking on the corresponding buttons.

Though most commonly displayed on a Profile Page under Profile Tabs, child forms also are used on Module Overview Pages, for Duplicate check child forms and for Correspondence Template Child Form HTML.

Managing Child Forms

A child form is linked directly to its parent form, and is added initially from the Form profile page, either from the child forms child form on the Primary tab, or from the add child form button on the Action Bar.

Once you have saved your child form, then you can edit it from the Form profile form on the child forms child form on the Primary tab, or for more convenience, you may edit the child form directly from the end user page by clicking the small edit child form button.

Displaying a Child Form on a Form

Once you have added a child form, in order for it to actually appear, you'll need to do one of the following, depending on the type of Form on which you want to show your child form.

• Profile Page - to place your child form on a profile page, you must add a Profile Detail to choose which Tab to place the child form; see Profile Detail, Move Child Form to Different Tab and Training: Place Child Form on Tab for tips. Note that you can show a child form on any profile page (as long as that Form belongs to an object that can parse the values in the child form select sql), not just the Form to which the child form initially was added; see Sharing Child Forms with Multiple Parent Forms for more details.

• Non-Profile Page - If the parent form is not a profile form (like the Country/State example in the image above), then you are done. All child forms added to the form will display, as long as the has child forms checkbox is checked on the parent form. There are not a lot of these kinds of pages in NetForum; most pages have enough child forms that it made sense to separate them into tabs.

• Module Overview Page - Works the same as Profile Page above; you'll need to add a Profile Detail on the Tab on which you want the child form to appear.

Primary Controls

Child Form Description: The description of the child form. By convention, this is named Parent Form -> Child Form, for example, Individual -> Individual Address. This description appears only in the Toolkit and not to the end user.

Title for Grid: This is the caption that will appear to the end user on the child form title grid.

Parent Form: The form under which this child form will appear. In the example above, the parent form is the Association.

Destination Form: The form you want the user to go to if they add or edit a record from the child form (with some abilities to [[Child Form Override Links|override]).

Parent Child Form: The parent child form (if any) of a child form, if the child form is to appear as a Grandchild Form under the Parent Form. See Grandchild Form below for more.

Order: The order that child forms will appear from top to bottom.

Child Key Column: The primary key column of the rows that will appear in the child form. This column must be selected in the Select SQL. This column is essential to the NetForum framework. The URLs behind the edit, delete, and goto icons must point to the correct record, and it is the Child Key Column that identifies the record.

Select SQL: The Select SQL statement returns the records that will appear in the child form. See Child Form Select SQL for how to write this statement.

Allow Add?: Check this checkbox if the user is allowed to add new records from the child form. When this is checked, the small add icon will appear on the right of the child form title bar, as shown above.

Allow Edit?: When checked, the edit icon will appear so that users may edit the record, as shown above.

Allow Delete?: When checked, the delete icon will appear, as shown above.

Allow Go To?: When checked, the GoTo icon will appear, as shown above. By convention, if you allow go to, then to make it apparent to end user where the goto is going, make the left most column that appears in the child form be associated with where the goto form is going. For example, if the destination form is Individual, then have the individual’s name on the left; if the destination form is Event, then have the Event Name column be the leftmost column.

Allow Export?: When checked, enables an export icon to appear.

Allow Preview?: When checked, a Child Form Preview icon will appear.

Goto Form: By default, the GoTo icon will take the user to the destination form of the Child Form. The GoTo arrow may be overridden by choosing a different GoTo form.

A common example of this is on the Committee Participant child form of the Committee Form. The edit icon will allow the user to edit the information about the Committee assignment, such as start date and end date. But the GoTo arrow can be configured to link to the actual Committee Participant profile page of that Committee member. Another example is the Mailing List profile page. Editing a mailing list member from the child form allows you to edit that record. But the "goto" takes you to the Individual.

To choose an override GoTo form, select the desired form.

Goto Key Column: If a GoTo Form is specified, the key column of the record to be accessed must be entered here and that column must be chosen in the Select SQL.

Is Recursive?: If the child form relationship can be recursive, check this box. An example is Committees and Sub-Committees, which can have an unlimited number of Sub-Committees. See Recursive Child Form for more.

Has Override Links?: Click this if there are override links for the child form. See Child Form Override Links for more information.

Visibility Controls

Child forms can be made conditionally visible or read-only depending on certain conditions. Additionally specific rows in a child form can also be made conditionally visible or invisible.

Row Level Security (RLS)

Sometimes a user should be able to see the child form information, but that same user should not be allowed to Edit or Delete the line on the child form. Row Level Security (RLS) allows an organization to control if a user can see the Edit and Delete icons on child form lines. See the main article for detailed information on Child Form RLS.

Advanced Controls

These are rarely or never used fields, accessible on the advanced page. Several of these fields are deprecated. The only field that is used on even a semi-regular basis is comments for grid.

Title Icon: The path and file name pointing to a small image icon that may appear on the title bar. The path may be absolute or relative.

Comments for Grid: Grid comments will appear directly under the title bar. This field supports HTML tags. Comments do not appear for grandchild forms.

Place Below Control: Deprecated field. Leave this empty.

Wizard Form: If the child form should activate a Wizard, select the Wizard Form here.

Same Window for Add?: By default, the add link on the child form bar opens the child form in a new popup browser window. Click this checkbox to make the add form stay on the same browser window instead of a popup. This does not apply if the Add form is a Wizard, only if the add form is a regular form.

Same Window for Edit?: Similar to Same Window For Add?, this checkbox will make the edit link stay on the same browser window. The default for edit links is to open a new browser in a popup form.

Static Edit Form: If you need to pass parameters to the form that opens up, for example to default the value of a control on the destination form, you can do so in this field. Preface the parameters you want to pass with the & character, for example, &a99_code=New. More rarely, you may enter the file name of a static edit form if the dynamic edit form is not to be used, for example, ~/forms/DocumentUploadModal.aspx. Width: Enter the width in pixels (eg, 375) to constrain the width of a child form.

Height: Enter the height in pixels to constrain the height of a child form. Not commonly used.

Stylesheet Class: Choose a cascading style sheet class for a child form. One commonly used class is SidePanelUnderline.

Uses

Correspondence Template Child Form HTML

A Correspondence Template can use Correspondence Template Child Form HTML to display a grid listing multiple detail items.

Move Child Form to Different Tab

If you want to move a Child Form from one Tab to another, you must do the following.

1. Navigate to the Profile Form. The easiest way to do this is to navigate to the profile form that has the child form you want to move, then copy (Ctrl-C) the FormKey from the querystring, then Paste (Ctrl-V) this into the Super Search search field and click the Find button. (Alternately, navigate to the Form from the Toolkit module.)
2. In the super search results list you should see the Form. Goto the Form.
3. On the form setup page, go to the tab called Profile.
4. The first child form on this tab is called profile tabs. Find the tab on which the child form currently is, then expand the folder to view the child forms on that tab.
5. Edit the profile detail containing the child form you want to reposition and switch the child form from one tab to a different tab.
6. After moving the child form, expand the Tab to which you moved the child form, and view the list of child forms on that Tab. Be sure that the order is where you want the child form to be positioned vertically. If you want to move it up or down, then change the number.
7. If you are moving a baseline child form, then be sure that you have Locked the profile detail metadata to ensure that your change is not reversed after an Upgrade.

Recursive Child Form

A recursive child form is a child form that will expand with nested grandchild forms infinitely as deeply as the data goes. The nearby examples shows committees and sub-committees. Another example is the organization tree child form.

Destinations of Child Forms

Suppose you are trying to get a list of all the child forms that point to a particular Form, or to any Form of a particualar Object. See main article for suggestions on how to do this with a special Query and by using the where form is used child form on the Form.

Grandchild Form

NetForum permits an unlimited amount of child-form nesting, although it is not recommended to go deeper than grand-child forms as this can be visually challenging for the end user, and it slows down the system. In the nearby example, you see a parent and child form:

Be aware that having grandchild forms can greatly slow down the load speed of a child form. Remember that it requires a single SQL command to load one child form (the SQL command is from the select sql). For grandchild forms to run, an additional SQL command is run for every row in the "main" child form. So, if ten records are displayed, then there will be eleven SQL commands to run. One for the first pass, and then one additional SQL command for each of those ten records.

For this reason, many of the grandchild forms in earlier versions of NetForum have been removed. Instead, if the user wants to see more information about a record, then they may click the goto arrow to navigate to that record. For example, instead of expanding an Invoice to see the Invoice Details, the user may instead click the to navigate to that invoice.

As you can imagine, great-grandchild forms are even worse from a performance standpoint, as you must run yet another level of SQL commands to get the great-grandchild records for each grandchild.

Child Form across different Forms

While a child form is linked to a specific form, you can still display that child form on other parent forms.

For example, the child forms that display A-Score information on the Individual profile form are also on the Organization, Chapter and Constituent profile pages. Rather than duplicating the same child form repeatedly, you can instead define the child form once and show it on any profiles you need.

See linked page for how to do this.

Troubleshooting

Child forms do not appear

Q. My child forms do not appear.

A. Be sure the has child forms checkbox is checked on the parent form. Also, if the parent form is a Profile form then you'll also need to add a child formprofile detail that places the child form on a Tab.

Child Form has no column header

Q. My childform has rows but no column headers, like this:

I run the SQL in SQL Query Analyzer and I don't get any errors. What is wrong?

A. Make sure that in your Child Form Select SQL statement, each column you want to display has an alias without the underscore characters. NetForum will not output columns that have an underscore or which are the guid data type.

Wrong:

SELECT a01_key, a01_code, a01_start_date FROM ...

Right:

SELECT a01_key, [Code] = a01_code, [Start Date] = a01_start_date FROM ...

Export to Excel Fails

The Child Form Select SQL statement must follow these rules:

• Do not include any commenting out using "--". Since the Export to Excel feature processes the Child Form Select SQL in a single line, any SQL code coming after the "--" commenting will be commented out. If you need to include commented out SQL code, be sure to enclose the commented out text between "/*" and "*/".
• If using a stored procedure (SP), the SP must have permissions granted to netFORUMReport.
• If using SELECT DISTINCT syntax, be sure that there is only one space between the words SELECT and DISTINCT. Also, be sure that SELECT and DISTINCT are on the same line in the Child Form Select SQL statement.

Inconsistent Number of Records in Child Form

Normally, the maximum number of records that can appear in a child form is capped by the DataGridRowLimit system option. If a child form appears to show more than that number, it could be caused by having any of these keywords in the SQL command:

• DISTINCT
• SELECT TOP
• UNION

The reason this happens is because having any of these keywords automatically causes the system option limiter to be ignored.

Active Tab

The tab that displays by default is controlled by a query string parameter that is passed during page load. The name of the querystring parameter is ActiveTab. The ActiveTab parameter is based on the action tied to the opening of the profile. For example, if the user was adding a user to a committee, the ActiveTab parameter would be set to ActiveTab=Committees. This would cause the committees tab (if available) to be the default tab opened the next time a profile page is accessed.

FAQ

Width of Columns in Child Form

Q. How does NetForum determine how wide to make each column? Can I override these widths in any way?

A. NetForum child forms use a third party component control that auto-sizes the columns based on the relative widths of the data.The control doesn't just look at the data in a single column, it looks at all the columns as a whole and tries to “share” the space as practically and “fairly” as possible between all of the columns. This is why the same child form can take on different column widths for any particular record.

As a developer, you are unable to override the widths. Some developers have tried to do so by adding non-breaking space characters to stuff white space around column headers or data, but we discourage you from doing so as adding "fake" characters like this will foul up exports and other operations.

If it seems that one column is abnormally wide, double-check the data as you might have hidden blank characters in the data arising from a faulty data import or conversion, or some other glitch that allowed the additional white spaces to get into the data.