Hierarchy

From Dreamwidth Notes
Revision as of 05:27, 5 May 2009 by Seperis (Talk | contribs)

Jump to: navigation, search

In an ideal world, this would teach puppies to code their own dwj from scratch. This probably won't do that, but it should demystify what makes up the average dwj layout and the parts that make it up.

In the Beginning

There were punch cards and no one would ever need more than 512K of hard drive. That was before the web.

Core2 is a web programming language that includes CSS and HTML. It is not impossible to understand. It just looks that way when you open Core2 and wonder what all the color coding means.

There are three components to core2 styles that are pretty much impossible to separate, and trust me, for the purposes of saving my fingers, I tried: classes, properties, and functions.

Below are the tables of core2 functions associated with view. Each child is listed below and to the right of the parent.

Table of View-Related Functions

Page
TagsPage
MessagePage
RecentPage
FriendsPage
DayPage
YearPage
MonthPage
EntryPage
ReplyPage
MonthDay
YearWeek
Comment
CommentInfo
Entry

Functions

For the purposes of this explanation, Views refers to the actual pages that you use to read your DWJ, your Reading Page, Archive.

To get a complete explanation of a function, go the wikipedia route. Non-technically speaking, a function is a way to combine several properties together instead of listing them over and over.

There are three types of functions: simple functions, methods of a class, and builtin. Builtin, or call functions, are built into the backend and cannot be edited by the user.

[Replace this with an actual useful code.]

Example:

function print_words ()
{
enter things here
}

Breaking it down, I create a function I named print_words. Then I said, every time I call this function, I want everything I put in it to occur. Let's say that the things inside it are a command to turn text red, make it very large, and then make it appear on a particular page. Instead of writing out all those things, I just use print_words every time that is supposed to happen.

The things that appear inside the brackets are called a function definition. You are defining your function by telling it what things it is supposed to do.

Or maybe I want to do this.

[Replace this with an actual code.]

function run_things()
{
function_a();
function_b();
function_c();
}

This function is defined by three functions, or it contains three functions that will run every time I call it. I'd create one of these if there were several things that needed to run together and would do it frequently. Sure, I could just write all three functions every time, but instead, I shorten my workload by just putting in run_things(), which will run all three and save my fingers.

Now, core has those, called simple functions. Then there's these. These are called methods of a class.

Example:

    function Image::as_string(string{} opts) [fixed] : string

You'll notice that now there is a new part: the Image::. Image is a class. We now call this function a method of a class.

Methods of a class are functions that are declared in a class for the purposes of calling on class properties. Or, instead of just tossing the function out there, you get specific on what exactly goes inside it. In this case, the function as_string() is being called in the class known as Image, and it is limited to using properties and functions that were defined in class Image. So when I wrote it out what it was supposed to do, or defined it, it would have functions and properties that appear only in the class Image.

Page View

Class Page and its associated functions are the center of core2 design. Changes to anything in a Class Page function affects all views unless they are edited separately.

The following will define the functions that make up the meat of your DW: the Page::print function that controls the layout of your journal, and the Page::print_entry(Entry e) that controls the look of each individual entry, with a breakdown of the functions they were created from.

Page View: The Layout

This is the layout of your entire dw journal. This is how the stucture is decided, columns created, and worlds destroyed.

    function Page::print()
    {
    """<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n
    <head profile="http://www.w3.org/2006/03/hcard http://purl.org/uF/hAtom/0.1/ http://gmpg.org/xfn/11">\n""";
    $this->print_head();
    $this->print_stylesheets();
    $this->print_head_title();
    """</head>""";
    $this->print_wrapper_start();
    $this->print_control_strip();
    """<div id="canvas">
    <div class="inner">
    <div id="header">
    <div class="inner">""";
    $this->print_global_title();
    $this->print_global_subtitle();
    $this->print_title();
    """</div><!-- end header>inner -->
            </div><!-- end header -->
            <div id="content">
                <div class="inner">
                    <div id="primary"><div class="inner">
                        """; 
                        $this->print_body();
    """</div></div><!-- end primary and primary>inner -->
                    <div id="secondary"><div class="inner">""";
                        $this->print_module_section("one");
    """</div></div><!--  end secondary and secondary>inner -->
                    <div id="tertiary"><div class="inner">""";
                        $this->print_module_section("two");
    """</div></div><!-- end tertiary and tertiary>inner -->
                </div><!-- end content>inner -->
            </div> <!-- end content -->
        </div> <!-- end canvas>inner -->""";
 
    """<div id="footer">
        <div class="inner">""";
       print safe """<div class="page-top"><a href="#">$*text_page_top</a></div>
        </div><!-- end footer>inner -->
    </div><!-- end footer -->
    </div> <!-- end canvas -->""";
    $this->print_wrapper_end();
    """</html>""";
    }

Breakdown

The following is a list and definition of all functions that can be used in the above, split by type and location.

Head Functions

The head-related functions are the first that are called on in function Page::print(). The first function combines two options: to print the default head, or to call on a custom head you write yourself.

function Page::print_head() 
{
    print $.head_content;
    $this->print_custom_head();
}
function Page::print_custom_head() 
{
    # blank
}
 
<source lang="perl">
function Page::print_linklist() 
{
    if (size $.linklist <= 0) 
    {
        return;
    } 
    elseif (not $*linklist_support) 
    {
        return;
    }
    foreach var UserLink l ($.linklist) {
        if ($l.title) 
        {
            if ($l.is_heading) 
            {
                "<b>$l.title</b>";
            } 
            else 
            {
                "<a href='$l.url'>$l.title</a>";
            }
        }
        "<br />";
    }
}


CSS Functions

This function in Page::print() calls the functions that control your stylesheet.

The first function calls on the default stylesheet for your style when you do not want to customize it.

    function Page::print_default_stylesheet()
    {
    """<style type="text/css">""";
    start_css();
    end_css();
    """</style>\n""";
    }

This function gives the user a choice to use an external stylesheet or custom css added to the existing default stylesheet.

    function Page::print_stylesheets()
    {
    if ($*include_default_stylesheet) {
        $this->print_default_stylesheet();
        if ($*external_stylesheet) {
            println safe """<link rel="stylesheet" href="$.stylesheet_url" type="text/css" />""";
        }
        else {
            println """<style type="text/css">""";
            start_css();
            print_stylesheet();
            end_css();
            println """</style>""";
        }
    }
 
    if ($*linked_stylesheet != "") {
        println safe """<link rel="stylesheet" href="$*linked_stylesheet" type="text/css" />""";
    }
 
    if ($*custom_css != "") {
        println """<style type="text/css">""";
        start_css();
        println safe $*custom_css;
        end_css();
        println """</style>""";
    }
    }
Title Functions

The third function in Layout refers to the title of the current view, such as Reading page, Recent Entries, and Year.

function Page::print_title() 
{
    print """<h2 id="pagetitle"><span>""" + $this->view_title() + """</span></h2>\n""";
}

This prints the Journal's title on the page.

function Page::print_head_title() 
{
    if ($this.journal.journal_type == "I") {
        print """<title>""" + $this.journal.name + $*text_default_separator + $this->view_title() + """</title>\n""";
    }
    else {
        print """<title>""" + $this.journal.username + $*text_default_separator + $this->view_title() + """</title>\n""";
    }
}

Add documentation here.

function Page::view_title() [notags] : string {
    return lang_viewname($.view);
}
function Page::print_global_title() {
    if ($.global_title) {
        """<h1 id="title"><span>""" + $.global_title + """</span></h1>""";
    }
}
function Page::print_global_subtitle() {
    if ($.global_subtitle) {
        """<h2 id="subtitle"><span>""" + $.global_subtitle + """</span></h2>""";
    }
}
function Page::view_title() [notags] : string {
    return lang_viewname($.view);
}
function Page::title() [notags] : string {
    return $this->view_title();
}
Wrapper Functions
    function Page::print_wrapper_start() 
    {
    $this->print_wrapper_start( { "" => "" } );
    }
    function Page::print_wrapper_start(string{} opts) 
    {
 
    var string class = $opts{"class"} ? """class="$opts{"class"}" """ : "";
    """<body class="page-$.view $*layout_type $class">\n""";
    }

"This function concludes the wrapper to the page. Overriding this function is NOT RECOMMENDED. Overriding this function could prevent sitewide improvements to styles, accessibility, or other functionality from operating in your layout."

    function Page::print_wrapper_end() 
    {
    """</body>""";
    }



<source lang="perl">
   function Page::print_body() {
    """<h2>No Default Renderer</h2><p>There is no body renderer for viewtype <tt>$.view</tt> defined.</p>""";
}
    function Page::print_module_section ( string section_name ) 
{
    """<div class="module-wrapper"><div class="separator separator-before"><div class="inner"></div></div>\n<div class="module-section-$section_name">\n<div class="inner">""";
    handle_module_group_array( $*module_sections{$section_name} );
    """</div>\n</div><div class="separator separator-after"><div class="inner"></div></div>\n</div>""";
    }
Date Functions
    function Page::print_time() {
    $this->print_time("","");
    }
 
    function Page::print_time(string datefmt, string timefmt) {
    if ($datefmt == "") {
        $datefmt = "med";
    }
    if ($timefmt == "") {
        $timefmt = "short";
    }
    var string ret;
    if ($datefmt != "none") { $ret = $ret + $this.local_time->date_format($datefmt); }
    if ($datefmt != "none" and $timefmt != "none") { $ret = $ret + " "; }
    if ($timefmt != "none") { $ret = $ret + $this.local_time->time_format($timefmt); }
 
    print safe """<span id="load-time">$*text_generated_on $ret</span>""";
    }
Page Navigation Function
    function Page::print_navigation() {}

Page view: the Entry

This is the function that gives structure and shape to your individual entries and forms the basis of the page you see when you click on Reply, when you click on Comment, or when the individual entry is directly linked to.

    function Page::print_entry(Entry e) 
    {
    $e->print_wrapper_start();
    """<div class="header">\n""";
    $e->print_subject();
    $e->print_metatypes();
    $e->print_time();
    """</div>\n""";
    """<div>\n""";
    """<div class="contents">\n""";
    """<div class="inner">\n""";
    $e->print_userpic();
    $e->print_poster();
    $e->print_text();
    $e->print_metadata();
    """</div>\n""";
    """</div>\n""";
    """</div>\n""";
    """<div class="footer">\n""";
    """<div class="inner">\n""";
    $e->print_tags();
    $e->print_management_links();
    if ($this isa EntryPage) {
        """<hr class="above-entry-interaction-links" />""";
        $e->print_interaction_links("topcomment");
        $this->print_reply_container({ "target" => "topcomment" });
        """<hr class="below-reply-container" />""";
    }
    else {
        $e->print_interaction_links();
    }
    "</div>\n</div>\n";
    $e->print_wrapper_end();
}

The Breakdown