Beginners Guide: Creating Custom Themes & Layers
This tutorial will explain to anyone new to S2 how to create custom themes and layers and what they are used for. I will not go into the details of S2 code itself. This requires a paid or permanent account. Hopefully I've aimed this at the right level - if anything is not clear, please let me know so I can fix it.
1. The Basics
In S2, Livejournal pages are created by S2 code, which spits out the HTML you see if you view the page source. The code that does this is contained in a layer. A layer is something like Expressive, or Component, or Flexible Squares, for example. These layers each have many themes which alter their appearance, such as Hills Green, or Urban Sunset (for Expressive). If you have a paid or permanent account, you can create new layers and themes to alter as you wish. Altering them requires some knowledge of S2 code, which has some similarities with programming languages such as PHP and Java. This code, on a basic level, consists of variables (such as colour values and link names) and functions (the actual code that spits out the web page HTML). This tutorial will not go into this code any further than that.
2. What's The Difference Between Custom Themes and Custom Layers?
A custom layer is something you create that is a child of (i.e. is based on) Livejournal's core layer (the very bones of Livejournal that us mere mortals don't generally need or want to interact with). When you create a custom layer, it is empty of all code and you won't have much of a journal to look at other than that produced by the default core layer.
The reason I find layers very good to use is that you can copy and paste the source code of an existing layer (such as Expressive) into it and you effectively have your own complete version of that style to manipulate. You can tweak the S2 code within it to do what you want.
A custom theme is something you create that is a child of (i.e. is based on) an existing layer, such as Expressive. This means it is Expressive but you now have the ability to add bits of S2 code (in isolation from the whole Expressive source code) that will override the existing code. For example, you could put in a bit if S2 code that defined the order of your entry navigation links that would override the deafult order. Generally speaking, it is easiest to put in a whole function, copied form the parent layer source code (e.g. Expressive) with your tweaks to it, so that it overrides the default function. The source code for most of the themes can be found here - click on the style you want to copy and then click on Syntax Highlighted or Raw Source Code to see the source code.
So the basic difference between a custom layer and a custom theme is that in the former you have a blank canvas to work with, in the latter, you are working on top of an already existing style such as Expressive, overriding bits of it as required.
3. Creating A Custom Theme
To creat a custom theme, on the front page of Livejournal go to Edit Journal Styles - Advanced - Your Layers.
Scroll down to Create Layout Specific Layer. Choose Theme from the dropdown menu and choose Expressive (for a theme based on Expressive) from the Layout menu, and press Create. Now you have a custom theme. It should now appear in the list above these buttons as a child of Expressive. It will be unnamed so far. Click on Edit next to it and you'll be taken to the page to edit your custom theme.
You will see three windows now. The left is a list of functions, classes and variables for navigation purposes - you can ignore that for now. The bottom will tell you of any errors when you make changes. The main window is where S2 code goes. Every time you put in some new code, just put it below the last item - order doesn't matter.
There are a few things you'll want to put in here before you do anything else. Firstly, give it a name by putting your name of choice into the inverted commas in this line like so (this line is automatically included in the theme):
layerinfo "name" = "Theme Name Goes Here";
Secondly, you will want to specify the default colour theme you have been using in Expressive so far to keep the look the same as you already had. So for example if you have been using the Urban Green theme, you should add the line:
set base_theme = "urban-green";
After you make any changes, click on Save & Compile at the top left of the main window, and check that no errors appear in the bottom panel. If there are any, you have typed some code in wrong.
4. Creating A Custom Layer
This is pretty similar to creating a custom theme. On the front page of Livejournal, go to Edit Journal Styles - Advanced - Your Layers.
Scroll down to Create Top Level Layer and choose layer from the drop-down menu. It will appear as a new unnamed child of LiveJournal S2 Core, v1 in the list above. Click on Edit to edit it. You will see three windows now. The left is a list of functions, classes and variables for navigation purposes - you can ignore that for now. The bottom will tell you of any errors when you make changes. The main window is where S2 code goes.
Give this layer a name in the same way as described above for Custom Themes. If you are very ambitious, this is where you can create a layer from scratch if you are fluent in S2 code and know exactly how Livejournal works. This is a very complex task and I wouldn't recommend it for any but the most die-hard coding enthusiast or Livejournal employees!
For the average user, a useful option is to copy and paste the entire code of an existing style (such as Expressive) which you can then modify as you please, assuming you know a little of how S2 code works. You can find the code of existing layers here. Click on the style you wish to copy, then click on Syntax Highlighted or Raw Source Code to see the code. Copy and paste this into your custom layer.
Once you've done this, you should change the name of the theme as described previously, and also change the author line if it exists, which looks like this:
layerinfo author_name = "Author Name";
It is polite to credit the original author, saying that yours is a modification of it.
You should also delete these lines (or their equivalents for other copied styles, these are from Expressive), if they exist:
layerinfo redist_uniq = "voxhtml/layout";
layerinfo previews = "voxhtml/layout.jpg";
The other initial lines - you can use common sense to adjust as feels appropriate.
Again, you may want to set the base_theme as described previously, this time simply replacing the name, not adding a whole new line (it already exists - as mentioned before, with a layer like this you are modifying existing code, not overriding). The line in question is pretty near the top, shouldn't be hard to find.
And as before, after making any changes, click the Save & Compile button at the top left, and check no errors appear in the bottom panel.
5. Using Your Custom Theme or Layer
Once you have created and edited a custom theme or layer and saved it, you need to go back to the main Edit Journal Style - Look And Feel. If you have created a theme, make sure you have the correct layer selected that you based it on, and choose your new theme from the Themes drop-down layer. If you have created a layer, choose your new layer from the Layout drop-down menu. New themes and layers are added to the end of the list. Save your setting and your journal should now be using your custom theme or layer.
References
Existing Layers' Source Code
S2 Code Documentation
1. The Basics
In S2, Livejournal pages are created by S2 code, which spits out the HTML you see if you view the page source. The code that does this is contained in a layer. A layer is something like Expressive, or Component, or Flexible Squares, for example. These layers each have many themes which alter their appearance, such as Hills Green, or Urban Sunset (for Expressive). If you have a paid or permanent account, you can create new layers and themes to alter as you wish. Altering them requires some knowledge of S2 code, which has some similarities with programming languages such as PHP and Java. This code, on a basic level, consists of variables (such as colour values and link names) and functions (the actual code that spits out the web page HTML). This tutorial will not go into this code any further than that.
2. What's The Difference Between Custom Themes and Custom Layers?
A custom layer is something you create that is a child of (i.e. is based on) Livejournal's core layer (the very bones of Livejournal that us mere mortals don't generally need or want to interact with). When you create a custom layer, it is empty of all code and you won't have much of a journal to look at other than that produced by the default core layer.
The reason I find layers very good to use is that you can copy and paste the source code of an existing layer (such as Expressive) into it and you effectively have your own complete version of that style to manipulate. You can tweak the S2 code within it to do what you want.
A custom theme is something you create that is a child of (i.e. is based on) an existing layer, such as Expressive. This means it is Expressive but you now have the ability to add bits of S2 code (in isolation from the whole Expressive source code) that will override the existing code. For example, you could put in a bit if S2 code that defined the order of your entry navigation links that would override the deafult order. Generally speaking, it is easiest to put in a whole function, copied form the parent layer source code (e.g. Expressive) with your tweaks to it, so that it overrides the default function. The source code for most of the themes can be found here - click on the style you want to copy and then click on Syntax Highlighted or Raw Source Code to see the source code.
So the basic difference between a custom layer and a custom theme is that in the former you have a blank canvas to work with, in the latter, you are working on top of an already existing style such as Expressive, overriding bits of it as required.
3. Creating A Custom Theme
To creat a custom theme, on the front page of Livejournal go to Edit Journal Styles - Advanced - Your Layers.
Scroll down to Create Layout Specific Layer. Choose Theme from the dropdown menu and choose Expressive (for a theme based on Expressive) from the Layout menu, and press Create. Now you have a custom theme. It should now appear in the list above these buttons as a child of Expressive. It will be unnamed so far. Click on Edit next to it and you'll be taken to the page to edit your custom theme.
You will see three windows now. The left is a list of functions, classes and variables for navigation purposes - you can ignore that for now. The bottom will tell you of any errors when you make changes. The main window is where S2 code goes. Every time you put in some new code, just put it below the last item - order doesn't matter.
There are a few things you'll want to put in here before you do anything else. Firstly, give it a name by putting your name of choice into the inverted commas in this line like so (this line is automatically included in the theme):
layerinfo "name" = "Theme Name Goes Here";
Secondly, you will want to specify the default colour theme you have been using in Expressive so far to keep the look the same as you already had. So for example if you have been using the Urban Green theme, you should add the line:
set base_theme = "urban-green";
After you make any changes, click on Save & Compile at the top left of the main window, and check that no errors appear in the bottom panel. If there are any, you have typed some code in wrong.
4. Creating A Custom Layer
This is pretty similar to creating a custom theme. On the front page of Livejournal, go to Edit Journal Styles - Advanced - Your Layers.
Scroll down to Create Top Level Layer and choose layer from the drop-down menu. It will appear as a new unnamed child of LiveJournal S2 Core, v1 in the list above. Click on Edit to edit it. You will see three windows now. The left is a list of functions, classes and variables for navigation purposes - you can ignore that for now. The bottom will tell you of any errors when you make changes. The main window is where S2 code goes.
Give this layer a name in the same way as described above for Custom Themes. If you are very ambitious, this is where you can create a layer from scratch if you are fluent in S2 code and know exactly how Livejournal works. This is a very complex task and I wouldn't recommend it for any but the most die-hard coding enthusiast or Livejournal employees!
For the average user, a useful option is to copy and paste the entire code of an existing style (such as Expressive) which you can then modify as you please, assuming you know a little of how S2 code works. You can find the code of existing layers here. Click on the style you wish to copy, then click on Syntax Highlighted or Raw Source Code to see the code. Copy and paste this into your custom layer.
Once you've done this, you should change the name of the theme as described previously, and also change the author line if it exists, which looks like this:
layerinfo author_name = "Author Name";
It is polite to credit the original author, saying that yours is a modification of it.
You should also delete these lines (or their equivalents for other copied styles, these are from Expressive), if they exist:
layerinfo redist_uniq = "voxhtml/layout";
layerinfo previews = "voxhtml/layout.jpg";
The other initial lines - you can use common sense to adjust as feels appropriate.
Again, you may want to set the base_theme as described previously, this time simply replacing the name, not adding a whole new line (it already exists - as mentioned before, with a layer like this you are modifying existing code, not overriding). The line in question is pretty near the top, shouldn't be hard to find.
And as before, after making any changes, click the Save & Compile button at the top left, and check no errors appear in the bottom panel.
5. Using Your Custom Theme or Layer
Once you have created and edited a custom theme or layer and saved it, you need to go back to the main Edit Journal Style - Look And Feel. If you have created a theme, make sure you have the correct layer selected that you based it on, and choose your new theme from the Themes drop-down layer. If you have created a layer, choose your new layer from the Layout drop-down menu. New themes and layers are added to the end of the list. Save your setting and your journal should now be using your custom theme or layer.
References
Existing Layers' Source Code
S2 Code Documentation