View source for S2 Guide: Style System Overview

= Layer Basics =

Every style is composed from a set of layers.  Things in later layers override things in earlier layers; the first layer is called the <em>core layer</em> and everything builds on top of it.

<graphviz caption='Order of layers'>
// This is just a wee graph of the order of layers!
digraph layers {
rankdir = "LR";

core_layer [shape="doubleoctagon" color="#002F74" fontcolor="black" label="Core"];
i18nc_layer [shape="Mdiamond" color="#017313" fontcolor="black" label="i18nc"];
layout_layer [shape="doubleoctagon" color="#444F96" fontcolor="black" label="Layout"];
i18n_layer [shape="Mdiamond" color="#01A313" fontcolor="black" label="i18n"];
theme_layer [shape="doubleoctagon" color="#886FA8" fontcolor="black" label="Theme"];
wizard_layer [shape="doubleoctagon" color="#BB8FCA" fontcolor="black" label="Wizard"];

subgraph {
  rank = same;
  core_layer;
  i18nc_layer;
}

subgraph {
  rank = same;
  layout_layer;
  i18n_layer;
}

core_layer -> layout_layer
core_layer -> i18nc_layer
i18nc_layer -> layout_layer
layout_layer -> theme_layer
layout_layer -> i18n_layer
i18n_layer -> theme_layer

theme_layer -> wizard_layer
}
</graphviz>

* Core layer -- The foundation layer; all the other layers build on the functions and classes available here.
* Layout layer -- The base layer for making an new layout.  Layout layers can define functions and new properties!
* Theme layer -- Goes on top of a layout layer, and defines variations of the layer.  Theme layers can override functions and set properties. 
* Wizard layer -- this layer is usually generated by the [http://www.dreamwidth.org/customize/options customization wizard] and lets users define their own colors or other properties such as fonts and modules.  Wizard layers can ONLY set existing layout properties.  Sometimes people use wizard layers to submit different color themes for a layout to <dwcomm>dreamscapes</dwcomm>.

= Creating and managing layers =

== View official layers ==

All official core, layout, and theme layers can be viewed here:

http://www.dreamwidth.org/customize/advanced/layerbrowse

You can use this browser to see:

* What properties a layer has set/defined
* What functions a layer has set/defined
* The raw code of a layer
* The layer info

== Manage layers ==

You can manage layers at the [http://www.dreamwidth.org/customize/advanced/layers Your Layers] page.  All your layers will be in a list with section headings.  Each layer's type will be in the list: layout, theme, or wizard.  Layout layers will be under the section of their parent core layer.  Theme and wizard layers will be under the section of their parent layout layer.

Clicking the LayerID link to a layer will bring you to the layer browser, which will let you see what properties and functions a layer has set or defined, the raw code of the layer, or the layer's info.  You can also click the "Edit" button to go to the layer editing interface, or the "Delete" button to permanently remove the layer for your list.  (Make sure no styles are using that layer!)

You may see wizard layers called "Auto-generated Customizations" -- these are layers generated automatically by the customization wizard.

== Create a new layer ==

At the bottom of the [http://www.dreamwidth.org/customize/advanced/layers Your Layers] page, you can create a new layout layer, or a new layer based on a layout such as a theme or wizard layer.

=== Create a new layout layer ===

To create a new layout layer, use the form under the "Create top-level layer" heading.  Choose "layout". Use Core Version 2 if you want to create a layout for Dreamwidth, or Core Version 1 if you're trying to import a layout from LiveJournal.

You will find your new layout layer as the last item in the layer table under  the section "Child of layer 550: Dreamwidth S2 Core, v2" with a title of "(none)".  Click the "Edit" button next to the layer and you will see the layer editing interface containing:

<syntaxhighlight>
layerinfo "type" = "layout";
layerinfo "name" = "";
</syntaxhighlight>

Put the name for your new layout inside the empty quotes on the <code>layerinfo "name"</code> line and save so you can easily find your layer in the list later.

=== Create a new theme layer ===

To create a new theme layer, use the form under "Create a layout-specific layer".  Select "Theme" for the layer type.  From the layout list, select the layout you want to base the theme on.  Official layouts come first in the list, and then come your personal layout layers.

You will find your new theme layer as the last item in the layer table under the section that has the title of the layout you are using.  Click the "Edit" button next to the theme layer and you will see the layer editing interface containing:

<syntaxhighlight>
layerinfo "type" = "theme";
layerinfo "name" = "";
</syntaxhighlight>

Put the name for your new theme inside the empty quotes on the <code>layerinfo "name"</code> line and save so you can easily find your theme in the list later.

=== Create a new wizard layer ===

{{Warn|text=When you are using a wizard layer in a style, and make changes in the customization wizard, the wizard will OVERWRITE your wizard layer!  If you want to prevent this from happening, use a theme layer instead. Wizard layers are meant to be used with the customization wizard.}}

You can create wizard layers manually, or using the customization wizard.

To create a wizard layer using the customization wizard, just use a style with a layout you want to make the wizard layer for, whether selected from [http://www.dreamwidth.org/customize/ the list of official styles] or from [http://www.dreamwidth.org/customize/advanced/styles Your Styles].  Go to the customization wizard:

http://www.dreamwidth.org/customize/options

Make any changes you would like, and save.  An automatically generated wizard layer will be created and used for the style you are currently using.  If a wizard layer already exists for this style, it will be overwritten with the new values.

To create a new wizard layer manually, use the form under "Create a layout-specific layer".  Select "Wizard" for the layer type. From the layout list, select the layout you want to base the wizard layer on.  Official layouts come first in the list, and then come your personal layout layers.

You will find your new wizard layer as the last item in the layer table under the section that has the title of the layout you are using.  Click the "Edit" button next to the wizard layer and you will see the layer editing interface containing:

<syntaxhighlight>
layerinfo "type" = "user";
layerinfo "name" = "";
</syntaxhighlight>

Put the name for your new wizard layer inside the empty quotes on the <code>layerinfo "name"</code> line and save so you can easily find your wizard layer in the list later.

== Using the layer editor ==

Clicking the "Edit" button next to any layer on the [http://www.dreamwidth.org/customize/advanced/layers layer list] will bring you to the layer editor.

The sidebar will help you navigate through your code; it lists property groups or functions present, and clicking on one will take you to that position in your code.

In order to save your layer, click on Save &amp; Compile at the top.  Only valid code will save--if you have syntax errors in your code, it will give you an error.  The [[S2 Guide: Troubleshooting|Troubleshooting]] page might give you some advice on how to fix it.

= Creating and managing styles =

== Managing styles ==

You can manage styles at the [http://www.dreamwidth.org/customize/advanced/styles Your Styles] page.  All styles you have are listed with action buttons next to them.

"Edit" will let you edit what layers a style uses, such as the layout and theme layers.

"Delete" will delete that style, removing it from the list of styles.

"Use" will make that style your journal's displayed style.

After the name of each style is a link made of that style's ID number.  Clicking that link will bring you to your journal, but displaying the style you have chosen instead of your journal's current style.  This is a good way to preview a style without using it.

== Creating styles ==

At the bottom of the [http://www.dreamwidth.org/customize/advanced/styles Your Styles] page, there is a form to start creating a new style with a given name.

Entering the name and hitting create will make the style and bring you to a form to fill in the style's details.

If you are trying to make a style with layers you have made for Dreamwidth layouts, leave it with Core Version 2.  If you are trying to make a style with layers you have imported from LiveJournal, select Core Version 1 and hit Change.

Next, select what layout you want to use with this style (official layouts come first in the list, then any custom layouts you may have) and hit Change.

You can new select what theme and/or wizard layers to use for this style.  (Again, official themes for a layer will be listed first, then your custom themes.)  Hitting the "Save Changes" button will then save all the changes to this style.

Now when you go back to [http://www.dreamwidth.org/customize/advanced/styles Your Styles], this new style will be listed in alphabetical order with the others.

= Layer Details =

== Core layer ==

The core layer is the foundation everything else builds on.  It can:

* Define classes
* Define <tt>builtin</tt> functions that are present in the backend
* Define global functions that don't belong to a class
* Define class methods
* Define and set properties

Dreamwidth has two different core layers.

* <tt>core1</tt> is inherited from LiveJournal and allows people to import their LiveJournal layouts.
* <tt>core2</tt> is Dreamwidth's core layer, that includes extra features built in, like modules.  Plain Tabula Rasa is the base style put out by <tt>core2</tt>.

If you're making a layout on Dreamwidth, you'll probably want to use <tt>core2</tt>. You can't make your own core layer as a site user.

You can see more information about [http://www.dreamwidth.org/customize/advanced/layerbrowse?id=core2 core2 on the site], such as the raw source code and available classes and functions!

== Layout layer ==

If you want to make a brand new layout, start with a layout layer.  Layout layers can:

* Define <tt>builtin</tt> functions that are present in the backend
* Define global functions that don't belong to a class
* Override existing class methods
* Define new class methods; the method name must have the prefix <tt>lay_</tt> to avoid future namespace collisions if the core layer expands
* Define and set properties
* Set up properties for the customization wizard

== Theme layer ==

A theme layer goes on top of the layout layer and tweaks it.  Start with a theme layer if you like a certain layout and just want to make some changes to it.

A theme layer can:

* Override existing functions
* Override names and descriptions of properties

It's usually used to make different versions to a base layout, such as different color schemes.

== Wizard layer ==

All a wizard layer can do is set existing properties.  Since a lot of layouts have many properties, this can change a lot of things!

{{Expand|text=Need to talk about how wizard layers get automatically generated, what to do to prevent them being wiped by the customization area, etc.}}

It's meant to be edited using the [http://www.dreamwidth.org/customize/options customize interface] on the site, but can also be created or edited manually.  (If you're familiar with styles on LiveJournal, this was called the "user layer".)

Many new layout themes have originated from people sharing wizard layers in <dwcomm>dreamscapes</dwcomm>!

== Internationalization layers ==

Unless you're translating a layout into another language, you won't have to worry about these layers.  The i18nc layer overrides text properties in the core, translating them into a specific language. It also overrides the default short, medium, and long date and time formats and functions which do things like return ordinal numbers from cardinal numbers and map item counts onto their plural form.

To achieve this goal, language layers can:

* Set properties
* Override the names and descriptions of properties
* Override existing functions

=== i18nc: core ===

This layer translates text properties in the core into a specific language, overrides the default date and time formats, and changes functions that do things like make pluralized item count statements--all things that can change according to different languages or standard conventions!

=== i18n: layout ===

This layer does the same as <tt>i18nc</tt>, but only for new properties or functions added by a layout.

== Layerinfo ==

Layerinfo declarations give information about a layout, like its name or author.

=== Available layerinfo settings ===

{| style="border-collapse: collapse" cellpadding="3px" border="1"
|+ All possible layerinfo settings
! Name
! Use
|-
| type (required)
| <tt>type</tt> is the only required layerinfo value.  It needs to be a string of one of the following values: "core", "layout", "theme", "user" (refers to the wizard layout).
|- 
|name
| This is a string of the name of the layer.
|-
| author_email
| This is a string of the author's email.
|-
| author_name
| This is a string of the author's name. ( This is used for the designer for public styles. )
|-
| des
| A string describing the layer.
|-
| is_internal (system)
| If this is present and set to <tt>1</tt> on a system layer, that means the layer does not show up in the theme browser or in the drop-downs on /advanced/styles. Please note that this does not prevent the style from being used, just makes it difficult.
|-
| is_public
| If this is present and set to <tt>1</tt>, that means the layer is available for other users to use in their own S2 styles.  That doesn't mean they can view the source, though; see <tt>source_viewable</tt>.
|-
| source_viewable
| If this is present and set to <tt>1</tt>, that means the layer's source is viewable to others.  That doesn't mean they can use this layer like with <tt>is_public</tt>, although if they can see the source they can make a layer of their own with the code.
|-
| majorversion
| FILL IN
|-
| minorversion
| FILL IN
|-
| previews (system)
| If a layer is going to be included in the main system, this indicates what preview image to use in the style selector.  
|-
| redist_uniq (system)
| If a layer is going to be included in the main system, it needs a unique identifier as a string.
|}

=== Examples of using layerinfo settings ===

<syntaxhighlight lang="s2">layerinfo "type"            = "theme";
layerinfo "name"            = "Sheep Sky";
layerinfo "author_email"    = "bwoolly@dreamwidth.org";
layerinfo "author_name"     = "B. Woolly";
layerinfo "des"             = "A layout featuring sheep as clouds.";
layerinfo "is_public"       = 1;
layerinfo "source_viewable" = 1;
layerinfo "majorversion"    = 2;
layerinfo "minorversion"    = 4;
layerinfo "previews"        = "test/test.jpg";
layerinfo "redist_uniq"     = "test/layerinfo";
</syntaxhighlight>

[[Category: S2 Guide]]