zlax/ljr
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

init

Browse Source
This commit is contained in:
ivan
2019-02-06 00:49:12 +03:00
commit 8dbb1bb605
4796 changed files with 506072 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
livejournal/doc/raw/lj.book/customize/hooks.xml Executable file
View File

@@ -0,0 +1,65 @@
<chapter id="lj.customize.hooks">
<title>Setting Site-Specific Hooks</title>
<abstract>
<para>
The LiveJournal code provides a number of hooks, which you can use to
alter or extend the functionality of the code, tailored for your own site.
You're free to implement as few or as many as you want.
<tip><para>
If there's a hook you want but don't see, email us at <email>dev@livejournal.com</email>
or file an issue in our
<ulink url="http://zilla.livejournal.org">Bug and Project Tracking System</ulink>
and we'll be more than happy to add it in.
</para></tip>
</para>
<para>
One of the reasons for implementing hooks on LiveJournal came from a
need to make distinctions between account status types, without leaving
a lot of kludge in the code base, and without having to write extensive
code libraries in the ljcom <abbrev>CVS</abbrev> repository.
</para>
<para>
Hooks are code references, subroutines that perform functions or return information
based on objects passed to the subroutine. Some programming knowledge is necessary
to write your own hooks.
</para>
</abstract>
<section id="lj.customize.hooks.setup">
<title>Writing Hooks</title>
<para>
Hooks are written either in your <filename>cgi-bin/ljconfig.pl</filename> file, or in a seperate
site-specific library file. Hooks are defined by the function <function>LJ::register_hook()</function>,
which takes two arguments: the name of the hook, and the hook's perl coderef.
</para>
<para>
Most hook coderefs are passed a single hash of various objects as their argument, though there are a few
exceptions. Consult <xref linkend="lj.customize.hooks.ref" /> for more information.
</para>
<example>
<title>Sample hook: userinfo_html_by_user</title>
<simpara>
To give you an idea of how a hook is set up, a smaller hook is sampled below:
</simpara>
<programlisting><![CDATA[LJ::register_hook("userinfo_html_by_user", sub {
my $o = shift;
my $r = $o->{'ret'};
my $u = $o->{'u'};
return unless (LJ::get_cap($u, "normal"));
$$r .= "<img src='$LJ::IMGPREFIX/talk/sm08_star.gif' width='20' height='18' alt='&#8902;' style='vertical-align: middle; border: 0;' />";
});]]></programlisting>
<simpara>
<varname>$o</varname> is the argument hash that is passed to the hook's subroutine,
and consists of the scalar reference member <varname>$o->{'r'}</varname> and the user object
member <varname>$o->{'u'}</varname>. The subroutine then checks to see if the user
is part of the capability class <quote>normal</quote>, and if so it will pass the
<abbrev>HTML</abbrev> image directive as the scalar reference. Now when someone loads
a user information page for a <quote>normal</quote> user, a small star will appear
next to their username and userid.
</simpara>
</example>
</section>
<section id="lj.customize.hooks.ref">
<title>Hooks Reference</title>
&lj.customize.hooks.ref;
</section>
</chapter>

18
livejournal/doc/raw/lj.book/customize/images.xml Executable file
View File

@@ -0,0 +1,18 @@
<chapter id="lj.customize.images">
<!-- (FIXME - detail the use of imageconf.pl) -->
<title>Using your own images and icons</title>
<section id="lj.customize.images.imageconf">
<title>Using <filename>imageconf.pl</filename></title>
<para>
LiveJournal uses a standard set of icons for specific pages that are distributed through the <filename role="dir">/img</filename> directory, and handles the configuration for these images in the file: <filename>cgi-bin/imageconf.pl</filename>.
Each image is configured as an associative array in perl, setup with attributes for each file.
(FIXME - this needs a lot of work.)
</para>
<para>
<literal>cgi-bin/imageconf.pl</literal> is provided. Don't
change that. But go ahead and add a new file,
<literal>imageconf-local.txt</literal> beside it in the same
format, which <literal>imageconf.pl</literal> will find and use.
</para>
</section>
</chapter>

40
livejournal/doc/raw/lj.book/customize/index.xml Executable file
View File

@@ -0,0 +1,40 @@
<part id="lj.customize.index">
<title>Customizing Your Installation</title>
<partintro>
<para>
Unless you're helping on the LiveJournal development team,
you're probably running the LiveJournal Server for your own
purposes and will want to customize its appearance, behavior,
limits, and other settings to suit your needs. The next couple
of chapters have been written with that aim in mind.
</para>
<para>
More importantly, however, the following sections tell you how
to customize the installation in the supported way. Although
you're welcome to just hack random parts up until it's working
how you want it too, you'll run into trouble later when you try
to stay in sync with the latest LiveJournal code.
</para>
<para>
By following these instructions, your life will be much easier,
as all our tools assume you are doing things this way. If you
end up not being able to change something, post in the
lj_everywhere community on LiveJournal.com and ask for help.
We'll either tell you the right way to do it, or add hooks/options
such that you can.
</para>
</partintro>
&lj.customize.local_cvs;
&lj.customize.images;
&lj.customize.text;
&lj.customize.limits;
&lj.customize.hooks;
&lj.customize.layout;
&lj.customize.tasks;
</part>
<!--
Local Variables:
mode:sgml
sgml-parent-document: ("../index.xml" "book" "part")
End:
-->

206
livejournal/doc/raw/lj.book/customize/layout.xml Executable file
View File

@@ -0,0 +1,206 @@
<chapter id="lj.customize.layout">
<title><abbrev>BML</abbrev> Schemes</title>
<subtitle>Changing your site's layout</subtitle>
<para>
<abbrev>BML</abbrev> is the language used to serve pages to users that they don't manage
themselves. To get an idea of what <abbrev>BML</abbrev>is, the following is a quote from the
<abbrev>BML</abbrev> manual:
<blockquote>
<attribution><citetitle pubwork="book">The Better Markup Language</citetitle></attribution>
<simpara>
<abbrev>BML</abbrev> is a server-side markup language that lets you define your own
<abbrev>BML</abbrev> blocks and use them as templates within your <abbrev>BML</abbrev>
pages. Your templates don't even have to be static. Because <abbrev>BML</abbrev> pages are
converted to <abbrev>HTML</abbrev> on the server when users request them, this also enables
you to embed live code within your <abbrev>BML</abbrev> pages, just like a
<abbrev>CGI</abbrev> script.
</simpara>
</blockquote>
</para><para>
With LiveJournal, we used <abbrev>BML</abbrev> because it makes it easier for us to write the
layouts that comprise LiveJournal, without requiring frequent changes or rewrites on our part
to come up with a customized look and feel. In the next section you will read how to make the
necessary additions to the LiveJournal schemes to tailor your LiveJournal installation to your
exact needs.
</para>
<para>For more information on <abbrev>BML</abbrev>, please refer to <xref linkend="bml.index" />.</para>
<section id="lj.customize.layout.new">
<title>Writing a <abbrev>BML</abbrev> Scheme</title>
<para>
<abbrev>BML</abbrev> is essentially a simple macro language. Macros are called
<wordasword>templates</wordasword> in <abbrev>BML</abbrev>. Templates are defined in
<wordasword>lookup</wordasword> files and are <wordasword>invoked</wordasword> in
<abbrev>BML</abbrev> files. Templates accept parameters and are divided into several types
according to how parameters are transmitted and how the definition of the template is able to make
use of them. Definitions of templates are essentially chunks of <abbrev>HTML</abbrev> with
potentially more recursive <abbrev>BML</abbrev> template invocations inside them.
</para><para>
For LiveJournal, the most common templates are defined in the file
<filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/global.look</filename>; all other
<wordasword>schemes</wordasword> either replace all of the templates, or inherit whichever
is not replaced.
</para><para>
To write your own scheme, all you have to do is write your own <abbrev>BML</abbrev>
lookup file that use the same templates as <filename><envar>$LJHOME</envar>/cgi-bin/bml/global.look</filename>.
Then, implementing a new scheme becomes pretty painless:
<procedure><title>Creating a new <abbrev>BML</abbrev> scheme: <replaceable>foo</replaceable>:</title>
<step><simpara>
Create a new file under <filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme</filename>, labelled
after the scheme name (<replaceable>foo</replaceable>). For example:
<filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/<replaceable>foo</replaceable>.look</filename>.
This file should contain all of the <abbrev>BML</abbrev> directives you've written for your unique layout.
The first line in this file should be <programlisting>_parent=&gt;global.look</programlisting>.
</simpara></step>
<step><para>
If you don't have a local <abbrev>BML</abbrev> configuration file (<filename>_config-local.bml</filename>)
in your <filename><envar>$LJHOME</envar>/htdocs/</filename> directory, you should create one now.
The contents of that file should look like:
<example>
<title>Sample <filename>_config-local.bml</filename></title>
<programlisting>DefaultScheme <replaceable>foo</replaceable></programlisting>
</example>
</para></step>
<step><simpara>
Manually restart the apache process.
</simpara></step>
</procedure>
</para><para>
After you've written your scheme, consider adding it to the array in <xref linkend="ljconfig.schemes" />, so that
your users can use their preferred scheme.
</para>
</section>
<section id="lj.customize.layout.ref">
<title><abbrev>BML</abbrev> Template Reference</title>
<para>For reference, here are the most commonly used BML templates in the LiveJournal repository:</para>
<itemizedlist>
<title>Pre-configured</title>
<para>The following are BML templates that are set from configuration options in <filename><envar>$LJHOME</envar>/cgi-bin/ljconfig.pl</filename>.
All templates here are defined as <quote>S</quote> (static).</para>
<listitem><link linkend="ljconfig.domain">DOMAIN</link></listitem>
<listitem><link linkend="ljconfig.imgprefix">IMGPREFIX</link></listitem>
<listitem><link linkend="ljconfig.statprefix">STATPREFIX</link></listitem>
<listitem><link linkend="ljconfig.siteroot">SITEROOT</link></listitem>
<listitem><link linkend="ljconfig.sitename">SITENAME</link></listitem>
<listitem><link linkend="ljconfig.admin_email">ADMIN_EMAIL</link></listitem>
<listitem><link linkend="ljconfig.support_email">SUPPORT_EMAIL</link></listitem>
</itemizedlist>
<para>The following BML templates are defined in <filename><envar>$LJHOME</envar>/cgi-bin/bml/scheme/global.look</filename>
and are available in every scheme.</para>
<variablelist>
<title>Global</title>
<varlistentry>
<term>SECURITYPRIVATE</term>
<listitem><simpara>HTML image sourcing from <filename>/img/icon_private.gif</filename></simpara></listitem>
</varlistentry>
<varlistentry>
<term>SECURITYPROTECTED</term>
<listitem><simpara>HTML image sourcing from <filename>/img/icon_protected.gif</filename></simpara></listitem>
</varlistentry>
<varlistentry>
<term>LJUSER</term>
<listitem><simpara>Given a username, it creates a properly formated LiveJournal username reference</simpara></listitem>
</varlistentry>
<varlistentry>
<term>LJCOMM</term>
<listitem><simpara>Given a community username, it creates a properly formatted LiveJournal community username reference</simpara></listitem>
</varlistentry>
<varlistentry>
<term>LJUSERF</term>
<listitem><simpara>Same as LJUSER, except that the link to the userinfo page includes the additional user information</simpara></listitem>
</varlistentry>
<varlistentry>
<term>HELP</term>
<listitem><simpara>Given a URL, this provides a small link with the caption <quote>help</quote></simpara></listitem>
</varlistentry>
<varlistentry>
<term>INERR</term>
<listitem><simpara>Displays an error message in an easily identifiable manner (bold red text)</simpara></listitem>
</varlistentry>
<varlistentry>
<term>NEEDLOGIN</term>
<listitem><simpara>A small blurb that's included on pages where the user is not logged in and is required to be</simpara></listitem>
</varlistentry>
<varlistentry>
<term>BADINPUT</term>
<listitem><simpara>An error message that displays when there is an encoding problem with the user's browser</simpara></listitem>
</varlistentry>
<varlistentry>
<term>REQUIREPOST</term>
<listitem><simpara>An error message explaining that certain user actions require POSTing information through an HTML form, rather than manually GETting the page</simpara></listitem>
</varlistentry>
<varlistentry>
<term>LOAD_PAGE_INFO</term>
<listitem><simpara>Initializes and populates a perl array that is used to create a sidebar of links along a page layout</simpara></listitem>
</varlistentry>
<varlistentry>
<term>H1</term>
<listitem><simpara>Top level header on a page</simpara></listitem>
</varlistentry>
<varlistentry>
<term>H2</term>
<listitem><simpara>Sub level header on a page</simpara></listitem>
</varlistentry>
<varlistentry>
<term>P</term>
<listitem><simpara>Generic HTML paragraph wrapper</simpara></listitem>
</varlistentry>
<varlistentry>
<term>STANDOUT</term>
<listitem><simpara>Given a block of text, this template tries grab the user's attention by using different text and background colors</simpara></listitem>
</varlistentry>
<varlistentry>
<term>BADCONTENT</term>
<listitem><simpara>An error message that displays when a problem (that the user can fix) has occurred during a request</simpara></listitem>
</varlistentry>
<varlistentry>
<term>DE</term>
<listitem><simpara>A template that de-emphasizes text</simpara></listitem>
</varlistentry>
<varlistentry>
<term>EMCOLOR</term><term>EMCOLORLITE</term><term>HOTCOLOR</term>
<listitem><simpara>Various emphasis colors</simpara></listitem>
</varlistentry>
<varlistentry>
<term>SCREENEDBARCOLOR</term>
<listitem><simpara>A color that is used to highlight screened comments in comment threads</simpara></listitem>
</varlistentry>
<varlistentry>
<term>CHOICE</term>
<listitem><simpara>Given 3 arguments (a URL, a title, and an explanatory blurb), this template fashions an item to be used in a CHOICES list</simpara></listitem>
</varlistentry>
<varlistentry>
<term>CHOICES</term>
<listitem><simpara>Given 2 arguments, this template tries to construct a side by side list of options and appropriate links</simpara></listitem>
</varlistentry>
<varlistentry>
<term>PAGE</term>
<listitem><simpara>This template is the BML template that governs the look of the entire scheme, and takes 4 arguments:
<variablelist>
<varlistentry>
<term>title</term>
<listitem><simpara>The page title</simpara></listitem>
</varlistentry>
<varlistentry>
<term>head</term>
<listitem><simpara>Page-specific elements that belong in a HTML head</simpara></listitem>
</varlistentry>
<varlistentry>
<term>bodyopts</term>
<listitem><simpara>Additional attributes for the HTML body element</simpara></listitem>
</varlistentry>
<varlistentry>
<term>body</term>
<listitem><simpara>The main content of the page</simpara></listitem>
</varlistentry>
</variablelist>
</simpara></listitem>
</varlistentry>
</variablelist>
</section>
</chapter>
<!--
Local Variables:
mode:sgml
sgml-parent-document: ("index.xml" "part" "chapter")
End:
-->

6
livejournal/doc/raw/lj.book/customize/limits.xml Executable file
View File

@@ -0,0 +1,6 @@
<chapter id="lj.customize.limits">
<title>Setting your own Limits</title>
<para>
(FIXME - discuss the necessity of setting good connection/throttle settings)
</para>
</chapter>

82
livejournal/doc/raw/lj.book/customize/local_cvs.xml Executable file
View File

@@ -0,0 +1,82 @@
<chapter id="lj.customize.local_cvs">
<title>Using your own <abbrev>CVS</abbrev> directory</title>
<para>
CVS is a version control system for source code. We don't care
whether or not you actually use it to control your site-local
modifications. However, even if you don't, it's still important
you put your modifications under a directory in <filename><envar>$LJHOME</envar>/cvs</filename>.
</para>
<para>
At this point, <link linkend='lj.install.install_files'>you already have</link> a directory named
<filename>cvs</filename> underneath your <envar><link linkend='lj.install.ljhome'>$LJHOME</link></envar>
directory. Further, that directory already has under it a directory called <filename>livejournal</filename>,
which holds the <quote>general</quote> files.
</para>
<para>
What you want to do now is make a directory that holds the
<quote>local</quote> files. The LiveJournal tools look for your
files in a directory beside <filename>livejournal</filename> named
<filename>local</filename>, but <filename>local</filename> can
actually be a symlink to your real directory.
<footnote>
<para>LiveJournal.com uses the directory name
<filename>ljcom</filename> for its site-local modifications, so
the <filename>livejournal</filename> directory is entirely free
of LiveJournal.com-specific code. If you're helping with
LiveJournal.com development, you'll want to symlink ljcom to
local.</para>
</footnote>
</para>
<section id='lj.customize.local_cvs.cvsreport'>
<title><application>cvsreport.pl</application>: Adding &amp; Overlaying</title>
<para>
In <filename><envar>$LJHOME</envar>/bin</filename> there's a tool named
<application>cvsreport.pl</application> which manages (among other
things) merging together the general files and your site-local
files into the live area under <envar>$LJHOME</envar>.
</para>
<para>
The command you'll need most of the time is:
<screen><prompt>$</prompt> <userinput>cvsreport.pl -c -s</userinput></screen>
<parameter>-c</parameter> is short for <parameter>--cvsonly</parameter>
(only copies from the <filename>cvs</filename> directory back to the live area, not
vice-versa) and <parameter>-s</parameter> is short for <parameter>--sync</parameter>
(which means actually do the copying, don't just print out what it would've done,
which is the default without <parameter>-s</parameter>).
</para>
<para>
So, say you want to override the provided
<filename>htdocs/index.bml</filename> file. Create the
<filename>htdocs</filename> under
<filename>$LJHOME/cvs/local</filename> and put a
<filename>index.bml</filename> file in it, then run
<application>cvsreport.pl</application> <parameter>-c -s</parameter> and you're set.
</para>
<para>
More commonly, you'll be adding new files, rather than replacing
provided ones. In general, you should never really need to
replace files, since you should already be able to change all
the text, images, and layout of any given page. Replacing a
file would mean duplicating functionality, and that's bad.
</para>
<para>
One popular strategy with the general code libraries is to look
for a similarly named file with <filename>-local</filename> in it
and load that also. That way you inherit all the functionality
that's provided, and change only what you want. When general
changes, you don't have to update right away... you can change
things later if you want, or keep the newly added stuff as it
was given to you.
</para>
</section>
</chapter>
<!--
Local Variables:
mode:sgml
sgml-parent-document: ("index.xml" "part" "chapter")
End:
-->

12
livejournal/doc/raw/lj.book/customize/tasks.xml Executable file
View File

@@ -0,0 +1,12 @@
<chapter id="lj.customize.tasks">
<title>Running your own Maintanence Tasks</title>
<para>
(FIXME - describe the different tasks from ljmaint.pl, etc... note: build.pl should auto-extract the taskinfo.txt text and put it in here somewhere?)
</para>
<para>
<literal>bin/maint/taskinfo.txt</literal> is provided. Don't
change that. But go ahead and add a new file,
<literal>taskinfo-local.txt</literal> beside it in the same
format, which <literal>ljmaint.pl</literal> will find and use.
</para>
</chapter>

48
livejournal/doc/raw/lj.book/customize/text.xml Executable file
View File

@@ -0,0 +1,48 @@
<chapter id="lj.customize.text">
<title>Customizing <abbrev>LJ</abbrev>&apos;s Content</title>
<para>
(FIXME - describe the /translate/ system)
</para>
<section id="lj.customize.text.new">
<title>Using site-specific text</title>
<para>
To create your own site-specific language file, all you have to do is select which strings you'd like to override from
<filename><envar>$LJHOME</envar>/bin/upgrading/en.dat</filename> and put them in a new file: <filename>en_LOCAL.dat</filename>
Then, you add the language to your database using the steps below:
<procedure><title>Creating a new site-specific language file: <replaceable>en_LOCAL</replaceable>:</title>
<step><simpara>
Create a new file under <filename><envar>$LJHOME</envar>/bin/upgrading/</filename>, labelled
<filename>en_LOCAL.dat</filename>. This file should contain all of the text that you'd like to override from
<filename><envar>$LJHOME</envar>/bin/upgrading/en.dat</filename>.
</simpara></step>
<step><para>
If you don't have a local <abbrev>BML</abbrev> configuration file (<filename>_config-local.bml</filename>)
in your <filename><envar>$LJHOME</envar>/htdocs/</filename> directory, you should create one now.
Add the following line to your local configuration file:
<programlisting>DefaultLanguage en_LOCAL</programlisting>
</para></step>
<step><para>
If you don't have a local language directive file (<filename><envar>$LJHOME</envar>/bin/upgrading/text-local.dat</filename>)
create one now. Add the following lines to your local language file:
<programlisting># EnglishLOCAL is child of English for general domain:
lang:100:en_LOCAL:English (Local):sim:en
langdomain:en_LOCAL:general
# EnglishLOCAL is root of FAQ:
langdomain:en_LOCAL:faq:1</programlisting>
</para></step>
<step><simpara>
Run <command><filename><envar>$LJHOME</envar>/bin/upgrading/texttool.pl</filename> <option>load</option></command>.
</simpara></step>
</procedure>
</para>
</section>
</chapter>
<!--
Local Variables:
mode:sgml
sgml-parent-document: ("index.xml" "part" "chapter")
End:
-->