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

beats head against wall

[zvi]

When I try to use your script, I get an error when I try to save the files generated that way; the error says that it could not open the files. I don't know what I'm doing wrong.

Re: beats head against wall

[afuna]

Hmm, what's the exact text of the error message? Did you set open up the script and set the file path, near the top?

Re: beats head against wall

[zvi]

Error opening file is the exact error message.

Yes, I set the file path to:
my $layout_path = "$LJHOME/bin/upgrading/s2layers/$layout_name";
my $cgibin_path = "$LJHOME/cgi-bin/LJ/S2Theme";

And I changed the editor to joe from edit.

Re: beats head against wall

[afuna]

Aha. Try this instead:

my $layout_path = "\$LJHOME/bin/upgrading/s2layers/$layout_name";
my $cgibin_path = "\$LJHOME/cgi-bin/LJ/S2Theme";

So what was happening was that the perl script has a blank value for $LJHOME, and so it ended up trying to edit a file from root (/bin/upgrading... instead of ~/dw/bin/upgrading...). Backslashing the "$" means that perl no longer considers it as a variable, so passes the $LJHOME string straight to your shell/terminal. The shell then uses its $LJHOME variable (which has the proper value).

Also, good idea on setting it to $LJHOME by default! I should edit my script to do that, instead :)

Re: beats head against wall

[afuna]

Ta -- edited. Try downloading it again; you should only need to edit $editor now.

Re: beats head against wall

[zvi]

WHEEE! It works, thank you!

[zvi]

Uh, I think one of the file names is wrong.

Shouldn't /bin/upgrading/s2layers/s2layers.dat actually be /bin/upgrading/s2layers.dat ? (i.e. it's up one directory.)

also, when writing cgi-bin/LJ/S2Theme/$layoutname.pm for the first time, one needs to add 1; at the bottom of it, or else start-apache won't work.

Also, also, in themes.s2, #NEWLAYER core2base/mytheme should be #NEWLAYER: core2base/mytheme

And, um, I did not know that update-db.pl meant $LJHOME/bin/upgrading/update-db.pl -r -p --innodb

[afuna]

Thanks for catching all these! Added instructions/modified, etc.

I completely missed the cgi-bin/LJ/S2Theme/$layoutname.pm bit, because I'm used to newlayout just generating it for me, oops.

How does that look now?

[zvi]

Hmmm. I wget'd the newlayout file, and I'm still having issues?

The s2layers.dat file is still opening in the wrong place.

And this bit has never worked for me, I only looked at the file to think it was supposed to do this today, but none of the pre-printed stuff appears. What I'm doing is

wget http://www.afunamatata.com/dreamwidth/scripts/newlayout
joe newlayout
#change editor to joe, save and exit.
./newlayout "layoutname" author "theme"

It opens four new, empty files

• ~/dw/bin/upgrading/s2layers/layout/layout.s2
• ~/dw/bin/upgrading/s2layers/layout/themes.s2
• ~/dw/cgi-bin/LJ/S2Theme/layout.pm
• ~/dw/bin/upgrading/s2layers/layout/../../s2layers.dat

and ~/dw/cgi-bin/LJ/S2Theme/../S2Theme.pm in joe.

[afuna]

Hmm. Okay, I'll take a look when I get home later.

[zvi]

Just to be on the safe side ... there is no signficance to the fact that one input is layoutname and all of the file names are layout. It's entirely up to me mapping what I did and the file names on two separate runs of the script.

[afuna]

Okay, I think I got it fixed now! Download it and try again, please?

[zvi]

It's all prefilled now! V. cool. Thank you.

[afuna]

\o/

[ninetydegrees]

Newbie question: is it ok to make several patches for the same files? For example let's say person X is adding a theme for layout Y and person Z is adding a theme for the same layout, there's no conflict?

OT: Did you get my PM about bug 1818? You sent me two messages and I answered them both but you only replied to one of them.

[afuna]

It depends! If you're touching the same area in the same file -- e.g., if the themes are close to each other alphabetically, then there's a likely chance of conflict. If you're touching different areas, then it likely won't cause a problem.

The quickest way around it is for us to be quick about committing stuff, before the patches start stepping on each other :x

(Yup, I got it, but I meant to look something up before replying. I should go do so now!)

[ninetydegrees]

Got it! BTW, I think your "enter bug" template (script?) doesn't have any keywords. I'm mentioning it because I find searching style-related minor bugs quite easier and faster when they have the effort-minor and why-styles keywords. /2 cents

Good then. Thanks.

[afuna]

Hmm. I *think* I did that deliberately, so that it would show up on D's search for bugs with no keywords, and she could keyword it appropriately (she does a keyword tagging run at intervals).

Another question

[ninetydegrees]

Should I wait if the first patch has been reviewed and committed but isn't live? My local files are patched so I though it wouldn't cause any problem but I really don't know. :)

Re: Another question

[afuna]

Nope! The repository doesn't know whether the code is live on DW or not , so just make sure your repository is still updated to the latest code version, and you're good.

Re: Another question

[ninetydegrees]

\o/ Thanks again you bloody marvelous you!

Note re: newlayout script

[zvi]

The current version of the newlayout script marks the base layout as a featured layout instead of a base layout. Is this correct?

[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?