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.)

[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.

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?

[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.

[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. :)

[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

[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?" !)