Creating patches for new styles and new themes

[afuna]

Here's the process to take an existing theme layer and convert it into patch form (with all the fluff and trimmings to make it work on the customize page, have proper credit, etc).

Adding a theme layer to an existing style

To add a theme layer to an existing style, you need to edit two files:

bin/upgrading/s2layers/$layoutname/themes.s2 (or themes-local.s2)
cgi-bin/LJ/S2Theme/$layoutname.pm (or $layoutname_local.pm)


The *local versions are there for those layouts which are in dw-free, and have themes in both dw-free and dw-nonfree (dw-nonfree will most likely be because of image licensing issues).

Now, ideally, the theme layer will already look something like this:


layerinfo type = "theme";
layerinfo name = "My Theme";
layerinfo author_name = "afuna";

set color_page_background = "#12345";
set color_page_text = "#54321";
# ... more properties


That is, it should be a header containing metadata for the theme, and then a list of properties.

Let's say that this theme is a child of Tabula Rasa, which has the layout code core2base. Add the theme to the bin/upgrading/s2layers/core2base/themes.s2 file (slot it in alphabetical order, please!):


#NEWLAYER: core2base/mytheme
layerinfo type = "theme";
layerinfo name = "My Theme";
layerinfo redist_uniq = "core2base/mytheme";
layerinfo author_name = "someuser";

set layout_authors = [ { "name" => "someuser", "type" => "user" }];

set color_page_background = "#12345";
set color_page_text = "#54321";


I've bolded the lines that I added; as you can see there are only three of them (four, if you need to link to a resources site).

The redist_uniq is, by convention, layoutcode/themecode. Most of the time, the layout code name will match the display name, but with spaces and special characters stripped out; Tabula Rasa is a very rare exception to this rule.

Remove any layerinfo lang, is_public, or source_viewable -- the theme layer isn't the proper place to set the language, and being a system layer will automatically have the same effect as the latter two, so it's just clutter.

You don't need to set the author name if the theme author is the same as the layout author. For more information on the syntax for giving credit, see this great guide to the credit module from stylemakers.


Then, add this to cgi-bin/LJ/S2Theme/core2base.pm:


package LJ::S2Theme::core2base::mytheme;
use base qw( LJ::S2Theme::core2base );
sub cats { qw() }

sub designer { "someuser" }


"Cats" refers to the categories over on /customize. Leave this blank, someone else will sort it out later. As above, the "sub designer" line doesn't need to be added if the theme author is the same as the layout author.

And that's it! Apply the generated patch to your dreamhack, run $LJHOME/bin/upgrading/update-db.pl -r -p --innodb, and you'll have a new theme.

Adding an entirely new style from a theme layer

This entry is purely about generating patches from a layer which is already s2-ified, so I won't cover the conversion from a stylesheet to a theme layer. If you need it, see the tutorial for S2 property conversion, which is thoroughly amazing. :)

Hopefully you won't need to do that yourself (the task is time-consuming, but not very complicated,so it's perfect for when you have plenty of time on your hands, but not much brainpower to spare). Let's just move on past it; I'll assume that either the theme came ready-converted, or that you did the conversion on your own.

So, you'll basically end up editing five files:

bin/upgrading/s2layers.dat
bin/upgrading/s2layers/$layoutname/layout.s2
bin/upgrading/s2layers/$layoutname/themes.s2

cgi-bin/LJ/S2Theme/$layoutname.pm
cgi-bin/LJ/S2Theme.pm


~
tangent

It's a bit tedious to remember it all each time, so I have a hacked up script I use to automate the filling in of the skeleton for me: newlayout script

Before running it, first edit $layout_path and $cgibin_path. Also edit the "system" call at the bottom to make it use an appropriate text editor.

(edit: changed the script to be a bit easier to configure)
Before running it, first edit $base_path and $editor. Then chmod u+x, and call it by doing this:

newlayout "My New Layout" authorname "The Default Theme for This Layout"

That will give you new files mynewlayout/layout.s2, mynewlayout/themes.s2, S2Theme/newlayout.pm, and if you've set an appropriate text editor, it will also open up the new files as well as a couple of existing ones that you'll need to touch
~


Now the edits you need to do to the files:

bin/upgrading/s2layers/s2layers.dat

You'll need to add a line in this format:

base filename         layer type      parent

You can mimic the existing layouts' lines; it's fairly straightforward. Now one important thing, though, is that if you're creating a layout that's straight from core2, the layer type will just be "layout". If you do this, you'll need to make sure to pull in all the module properties, etc etc.

If you're creating a layout from something that was originally a theme of another layout, then you can create a layout layer that combines both the parent layout and the current layout by putting "layout(parentlayercode/layout)" as the layer type.

bin/upgrading/s2layers/$layoutname/layout.s2

Important metadata:

layerinfo "type" = "layout";
layerinfo "name" = "My New Layout";
layerinfo "redist_uniq" = "mynewlayout/layout";
layerinfo "author_name" = "authorname";
layerinfo "lang" = "en";

set layout_type = "two-columns-right"; # or choose one at random;
set layout_authors = [ { "name" => "authorname", "type" => "user" } ];

## any custom layout functions


It's good to sanity-check the layout before creating the patch. Some things to look at:

# make sure it uses properties; it can use the generate_* convenience functions, which also make the print out of the CSS smart when the properties are empty
# check comment form positioning
# check contrast
# check fluid width

bin/upgrading/s2layers/$layoutname/themes.s2

Same as when adding a new theme to an existing layer.

cgi-bin/LJ/S2Theme/$layoutname.pm

Same as adding a new theme to an existing layer. But also make sure that you put a "1;" at the very end of the file; that is a quirk of the Perl module syntax. So:

package LJ::S2Theme::core2base::mytheme;

...blah blah blah

1;

cgi-bin/LJ/S2Theme.pm

Look for %default_themes; insert your layout and its default theme into the hash.

After this , one final step, leave a comment on Bug 680: screenshots for layouts.




Other things: images for layouts go under: htdocs/stc/$layoutname/imagename.png, etc. (under stc so that we can access them as relative urls from stylesheets, though in practice, we've been setting them as absolute URLs in properties by using variables, etc)

And uhh. I guess that's it!

Edit: 10/01: fixed a few errors, clarified a few instructions, courtesy of zvi

Comments

[zvi]

I don't know if it is more appropriate to be added to this explanation or branch's conversion explanation, but there should be a note about how, if you create properties to be set in the wizard in a layout that is based on a pre-existing layout, you need to add them to

propgroup propgroupname_child

so they don't wind up off in a miscellaneous tab and you don't hose the default wizard settings.

[afuna]

Hmm, I'm beginning to think it would be best to move this off to a wiki so we can keep this updated with the latest info.

(PS. you are right about the newlayout script thing; the "featured" it adds is before we changed policy, so it should be changed to "base". I haven't been able to poke at it enough to twiddle the right bits but I shall try tomorrow. And it is mildly offtopic, but I thought of it, because that's another entry I have been thinking of moving over to the wiki.)

[zvi]

I don't want to wikify it, maybe we could ask if someone on the docs team would like to do so?