A Guide to S2 Layer Customization and CSS in Layers

[av8rmike]

Questions about the interactions of "theme" and "user" layers seem to crop up all the time, as well as "where do I put my CSS changes", so I thought I'd write a tutorial on how to consolidate things.
UPDATE (11/05/07): This tutorial has been updated and expanded to reflect the changes to the Customize Journal section and include directions on creating a theme layer.

Layer Interaction

As explained in many places, all S2 styles are combinations of layout and theme layers. In Expressive, the theme layers can control more than just color variations; by modifying the CSS they can control fonts, headers, backgrounds, and almost anything else. The designers of the Expressive layout provide for additional user customizations, such as changing text strings and sidebar order, through the Customize Journal Style page of the new customization section. The S2 documentation section on layer types explains what this customization area does: It creates a "user" layer and appends it to your current style (which is probably named "wizard-voxhtml"). This user layer will be called "Auto-generated Customizations" and will contain the code (in the S2 language) for the changes you've made from the defaults.

So what's the problem? Well, none, if all you want to make is minor text or CSS changes. However, changes to the layout code, like modifying the way entries or sidebar widgets are printed, should go into a theme layer rather than a user layer. Any code that's entered into a user layer will be overwritten the instant the "save changes" button is clicked in the Customize Journal area. In addition, some people (like me) just prefer to have all the changes consolidated into one layer instead of two. Get rid of the pesky auto-generated layer by going to "Your Layers". If there is a User layer called "Auto-Generated Customizations", click on the Delete button next to it. A confirmation page will come up, just click Delete again.

Creating a Theme Layer
This post gave a good explanation of how to create a custom theme layer, but the steps have changed because of the new customization pages. So, I'll try to explain step-by-step how to create one from scratch.

1. From the new customization page, click on the link called "Developer Area" on the left sidebar.
2. This link takes you to the former "Advanced" customization area, and has not changed with the update. Click on "Your Layers".
3. Under "Create Layout-Specific Layer", click Theme in the first drop-down box, then Expressive in the second.
4. A new blank layer will appear in the boxes at the top of the page, listed as "Child of layer 7176168: Expressive" and with (None) as the name. Click on Edit next to this name.
5. You will be taken to the layer code editor. The large pane in the upper right is where all S2 code is entered. Start by entering these lines:
   layerinfo "type" = "theme";
   layerinfo "name" = "name for your theme";
   set base_theme = "name of base theme";
   set theme_designer = "get from base theme";
   set theme_designer_type = "get from base theme";For "name", simply give a name that will be displayed in the "Your Layers" page. For "base_theme", "theme_designer", and "theme_designer_type", you will need to use the settings for the theme you wish to customize. This information can be found in the Public Layers Browser, under Expressive children by clicking on the theme of your choice, then on View Source. For example, to use "Inked Red" as a base:
   set base_theme = "inked-red";
   set theme_designer = "chasethestars";
   set theme_designer_type = "ljuser";To use no theme for a base and completely style the layout from scratch, use these settings:
   set base_theme = "__none";
   set theme_designer = "";
   set theme_designer_type = "";
6. Copy or type in any other S2 code to apply to this layout, such as properties or functions, after the lines above. (See below for information on using CSS in a theme layer).
7. Click on "Save & Compile". If everything is correct, the compiler should report "Compiled with no errors" at the bottom. If it doesn't, it should report the type of error generated and the context of the error. (If you can't fix it, feel free to post a message asking for help. Just make the layer viewable before you do.)
8. Once the layer code compiles, it still needs to be made the "active" layer for your journal, otherwise the changes won't be seen. Return to the Customization front page and click on "Your Custom Layers" in the sidebar. Then click on the "Apply Theme" button underneath the layer your just created. If all goes well, the new theme layer with your new codes should now be active.

Using CSS in Theme Layers
So, where does the custom CSS go in the theme layer?
Method 1: An External Stylesheet
If you are using a stylesheet hosted from your own server, add a line to the theme layer after the "layerinfo" lines and before any functions to change the linked_stylesheet property:
set linked_stylesheet = "http://URL TO STYLESHEET";Method 2: Custom Stylesheet Box
The CSS that would normally appear in the "Custom Stylesheet" box on the "Custom CSS" page changes the custom_css property:
set custom_css = """
/* Your Custom CSS goes between the quotes */
""";Add whatever CSS changes you want to make to the theme by putting the statements between the triple quotes.

To give directions on changing all of the properties in the Expressive layout would take far too much time and length. However, a full list of all the properties defined can be found in the Expressive Public Layer Browser, under "Properties Set". Using this syntax:
set property = "";any of these properties can be changed in the theme layer, since that's exactly what the user layer does. Just replace the red text with the name of the property, exactly as it's written in the table, and put the new value between the quotes.

Troubleshooting
If something isn't working right, first make sure the layer is compiling without errors. Check that:

1. ...CSS is not being entered directly into the layer code. Follow method 2 above and put all CSS between the quotes.
2. ...The site that is hosting your stylesheet is active and accepting connections, if you are using Method 1.
3. ...Each declaration block in the CSS has its own { and } brace.
4. ...You didn't accidentally put a parenthesis where a brace goes, or vice versa.
5. ...All property set declarations must end with a semi-colon (;).
6. ... There isn't a User layer attached to your active style that is also modifying settings like text, colors, or Custom CSS. If a user layer and theme layer are both trying to modify the same settings, the user layer will take precedence. To fix this problem, go to the "Your Styles" page and click Edit next to the bolded style, which will probably have a name like "wizard-#######" (the number corresponds to your theme layer). If the box next to "User" has an "Auto-generated Customizations" layer in it, disable it by selecting the blank area at the top of the box. Alternatively, you could edit that layer directly to remove any conflicts with the theme layer.

That's about all I can think of for now. Any suggestions, questions, or problems, feel free to comment.