Fix theme system regressions in 4.7

Oops -- sorry... made a mistake.

I just noticed that phptemplate is using path_to_theme now... so changing it breaks other things.

Attached is the same path, but with the path_to_theme changes removed. Contrib themes will just have to add a base_path() to all their path_to_theme calls, I guess.

Sorry for the noise.

changes are very minor -- but important. Please review/commit.

I actually think this needs better documentation, but I'm not sure where to place it.

theme_add_style and theme_get_styles were added shortly after the big theme patch landed to solve the problem of referencing stylesheets in the proper order. At that time, we only had drupal_set_html_head available to us. We needed to reference drupal.css (which comes from drupal_set_html_head / drupal_get_html_head), common.css (which is part of chameleon), then style.css (which is style-specific)... but it was important that they were referenced in the order I just listed. The solution (which I credit to Steven) was theme_add_style. theme_add_style is for use by the theme system for including style-specific CSS. It can also be used by end-users on PHP pages (or perhaps by a yet-to-be-written "custom user-created stylesheet" module) for including CSS only on certain pages within the site.

Modules, on the other hand, should not be using theme_add_style because situations can develop in which themers cannot override module-specific CSS. (module CSS should be referenced BEFORE all theme CSS) For this reason, modules should use drupal_set_html_head instead.

The problem in the chameleon theme is that it's specifying to theme_add_style to reference the common.css file in the chameleon_page function. By the time we run that function, we've already executed init_theme, which is where style.css gets passed to theme_add_style. The styles are them returned (by theme_get_styles) in that order, which is the opposite of what most themers are going to expect. Style-specific CSS should be last. (unless followed by page-specific CSS, which is why theme_add_style can be used in PHP pages)

theme_stylesheet_import is used to generate the HTML necessary to reference a style. We could use it in chameleon.theme if we wanted. I actually didn't use it because I forgot about it. I've attached a new patch which uses theme_stylesheet_import instead of a link tag.

Please let me know if any of this is unclear; it's quite late here, so my explanation may end up being a bit confusing.

To clarify:

// Modules should do:
drupal_set_html_head(theme('stylesheet_import', base_path() . drupal_get_path('module', 'mymodule') .'/mymodule.css'));

// user-created PHP pages/blocks/comments/etc. should do:
theme_add_style('misc/local/my_custom_style.css');
// (theme_add_style is also used internally for the style.css files)

// chameleon (and other themes) should do:
$output .= theme('stylesheet_import', base_path() . path_to_theme() . '/extra_stylesheet.css');
/* note that this should be BEFORE theme_get_styles, which will reference
   the style.css file and anything added by the user... themers will probably also
   want it located after drupal_get_html_head, which will bring in any module-specific CSS
*/

So this is the order we end up with:
1. drupal.css
2. module CSS (i.e. event.css from event.module)
3. theme CSS (i.e. common.css from chameleon)
4. style CSS (style.css files from any theme)
5. user CSS (something page-specific)

Stylesheets can override rules applied in any CSS which precedes them. (i.e. style CSS can override everything else, except for user CSS)