Introduce hook_theme_suggestions[_HOOK] and hook_theme_suggestions[_HOOK]_alter

[jenlampton]

Problem/Motivation

The preprocess phase is responsible for too many aspects of the theme system, including providing alternate theme hook suggestions. This makes things tangled and makes critical issues like #939462: Specific preprocess functions for theme hook suggestions are not invoked more difficult to solve than they should be.

Proposed resolution

Move the creating/altering of theme hook suggestions to separate hooks, and handle the altering of theme hook suggestions before any preprocess functions are called.

API changes

New hooks introduced:
hook_theme_suggestions_HOOK(array $variables)
hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

Removed the ability to change template suggestions in preprocess functions by altering $variables['theme_hook_suggestion'] and $variables['theme_hook_suggestions'].

Code that altered $variables['theme_hook_suggestions'] or $variables['theme_hook_suggestion'] in preprocess needs to be moved to suggestion hooks:

From the module that is implementing hook_theme():
Suggestions code is moved from template_preprocess_HOOK() to returning an array in hook_theme_suggestions_HOOK().

Before:

/**
 * Prepares variables for search results templates.
 */
function template_preprocess_search_results(&$variables) {
  $variables['theme_hook_suggestions'][] = 'search_results__' . $variables['plugin_id'];
}

After:

/**
 * Implements hook_theme_suggestions_HOOK().
 */
function search_theme_suggestions_search_results(array $variables) {
  return array('search_results__' . $variables['plugin_id']);
}

Here's the corresponding issue on d.o: https://drupal.org/node/1751194