What is the best practice for theming?

Question

I'm about to start theming a Drupal 7 website for the first time. I've watched Moshe's video, Lia Clark's introduction to theme overrides using context naming, and Franz's talk at Drupalcon Chicago. These are all great, but like everything else in Drupal there must be a thousand different ways to theme now.

What is are the best techniques and practices to theme now in Drupal 7? More specifically, how do I best use hook_page_alter($page)? I'm imagining that after I move all the parts of the page around it will be huge and unwieldy. Are there ways to add a region to a node template?

Edit:

Here is an example of moving a page region that is populated with the Context module while the block module is disabled completely. It was the first way of doing this that came to my mind. Why someone would want to put a region between the links and comments, I don't know. Still it's cool to be able to put stuff there.

In template.php:

function hook_page_alter(&$page){

  $main_content_display = &drupal_static('system_main_content_added', FALSE);

  // Need to beat common.inc drupal_render_page() line 5485 to this
  if (!$main_content_display) {
    $page['content']['system_main'] = drupal_set_page_content();
  }

  if ($node = menu_get_object()) {
    $region_to_embed = $page['sidebar_first'];
      $page['content']['system_main']['nodes'][$node->nid]['#node']->region = $region_to_embed;
    unset($page['sidebar_first']);
  }
}

And in node.tpl.php:

  <?php print render($content['links']); ?>
  <?php if ($node->region): ?>
    <?php print render($node->region); ?>
  <?php endif; ?>
  <?php print render($content['comments']); ?>

Answer 1

Kind of a "big"/multiple question(s), that is hard to answer. Try to ask more specific, single questions in the future.

About hook_page_alter(). In a theme, you should customize the output by overriding default templates. IMHO, that hook is more meant if modules want to alter the output of other modules, especially if they return render arrays instead of arbitrary strings.

Speaking of render arrays, that is one of the main things I do with my modules now, instead of arbitrary templates. I've already replaced quite a few specific "page callback templates" by building and returning a so called render array. The advantage is that, if you for example want to change the order of the table rows, or add/hide a table row, you can do that without duplicating a template with maybe 100 lines of code. And, multiple modules can add/change things.

Two examples:

• userpoints_admin_transactions()
• user_relationships_page()

Edit:

And for your last question: Regions in "Theme-speak" are places where blocks can be placed. Regions are defined in the .info file of a theme. The node template itself is more or less a block (The "Content" block, which is the output of the executed page callback). Since it is not possible to nest regions within regions/blocks you can also not place regions in a node template.

That said, you can make your node template as complex as you want, and split the content up into "visual regions" for example.