Why does the '#weight' property sometimes not have any effect in Drupal forms?

Question

I'm trying to create a node form for a custom type. I have organic groups and taxonomy both enabled, but want their elements to come out in a non-standard order. So I've implemented hook_form_alter and set the #weight property of the og_nodeapi subarray to -1000, but it still goes after taxonomy and menu. I even tried changing the subarray to a fieldset (to force it to actually be rendered), but no dice. I also tried setting

$form['taxonomy']['#weight'] = 1000 

(I have two vocabs so it's already being rendered as a fieldset) but that didn't work either.

I set the weight of my module very high and confirmed in the system table that it is indeed the highest module on the site - so I'm all out of ideas. Any suggestions?

Update:

While I'm not exactly sure how, I did manage to get the taxonomy fieldset to sink below everything else, but now I have a related problem that's hopefully more manageable to understand. Within the taxonomy fieldset, I have two items (a tags and a multi-select), and I wanted to add some instructions in hook_form_alter as follows:

$form['taxonomy']['instructions'] = array(
  '#value' => "These are the instructions",
  '#weight' => -1,
);

You guessed it, this appears after the terms inserted by the taxonomy module. However, if I change this to a fieldset:

$form['taxonomy']['instructions'] = array(
  '#type' => 'fieldset', // <-- here
  '#title' => 'Instructions',  // <-- and here for good measure
  '#value' => "These are the instructions",
  '#weight' => -1,
);

then it magically floats to the top as I'd intended. I also tried textarea (this also worked) and explicitly saying markup (this did not).

So basically, changing the type from "markup" (the default IIRC) to "fieldset" has the effect of no longer ignoring its weight.

Answer 1

This sounds pretty strange because the manipulation of the form elements' #weight parameter always works reliably for me as advertised. One thing to note, though, is that the weights only affect the order relative to the elements siblings, so if the element you want to move around is on a level below that of the other elements, you'd have to change the weight of the parent element that is on the same level as the ones you want to move against.

To clarify, if you have a hierarchy like so,

$element['foo'];
$element['bar'];
$element['bar']['baz']

you can not move 'baz' relative to 'foo' by setting the weight of 'baz'. You'd have to either set the weight on 'bar' (moving it also), or pull out 'baz' and bring it to the same level as 'foo'.

Another possible reason could be CCK: If you have CCK installed, it allows you to set the order of its own as well as other fields under admin/content/node-type/<yourNodeType>/fields. It changes the order by registering the pre-render callback content_alter_extra_weights(), so this would run after your changes in hook_form_alter.

---

Edit: Update to answer the question update

The markup field type has a special behavior when used inside fieldsets, which is hinted on in the forms api documentation:

Note: if you use markup, if your content is not wrapped in tags (generally <p> or <div>), your content will fall outside of collapsed fieldsets.

It looks like if it does not only fall outside of collapsed fieldsets, but also refuses to respect the weight in those cases. Wrapping the content of the markup field in <p> tags makes it respect the weight on my machine:

$form['taxonomy']['instructions'] = array(
  '#value' => "<p>These are the instructions</p>",
  '#weight' => -1,
);

Answer 2

Sometimes (or always, when weighting CCK elements) the line that works in your hook_form_alter or $form['#after_build'] callback is this one:

$form['#content_extra_fields']['taxonomy']['weight'] = 5;