Difference between revisions of "Newbie Guide for People Patching Styles"

From Dreamwidth Notes
Redirect page
Jump to: navigation, search
(theme credited with new prop now + minor edit)
 
(65 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= How Do I File a New Bug? =
+
#REDIRECT [[Newbie_Guide:_How_to_Patch_Styles_and_Themes]]
 
+
* In Bugzilla, click on New. Select Dreamwidth Development. In Component, select Style System. Enter a Summary and a Description. Mention style and theme names in the summary if needed. If you're adding a style or a color theme, indicate style name, theme name(s), the name of the author and the Dreamscapes submission URL in the description.
+
 
+
* Click on Show Advanced Fields. Set Initial State to ASSIGNED and enter your Bugzilla e-mail address in Assign To.
+
 
+
 
+
= Where Are Style Files? =
+
 
+
* core2.s2 is in <code>~/dw/cs/dw-free/bin/upgrading/s2layers/</code>
+
 
+
* Theme and layout .s2 files are in <code>~/dw/cs/dw-free/bin/upgrading/s2layers/LAYERNAME/</code> or <code>~/dw/cs/dw-nonfree/bin/upgrading/s2layers/LAYERNAME/</code>
+
 
+
* .pm style files are in <code>~/dw/cvs/dw-free/cgi-bin/LJ/S2Theme/</code> or <code>~/dw/cs/dw-nonfree/bin/upgrading/s2layers/LAYERNAME/</code>
+
 
+
* S2Theme.pm is in <code>~/dw/cvs/dw-free/cgi-bin/LJ/</code>
+
 
+
* S2Theme_local.pm is in <code>~/dw/cvs/dw-nonfree/cgi-bin/LJ/</code>
+
 
+
* s2layers.dat is in <code>~/dw/cs/dw-free/bin/upgrading/</code>
+
 
+
* s2layers-local.dat is in <code>~/dw/cs/dw-nonfree/bin/upgrading/</code>
+
 
+
 
+
= Dw-free or dw-nonfree? =
+
 
+
* To be usable on the site, third party images must be obtained from a site which explicitly allows storage on one's own server, commercial use, and use in website templates, or you must have acquired a written permission from the image owner and include them in your [[CLA|Contributor Licensing Agreement]]. If this isn't the case, images must be replaced or removed from the style/theme.
+
 
+
* If the style is in dw-free, themes which contain images Dreamwidth can use but can't redistribute/sublicense go to dw-nonfree in local files.
+
 
+
* If the style is in dw-nonfree all its themes automatically go there as well. This the case for Transmogrified and Sunday Morning themes for example.
+
 
+
 
+
= Adding a New Style =
+
 
+
== Edit s2layers.dat ==
+
 
+
* If the style goes to dw-nonfree, edit <code>s2layers-local.dat</code> instead.
+
 
+
* If this is a new Core2 layout, add:
+
<syntaxhighlight lang="perl">
+
stylename/layout          layout          core2
+
stylename/themes          theme+          stylename/layout
+
</syntaxhighlight>
+
 
+
* If this is a child of Tabula Rasa, add:
+
<syntaxhighlight lang="perl">
+
stylename/layout          layout(core2base/layout)    core2
+
stylename/themes          theme+                      stylename/layout
+
</syntaxhighlight>
+
 
+
 
+
== Edit S2Theme.pm ==
+
 
+
* If the default theme goes to dw-nonfree, edit <code>S2Theme_local.pm</code> instead.
+
 
+
* Scroll down to <code>%default_themes</code> and add the style and default theme:
+
<syntaxhighlight lang="perl">
+
layoutname => 'stylename/defaulttheme',
+
</syntaxhighlight>
+
 
+
 
+
== Create LAYOUTNAME.pm  ==
+
 
+
* Create LAYOUTNAME.pm in <code>~/dw/cvs/dw-free/cgi-bin/LJ/S2Theme/</code> or <code>~/dw/cvs/dw-nonfree/cgi-bin/LJ/S2Theme/</code>.
+
 
+
* Add:
+
<syntaxhighlight lang="perl">
+
package LJ::S2Theme::layoutname;
+
use base qw( LJ::S2Theme );
+
use strict;
+
 
+
sub layouts { ( "1" => "one-column", "2l" => "two-columns-left", "2r" => "two-columns-right", "3" => "three-columns-sides", "3r" => "three-columns-right", "3l" => "three-columns-left" ) }
+
sub layout_prop { "layout_type" }
+
 
+
sub designer { "name" }
+
 
+
1;
+
</syntaxhighlight>
+
 
+
Remove layout options that don't apply to the style, of course.
+
 
+
 
+
== Create the LAYOUTNAME directory  ==
+
 
+
* Create a directory with the name of the style in <code>~/dw/cs/dw-free/bin/upgrading/s2layers/</code> or <code>~/dw/cs/dw-nonfree/bin/upgrading/s2layers/</code>.
+
 
+
 
+
== Create layout.s2  ==
+
 
+
* In the directory you've created, create a file named <code>layout.s2</code>. Add:
+
<syntaxhighlight lang="s2">
+
layerinfo type = "layout";
+
layerinfo name = "layoutname";
+
layerinfo redist_uniq = "layoutname/layout";
+
layerinfo author_name = "someuser";
+
layerinfo lang = "en";
+
 
+
set layout_authors = [ { "name" => "someuser", "type" => "user" } ];
+
</syntaxhighlight>
+
 
+
* If there are resources to credit, add them:
+
<syntaxhighlight lang="s2">
+
set layout_resources = [ { "name" => "Name", "url" => "http://URL" } ];
+
</syntaxhighlight>
+
 
+
* Add the style code.
+
 
+
* If the style has custom properties, they should be sorted into existing groups (presentation, colors, fonts, images, modules, text, other) by appending <code>_child</code> to the group name. For example:
+
<syntaxhighlight lang="s2">
+
propgroup images_child
+
    property string image_module_list { des = "Module list image"; }
+
</syntaxhighlight>
+
 
+
* If a module has more or fewer available positions than other modules, you can customize the sections it can be set to by using <code>_override</code>. For example:
+
<syntaxhighlight lang="s2">
+
    property string module_navlinks_section_override {
+
        values = "none|(none)|header|Header|one|Group One|two|Group Two";
+
        grouped = 1;
+
        }
+
 
+
set grouped_property_override = { "module_navlinks_section" => "module_navlinks_section_override" };
+
 
+
set module_navlinks_section = "header";
+
</syntaxhighlight>
+
 
+
: Of course, you need to make sure it's printed correctly when set to every position, possibly by editing <code>function Page::print() { }</code>.
+
 
+
 
+
== Check layout.s2  ==
+
 
+
* No tabs or trailing spaces.
+
 
+
* No empty properties (S2 or CSS).
+
 
+
* No hardcoded colors, fonts or text except shadows or <code>:before</code>/<code>:after</code> text/characters.
+
 
+
* No redundant code (S2 or CSS).
+
 
+
* Format CSS to be easily readable and editable. Selectors should be listed in the order they're displayed on the screen, divided into sections thanks to comments, properly indented and spaced out; properties should be listed alphabetically:
+
<syntaxhighlight lang="css">
+
    /*--- Entries & Comments ---*/
+
 
+
    .entry, .comment {
+
        margin: 2em .5em;
+
        padding: 2em;
+
        }
+
</syntaxhighlight>
+
 
+
* Remove leading zeros from decimals (.5em instead of 0.5em).
+
 
+
* Format CSS to use shorthand whenever possible:
+
<syntaxhighlight lang="css">
+
        border: 1px solid $*color_module_border;
+
        border-top: none;
+
        list-style: square inside url($*image_list_bullet);
+
        margin: 2em .5em 1em;
+
</syntaxhighlight>
+
 
+
instead of:
+
<syntaxhighlight lang="css">
+
        border-bottom: 1px solid $*color_module_border;
+
        border-left: 1px solid $*color_module_border;
+
        border-right: 1px solid $*color_module_border;
+
        list-style-image: url($*image_list_bullet);
+
        list-style-position: inside;
+
        list-style-type: square;
+
        margin-bottom: 1em;
+
        margin-left: .5em;
+
        margin-right: .5em;
+
        margin-top: 2em;
+
</syntaxhighlight>
+
 
+
* Group selectors whenever possible.
+
 
+
 
+
== Create themes.s2  ==
+
 
+
* In the directory you've created, create a file named <code>themes.s2</code>.
+
 
+
* If some themes go to dw-nonfree, create <code>themes-local.s2</code> in dw-nonfree as well.
+
 
+
* Follow the steps outlined in [[#Adding a New Color Theme|the next section]].
+
 
+
 
+
= Adding a New Color Theme =
+
 
+
 
+
== Edit themes.s2 ==
+
 
+
* If the theme goes to dw-nonfree, edit <code>themes-local.s2</code> instead.
+
 
+
* Make sure the color theme has the right header. As Afuna explained [http://dw-dev-training.dreamwidth.org/9656.html here] in <dwcomm>dw_dev_training</dwcomm>, it should look like this:
+
<syntaxhighlight lang="s2">
+
#NEWLAYER: layoutname/themename
+
layerinfo type = "theme";
+
layerinfo name = "Theme Name";
+
layerinfo redist_uniq = "layoutname/themename";
+
layerinfo author_name = "someuser";
+
</syntaxhighlight>
+
 
+
* If the color theme author is not the style author, add this this line below, separated by a blank line:
+
<syntaxhighlight lang="s2">
+
set theme_authors = [ { "name" => "someuser", "type" => "user" } ];
+
</syntaxhighlight>
+
 
+
* If there are resources to credit, add them:
+
<syntaxhighlight lang="s2">
+
set layout_resources = [ { "name" => "Name", "url" => "http://URL" } ];
+
</syntaxhighlight>
+
 
+
: If there were already resources credited in the style, don't forget to add them again.
+
 
+
* If the theme has any images, name them like this: <code>themename_imagename.xxx</code>. Keep the image name used in other themes if there are any.
+
 
+
: If there's only one image, give it the theme name: <code>themename.xxx</code>
+
 
+
: If the theme has generic images used in other themes, simply use <code>imagename.xxx</code>.
+
 
+
: In the theme, use <code>layoutname/themename_imagename.xxx</code>, <code>layoutname/themename.xxx</code> or <code>layoutname/imagename.xxx</code> as the URL.
+
 
+
* If you need to add theme-specific CSS, use:
+
<syntaxhighlight lang="s2">
+
function Page::print_theme_stylesheet() {
+
    """
+
    CSS HERE
+
    """;
+
}</syntaxhighlight>
+
 
+
* Make sure to add the theme code in the right place (themes should be alphabetically sorted).
+
 
+
 
+
== Check your theme file  ==
+
 
+
* No tabs or trailing spaces.
+
 
+
* No empty properties (S2 or CSS).
+
 
+
* No hardcoded colors in <code>print_theme_stylesheet()</code> if possible.
+
 
+
* Use shorthand for color codes whenever possible (#555 instead of #555555; #abc instead of #aabbcc).
+
 
+
* Sort properties into categories using these headers:
+
<syntaxhighlight lang="s2">
+
##===============================
+
## Page Colors
+
##===============================
+
</syntaxhighlight>
+
 
+
: Colors are sorted into three categories: Page Colors, Entry Colors and Module Colors.
+
 
+
: Other categories are Images and Fonts.
+
 
+
* Sort properties alphabetically into each category, but put generic properties before specific properties (e.g. color_page_background before color_header_background).
+
 
+
* Format CSS to be easily readable and editable: use indents and spaces, list properties alphabetically, use shorthand whenever possible.
+
 
+
* Each theme file must be separated by two blank lines. Leave one blank line after the last theme in the file.
+
 
+
* If you see another theme which needs editing, create a second patch/another bug for it.
+
 
+
 
+
== Edit LAYOUTNAME.pm ==
+
 
+
You must include the theme into the general style file. Otherwise, people wouldn't be able to select it at Customize.
+
 
+
* Find the correct place in the file so that themes stay alphabetically sorted.
+
 
+
* Add the following code:
+
<syntaxhighlight lang="perl">
+
package LJ::S2Theme::layoutname::themename;
+
use base qw( LJ::S2Theme::layoutname );
+
sub cats { qw() }
+
</syntaxhighlight>
+
 
+
* If the color theme author is not the style author, add this line:
+
<syntaxhighlight lang="perl">
+
sub designer { "someuser" }
+
</syntaxhighlight>
+
 
+
 
+
= On PuTTY =
+
 
+
* Type <code>hg addremove</code> if this patch adds or delete files then <code>hg refresh</code>.
+
 
+
 
+
= On your Dreamhack =
+
 
+
* Test, test and test. Make sure styles/themes are correctly listed in Customize and that names are correct. Make sure you can select the layouts working with your style. Make sure you can customize your style. On your test account, check colors on all pages for themes. For styles, make sure all types of layouts, all pages, all sorts of entries and comments display correctly and display correctly in various screen resolutions and font sizes. Also make sure community journals look fine.
+
 
+
* Make preview pictures if you can. Their size is 150x114 pixels. You may need to add/edit/remove entries, add/edit/remove modules, change screen resolution and font size so that your screen cap can be resized to this exact size.
+
 
+
 
+
= On Bugzilla =
+
 
+
* Don't forget to zip images and attach them to your bug if there are any. Also set them to review ? and commit ?
+
 
+
* If you can't do the preview pictures mention it so that someone can do them for you. You can also ask for help at <dwcomm>dreamscapes</dwcomm>.
+
 
+
[[Category:Development]]
+
[[Category:Styles]]
+
[[Category:Getting Started]]
+

Latest revision as of 16:31, 13 March 2013