Difference between revisions of "Hierarchy"

Revision as of 07:27, 5 May 2009

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 what exactly is going on in those lines and lines of code and why they're needed.

In the Beginning

There were punch cards and no one would ever need more than 512K of hard drive and there was no internet. Those were dark times. A lot has changed since then.

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.

Table of View-Related Functions

Below is the table of core2 functions associated that control what you see when you look at your journal. Each child is listed below and to the right of the parent.

[Might as well add classes in here as well.]

Page

TagsPage

MessagePage

RecentPage

FriendsPage

DayPage

YearPage

MonthPage

EntryPage

ReplyPage

MonthDay

YearWeek

Comment

CommentInfo

Entry

All About Functions

For the purposes of this explanation, Views refers to the actual pages that you use to read your DWJ, your Reading Page, or 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 or functions together instead of listing them over and over. In essence, it's a shortcut.

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

This page will cover the first two types.

Simple Functions

[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 'other' 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.

Methods of a Class

[Replace with a simpler code.]

Example:

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

You'll notice that now there is a new part appearing in the function. Image is a class. That is why we now call this function a 'method' of a class.

A 'methods of a class' is a function that is declared in a class.

Here is an example from core2 v2's source.

class Link
"A link or button"
{
    var readonly string url "URL which the link points to";
    var readonly string caption "The caption for the link";
    var Image icon
    "A suggestion from the server as to which icon to use. layouts/users can override this of course.
    alt text works similarly to [member[Link.caption]].";
 
    function print_button
    "Output this Link as a clickable button using [member[Link.icon]]";
 
    function as_string() : string
    "Return the button HTML link.";
}

You'll notice that there are a lot of things in class Link that are unfamiliar, Don't worry; you can safely ignore them. Skip down and notice the two functions. If you were to use function as_string() : string, then you would write it like this.

function Link::as_string() : string

Some functions are defined, or placed inside of, several different classes and may do slightly different things depending on what class they are in. In other words, function Link::as_string() : string may not do exactly the same thing as say, function MadeUpClass::as_string() : string.

[Okay, this explanation is going to need some work and actual examples.]

Page View

Now that the basic structure of a function and how it relates to class has been explained, we'll start with the meat of your dw journal and go from there. The following two functions are the base of your journal style. They are a mixture of functions, HTML, and CSS. They are terrifying, as they are huge and in many colors. But if you read through this, you know something else: they are, in the end, just a lot of simple functions sandwiched together.

Your journal Views are based primarily off of two separate functions: function Page::print() and function Page::print_entry(). First, I'm going to show you the function in all it's colorful glory. Then I'll break it down into its component functions and explain what they do and why.

Functions are always green. Those are what you want to look at.

This is Your Layout: The Page::print() Function

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.

HTML and CSS

The first thing you see is the standard html header for a webpage. If you are familiar with webpages, you know this appears on every webpage. It is basicallly declaring it is html, what program made it, and various declarations. Ignore this. You will not need to touch it.

This function has a lot of red text. That's the CSS code that gives pages their shape and tell the functions where to go. For now, ignore anything that's red while we explore the wild and wacky functions and what exactly they are doing.

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, which is what the second function does.

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. It contains two functions inside 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>""";
    }
}

You'll notice something new: if and else, along with more brackets. Don't panic. We'll do this line by line.

[Add explanation of if and else lines here.]

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

These functions are called wrappers. They are preset with a variety of functions and properties in them. Do not override these or try to change them.

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""";
}

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

Body

function Page::print_body() 
{
    """<h2>No Default Renderer</h2><p>There is no body renderer for viewtype <tt>$.view</tt> defined.</p>""";
}

Modules =

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>""";
}

This Is an Entry in Your Journal: The Page::print_entry() Function

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

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>""";
}

Subject

function print_subject () [fixed] "Print the formatted subject for this entry or comment";

function print_subject (string{} opts) [fixed] "Print the formatted subject for this entry or comment, gets hash of attributes - class and(or) style ";

Metatypes

Time

Userpic (Icon)

Poster (DW Username)

Text

Metadata

Entry Management Links

Entry Interaction Links

Reply Container

Conclusion

And that concludes Crazy About Pages. With just these two, you have successfully defined the look of your journal.

That is, if you want all the pages to have the same basic style. But what if you want every view to be a little different? What if ReplyPage should have a lime background and you want all your comments in salmon pink? What if you want your Recent Entries page to go in reverse order and your Reading Page to go in order of date?

That will take a little more work, but if you got through this, it'll be a snap.

@@ Line 83: / Line 83: @@
 You'll notice that now there is a new part appearing in the function. Image is a class.  That is why we now call this function a 'method' of a class.
-A 'methods of a class' is a function that is declared in a class for the purposes of calling on class properties.  Or, instead of just tossing any function I have into the function definition, I get specific.  In this case, the function 'as_string()' is being called in the class known as Image.  When a function is called by a class, that means it will be defined by properties and functions that are located 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.
+A 'methods of a class' is a function that is declared in a class.
+Here is an example from core2 v2's source.
+<source lang="perl">
+class Link
+"A link or button"
+{
+    var readonly string url "URL which the link points to";
+    var readonly string caption "The caption for the link";
+    var Image icon
+    "A suggestion from the server as to which icon to use. layouts/users can override this of course.
+    alt text works similarly to [member[Link.caption]].";
+    function print_button
+    "Output this Link as a clickable button using [member[Link.icon]]";
+    function as_string() : string
+    "Return the button HTML link.";
+}
+</source>
+You'll notice that there are a lot of things in class Link that are unfamiliar,  Don't worry; you can safely ignore them. Skip down and notice the two functions.  If you were to use <i>function as_string() : string</i>, then you would write it like this.
+<source lang="perl">
+function Link::as_string() : string
+</source>
+Some functions are defined, or placed inside of, several different classes and may do slightly different things depending on what class they are in.  In other words, <i>function Link::as_string() : string</i> may not do exactly the same thing as say, <i>function MadeUpClass::as_string() : string</i>.
+[Okay, this explanation is going to need some work and actual examples.]
 === Page View ===
@@ Line 354: / Line 384: @@
 }
 </source>
+===== Body =====
 <source lang="perl">
@@ Line 361: / Line 393: @@
 }
 </source>
+===== Modules ======
 <source lang="perl">
@@ Line 369: / Line 403: @@
      """</div>\n</div><div class="separator separator-after"><div class="inner"></div></div>\n</div>""";
 }
-</source>
-===== Page Navigation Function =====
-<source lang="perl">
-    function Page::print_navigation() {}
 </source>
@@ Line 504: / Line 532: @@
 ===== Reply Container =====
+=== Conclusion ===
+And that concludes Crazy About Pages.  With just these two, you have successfully defined the look of your journal.
+That is, if you want all the pages to have the same basic style.  But what if you want every view to be a little different?  What if ReplyPage should have a lime background and you want all your comments in salmon pink?  What if you want your Recent Entries page to go in reverse order and your Reading Page to go in order of date?
+That will take a little more work, but if you got through this, it'll be a snap.