2. Positioning

This module uses a grid-based approach to describe where to put form elements. Rows and columns are numbered starting with 1, not 0, however. This avoids a conflict with the way Drupal uses element weights, internally. Furthermore, when using the table theme, row 1 is considered to be the table header; its cells are always surrounded with <th> tags.

Row and column numbers need not be sequential. You could have row numbers like 2, 10, 99, 101 if you want. The important thing when using the table theme is to be consistent for each row, because any "missing" values will be subject to column or row "spans", to take up the gaps. See the section on Omitting Rows/Columns for more details.

There are four different ways row and column numbers can be represented for this module. It is important that you not mix methods within a given table or themed <div>.

Using #form_panel_row and #form_panel_col

The easiest method to understand is to explicitly set the row and column numbers using two special attributes that the theme function reads.

In the example that follows, and most of the other examples in this document, we're using a simple #value to represent the form element. Normally, you would set #type, #title, #description, and other attributes to define a real form element that accepts user input.

  $form = array(
    '#theme' => 'form_panel_table',
    '#form_panel_table_attributes' => array('border' => 1));
  $i = ord('A');
  $form[chr($i)] = array('#value' => chr($i++),
    '#form_panel_row' => 2, '#form_panel_col' => 1);
  $form[chr($i)] = array('#value' => chr($i++),
    '#form_panel_row' => 2, '#form_panel_col' => 2);
  $form[chr($i)] = array('#value' => chr($i++),
    '#form_panel_row' => 3, '#form_panel_col' => 1);
  $form[chr($i)] = array('#value' => chr($i++),
    '#form_panel_row' => 3, '#form_panel_col' => 2);
  // This next line is just an example. Normally, you would "return" the value.
  print drupal_render($form);

Integer

This is the default method, if #form_panel_row and #form_panel_col are not specified.

In this method, the row and column are represented by setting the #weight of an element to an integer from 1001 to 999999. The thousands part of the number is the row, and the part less than 1000 is the column.

Example:

  $form = array(
    '#theme' => 'form_panel_table',
    '#form_panel_table_attributes' => array('border' => 1));
  $i = ord('A');
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 2001);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 2002);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 3001);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 3002);
  print drupal_render($form);

Decimal

To use this method, you set the #form_panel_weights_decimal attribute on the outer form element to TRUE.

In this method, the row and column are represented by setting the #weight of an element to a decimal number from 1.001 to 999.999. The integer part of the number is the row, and the fraction (the part to the right of the decimal point) is the column.

To make the code look cleaner, you can leave off the extra zeros in the fraction, if you are dealing with few enough columns. For instance, the rows/columns (1.001, 1.003, 1.007) can also be represented as (1.1, 1.3, 1.7). That's because, internally, the columns get converted to 100, 300, and 700.

You need to be careful when using this method, however. If you use the weight 1.1 to represent (row=1, col=1), how do you represent (row=1, col=10)? The numbers 1.1 and 1.10 are identical, as far as PHP is concerned. Instead, you need to use either 1.01 or 1.001 for (row=1, col=1). Then, you can use either 1.10 or 1.010 for (row=1, col=10).

Example:

  $form = array(
    '#theme' => 'form_panel_table',
    '#form_panel_table_attributes' => array('border' => 1),
    '#form_panel_weights_decimal' => TRUE);
  $i = ord('A');
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 2.1);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 2.2);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 3.1);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 3.2);
  print drupal_render($form);

Hexadecimal

To use this method, you set the #form_panel_weights_hex attribute on the outer form element to TRUE.

In this method, the row and column are represented by setting the #weight of an element to a hexadecimal number from 0x0101 to 0xFFFF. The part of the number >= 256 (decimal) is the row, and part of the number < 256 is the column.

Example:

  $form = array(
    '#theme' => 'form_panel_table',
    '#form_panel_table_attributes' => array('border' => 1),
    '#form_panel_weights_hex' => TRUE);
  $i = ord('A');
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 0x0201);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 0x0202);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 0x0301);
  $form[chr($i)] = array('#value' => chr($i++), '#weight' => 0x0302);
  print drupal_render($form);