# Using S2 on LiveJournal

## Resources

Customization area

  Regular end-user destination to select layouts and corresponding themes with pretty graphical previews, and graphical wizard to override text/colors.

Advanced area

  Create styles & layers. View the S2 source and documentation page of any public layer, notably the core layer and all the classes, functions and properties it provides.

## Layer Guidelines

This section is a list of suggestions for making good layers for LiveJournal, and also forms the requirements for creating layers to be offered as standard by LiveJournal. You should read this if you're designing a LiveJournal layout, or if you're writing the code to implement a layout designed by someone else, or if you're just interested.

It seems that most people start creation of a layout by creating a static HTML mockup of roughly what the layout will include. With this in mind, the guide is separated into two parts, the first for those creating a design, and the second for those who are implementing a design in S2 code. You might, of course, be both!

### Guidelines For Layout Designers

When starting to design a layout, you should keep in mind the following points.

- #### Beware Copyright

  Practically everything creative is copyrighted, from images to site designs to program code. If you copy or clone someone else's design or HTML, or use an image created by someone else, you may find yourself in a copyright lawsuit. Also, any style which is to be part of the LiveJournal system must be distributable under the GNU General Public Licence (GPL) under which the LiveJournal source distribution is licenced. The easiest way to keep to this is to only use your own work in creating a layer.

- #### Design Flexibly

  S2 is designed to be extensible, and if you think about extensibility early on your will make it much easier to adapt to suit additions to LiveJournal later on.

  Some particular things to bear in mind are:

  - Try to allow for new view types to be added in future. If you've got a list of views (Recent Entries, Friends etc) then will it be easy to add more views to it later on without breaking the design?

  - Try to keep the global HTML distinct from the view-specific HTML. That is, decide what is part of the recent view and what will be present on all views. Try to avoid the view-specific HTML depending on the global HTML if you can.

- #### Design for standard page elements

  There are certain things which users expect to find in LiveJournal styles. These include:

  - Links from the archive calendar view to see the month view for each month shown.

  - A way to easily obtain permalink for each entry which can be used to link to the entry. The S2 system will provide the URL for this, but you need to decide where to put it.

  - Links on the Recent Entries and Friends views to navigate to older entries and back to newer entries.

  - Links on a day page to view the previous and next day.

  - Links on the Archive calendar to view other years.

  - Titles and subtitles. The system allows the user to give their journal a title and a subtitle, as well as a special title for their friends view. You should display at least the main titles as headings, and try to include the subtitle at least on the Recent Entries view.

- #### Design for Customization

  As you are creating your design, try to think of things that users might want to customize. Colors are the easiest to think of, but you could also provide options for margin sizes, the position of navigation bars and chosing classes of fonts.

  A gotcha with customization is that it can make it hard to incorporate images into a style, since colors and alignments can change. If you are writing a potential system layout, the system can provide dynamic image color changes for your style in certain cases, but try to avoid this if you can.

- #### Design for Internationalization

  If you are designing a layout you should try to allow for the text in your layout to be translated. A lot of commonly-used text is already provided by the system translated, and it will be a lot easier to make your style multi-lingual if you make use of the standard text.

  One example is comment links on entries. The system provides functions to create the comment links with text set in an internationalization layer, including the correct pluralization for the comment count. If you design such that any text could be used in your comment links (and anywhere else where text appears, for that matter) your layout will be easily translatable.

  Another thing to avoid is including text in images, as this is practically impossible to translate flexibly.

### Guidelines For Implementors

If you are a programmer writing the S2 code for an S2 layout (or, to a lesser extent, some other layer) then this section is for you.

- #### Use Properties

  If you expose properties from your layout, the end-user will be able to customize these properties from a web-based GUI interface. In general, the more of these you have the better, but don't go overboard.

  - Colors are the main customizable feature of most layouts. Try to allow the user to change the color of all major page elements, but also dynamically generate similar colors based on user-supplied properties using the methods of the `Color` class to lighten, darken, invert or average.

  - Font selection is supported by the core layer, but you'll have to explicitly state that you wish to expose these properties in your layout. (See documentation on properties)

    The core layer provides options to select a primary font family as well as a fallback CSS generic font family, and one or both of these can be ommitted. You should generate a sensible CSS font-family property rule or equivalent FONT FACE value from these two properties.

- #### Let the System Help You

  The core layer has lots of useful default implementations of various page features. For example, it can generate links to users and form page titles and subtitles from the relevant user settings and translation properties. Using these defaults can save you a lot of work.

  The system also has several features to help layouts be expandable without modifying a layout at all:

  - You can generate a list of views by iterating over the `views_order` member of `Page`, and if new top-level views are added in future, or if the URL to one changes, your layout will automatically reflect the change.

  - The body of each view is separated from the navigation and layout around it, so that if you make sure you separate the view-specific code from the global code, new views can be added in future and the default HTML generated by the core layer will be used until the layout is revised to provide customized output.

- #### Text Abstraction

  All text in a layout should be easily overridable either by properties or by functions. Functions are required when text includes a number which affects the grammar of a sentence, such You are viewing the 10 most recent entries.

  Don't break up sentences when allowing sentences to be changed, as sentence construction differs wildly between languages.

  Finally, check to see if the text you need is already provided by a function in the core layer, as this will not only save you effort, but also save the effort of anyone who tries to create internationalization layers for your layout. The core layer provides functions and properties which are useful in practically all layouts, including text for comment links and view names.