[documentation] [Documentation feature] Basic Theming
Gary Feldman
drupal-docs at drupal.org
Fri Jun 23 23:39:38 UTC 2006
Issue status update for
http://drupal.org/node/70393
Post a follow up:
http://drupal.org/project/comments/add/70393
Project: Documentation
Version: <none>
Component: User Guide
Category: feature requests
Priority: normal
Assigned to: Anonymous
Reported by: pcwick
Updated by: Gary Feldman
Status: active
Back in the good old days of hardcopy manuals, it was fairly common
practice to have separate reference manuals and user guides. (They
weren't called tutorials because they usually had more depth.) That's
still the case for many large, successful projects, with Microsoft's
Visual Studio/MSDN being one significant example. So yes, I think
there's a need for both.
I don't think they should be combined. While the conversion to
hypertext has many obvious advantages, one of the disadvantages is that
it's easy to get lost in a maze of twisty little passages. It can be
difficult to know what to read next, difficult to find something you
were just reading yesterday but forgot to bookmark, and so on. I don't
see any problem with having a strong top-level distinction between
tutorial/user guide and reference material. To some extent, that
distinction already exists when comparing the API documentation to the
handbook; it's obvious that they're different if for no other reason
than the sidebar being on opposite sides.
Gary
Gary Feldman
Previous comments:
------------------------------------------------------------------------
Fri, 23 Jun 2006 01:01:15 +0000 : pcwick
I'm not familiar with the way things work here in the documentation
area. Not sure this is the appropriate way to make this request,
though I think it is a valid request.
I am thinking that a section titled "Basic Theming" might be well
placed under the "Customizing and Theming" section.
I believe a comment by panatlantica should be a page in "Basic
Theming".
http://drupal.org/node/56574#comment-112329
This single post would have saved me many hours and much frustration
about 12 months ago. Even today, it clarified the concept for me.
I believe I will be inspired to expand upon panatlantica's comment with
additional basic theming pages.
I also note there is no option to select "Customizing and Theming" in
the "Component" drop down on this issue subsmission form.
------------------------------------------------------------------------
Fri, 23 Jun 2006 02:08:46 +0000 : pwolanin
Yes, I agree that such a section would be good- and you (or I) can just
add it! Go to the handbook and click "Add child page". See also,
http://drupal.org/node/339
If you have the time just click this link:
http://drupal.org/node/add/book/parent/257
Or maybe it should be here, under "Theme how-to's":
http://drupal.org/node/add/book/parent/22803
------------------------------------------------------------------------
Fri, 23 Jun 2006 03:33:40 +0000 : pcwick
Thanks for the reply. I have sent a message to panatlantica. If he
agrees, I will gladly take the time to post the comment to the
handbook.
By title alone, Theming Howto's sounds like a good place to put this
information, however, it took me several minutes to figure out where
theming howto's is located.
Theme development sounds more like a section in which to find theming
matters related to coding, and indeed it appears to be just that. I
suggested "Basic Theming" as a place for fundamentals like how css
works in Drupal. The stuff a new Drupaler is looking for, and when a
new Drupaler sees the title "Basic Theming" s/he says, "hey, that's
me." First steps in making a Drupal site one's own.
If I post the comment, I will try to put it in just such a new
category. If panatlantica posts his own comment to the handbook, it
will be up to him where it goes, of course.
------------------------------------------------------------------------
Fri, 23 Jun 2006 03:47:00 +0000 : sepeck
If we get content that justifies a new section, then we'll start a new
section. Not that big a deal. I just don't want to have sections with
titles and no content. If you want to collaborate I have a scratch site
you can have rights on to hammer out some content before moving it to
Drupal.org.
------------------------------------------------------------------------
Fri, 23 Jun 2006 04:42:15 +0000 : Gary Feldman
I appreciate the value people might get from this post, but I think it
important that it be edited (and not just to fix the typos).
Part of the problem is that a big chunk of that comment is vanilla CSS
stuff - vanilla in the sense that it applies to CSS anywhere, not
specifically Drupal. As has already been noted, it can be difficult to
find things in the handbook. The more that gets put into the handbook
that isn't specific to Drupal, the harder it will be to find things
that are.
The other problem is that the comment is written specifically around
blocks, while the tactics related to the way Drupal assigns classes and
ids apply everywhere. So rather than having a page that says "here's
how to exploit classes and ids to customize the appearance of a block",
what's really needed is one that is more general, perhaps with some
HOWTO sections that are more specialized.
Having said that, I expect that many people will find value from notes
like that. Perhaps there should be a separate section or appendix for
contributed case studies or tutorials that cross the boundaries of
technologies.
Gary
------------------------------------------------------------------------
Fri, 23 Jun 2006 05:15:12 +0000 : webchick
Title fix; bear in mind when you change the title of issue replies it
changes the title for the whole issue.
I skimmed the notes and while there's a lot of really good info there,
I agree that at least parts of it indeed need to be rewritten a bit so
that it's more like a basic theme tutorial and less like a "helping
this one guy out" post, taken by itself.
Hopefully either panatlantica or pcwick or another interested party can
take this on, as theming introductions are something that's been
identified as an area documentation is lacking for some time.
------------------------------------------------------------------------
Fri, 23 Jun 2006 15:36:33 +0000 : Gary Feldman
Sigh. Sorry about that. Yet another reason for my belief that
per-comment titles are worse than useless. I don't know why I did that
- I always ignore the titles when reading, and usually ignore that field
while replying. I think the difference is that the forums leave the
title blank, while the issues section prefills the field. But the fact
that the email notification uses the new comment title instead of the
base title is a bug in the email notification, which I'll try to
report. </end mini-rant>
Late last night, I started thinking in terms of an outline for an intro
to themes, and here's what I came up with:
* /Overview of the theme system/
* Themes are about the look and feel
* In Drupal, themes are are implemented via theme engines. We're only
going to discuss the default, PHPTemplate.
* An individual (PHPTemplate) theme can have .css files, tpl.php files,
image files, .js files, and a general template.php file. They don't
necessarily have to have all of these.
* /Easy theming using only CSS/
* Because of the power of CSS, a large amount of customization can be
done using just .css files, without having to write any PHP
* Drupal follows conventions for classes and ids that facilitate
theming with just CSS. Here's the convention: /<insert relevant parts
of the aforementioned note by panatlantica>/
* Here's a basic example for blocks.
* Here's another example for node content
* /Theme hooks/
* intro and examples about theme hooks...
If this seems to make sense, I'd be happy to work on a section. If
stuff like this already exists, I haven't found it.
Regards,
Gary
------------------------------------------------------------------------
Fri, 23 Jun 2006 15:51:12 +0000 : Heine
I and some other people are willing to work on theming docs. An existing
draft for new theme book setup can be found at
http://scratch.blkmtn.org/node/9
While the focus should be on phptemplate, other theme systems and pure
php themes need to be included as well.
------------------------------------------------------------------------
Fri, 23 Jun 2006 17:14:07 +0000 : rivena
And the Theme Developer's Guide http://drupal.org/node/509 was so
difficult to find because.... ?
^.^
But last time I filed an edit for it, someone (Heine?) said that the
theming pages were already going a slow but massive rewrite?
Anisa.
------------------------------------------------------------------------
Fri, 23 Jun 2006 17:46:13 +0000 : pwolanin
to get things rolling, I reposted most of the content from the original
forum topic at:
http://scratch.blkmtn.org/node/19
http://scratch.blkmtn.org/node/20
I did very minimal editing.
Note- the site CSS doesn't seem to be making <strong> tags show as
bold, nor put spaces after <p></p>
------------------------------------------------------------------------
Fri, 23 Jun 2006 20:10:26 +0000 : pcwick
Wow! This is great. I can't take much time I want to note that
including some elementary concepts that may not necessarily be Drupal
specific in introductory materials is probably a very good idea from
the standpoint of teaching new concepts. It provides context.
Something for the brain to latch onto and then build from. Its the
reason teachers often begin a semester with a review.
I woke up this morning wondering if there are kinda two different ideas
about what the handbook should be. Is it an instruction manual or a
technical reference manual? Seems clear to me that both are needed.
Can they be effectively combined in one text? Just some thoughts.
Skimming Gary's outline, it looks like a really good start for an
instruction manual. It has that "okay, here is what you do next" feel.
Heine's outline over on http://scratch.blkmtn.org/node/9 seems to me
more of a functional analysis, a technical manual approach. Nothing
black and white intended by these quick observations as Heine's
includes elementary stuff in the intro. I really like both of these
outlines.
The Theme Developer's guide was not difficult to find. I wasn't
looking for a theme developer's guide. I was looking for basic
theming. I make the distinction that basic theming is styling with
css. Theme development is working with template files, tpl files. I
think that styling with css is info many will want when becoming
familiar with drupal styling and it should be separate from more
technical matters.
So, Heine, pwolanin, do I just register on blkmtn and start editing?
Is there a process you prefer to be followed?
------------------------------------------------------------------------
Fri, 23 Jun 2006 20:23:18 +0000 : pwolanin
Since it looked to be activated, I just used the drupal cross-site login
mechanism to login (hope no one minds)- i.e. you can login as
pcwick at drupal.org with your drupal.org password.
More information about the documentation
mailing list