G2 Theme API complete!

Hi, all. It's taken me several weeks of steadily hacking on things, but I believe that I have come up with a pretty powerful theme API that passes a lot of control down into the theme without giving up control in the templates.

I have to write a lot of documentation about this and that'll take a little while. In fact, if there are any volunteers out there who'd be willing to work with me on documenting it that would be terrific. But in the meantime, let me give you a very basic thumbnail sketch of what's going on.

G2 template files don't contain HTML. Instead they contain a special set of tags that I designed. These tags are used to describe the page, so for example on a Site Admin page you have tags that say something like "put a side bar here. Put some side bar boxes inside them. This side bar box has a title, and here are a set of links to put into the box", except it's not in english so it'd look something like this (taken from modules/core/templates/SiteAdmin.tpl)

  {g->main} 
    {g->breadcrumb} 
      {g->item} 
        {g->title} 
          {g->text text="Site Administration"} 
        {/g->title} 
      {/g->item} 
    {/g->breadcrumb} 
 
    {g->sidebar} 
      {g->box style="sidebar"} 
        {g->title} 
          {g->text text="Admin Options"} 
        {/g->title} 
 
        {g->listing} 
          {g->item} 
            {g->title} 
               ...
            {/g->title} 
          {/g->item} 
          {g->item} 
            {g->title} 
               ...
            {/g->title} 
          {/g->item} 
        {/g->listing} 
      {/g->box}   

      ...

I cut out some of the logic because it doesn't serve this illustration. So now we have a template file that describes the page. For each of these elements, G2 will then pass control to the theme. So the theme will get a call saying "Create a listing with these items", then "create a box of style sidebar with this title, and put that listing in it", then "create a sidebar and put these boxes in it". G2 groups the contents of any themed element and passes them to the theme in the form of a function call. The theme then spits out HTML to render the item.

Look in themes/matrix/theme.inc for an example theme. Yes, this is a little complex at first, and we will have to write a theme developer's guide to explain it all. But in the meantime, check out how every single bit of HTML gets generated in this one theme file. The theme decides whether the entire application uses <tables> or <divs> (well ok, there is a "table" themeable element -- but you could implement that using divs if you wanted). If you want XHTML or HTML4.01 compliance, you do it here. All style sheet specifications happen here.

If you want to get started quickly, try this. In the themes directory, copy the "matrix" directory to something new, like "foo". Then edit themes/foo/theme.inc and change any references to MatrixTheme to FooTheme (the class name must line up with the directory name). Then go and tinker with the styles/theme.css file and make some changes. Then edit the Album Settings of any album and change its theme to your new foo theme. Voila! You have created a new theme -- now you can screw around with the PHP and the CSS to get it to do exactly what you want!

How's it going? Any questions?

Online it is. Installation went fairly well...once I read all the instructions.

I will take a look at the templates tomorrow night if I get off of work at a decent hour. I will keep you updated!

=)
Jade

Update: the theme.inc

I looked through all the code and made my notes accordingly. Alot of them are for my own use at the moment, so they may not make sense to you. I will clean them up once I create a new theme.

My notes are viewable here.
http://drazanfamily.com/g2/gallery2/notes/theme.inc.txt

again these are preliminary notes.

=)
Jade

Sorry for the delay -- I've been swamped the past two days. Getting you going is a big priority for me and I promise to be more responsive!

I looked at your comments a couple of days ago and they looked pretty accurate, except for one thing, but I can't remember which thing that was right now and your site is down! (or at least I can't reach it at the moment). I'll try again ASAP.

In the meantime, I have a plan to create what I call a "template sampler" . This is a new module that will have a series of pages, each which contains a whole lot of different types of themeable objects all on one page. The plan is that you can modify your theme then go to this sampler page and see lots of different variations at a glance to know how your change is going to look. Will this be helpful to you? Any feedback on this would be very helpful

I keep going back and forth about having a global header and footer. Ie, I keep adding them and taking them back out and then adding them again. Right now they're out. Here's why.

G1 can be run in standalone and embedded modes at the same time. But this causes more problems than its worth, so my plan for G2 is that you pick which mode you want to run it in and leave it at that. This means that if you're embedding it into your website you're going to have it embedded all the time. So my plan is that you get to modify global.tpl to make it look exactly the way you want to fit into your site.

In the old system, you had to modify header and footer files separately and it was hard to see your changes in context. But with this system, you have just one file and as long as you leave the two {include} tags in there, you can decorate your G2 any way that you want. Typically I figure this means that you put your standard site header and footer on the page and maybe an overall stylesheet (or not). The theme controls everything thats rendered inside those {include} tags.

I have a plan for the future where you don't actually modify global.tpl, but you modify global.tpl.new (or something) so that when we upgrade your changes don't get overwritten. Haven't done that yet, though

A "template sampler" or "dummy module" would be very useful as an example not only of templates but also our module format. I am +1 for this.

Sorry this has taken so long. I had a deadline for a story to be published this year. Now that is done I can turn my attention to Gallery again. Should have something to show you this weekend.

=)
Jade

I'm back working on this. RL has proceded to limit my net activities for the past couple months. Things have settled down and I have more free time. Yay!

I'll be posting soon!
=)
Jade

Just let me know what you need me to do. I'll check back in often.

=)
Jade

Don't worry, we're not ditching layouts. All we're going to do is to change the contents of the .tpl files so that instead of using tags like {g->box} and letting the theme rewrite that as a <div> (or a <table>) we're going to use <div>s in the .tpl file directly. This will allow the theme to be just a CSS file which'll make life a lot easier for theme developers.

Also.. as I'm going through this trying to customize the layout I'm really at a loss following some of the logic in the inc files regarding which tpl file does what. The sidebars are pretty self explanitory. Am at a loss for the albumbody, itemnavigator, and singlebody.

Basically, I'm looking at how to get at the pieces for how the top level gallery, album/sub-album, and the actual picture display get called.

To give some background, what I'm trying to do is to have a 3 column layout for the client. They need to have a number of albums, with 3 pictures in each. The item view will be in the center column, with the left column being textual links to first item in each album using the name of the album, the right column will be small thumbnails for each album in a 3 column/12 row list with no text under each.

The item view will need to have textual links under each item with the text 1,2,3 for the photos in the album.

My gut tells me that I'll need 2 different tpl's for each sidebar based off the same logic as the album view. For the left sidebar I'll just have to strip out everything but the textual piece of it, and just make sure that the first item in the album is the same as the album. For the right sidebar I'll do the same, but it'll simply be the thumbnail view.

What I'm at a loss for is, where the code is that determines the current album view (so I can take it out and play with it for the sidebars) and also where the code is the for the gallery view.

any help identifying where these pieces are, and if I'm looking at this the right way is correct, would be greatly appreciated.

Let me preface all of this by saying that I am still dissatisfied with the way that the layout code is structured. Right now, the layout has a lot of control over what's displayed and where it's displayed, but this means that the layout has to do a lot of work just to do a relatively simple render.

I've been toying with the notion of simplifying layouts considerably so that we generate the sidebars and navigation for you, leaving you with just the center area as your canvas. This would lift a lot of the work off of the individual layouts, but it would also limit what a layout could do. Any thoughts on that?

albumBody and singleBody are the two main styles of view (eg, are you looking at the contents of an album or are you looking at a single item?).
The itemNavigator is just a convenient snippet to put up the first/back/next/last links.

If you want to change how an album is rendered, you need to look in the _loadAlbumTemplate function in matrix/layout.inc and then the matrix/templates/albumBody.tpl file. There's a lot of stuff going on in there and I'm trying to figure out how to simplify it (see my statements above).

I think I understand. A simple sketch would help me visualize it, though. It sounds like you want to show thumbnails from multiple albums on the same page which is not a big deal, but it's different enough that you may
have a hard time re-using the stuff in the current matrix layout.

Since you want the center view to display an actual item, you should probably start by reusing bits from singleBody and just displaying a single item in the middle area. Then you can work with the sidebars to get the text contents that you want. This is certainly not going to be trivial (all of the layout work has been a real PITA thus far) and I want to make it easier but again I'm really not sure how to go about doing that.

also, in relation to a way to approach making this easier for folks to customize. I've done alot of work with postnuke, and really like the way the guys over at Spidean put together AutoTheme. Basically boils down to:

Each page is made up of a series of html templates, main page template and box templates. each template requires that you put in a self descriptive tag (pre-defined as part of the theme engine) in each place that you want something to go. So for instance:

Lets say that in the above example of the 3 column layout, I'd create the main page with whatever header/footer html I wanted on every page. This main (lets call it "theme.html") would also include the table layout (or css divs), for the main page elements. It might looks like this
======================
<html>
<head>
</head>
<body>
<table>
<tr>
<td><!-- [leftblock] --></td>
<td><!-- [centerblock] ---></td>
<td><!-- [rightblock] --></td>
</tr>
</table>
</body>
</html>
==============================

Then each of the blocks would use it's own html file for the layouts. For example, lets use the example of the thumbnail list from the graphic in my previous post.
=========================
<table>
<tr>
<td>Albums</td>
</tr>
<tr>
<td><!-- [albumview1] --></td>
</tr>
</table>
===============================

Where albumview1 is configurable, as far as elements shown, positioning in either another .inc file, tpl file.. something. As one drills down through the page elements it's likely that the complexity will increase, which is to be expected.

Using these examples, it'd require that each of the differnt tags be defined, like in the current theme.inc file, it's just a little different. I suppose they could even just be stored in the database and there could be a GUI in the admin area to customize each of them.. or not, if they were all easily identifiable in the theme.inc it'd probably be just fine, just so long as there are user configurable ones.

I think the thing is to make it heirachical in such a way that as a designer drills down through the layers of customization it stay as simple as possible. In otherwords, in every file where it's possible to use a simple tag to call functionality defined elsewhere, rather than using code will ensure that as many people as possible can use the theme/layout system.

You might talk to Shawn McKenzie. He's the guy who developed autotheme for postnuke. His site is http://www.spidean.mckenzies.net (where you'll find a copy of gallery running . I think he goes by abracadaver elsewhere.

bharat

Do you want me to have a go with what you have done already? I'm on light workloads for the next couple months and could really put some time on this.

As far as layout structure, this needs to be on the user level. I thought that was one of the main goals of G2.

What's the latest working files? I'll take a look and offer my input.

=)
Jade

Certainly! You can get the latest G2 code from the snapshots (see the download link to the left) or from CVS and try it out. Most of what I said at the top of this post is still valid now so you can work with it and let us know what you think.

thanks!