Creating and using custom layers

[matgb]

Hallelujah. I've been trying to figure this out for years. I have never read a how-to that explained how, or why, you could or would create a custom layer.

I've been hacking the complete source code for Expressive on LJ the whole time, as it was the only thing I could figure out to do. Somehow, none of the how-tos made any sense. So, on the assumption that I'm not the only one that needs it explained with a different logic, and because I might need a reference point when I've forgotten, here's how (and why) it's done:

In order to generate your journal layout, Dreamwidth (and LJ) uses a custom style system. This has a base, default, set of code that knows how to do everything.

When you select a Layout, that layout uses the base style (known on DW as Core2), and tells it which bits not to use, and instead replaces them with the code in the Layout layer.

When you select (or build) a Theme, the theme uses the code from both the Layout and the Core, but overrides and replaces/adds extra code.

In other words, the lowest layer has priority, but unless told otherwise, DW will assume the Core is correct. Can someone that actually knows this stuff confirm it?

So, if you like a Layout that you see somewhere, but would like to change little bits of it, the odds are very good you can by creating a Theme to override the Layout. Here's how I've just done it:

I'm using the basic Layout 'Core2Testing' available from the 'all' tab in the customisation area. I've already done a huge amount of hacking with the CSS (in the CustomCSS bit, easy stuff), and haven't finished yet.

But, there are aspects I really don't like. Specifically, the page TITLE (what shows in the window title, the Tab text, what something is bookmarked as and what Search pages on Google show) displays as "username | Page Title". This is bad for me—both usability and SEO studies show it's much better to display as "Page Title | Author". I also want some other changes, but I haven't done them yet.

So...

I went to the Public Layers page and had a look at the source code for Core2. It took a bit of figuring out, but I found the code that generates the Function that DW uses to generate the title. It looks like this:

function Page::print_head_title() 
"Using standard CSS, print the journal title. If you want to change the way this looks, modify the CSS."
{
    if ($this.journal.journal_type == "I") {
        print """\n""";
    }
    else {
        print """\n""";
    }
}

Now, I'm not clear on what all of it means (can anyone tell me what journal_type == "I" means or refers to?), but I can see the code I want to swap around. So I copied it into a text file.

Now, I went to the Your Layers page. At the bottom, there's a bit called "Create a layout-specific layer". I want to create a Theme, that's attached to my use of Core2Testing. So in the first dropdown I select 'Theme', in the second I select 'Core2Testing'. If you hit 'Create', when the page reloads, there's now a blank theme layer in the area underneath "Child of layer 551: Core 2 Testing". Hit Edit.

You now get taken to the layer editor. This can be quite daunting to use, but it's fairly straightforward once you've got your head around things. You've currently got 2 lines of code in the main window. The top is the code telling DW that this is a theme layer. The second? Put a name for your layer in between those empty quotes. I called mine "Sludgulike" because, y'know, I tend to build layouts using sludge grey backgrounds.

Now, I went to my text file, and copied out the code I found earlier, and swapped the bits around, so that instead of + $this.journal.name + $*text_default_separator + $this->view_title() + I instead have + $this->view_title() + $*text_default_separator + $this.journal.name.

At the top of the screen, hit 'save and compile'. It'll sort the code out, and assuming there are no errors, it's say "job done" in the bottom window. Actually, it'll say something like:

S2 Compiler Output at Sat May 9 21:37:24 2009
Compiled with no errors.

But it's the same difference. If, on the other hand, you've messed some code up, the bottom window will tell you what it thinks is wrong or what it can't figure out.

If in doubt, look for a missing semi-colon.

There you go, you've got a new theme all shiny and done. Now all you have to do is tell DW you want to use it. Go to Your Styles. If, like me, you're prone to changing your layout on a whim, or when someone announces they've created something new, this page is the single most useful page on the site. It lists all the styles you've used, lets you preview each of them, and lets you edit them around a bit. Why it's hidden in the guts of the advanced pages is utterly beyond me—I know bits of it are complex and advanced, but the simply "I want to go back to the theme I was using yesterday" function is a godsend, especially if you'd spent a long time playing with text/CSS options. Hopefully, the useful bits'll be moved before formal launch. Anyway...

In the lists, one of them is bold—that's the layout you're currently using. I'm assuming that that's also the one you've created this theme for. Click 'Edit'. You can now rename it (mine is now called "Core2Sludge") and crucially at the bottom, also apply the theme layer.

The last line (User) should have 'user generated customisations'. DON'T TOUCH THIS. It's the layer that DW stores all your CSS and text amendments made using the wizard. If you change this, you might use all of them. If that includes un-backed-up sidebar text linking all the awards or similar you've won, it's a real PITA.

That's it, job done. It really is that simple. Once you've got your head around it. The taskflow is unintuitve, there's nothing telling you what to do (or, perhaps more importantly, why), and the pages don't link to each other well.

It's no wonder I could never figure it out. Still, now that I have, I can A) add a few extra bits to my sidebar (like some text linking all the awards &c I've won) and b) maybe tidy this ramble up into something the dw_docs team can use.

But now now—gotta go get miss_s_b from work. If you know what you're doing, can you check for errors and/or answer my minor questions. If you don't know what you're doing, or bits make no sense, ask, as if I can't help someone else might, etc. And I'd like to figure it out.

Comments

[ninetydegrees]

1. In other words, the lowest layer has priority, but unless told otherwise, DW will assume the Core is correct.

If by lowest you mean 'theme' (or 'user'), then yes.

2. I = external identity. You can find this in the Core:

var readonly string journal_type "Type of account: P (personal), C (community), Y (syndicated), I (external identity) etc";

[matgb]

Aha! Danke, I looked but didn't see it anywhere.

In which case I don't think the code as is in Core is good—it shouldn't default to displaying username in the title, it should default to the user-changeable display name. But that's an opinion, and I've fixed it for mine anyway.

[ninetydegrees]

You're welcome. The variables are generally defined/explained in the first part of core but if they aren't, they can be found in S2.pm (link to the latest version).

I prefer it the way it is, tbh, but, that's because some (many?) people use quotes or little hearts or whatever as their names.

[matgb]

Good point. I'm actually wrong anyway. It should be username or user display name. It should be Journal Title, that's what the Title field is there for anyway, right?

Guess I'll have to go find the code for that and fix it in mine, they're currently the same but...

Hmmm, wonder if I could hack it so that on journal home/recent entries page it shows journal title/subtitle, but on everything else it shows page title/journal title? Probably...

[ninetydegrees]

Hmmm, wonder if I could hack it so that on journal home/recent entries page it shows journal title/subtitle, but on everything else it shows page title/journal title? Probably...

Sure you can. Maybe this:

function Page::print_head_title() 
{
    if ($this isa RecentPage) {
        print """<title>""" + $.global_title + $*text_default_separator + $.global_subtitle + """</title>n""";
    }
    else {
        print """<title>""" + $this->view_title() + $*text_default_separator + $.global_title + """</title>n""";
    }
}

And then you'd have to edit some view_title functions so that they display the page title to your liking.

[matgb]

This appears to have worked—except that the reading page appears to be a RecentPage, but that matters little really.

Danke, I'd have got there eventually but if you already know the variables it helps.

[ninetydegrees]

Oh, should I tell you how to fix it or let you figure it out on your own? Or maybe give a clue...

[liv]

This is totally awesome, thank you so much for writing it up. I'm part of the styles docs team and we might well incorporate some of this into a guide. Because yes, good documentation of the custom layers workflow would be really, really helpful. Especially now free users have (limited) access to the layers interface!

[matgb]

Feel free to use any or all of it—it was mostly written at 11pm last night because I knew I'd forget some of it this morning, so it's not even at first draft stage for proper documentation, but it's there, which is better than nowt; I'll rewrite it for my own journal at some point I suspect.

The other thing I figured out while doing it is that we really need to do something with the taskflow on the site while doing it, it's pretty dire at the moment. That would, naturally, require rewriting this, but I'd be much happier doing the latter.