Improve integration with entity form button-level and form-level submit handlers, form/entity (re-)building, and previews

There are modules which try to integrate with all (entity) forms and want to store data for a newly created entity upon form submission.

Node module's node_form() uses both button-level and form-level submit handlers, because it needs to take the "Preview" case into account, which does not create a new entity upon submit.

When hitting "Submit" (not Preview), then the button-level submit handler invokes all form-level submit handlers first. This means that the new node has not been saved yet, so form-level submit handlers do not have a 'nid' or $node to work with.

For example:

@@ -658,7 +658,18 @@ function mollom_form_alter(&$form, &$form_state, $form_id) {
      // Append a submit handler to store Mollom session data. Requires that
      // the primary submit handler has run already, so a potential 'post_id'
      // mapping can be retrieved from $form_state['values'].
      // @todo Core: node_form_submit() uses a button-level submit handler,
      //   which invokes form-level submit handlers before the node/entity is
      //   saved, so $form_state does not contain the new node ID yet. There is
      //   no #post_submit property or form processing phase, we could rely on.
      //   Potentially applies to other contrib entities, too.
      if (isset($form_state['build_info']['base_form_id']) && $form_state['build_info']['base_form_id'] == 'node_form') {
        $form_submit_key = &$form['actions']['submit'];
      }
      else {
        $form_submit_key = &$form;
      }
      $form_submit_key['#submit'][] = 'mollom_form_submit';

This is a can of worms.

There are various kinds of submit handlers:

1. Submit handlers that want to tack submitted form values onto the $entity. Those should use #entity_builders instead.
2. Submit handlers that must not run for previews.
3. Submit handlers that want to run before the entity is saved, in order to adjust/manipulate whatever they need to do.
4. Submit handlers that need to run after the entity was saved, in order to process or save corresponding data.