Properties and Conversion

[branchandroot]

This post is for people who want to work on converting layouts, either their own or other people's.

Basic Terms

If you are not familiar with S2 coding or the making and use of layers, please read these faqs first. Parts of them will not quite fit. The links go to LJ documentation because our Documentation Team is still in the process of documenting the S2 system here (and they are doing a fantastic job and everyone should thank them).

Layer vocabulary

Different layer types

Creating a custom layer

For those who are unfamiliar with S2, it may be easiest to learn this if you copy all of the code of the Tabula Rasa layer and paste it into a theme layer you create. Make sure the theme layer is a child of Tabula Rasa. Name it something memorable and select it as your journal theme when you want to experiment.

Introducing properties

If you've taken a look at the code of Tabula Rasa, you've probably noticed it's pretty much a bunch of properties and a style sheet. Some of those properties are marked as "Page colors", "Entry colors", etc and look like color_entry_text or color_module_link. They are one of the big changes in Dreamwidth's version 2 of the Core layer. All of those color and background properties can be adjusted by any user through the Customize Style wizard, so we want to use them in all theme style sheets to make the themes as flexible and customizable as possible.

Tabula Rasa theme layers should look a lot like the Tabula Rasa layout layer. At the top, you will need to set the value of all the properties you use, and inside the print_stylesheet function you will need to put all your css, with properties in place of colors. Your theme stylesheet should go inside a bit of code that looks like this:

function print_stylesheet () {

"""
/* Theme CSS */

""";
}

Feel free to copy this snippet into your test theme layer and paste your CSS inside it.

Note that, while Tabula Rasa and other top level layouts use the function print_default_stylesheet, layouts that are children of Tabula Rasa will use print_stylesheet, and individual themes can use print_theme_stylesheet. This means that your theme CSS will be sitting on top of the Tabula Rasa base sheet you see in the Tabula Rasa code. Look at the base sheet to get a feel for what's already done; most of it is column positioning. If you find you need some CSS for one particular theme variation, use print_theme_stylesheet to include it.

If you've never used a function to print out a style sheet and use properties in it, you can get a feel for how it works by going to that theme layer into which you pasted the Tabula Rasa code and playing around with setting all those variables to different colors and seeing what happens. You may also want to start out by designing purely with CSS, testing that out until you're happy with it, and only then pasting your CSS into your test theme layer and replacing the color codes with properties.

How to set a property

This is very simple. At the top of your theme you need to set a value for each property you use. It will look like this:

set color_page_background = "#ffffff";

If you leave the quotation marks empty, as Tabula Rasa does, then the property has no setting. If you aren't using a property in your theme, you might as well delete it, it will make keeping track of things easier.

How to use a property

So, let's say that you have designed a theme in which the page background is an image over a color, the entry background is white with a gray border, and the entry header is the same as the background color. Your original css might look like this:

body { background: #006633 url("path/to/your/image.jpg") repeat-x; }
.entry { background-color: #ffffff; border: 1px solid #999999; }
.entry-title { background-color: #006633; }

When you take that css and put it inside the print_stylesheet function, it should look like this:

body { background: $*color_page_background url("$*image_background_page_url") $*image_background_page_repeat; }
.entry { background-color: $*color_entry_background; border: 1px solid $*color_entry_border; }
.entry-title { background-color: $*color_entry_header_background; }

And all those properties will need to be set, at the top of your theme, using the colors and image path from the original css.

Note that, although the body background and header background are the same color, they use different properties, which will both have to be set with that hex color. Why go to all this trouble? So that users will be able to customize your theme easily! So that, if they want to use a different background image, if they want to change the entry colors to light text on a dark background, they will be able to do so. Always try to use the appropriate property for the page element you're setting colors for.

In many cases, however, all you will really need to do is set the color values. The base sheet will do a great many things for you.

The refinements

That body background css above? In actuality, you won't need to write out that css if you don't want to, because the Styles Team has done it for you already.

There are a handful of small pre-written functions in Core and Tabula Rasa that spit out text color, background color and background image css when called on. If you look at the Tabula Rasa code, right at the top of the print_default_stylesheet function there's a long list of things that start with "var". Those set the pre-written code spitting functions. If you look a little further down you can see that, for example, the body css contains a line that only reads "$page_background". That calls on the pre-written function above to put several properties together and spit out the right css. So you can just set the properties at the top of your theme and the little functions will output the background-making css for you.

Be aware, these can also interfere with your css! If you have added your CSS to your theme and set the properties, and find that your backgrounds aren't working the way you expect them to, or you have unexpected borders, look up through the base style sheet code or the html output and see if the base sheet is printing something that conflicts with your CSS. You may need to re-phrase your CSS rules to override the base sheet in places.

If you wish to design without using the base sheet, you can do this by using print_default_stylesheet to enclose your CSS, rather than using print_stylesheet. Be aware that, if you do this, you will need to write all of the different column-left, column-right placement that the base sheet contains into your theme sheet.

Properties available

If you look at the code of the Tabula Rasa layer again, you will see, first thing, a few lists of variables that start with "use" instead of "set". Those lists contain all the variables that are available for Tabula Rasa themes to use. If you want to give part of your layout a color and there isn't a property specifically for it, try to use a closely related property; for example, you might use the $*color_entry_border property to set the border on the entry footer. Don't hard code the color value in your CSS. If you find that you absolutely require something that isn't here, it can probably be added by making your theme a layout layer, where one can create new properties. If you need a custom property, note it in your submission.

Comments

[turlough]

I was just thinking today that I really need to sit down and try to convert my ported Flexibel Squares layout to "proper" DW code so this post was very timely. *bookmarks*

[foxfirefey]

Thank you so much for writing this!

[zvi]

This is a great explanation!

The only thing I wanted to know that you didn't explain was how to escape quotes. Does the same escaping apply in S2, v2?

(People who are setting fonts with spaces in the name, e.g. Times New Roman, should put quotation marks around the name to make them display properly. I get funny results in Ubuntu sometimes when people don't.)

[branchandroot]

*wry* Yeah, escaping quotes is just a little weird in S2. You use the triple quotes; I think that was borrowed from Python. That's why the print_stylesheet function needs """ and """; at the start and end. Inside those, you can use quotes as you would in a regular style sheet.

[zvi]

I set the page link colors in a Transmogrified theme layer, and then tried to include them in the CSS by copying

a { $page_link_colors }
a:active { $page_link_active_colors }
a:hover { $page_link_hover_colors }
a:visited { $page_link_visited_colors }

from the layout layer, but it gave me an error.

Compile error: line 73, column 16: Unknown local variable $page_link_colors
S2::NodeVarRef, S2/NodeVarRef.pm, 180
S2::NodeVarRef, S2/NodeVarRef.pm, 151
S2::NodeTerm, S2/NodeTerm.pm, 174
S2::NodeTerm, S2/NodeTerm.pm, 66
S2::NodeSum, S2/NodeSum.pm, 65
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeSum, S2/NodeSum.pm, 64
S2::NodeTerm, S2/NodeTerm.pm, 76
S2::NodeTerm, S2/NodeTerm.pm, 66
S2::NodeExpr, S2/NodeExpr.pm, 46
S2::NodePrintStmt, S2/NodePrintStmt.pm, 55
S2::NodeStmtBlock, S2/NodeStmtBlock.pm, 108
S2::NodeFunction, S2/NodeFunction.pm, 230
S2::Checker, S2/Checker.pm, 374
S2::Compiler, S2/Compiler.pm, 34

, which was not what I was expecting based on this tutorial ...?

Also, it occurs to me that you didn't explain why some of the variables in your CSS example above had asterisks in them.

[afuna]

Variables with an asterisk ($*) are properties; variables without are normal ones that are created within the function for whatever use.

[branchandroot]

First of all, if you're making a theme for Transmogrified, you need to look at the Transmogrified layout layer and see what color variables are actually available (http://www.dreamwidth.org/customize/advanced/layersource?id=5927&fmt=html). See last section, "Properties Available". Transmogrified does not use color_page_link at all, so themes that are a child of Transmogrified will not recognize it. In addition, the shape of a color variable will be color_location_item, so, for example, color_page_link and not page_link_color. Use the exact variable that the layout layer uses, or it will not be recognized.

Also, as Afuna says, all the variables inherited from the core layer (anything that is set in a layout layer with "use some_variable_name") must have an asterisk, as shown in the tutorial here. E.g. $*color_page_link and not $color_page_link. The non-asterisk variables are, as the error says, "local" ones that are invented in a function within the immediate layer, not the core layer. For the purposes of converting a theme, every variable you use should have an asterisk.

[zvi]

The page you linked to does not have a section called Properties Available.

It does show that Transmogrified sets the variables I'm interested in.

var string page_link_colors = generate_color_css($*color_page_link, new Color, new Color);
var string page_link_active_colors = generate_color_css($*color_page_link_active, new Color, new Color);
var string page_link_hover_colors = generate_color_css($*color_page_link_hover, new Color, new Color);
var string page_link_visited_colors = generate_color_css($*color_page_link_visited, new Color, new Color);

So, I thought I could set call them and put them in the theme style sheet? I confess I'm no longer sure where I copied and pasted the variables I showed from. Probably I transposed and typed.

[branchandroot]

No, no, the Properties Available section of this post.

Okay, let's see if I can explain this. Local variables, the ones without an asterisk, only work in the particular layer they are written in. They cannot be inherited, the way the universal variables (with asterisk) from the core can.

So any non-asterisk variables that you may see in the Transmogrified layout layer can only be used in that layer. The same is true for non-asterisk variables you see in the Tabula Rasa layer. They only get recognized and parsed locally (in that particular layer).

Now for the slightly complicated bit: if your theme is a child of the layer where the non-asterisk variables you show above are set, then if you simply set the asterisk variables involved ($*color_page_link_etc) to the colors you want, things will Magically Happen and you don't have to mess around with setting the CSS specifically yourself; the layout layer will do that for you, because the theme calls on everything the layout layer does and adds whatever it does on top of that.

If your theme is not a child of the layer where those variables are set (and I think that is a Tabula Rasa set of variables and not a Transmogrified one), you can't use them at all. You could, theoretically, paste those variable definition strings into your print_stylesheet function, but, because Transmogrified does not set the universal variables in question ($*color_page_link_etc) to "use", your theme layer still won't know what they are and what to do with them. You can only set "use" in a layout layer, not a theme layer.

Bottom line, if you are making a theme layer, you need to stick to the universal variables that are set to "use" in the parent layout layer and do not try to use local variables from any other layer.

print_default_stylesheet

[zvi]

You can't use print_default_stylesheet with a theme layer. When I try, I get an error that reads:

Compile error: line 20, column 1: Only core, markup and layout layers can define new functions.
S2::NodeFunction, S2/NodeFunction.pm, 191
S2::Checker, S2/Checker.pm, 374
S2::Compiler, S2/Compiler.pm, 34

If you want to take what was essentially a theme for Tabula Rasa and write it as a layout, so one can use print_default_stylesheet, are there any functions that need to be re-written in the layout layer in addition to setting properties and writing the css?

Re: print_default_stylesheet

[afuna]

(Going over this in IRC, but for the sake of anyone peeking in)

print_default_stylesheet should be Page::print_default_stylesheet; print_stylesheet is still print_stylesheet.

Re: print_default_stylesheet

[zvi]

Okay. If you do NOT want to use the default stylesheet, in either a theme layer or a layout layer, this is what you do:

function Page::print_default_stylesheet {
"""<style type="text/css">""";

start_css();
"""

Insert Your Stylesheet Totally From Scratch Here

""";
end_css();
"""</style>""";
}

(I was told that the start_css stuff is a CSS cleaner.)

---

If you want to write a LAYOUT, as opposed to a theme layer, you need to copy over the property groups that need to go into the wizard, and then delete the color properties that your style does not use. (The property groups are that long section in Tabula Rasa that starts

##===============================
## Display settings - general
##===============================

Each individual propgroup starts propgroup name_of_property_group { and closes with a }. It's followed with the default settings for the properties in the group.)

[ninetydegrees]

I'm trying to convert http://dreamscapes.dreamwidth.org/12477.html and this has several edits which are not color changes (font sizes, underlines, etc.). Should I try to include them or consider them as personal customizations? I'm thinking the latter but I'd like to be sure.

[afuna]

Hrrrm. I'm leaning more towards including them, since they do add up subtly to the whole look.

[ninetydegrees]

That's going to be a lot of CSS but all right! :)

One more question: this user submitted two very close very versions of the same theme. Actually there is only one difference between the two of them: a background for primary or no background. I just want to make sure it's ok to convert both themes as it may a bit hard for users to see the difference between the two on the tiny previews.

[afuna]

Yes! Hrrrm I thought the main difference between the two, though, was that one was the sidebar on the left and one was the sidebar on the right?

[branchandroot]

Ideally, maybe we should say that if someone wants to do a theme with font sizing like this (instead of large, small, etc.) they should do it in percentages? That way the user can still customize the font size and the percentages (I think) will go larger and smaller from that starting point. That would require making the body font size explicitly the base-font-size variable, so that everything cascades from that one.

[afuna]

Yeah, agree with. Explicitly setting the base-font-size variable -- as px, you mean? or?

[ninetydegrees]

Another question about http://dreamscapes.dreamwidth.org/12477.html. Daven has included hacks for IE5 (Mac version?). Should I include these too? It was my understanding that this version of IE was not supported by DW but, again, I'd rather have your advice. :)

[afuna]

Nope, don't include them -- your understanding is correct, we don't support that version of IE. Feel free to strip them out (just let Daven know, etc)

[zvi]

You might want to update this to reflect bug 1941:

- print_default_stylesheet is Tabula Rasa or whatever base layout
- print_stylesheet is modish or basic boxes or whatever
- print_theme_stylesheet is then any theme-specific bits

[branchandroot]

*adds that in* Thanks!

[kaigou]

I'm not entirely sure if I'm reading the syntax right, but when a function is defining a variable string, this is effectively taking all the globals (ie, font size, font base, and so on) and compiling them into a local variable (ie $page_font) and using that in the CSS instead.

Presuming that's correct, then this means the logic is that you have property, set value, create tossed-salad of globals using values as set in this instance and output local variables. Thus if you reset a property (as for a child theme), this tossed-salad step rejuggles the property values into a new local variable. Yes? No?

Hm. What is the reasoning (if any) behind not just taking the global straight up, that is, instead of:
var string page_background = generate_background_css ... etc etc
which shows up again as:
body { $page_background ... etc etc
why not skip the combination step and just do:
body { background: $*color_page_whatever url($*url_page_whatever) ... etc etc

Or is the combine-global-with-this-value a required step to be able to do children styles?

(Babe, soon as you saw my name on here you probably knew what was coming, eh. I can't make heads nor tails of any language until I can grasp the grammar. Aka, "but why can't I say ain't?" !)

[branchandroot]

*grins* Oh yeah.

This one was not one of my own suggestions, but you have the code-logic correct, yes. I believe one reason for it was so that layouts could use the wizard-changeable variables in an expeditious way. The generate_background_css stuff is in the very core layer, and, this way, can be invoked fairly easily using any combination of the universal variables. It's flexible and powerful, if you know what you're doing; kind of like keystroke commands.

I think the combined background command is being avoided for a) standards compliance and b) so that the individual parts are easier for newbies to find and alter. But that's a guess.

[kaigou]

Uhm. Okay, confused, because it sounds like you're saying yes, here is reason to use multiple steps, and then following that up by saying multiple steps are being avoided. So should I set a bunch of variable strings, do the generate_css and whatnot, or should I just go from globals into the css and skip the tossed-salad put-it-together variable string step?

Part of the reason to ask is b/c after conferring with Afuna about the style, it looks as though it'd be best to minimize the changeable parts in the end-user's wizard. That means the CSS doesn't really have a plethora of variables strung together, but mostly fixed values with maybe just one being locally settable. That makes it seem (to me, in this case) like overkill to do a variable string setting when of the four, three are constants. Or for standards compliance should I treat even the constants as potentially adaptable?

Also, you might want to add a few notes in the main post about how to enter comments or descriptions. One thing that bugs the hell out of me is the lack of descriptions in the current wizard, because styles are no more self-commenting than code! I believe the transmog style has descriptions, but the syntax isn't immediately obvious. So maybe a paragraph about where and how to comment, and where those comments will show up -- that is, between doing { des = "here's a bit of info" ; } --- and why the closing semi-colon is INSIDE the curly brackets even though the curly brackets don't enclose the entire line! -- versus doing ## comment goes here ## aka the propgroup lines, versus putting it in the CSS.

Y'know, in all your copious spare time.