How can I theme a form "checkboxes" element?

Question

I've got a checkboxes field displayed on the user profile form. I'm trying to restyle that field to put the description BEFORE the checkboxes. That seems like it should be a simple thing?

So far I've got:

function MYTHEME_form_user_profile_form_alter(&$form, &$form_state, $form_id) {
    $form['my_field_id'][LANGUAGE_NONE]['#theme'] = 'checkboxes_description_before_element';
}

function MYTHEME_theme($existing, $type, $theme, $path) {
    return array(
        'checkboxes_description_before_element' => array(
            'render element' => 'element',
            'function' => 'theme_checkboxes_description_before_element'
        ),
    );
}

function MYTHEME_checkboxes_description_before_element($variables) {
    return "XYZ";
}

The checkboxes field is still stubbornly sitting on the markup generated by theme_checkboxes instead of "XYZ".

I know that the form element is getting the new '#theme' through checking with dpm().

Answer 1

The checkboxes description is not rendered in theme_checkboxes or theme_checkbox. It comes from theme_form_element.

1. If you want every form element on the site (not just checkboxes) to have the description first, then you could just override and modify theme_form_element.
2. If you want only specific checkboxes to have this, then you could override and modify theme_form_element to position the description based on a variable (similar to what it already does with #title_display). You could then set the variable when creating the FAPI array.
3. If you want all checkboxes (but only checkboxes) to follow this behaviour, then you could override theme_form_element as above, and use hook_element_info_alter() and change checkboxes to have the new variable you created appopriately set.

Let me know if you have any questions.

Answer 2

This seems to be pretty similar to How to theme a radio button field on node edit form?, I think this should explain what you're looking for.

Answer 3

I have done this before and I can find the code if this first suggestion doesn't work.

If you just need to put the description before the checkboxes, you can use hook_form_alter and add a #field_prefix to the field.

I assume you have the knowledge to extract the field description, unset it from below the checkboxes and put it into the #field_prefix?

Answer 4

There are 2 functions that are responsible to theme checkboxes: theme_checkboxes() and theme_checkbox(). Where the former themes the wrapper div around the checkboxes, the latter themes the individual checkboxes.

If you want to override one of them or both you should copy them in template.php file under your theme folder and rename like YOURTHEME_checkboxes and YOURTHEME_checkbox.

Then don't forget to clear the caches.