[paidaccount] Creating and Using a Theme Layer
Contents: [ Introduction] [ Creating a Theme Layer] [ Setting Properties in a Theme Layer] [ Using a Theme Layer to Replace a Function from the Layout Layer] [ Applying a Theme Layer to Your Style]
Paid Accounts OnlyThe following tutorial requires creating and editing a custom style, which in turn requires a paid, permanent, or early adopter account. Please read What are the paid account benefits? and How do I buy a paid account? to learn about the paid account benefits and how to buy a paid account. Introduction
Many advanced S2 customizations require you to create and edit a theme layer, in order to set properties or replace functions from the layout layer. Using a theme layer allows you to change many parts of the layout without having to create an entire layout layer. This tutorial explains how to create a theme layer, set properties, and replace functions.
Creating a Theme Layer
S2 layers are managed through the Advanced Customization area. To create a theme layer, go to this area and click on "Your Layers". At the bottom of the Your Layers page, under the heading "Create layout-specific layer", select "Theme" from the drop-down box for layer type. Then select the name of the layout you wish to customize from the drop-down box for layout, and click the "Create" button.
A link to your new theme layer will appear in the list of layers, under a heading that includes the name of the layout for which this theme layer was created. For example, a theme layer for the Generator layout will be under a heading that says "Child of layer 6: Generator".
The line which lists your theme layer will contain the layer's ID number in the column labeled "LayerID", the word "theme" in the column labeled "Type", and the word "(none)" in the column labeled "Name". This line also contains some buttons for working with your layer. In order to edit a theme layer, click the "Edit..." button next to the layer's name. This will lead you to the S2 compiler page, where you can add code for the customizations you wish to make.
When you edit a newly created a theme layer, the following code will already be displayed in the compiler:
layerinfo "type" = "theme";
layerinfo "name" = "";
So that you can easily identify this layer in your list of layers, you should give it a unique name by placing this name between the final set of quotation marks. For example, if you name your layer "Testing Layers", then the code will look like this:
layerinfo "type" = "theme";
layerinfo "name" = "Testing Layers";
Now you can click the "Compile" button to save the layer with its new name. Any further code which you place in your layer should be located below the two layerinfo lines, and you will need to click "Compile" each time you wish to save your work.
You can only use one theme layer at a time. If you want to use colors from a theme layer other than the layout default, you will need to copy the settings into your new theme layer. You can view the source code of theme layers for the system layouts at the Public Layers page.
Click on the "[# children]" link below the name of the layout layer you are using to see a list of the theme layers for that layout, then click on the name of the theme you wish to copy to see information about that theme. For example, you can see the layerinfo and properties of the Mint Chocolate Chip theme for the Generator layout.
To copy the properties from the theme layer you have chosen, click on the "Raw Source Code" link at the top of this information page. Copy all of the code from this page, except for the lines which begin with layerinfo, and paste it into the bottom of your custom theme layer.
After you have saved your changes, you can select your new theme layer for use. Go to the Customize Journal page and ensure that you are using the layout for which you created your theme layer, then select the new theme layer from the "Themes" dropdown list and click the "Change" button.
Setting Properties in a Theme Layer
One use of a theme layer is to set a property. Many properties can be set in a user layer, which is automatically generated when you use the "Change Individual Settings" section of the Customize Journal area. However, some layouts do not allow all properties to be overridden by the "Change Individual Settings" interface. If you wish to change these properties, you will need to set them in your theme layer instead. For example, if you are using the A Sturdy Gesture layout and want to change the text for previous and next skiplinks, you can do so by placing the following code in your theme layer:
set text_page_prev = "Go backwards";
set text_page_next = "Go forwards"; property name Name given to the property when it was defined in either the core or layout layer. At any place in the layout where this property name is referred to, it will be replaced with the text or option which you set for the property. property value Text or an option setting which will replace the property name within the layout.
There are three types of properties: bool, string, and int.
- A bool property can have a value of either true or false. This type of property is used to enable or disable a particular feature of the layout, such as the use of styled comment pages.
- A string property can have any value, the text of which will appear in place of the property wherever it is used in the layout. This type of property is used for things such as setting the name of a link or a stylesheet attribute such as the URL of a background image. The value of a string property must be placed in quotation marks.
- An int property can have a value which is a positive whole number. This type of property is used to set options such as how many entries appear on your Recent and Friends pages.
You also may wish to set properties in a theme layer if you plan to always use those property settings together. For example, you could create a bee theme for your journal, where yellow and black colors, a background picture of a beehive, and comment link text such as "3 bees buzzed | join the buzzing" are all part of the theme layer. Then you would be able to select all of those options in one easy step by changing to that theme layer.
Using a Theme Layer to Replace a Function from the Layout Layer
A more powerful use of a theme layer is to replace functions created in the layout layer. This allows you to add extra functionality to your style, or make significant changes to its appearance.
In order to override a function, you will need to copy the entire existing function from the layout layer into your theme layer, and then make the appropriate changes. Make sure that you copy everything down to and including the closing bracket, which will be the last character before the beginning of the next function.
For example, the Variable Flow layout does not have property settings for changing the text of the current music and current mood. In order to change this text in Variable Flow, you must override the metadata_title function, which looks like this:
function metadata_title(string which) : string
"Until core provides a function for this, i18n layers should override this."
{
if ($which == "music") {
return "Current Music";
}
elseif ($which == "mood") {
return "Current Mood";
}
else {
return $which;
}
}
In this code, you would change Current Music and Current Mood to the text you wish to display next to your current music and current mood.
Most of the customization tutorials in s2howto will require you to create a theme layer and replace a function from your layout layer. In these tutorials, you will be given the necessary code to copy for that function. However, if you wish to replace a function for which there is no tutorial, you can find the function within the layout's source code at the Public Layers page.
To view the source of a layout layer, first click on the name of the layout, then on the "Raw Source Code" link at the top of the page. Please note that some system layouts, such as Component and The Boxer, are "closed source". This means that it is not possible to view the source code of these layouts in order to copy functions from them. However, it is still possible to override these functions by using tutorials provided in s2howto or by using trial-and-error to determine what the existing functions are.
Applying a Theme Layer to Your Style
Once you have finished creating your new layer, you can save your theme layer by clicking on the "Save & Compile" button at the top of the screen. Your changes will not take effect until you apply your theme layer by selecting it's name in the "Themes" section of the Customize Journal page.
Additional References What are the different S2 layer types?
S2 Manual Contributed by phoenixdreaming and alsatia