By wcrowshaw@yahoo.com on

While I am pretty much committed to working with drupal because of its open-source nature, I seem to be having trouble finding sufficient documentation for my theme building purposes. Perhaps this is a short-coming on my part; that I just haven't found the right documentation yet.

I'm aware of http://drupal.kollm.org/ with its core documentation, but its not that great IMO. For instance, look at the node method in BaseTheme. Its absolutely fundamental when it comes to placing content in your theme. It almost certainly must be overriden when you build your theme. And yet the documentation doesn't even bother to tell you what it does.

Are there any better places to look for documentation? For instance, it seems to me that the variables (global?) $this and $node have several members ($this->links or $node->teaser) which I need to fine tune my theme, but I can't really find a complete reference on $this and $node, not even on kollm.org core documentation.

Any pointers for mo' info would be greatly appreciated. I'd rather sort through the documents than inundate you all with questions.

Thanks,

William

Comments

dries’s picture

dries commented

Have you seen http://drupal.org/node/view/509 (and http://drupal.org/node/view/1922)? If so, could you please describe what information you are missing? This would help us improve the documentation and allows us to answer your questions. Thanks.

Anonymous’s picture

(not verified) commented

Sure, I've seen those pages. But they aren't exactly in depth at all. They're simply helpful starters.

I'm starting to get into the nuts and bolts of drupal, because I have very specific needs for my theme. Without sufficient, detailed, documentation, it looks like I have two choices: 1) keep posting very specific questions about what I want to do or 2) reading drupals source code (a task that is particularly difficult considering the lack of code comments and my rudimentary php knowledge).

Frankly, the whole documentation issue worries me because I would like to use drupal, but I seriously question the longevity of a project that doesn't have adequate documentation for developers. At this point, as well, the code base of drupal seems pretty big, so it's going to take alot of work to comment the code.

But hey, I could be mistaken about the documentation issue, because perhaps I haven't found the link for the proper documentation. But I've seen several other posts where developers describe looking at the code for hours to figure out how it works.

As far a specific questions about drupal, I already asked one in my previous post. What are the members variables of the $this, and the $node (or even $user)? Looking at the examples, I see that $this->links and $node->teaser. But what exactly does "links" stand for?

Thanks for any help or pointers you can offer me. Despite my criticisms I do appreciate the work people have put into drupal.

William

dries’s picture

dries commented

To see what the member fields of $this or $node are, use:

  print_r($this);
  print_r($node);

Not sure what $this->links is; it must be a typo/braino in the documentation. What URL/page shows its example usage?

Feel free to help documenting the code as you discover things. I'd be happy to review your comments and include them in the HEAD version of Drupal.

wcrowshaw@yahoo.com’s picture

wcrowshaw@yahoo.com commented

print_r($this) -- interesting. Probably in includes/common.inc. I'll check it out.

Yes the "$this->links" was a typo (oops) -- should have been $this->links() which is a function of BaseTheme.

I just might help you out on the documentation, if I just wrote down some of my discoveries. At the moment, it's a bit like reverse-engineering-archeology.

William

ax’s picture

ax commented

* to answer your questions:
  + the members variables of the $this are quite well documented (they deal mostly w/ colors and aren't that important). note that $this->links() isn't a member variable but an instance method - all of which are nicely listed (if not documented) at my site.
  + the members variables of $node cannot really be documented as we don't have a node class (we really should - but thats a different story). the $node parameter passed to Theme::node() result from a <a href="http://drupal.kollm.org/drupal-phpdoc/database_8mysql_8inc.html#a4">db_fetch_object($result)</a> which fetches a node from the table with the same name in the database and returns it as an object. the "members variables" of $node are all fields in the node table, then. the same applies for the $user (and other) objects.

* i absolutely agree with you in that drupals code base has a serious documentation problem. i brought this issue up quite some times and suggested using phpdoc (your two questions above could have been perfectly answered in phpdoc comments in the BaseTheme class), but at last resignated as for the core developer(s) this doesn't seem to be an (important enough) issue, or because they don't like inline code doc (search this site and the mailing list for "phpdoc*" for background). you may have noticed Should Drupal use /** ... */ Doc Comments consistently to allow for automatic generation of API docs? and a 13:0 in favour of phpdoc - but this doesn't help if phpdoc comments get removed before committed to cvs ...

wcrowshaw@yahoo.com’s picture

wcrowshaw@yahoo.com commented

oops -- duh, yep, links() is a member function of a class derived from BaseTheme.

Regarding $node, it is rather shocking that $node isn't it own class when it seems so fundamental. But I'm not completely sure I understand your answer. I guess I'm going to have to look at what the $node parameter is on a per function basis. Which means I'll have to trace out the function which is supplying the $node parameter, just has you traced the BaseTheme:node() to the calling function of db_fetch_object($result). That's not going to be fun.

Yet another reason why there ought to be better documentation -- and yes, machine generatable from comments embedded in the code like java. I whole heartedly agree. I'm surprised the core developers can keep it all straight.

Thanks for your help. I'm sure I'll be calling upon it again sometime soon.

William

ax’s picture

ax commented

if you use a debugger: set a breakpoint at the start of function which is supplying the $node parameter and, once you are there, look at and follow the call stack. much recommnded (using a debugger).

shane’s picture

shane commented

You've got to be kidding if you are recommending using stack tracing and debuggging to figure out what the code is doing. That's absolutely absurd.

Don't get me wrong - I AM grateful for the hard work that all of the core developers put into Drupal - obviously despite my often vocal criticism, I'm still here, plugging away at using it on a high volume production site... But for crying out loud - the obvious lack of concern for the final finished product that the end users *actually* use is amazing to me.

It's obvious people want to get in on this Drupal-thang, muck around in the themes, fix things, make things better, help out ... but the barrier to entry is unbelieavably high. I've been mucking with it for almost a year now. I'm not a programmer, but I've been hacking code in one form or another (Ada, C, C++, Java, Javascript, Bourne Shell, Korn Shell, C Shell, Perl, PHP, Python, and others) for over 10 years. In any case of hacking code, you've simply got to have some comments somewhere. Code is too complex for an outsider to simply just follow along through dozens of source files, with 100s of functions, and several dozen different authors with slightly different ways of doing things.

It is a testament to how well the code runs, and how the basic structure of things are put together - that Drupal is as successful as it is. It's obviously *not* based on a backbone of well documented information on how to use it, extend it, hack it, theme it, contribute to it.

Yeah - I know, the documentation *has* been getting better and better, but it's also getting harder and harder to find the info. As the main drupal.org site grows with forum listings, bug postings, scattered and barely-there half written book documentation, outdated methods of doing things as every minor point release changes three dozen core ways of functioning, etc...the information is scattered all over the place - and the search function to find things is absolutely bare bones barely there.

I apologize if you think my criticiscm is unfounded - but I'm trying to point out the very obvious and hard truths to trying to be an end admin - building and running a complex Drupal site. It's almost enough to make me go drop hard earned money on something else that "just works" - except that really doesn't exist...

ax’s picture

ax commented

i recommend debugging to /thoroughly/ understand whats going on. which you need if you find a bug, write custom modules or want to modify / extend drupal.

you don't learn how a car works by reading the manual - as good as it may be. you have to get your hands dirty.

that being said, i completely agree that the drupal documentation should be better. i mean i am the phpdoc guy ;). but i guess you know why it is so hard to get there ...

ron_mahon’s picture

ron_mahon commented

I thought I was loosing my mind trying to find out how this worked
Then I stumbled on to Polder theme and the style module. Now I don't care how it works (almost) because I have created 6 themes with different number of columns and blocks on different sides all under control of the style program. Which also doesn’t have much documentation, but was extremely easy to figure out?
Check it out under downloads