205 lines
12 KiB
XML
205 lines
12 KiB
XML
|
<chapter id='&s2.idroot;s2onlj'>
|
||
|
|
<title>Using S2 on LiveJournal</title>
|
||
|
|
<section id='&s2.idroot;s2onlj.resources'>
|
||
|
|
<title>Resources</title>
|
||
|
|
<para><variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><ulink url="&siteroot;/customize/">Customization area</ulink></term>
|
||
|
|
<listitem><simpara>Regular end-user destination to select layouts and corresponding themes with
|
||
|
|
pretty graphical previews, and graphical wizard to override text/colors.</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><ulink url="&siteroot;/customize/advanced/">Advanced area</ulink></term>
|
||
|
|
<listitem><simpara>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.
|
||
|
|
</simpara></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist></para>
|
||
|
|
</section>
|
||
|
|
<section id='&s2.idroot;s2onlj.layerguide'>
|
||
|
|
<title>Layer Guidelines</title>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>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!</para>
|
||
|
|
|
||
|
|
<section id='&s2.idroot;s2onlj.layerguide.design'>
|
||
|
|
<title>Guidelines For Layout Designers</title>
|
||
|
|
<para>When starting to design a layout, you should keep in mind the following points.</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Beware Copyright</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Design Flexibly</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
<para>Some particular things to bear in mind are:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><simpara>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?</simpara></listitem>
|
||
|
|
<listitem><simpara>Try to keep the <quote>global</quote> 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.</simpara></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Design for standard page elements</title>
|
||
|
|
<para>There are certain things which users expect to find in LiveJournal
|
||
|
|
styles. These include:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><simpara>Links from the archive calendar view to see the
|
||
|
|
month view for each month shown.</simpara></listitem>
|
||
|
|
<listitem><simpara>A way to easily obtain <quote>permalink</quote> 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.</simpara></listitem>
|
||
|
|
<listitem><simpara>Links on the Recent Entries and Friends views to
|
||
|
|
navigate to older entries and back to newer entries.</simpara></listitem>
|
||
|
|
<listitem><simpara>Links on a day page to view the previous and next day.</simpara></listitem>
|
||
|
|
<listitem><simpara>Links on the Archive calendar to view other years.</simpara></listitem>
|
||
|
|
<listitem><simpara>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.</simpara></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
</formalpara>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Design for Customization</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
<para>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.</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Design for Internationalization</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>Another thing to avoid is including text in images, as this is practically
|
||
|
|
impossible to translate flexibly.</para>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='&s2.idroot;s2onlj.layerguide.implementation'>
|
||
|
|
<title>Guidelines For Implementors</title>
|
||
|
|
<para>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.</para>
|
||
|
|
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Use Properties</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><simpara>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 <classname>Color</classname> class to lighten, darken,
|
||
|
|
invert or average.</simpara></listitem>
|
||
|
|
<listitem>
|
||
|
|
<simpara>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)</simpara>
|
||
|
|
<simpara>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.</simpara>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</listitem>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Let the System Help You</title>
|
||
|
|
<para>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.</para>
|
||
|
|
</formalpara>
|
||
|
|
<para>
|
||
|
|
The system also has several features to help layouts be expandable
|
||
|
|
without modifying a layout at all:
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><simpara>You can generate a list of views by iterating over
|
||
|
|
the <varname>views_order</varname> member of <classname>Page</classname>,
|
||
|
|
and if new top-level views are added in future, or if the URL to
|
||
|
|
one changes, your layout will automatically reflect the change.</simpara></listitem>
|
||
|
|
<listitem><simpara>The <quote>body</quote> 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.</simpara></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<formalpara>
|
||
|
|
<title>Text Abstraction</title>
|
||
|
|
<para>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 <quote>You are viewing the 10 most recent
|
||
|
|
entries</quote>.
|
||
|
|
</para>
|
||
|
|
</formalpara>
|
||
|
|
<para>Don't break up sentences when allowing sentences to be changed, as sentence
|
||
|
|
construction differs wildly between languages.</para>
|
||
|
|
<para>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.</para>
|
||
|
|
</listitem>
|
||
|
|
|
||
|
|
</itemizedlist>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</chapter>
|