Problem/Motivation

The 'regions_hidden' attribute added to the .info file in Drupal 7 is not documented and subject to incorrect usage.

Proposed resolution

Add attribute documentation to http://drupal.org/node/171205

User interface changes

none

API changes

none

Comments

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented

The following is a suggested entry and more than likely needs correction by those responsible.

regions_hidden
This new Drupal 7 attribute can be applied to any defined 'regions'. The syntax is shown below. Regions with this attribute will not show up on the admin/structure/blocks page and therefore can't have blocks assigned to them by ordinary mechanisms. For example, Drupal uses this feature to protect the special 'page_top' and 'page_bottom' regions from adventurous themers. This can be used by module writers and theme writers to protect a given region from having unexpected content inserted into the output.

 regions_hidden[] =  'region machine name'

example: regions[my_use_only] = My use only
         regions_hidden[] = my_use_only

Adding a 'regions_hidden' statement for a region not also defined with a 'regions' statement can lead to unexpected behavior.

dddave’s picture

dddave CreditAttribution: dddave commented
Version: 7.0 » 7.x-dev
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: 'regions_hidden' attribute in .info file not documented » 'regions_hidden' attribute in theme .info file not documented
Project: Drupal core » Documentation
Version: 7.x-dev »
Component: documentation » Missing documentation
Issue tags: +theming

Where are you saying this should be added? Oh I see, you suggested adding it to "[#171205]". Only issues turn into links that way, so I guess you meant
http://drupal.org/node/171205

Moving to correct project to add this documentation to the Theming guide.

benjifisher’s picture

benjifisher
he/him or they/them
Primary language English
Location Boston area
CreditAttribution: benjifisher commented

Maybe I should open a separate issue, but this is closely related.

The keys settings and package should also be added to http://drupal.org/node/171205. I just added a comment to that effect. Both are used in the Bartik theme, themes/bartik/bartik.info.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

That page should have an "Edit" button on it. It's just as fast to edit the page and fix it as it is to comment there and on this issue. :)

benjifisher’s picture

benjifisher
he/him or they/them
Primary language English
Location Boston area
CreditAttribution: benjifisher commented

Is that "should" as in "go ahead and look for it" or as in "someone ought to put it there"?

I do not see an "Edit" button, nor a tab. I searched the page for "edit" (case insensitive) and the only link was the one next to my comment.

If you see something I don't, then I guess you have some permission on d.o that I do not have. Probably with good reason. ;)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Oh sorry! You should be able to edit the page now. It had been set to "documentation" input format, because of an image, but now that Filtered HTML can accept images, I've set it to that and now anyone can edit the page.

benjifisher’s picture

benjifisher
he/him or they/them
Primary language English
Location Boston area
CreditAttribution: benjifisher commented

jhodgdon, thanks.

I looked into it some more, and I see that drupal_parse_info_file() (D6) and drupal_parse_info_format() (D7, D8) will accept almost anything as a key name.

I think I will simply add a line that other themes and modules can add their own keys.

I have already spent some time getting this far, so I will continue tomorrow. I will have to check whether settings, package, or regions_hidden are used by Drupal core. I know that settings is used by Zen (at least in D6), and I think I saw package in Corolla (D7).

Another thing I noticed from looking at the code (and the D6 version of zen.info) is that a semicolon (";") starts a comment if it is the first non-blank character in a line. It does not have to be in column 1, although maybe coding standards say it should be.

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented

I am not sure if it is documented anywhere but I have seen strong comments somewhere that theme and module creators should not use the .info files to store local variables. That would be a bad practice to adopt. So perhaps you shouldn't mention that "feature".
If you look at function system_system_info_alter (~line 2700) in system.module you will see that Drupal does indeed use regions_hidden.
Look at http://drupal.org/update/themes/6/7#closure, http://drupal.org/update/themes/6/7#theme-settings, and http://drupal.org/update/themes/6/7#package-core for more discussion.

benjifisher’s picture

benjifisher
he/him or they/them
Primary language English
Location Boston area
CreditAttribution: benjifisher commented

@dcrocks, thanks for the links! (I do not have access to the first one you gave.)

The Features module and the Zen theme look for custom keys in .info files. It looks like accepted practice to me, so I do not want to say anything in the docs to discourage it unless I have a specific reference. (I spent some time searching, with no results.)

OK, regions_hidden should definitely be mentioned; package should be mentioned but discouraged (except for core themes). Both of those are for D7. I think that settings should be mentioned for D6 and D7, since it appears in zen 6.x and Bartik and Seven. I guess zen implements it as a custom key for D6. In D7, theme_get_settings() looks for $themes[$theme_key]->info['settings'].

I goofed in #7 above when I said that Corolla might have a package key. I should have re-read my own comment #4.

Once I edit the page, I can edit my own comment on that page, but I do not think I can remove it.

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented

I fixed the 1st link, as is is pertinent to page_top/_bottom. I think what modules do to .info files is considered differently than themes. Even Zen does it only as a special case(the conditional_styles module doesn't exist) and in template.zen.inc says
* Add stylesheets that are only needed when Zen is the enabled theme.
*
* Don't do something this dumb in your sub-theme. Stylesheets should be added
* using your sub-theme's .info file.

benjifisher’s picture

benjifisher
he/him or they/them
Primary language English
Location Boston area
CreditAttribution: benjifisher commented

According to their project pages, Zen is used on about 10 times as many sites as Conditional Styles. In effect, Zen adds the conditional-stylesheets key.

To be clear, when I say a key is "added" I really mean that if the .info file contains a line with that key, then it will have some effect.

In D6, Zen also "adds" the settings key. AFAICT, this key is recognized by D7 core but not D6 core. See zen/zen/template.theme-registry.inc.

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented

Actually, zen only uses this technique if zen itself is used as a theme, rather than just a base theme, so the count isn't indicative. The code that scans this file is very simple and open to all kinds of unexpected output. It would seem bad practice to store a value specific to one theme in a system variable that you can't update except through either a module or by changing the file.
Actually, I would think it best, at this point, to leave D6 things alone, since this is really old now. I don't know why they don't separate the D6 and D7 stuff to separate entries. What are they going to do when D8 comes out?

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented
Status: Active » Closed (fixed)

Docs have been improvd

dcrocks’s picture

dcrocks CreditAttribution: dcrocks commented
Issue summary: View changes

fix page URL