Proposal: documenting Drupal's ID's and classes

By clairem on 26 Jan 2005 at 13:18 UTC

This is a proposal which picks up on Chromatic's suggestion in in a comment on the misc/drupal.css thread that there should be a documentation site for Drupal's class and ID output, ala' http://drupaldocs.org

I think it's an excellent idea, which would be invaluable for themers, and probably rather overdue. I think it it would also reveal any illogicalities or inconsistencies in the output.

I would be delighted to help in doing some of the work in unearthing the styles and IDs from the modules. However, I would need some guidance in how to structure this, and I wouldn't be able to set up a documentation site.

Is anyone interested in building the infrastructure for this ID&Class documentation?

It seems to me that ideally it should be linked to the existing drupal docs, because the the class and ID documentation is inextricably linked to the module code. But I'm sure that there are wiser folks who may have better ideas!

Doing it this way might would not just help to tidy up any existing illogicalities or inconsistencies, it would also start to show up any new glitches introduced in development.

Comments

I Second

Shane Birley commented 31 January 2005 at 18:08

And will help in anyway I am needed. Should I assume you will head it up or do we need to find someone who is able to help out in the "organization" of this group.

---
Shane Birley
Left Right Minds
https://www.leftrightminds.com

Great attitude

kbahey commented 31 January 2005 at 19:39

Thanks for the great idea and energy.

I think documenting the HTML id=/class= elements of Drupal is a much needed thing for themers.

Perhaps it is best to join the drupal documentation mailing list, and discuss it with everyone there.

http://lists.drupal.org/listinfo

--
Drupal performance tuning and optimization, hosting, development, and consulting: 2bits.com, Inc. and Twitter at: @2bits
Personal blog: Ba

Energy? Moi?

clairem commented 1 February 2005 at 23:46

Not so sure if it's really energy, or just a bout of insanity, volunteering for more work :)

Anyway, I have just subscribed to the documentation list, and if folks there think it's a good idea, I'll be back here to take up those kind offers of help.

Send a message

kbahey commented 2 February 2005 at 02:59

Send a message on the list referencing this post, so as to stirr things up and get matters started.

--
Drupal performance tuning and optimization, hosting, development, and consulting: 2bits.com, Inc. and Twitter at: @2bits
Personal blog: Ba

I agree

iraszl commented 31 January 2005 at 19:41

And I'm here to help. Let me know how!
---
http://creativebits.org

What about a wiki?

media girl commented 1 February 2005 at 23:57

A collaborative effort, which can also include tips and tricks people have found to do xyz with Drupal. Ultimately I think the resulting pages should be added to the Drupal.org themes pages of the book.

I've also found that there's a difference between themes and engines. Applying an xtemplate theme's CSS file to a phptemplate theme can result in a total mess.
--
mediagirl.org

I'm interested in helping

sepeck commented 2 February 2005 at 01:07

I'm interested in helping and can probably host a server for a while. In fact I can probably toss up a Drupal site if someone is interested building out the taxonomy and content for folks to get started

I can't commit more than time than that until the end of February.

-sp
---------
Test site...always start with a test site.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

good idea, but rather impossible

Bèr Kessels commented 2 February 2005 at 01:44

Since drupal outputs its HTML trough themes, these themes can (and will) change all the ids and classes. So you would need a per-theme-per-case list of ids and classes.

[Ber | Drupal Services webschuur.com]

Maybe we should standardize

kbahey commented 2 February 2005 at 03:04

Maybe we should standardize on a base set of id/classes in the base drupal, and then going forward, themes should stick to it.

Then contributed modules could follow as well.

If this is done, then future themes, or updates to theme can stick to the id/classes that are documented (the standard set).

I am playing with a theme now, trying to customize it, and it is really one of those tasks that I hate doing: trial and error. Change this, see how it looks ad nauseum .... It nees some sanity instilled into it.

A starting point is misc/drupal.css, and style.css.

Developers are always (notoriously) terrible in UI stuff. We have the volunteers who want to do UI. Why not put them to good use?

--
Drupal performance tuning and optimization, hosting, development, and consulting: 2bits.com, Inc. and Twitter at: @2bits
Personal blog: Ba

positive energy - let it flow

moshe weitzman commented 2 February 2005 at 12:26

there are many theme functions which themes hardly ever override core theme functions. tables, pager, unordered node lists/user lists/item lists, and so on. all of these could be documented, and themers everywhere would benefit a lot. further, even if one core theme documeted its special class names/IDs, then new themers would likely follow its lead, since there would be only 1 published example of a "right" way. so i do find lots of merit in this exercise.

one of the least attractive features of us programmers is that we like to point out the few cases where a given solution will not completely meet the need. we say then that the solution is *flawed*. we do this partly out of laziness, because we don't want to deal with the messy 5%.

First we need more classes, but standardised

Bèr Kessels commented 2 February 2005 at 12:33

Documenting is one solution for the clutter we have now, but much better would be to have a standard way in drupal.
my proposal at http://drupal.org/node/15332 never got committed, not sure why.

But *if* that goes in, we should start wrapping all output in those boxes, and so we will get a standardised set of IDs and classes.

[Ber | Drupal Services webschuur.com]

The Documenting...

Shane Birley commented 2 February 2005 at 18:42

...is important but there needs to be some core adaptations where the drupal.css can be turned on and off with a check box.

That, along with a good listing of what the "built in" css does is probably a "both worlds" solution.

Of course, there are some details to take care of. So, what you proposed appears to be something along those lines.

---
Shane Birley
Left Right Minds
https://www.leftrightminds.com

should it be part of EACH themes documentation?

freyquency commented 2 February 2005 at 16:00

I think it would be a real time saver if each theme were required to have a list of it's classes and ids that it uses in the stylesheet as a text file. That way you could at least get an idea of what is used in the theme... or at least we could provide doc's for it.

Cascades themselves are going to be the tough thing to document when gleaning classes and ids from engine or theme templates. Each one will (or could) be different. Which isn't totally bad. You say node, I say entry - that sort of thing.

I was thinking that it would be cool to write a simple php script that scans the template file(s) and the stylesheet(s) and finds instances of class and id and prints what it finds. Perhaps in two columns, if it were something that seemed worthwhile to compare. For irony it would be fun to make it into a table.

But most of all, getting the little bits documented that are commonly used, such as the id's for blocks would be worthwhile. Those are hair pullers for themers or newbies.

I'd also be interested in getting feedback from designers about which sort of div tags are useful and necessary for 90% of the css designs. Ignoring the table based themes - if one converts it to pure css layout - how many tags does it take to contain everything? What's the layout like without stylesheets on? For example, I've frequently been adding another container div to the layout to support the css dropshadow techniques i've found on the web. I'm curious about things like that...

Count me in, i'd be willing to contribute to the project.

[]+][+][+[]
erik mallinson
http://coacalina.org

I think generally we can't

iraszl commented 2 February 2005 at 18:04

I think generally we can't standardize the ids and classes since every theme may require new ones. However we should still document the basic set of ids and classes.

BTW, i subscribed to the mailing list, but received no emails in 48 hours. :(
---
http://creativebits.org

The list is very low

sepeck commented 2 February 2005 at 18:08

The list is very low traffic. Coding is more sexy :)

-sp
---------
Test site...always start with a test site.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

on a related note

freyquency commented 3 February 2005 at 06:04

I think there should be documentation for
1. basic id's and classes that get passed through engines
2. basic id's and classes that are created by engines
3. optionally for themes that are developed

the first two should be clearly labeled as separate css 'issues' - basic vs. engine specific...

but perhaps a better way to approach this would be a css primer for drupal, an introduction to css, but focused on drupal, where cascades are better explained for blocks, nodes and the like. this would be more 'basic' than any engine would specify, but more focused on creating powerful style sheets from what is there. for example:

<div class="block" id="comments">
<h2>title</h2>
<ul>
<li><a href="" title="">yeah a css documentation would be great</a></li>
<li><a href="" title="">I agree</a></li>
</ul>
</div>

has a lot of power, and explaining how to harness it could be worthwhile too. Also if things are put forth as good css code we can weed out what is good about it and when and id or class isn't necessary and trim things down.

...And this is a very vague help request. I remember a few weeks ago I saw a page (on the web, not drupal related) on usability that was regarding a survey of the most commonly used classes and id's by corporate web sites. I was looking for it in relation to drupal themes, so it's relevant, also it also may have been linked to from a drupal users site... If anyone says "aha! you mean this one!" than please share, i figure this forum post is about as attentitive as one could get on the matter. It's a difficult thing to search for...

this would probably be a suitable question for the theming enclave that is flourishing... hey, maybe we could get a mailing list for drupal-themers too?

[]+][+][+[]
erik mallinson
http://coacalina.org

Theming List

Shane Birley commented 3 February 2005 at 18:06

Great suggestion! I would be on it the first moment it went live.

Hey, how is this for another suggestion. Somehow using the already cool site (http://webschuur.drupaldevs.org/) involved in the documentation of the CSS and IDs.

I thought if we centralize it all on Drupal and on that site, we would be able to get the word out.

---
Shane Birley
Left Right Minds
https://www.leftrightminds.com

Any new thoughts as to where

freyquency commented 10 February 2005 at 18:13

Any new thoughts as to where we can go? I don't mind http://webschuur.drupaldevs.org/ - themes garden - i've posted there before but no one seemed to respond. We should find somewhere else if that isn't ok with anyone.

[]+][+][+[]
erik mallinson
http://coacalina.org

groups.drupal.org is setting

freyquency commented 3 May 2006 at 16:47

groups.drupal.org is setting up a theme group... This should be prime space for what's been talked about here!

glad

drupalec-1 commented 3 May 2006 at 17:12

that sounds good. Seems like the group should be announced. Is there a way (preferably via email) to find out what new groups are being formed every time a new one is formed?

-----
Drupal ecommerce, at www.drupalecommerce.com is a new site written using language that Drupal beginners and intermediate users can understand. Which version to use? http://www.drupalecommerce.com/47vs46

groups.drupal.org is still

sepeck commented 3 May 2006 at 17:17

groups.drupal.org is still in late alpha, early beta status and not really all ready yet. When it does open, it will be announced on the front page, links added, etc.

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

thank you

drupalec-1 commented 5 May 2006 at 18:06

make static -> use search

dvessel commented 20 May 2006 at 09:24

I don't think we should have to worry about id/classes defined in themes. That's for the theme authors to decide on. What needs to be documented are those put out by drupal & modules. I plan on documenting the drupal.css file myself and a good portion of it can be automated in a way.

Use something like the ScrapBook Firefox add-on to make a static file of the site. I'm sure there are better tools for this but it seems to work well. Filter it somehow so the size is manageable then search through all the static files in one go with grep to find all the classes and id's. A basic theme should be used that has no markup so it doesn't interfere with the search. Just comments to identify where the id/classes would be presented.

Example:

<?php if ($messages != "") { ?>
<!-- MESSAGE SECTION START! -->

	<?php print $messages ?>

<!-- MESSAGE SECTION END! -->
<?php } ?>

From there I'm sure it can be filtered further. This is just an idea at this point and what I'm trying to do is a bit simpler but it shouldn't' be too difficult. I might be missing something here. I know very little on grep but bbedit's search tool and the documentation they provide on grep should be enough to get me started.

Another possibility is to use grep to find out the context of the id/classes for easier documenting which I think is possible. Just need someone who knows grep very well.

Just putting this idea out there.

-joon
www.dvessel.com

Link to Drupal CSS Analysis

Marc Bijl commented 20 May 2006 at 09:34

Just stumbled upon this topic, and remembered I posted this link a few times at the forum for people who want to know more about the Drupal CSS id's and classes, even for some different "core" themes:

- http://urbits.com/_/content/20060406/drupal_article01.php

The pages says April 06, so it should be pretty up to date. Might be interesting stuff for the ones who want to create some basic overviews / documentation / etc

___________________
discover new oceans
lose sight of the shore