Difference between revisions of "Hierarchy"

From Dreamwidth Notes
Jump to: navigation, search
(Added source wiki formatting and miracles occurred.)
m
 
(28 intermediate revisions by one other user not shown)
Line 1: Line 1:
There are three components to core2 styles:  classes, properties, and functions.  This will be a short overview of the hierarchy of the view-related functions and how they associate with each other.
+
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.
  
Below are the tables of core2 functions associated with view.  Each child is listed below and to the right of the parent.
+
<hr>
  
=== Table of View-Related Functions ===
+
=== Purpose ===
 +
 
 +
Each of these pages is specifically designed to follow a function from how it appears in a view page down to its root functions, variables, and properties. Basically, by the end, you should understand in theory why a function exists and how its put together. Eventually, you will also be able to understand how to alter, change, and even override the functions and both where their variables are stored and why they're there.
 +
 
 +
<hr>
 +
 
 +
=== 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. 
 +
 
 +
<hr>
 +
 +
=== Table of Classes ===
 +
 
 +
Below is a complete table of all the core2 Classes.  These are the basis of core2 design.
 +
 
 +
A child is indicated by indentation below a class.  A child class inherits properties from the parent class, so it can also be said to be an extension.  This will be important later.  A complete explanation of classes will be handled somewhere, I'm sure.  For my purposes, they exist.
 +
 
 +
These are in no particular order yet.
  
 
:Page
 
:Page
Line 20: Line 42:
 
:CommentInfo
 
:CommentInfo
 
:Entry
 
:Entry
 +
:Date
 +
::Datetime
 +
:Image
 +
:Link
 +
:ItemRange
 +
:UserLink
 +
:UserLite
 +
::User
 +
::Friend
 +
:Redirector
 +
:RecentNav
 +
:YearYear
 +
:YearDay
 +
:YearMonth
 +
:MonthEntryInfo
 +
:ReplyForm
 +
:PalItem
  
=== Functions ===
+
<hr>
  
For the purposes of this explanation, Views refers to the actual pages that you use to read your DWJ, your Reading Page, Archive.
+
=== All About Functions ===
  
To get a complete explanation of a function, go the wikipedia route.  So we'll start assuming this is already a familiar concept and go on from there.
+
For the purposes of this explanation, Views refers to the actual pages that you use to read your DWJ, your Reading Page, or Archive.
  
There are three types of functions: simple functions, methods of a class, and builtinBuiltin, or call functions, are built into the backend and cannot be edited by the user.
+
To get a complete explanation of a function, go the wikipedia routeNon-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.
  
Example:
+
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.
    function print_userpic()
+
  
Methods of a class are functions that are declared in a class for the purposes of calling on class properties.
+
This page will cover the first two types.
  
Example:
+
<hr>
    function Image::as_string(string{} opts) [fixed] : string
+
  
=== Page View ===
+
==== Simple Functions ====
  
Class Page is the center of core2 design.  Changes to anything in a Class Page function affects all views unless they are edited separately.  Below is a list of all functions and properties directly associated with the Page class.
+
[Replace this with an actual useful code.]
  
==== Page View Functions ====
+
Example:
 +
<source lang="perl">
 +
function print_words ()
 +
{
 +
enter things here
 +
}
 +
</source>
  
===== CSS Functions =====
+
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.
  
This adds CSS to all layouts in your theme.
+
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.
  
<source lang="perl">
+
Or maybe I want to do this.
    function Page::print_default_stylesheet()
+
    {
+
    """<style type="text/css">""";
+
    start_css();
+
    end_css();
+
    """</style>\n""";
+
    }
+
</source>
+
  
If you have specific CSS to code onto all themes using this layout, override print_default_stylesheet.  If you have specific CSS to code into this theme, set the external_stylesheet property or override the print_stylesheet function. An end user can choose to link to an off-site stylesheet using the linked_stylesheet property and/or use the custom_css property.  Overriding this function is NOT RECOMMENDED. Overriding this function could prevent sitewide improvements to styles, accessibility, or other functionality from operating in your layout.
+
[Replace this with an actual code.]
  
 
<source lang="perl">
 
<source lang="perl">
    function Page::print_stylesheets()
+
function run_things()
    {
+
{
    if ($*include_default_stylesheet) {
+
function_a();
        $this->print_default_stylesheet();
+
function_b();
        if ($*external_stylesheet) {
+
function_c();
            println safe """<link rel="stylesheet" href="$.stylesheet_url" type="text/css" />""";
+
}
        }
+
</source>
        else {
+
            println """<style type="text/css">""";
+
            start_css();
+
            print_stylesheet();
+
            end_css();
+
            println """</style>""";
+
        }
+
    }
+
  
    if ($*linked_stylesheet != "") {
+
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.
        println safe """<link rel="stylesheet" href="$*linked_stylesheet" type="text/css" />""";
+
    }
+
  
    if ($*custom_css != "") {
+
<hr>
        println """<style type="text/css">""";
+
        start_css();
+
        println safe $*custom_css;
+
        end_css();
+
        println """</style>""";
+
    }
+
    }
+
</source>
+
  
 +
==== Methods of a Class ====
  
===== Title Functions =====
+
[Replace with a simpler code.]
  
 +
Example:
 
<source lang="perl">
 
<source lang="perl">
function Page::print_title()
+
    function Image::as_string(string{} opts) [fixed] : string
"Using standard CSS, print the page title. If you want to change the way this looks, modify the CSS."
+
{
+
    print """<h2 id="pagetitle"><span>""" + $this->view_title() + """</span></h2>\n""";
+
}
+
 
</source>
 
</source>
 +
 +
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.
  
 
<source lang="perl">
 
<source lang="perl">
function Page::print_head_title()
+
class Link
"Using standard CSS, print the journal title. If you want to change the way this looks, modify the CSS."
+
"A link or button"
 
{
 
{
     if ($this.journal.journal_type == "I") {
+
     var readonly string url "URL which the link points to";
        print """<title>""" + $this.journal.name + $*text_default_separator + $this->view_title() + """</title>\n""";
+
    var readonly string caption "The caption for the link";
     }
+
     var Image icon
     else {
+
     "A suggestion from the server as to which icon to use. layouts/users can override this of course.
        print """<title>""" + $this.journal.username + $*text_default_separator + $this->view_title() + """</title>\n""";
+
    alt text works similarly to [member[Link.caption]].";
    }
+
}
+
</source>
+
  
<source lang="perl">
+
    function print_button
function Page::print_global_title() {
+
     "Output this Link as a clickable button using [member[Link.icon]]";
     if ($.global_title) {
+
        """<h1 id="title"><span>""" + $.global_title + """</span></h1>""";
+
    }
+
}
+
</source>
+
  
<source lang="perl">
+
    function as_string() : string
function Page::print_global_subtitle() {
+
     "Return the button HTML link.";
     if ($.global_subtitle) {
+
        """<h2 id="subtitle"><span>""" + $.global_subtitle + """</span></h2>""";
+
    }
+
 
}
 
}
 
</source>
 
</source>
  
<source lang="perl">
+
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.
function Page::view_title() [notags] : string {
+
    return lang_viewname($.view);
+
}
+
</source>
+
  
 
<source lang="perl">
 
<source lang="perl">
function Page::title() [notags] : string {
+
function Link::as_string() : string
    return $this->view_title();
+
}
+
 
</source>
 
</source>
  
===== Wrapper Functions =====
+
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>.
  
<source lang="perl">
+
[Okay, this explanation is going to need some work and actual examples.]
    function Page::print_wrapper_start()
+
    {
+
    $this->print_wrapper_start( { "" => "" } );
+
    }
+
</source>
+
  
<source lang="perl">
+
<hr>
    function Page::print_wrapper_start(string{} opts)
+
    {
+
  
    var string class = $opts{"class"} ? """class="$opts{"class"}" """ : "";
+
==== Builtin Functions ====
    """<body class="page-$.view $*layout_type $class">\n""";
+
    }
+
</source>
+
  
"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."
+
[Find a link to someone else talking about this.]
  
<source lang="perl">
+
<hr>
    function Page::print_wrapper_end()  
+
 
    {
+
=== Page View ===
    """</body>""";
+
 
    }
+
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. 
</source>
+
 
   
+
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.
===== Layout Functions =====
+
 
 +
Functions are always green.  Those are what you want to look at.
 +
 
 +
<hr>
  
This is the layout of your entire dw journal. 
+
==== This is Your Layout: The Page::print() Function ====
  
Note: Divs are breaking formattingWork out how to fix that.
+
This is the layout of your entire dw journalThis is how the stucture is decided, columns created, and worlds destroyed.
  
 
<source lang="perl">
 
<source lang="perl">
Line 224: Line 221:
 
</source>
 
</source>
  
 +
<hr>
  
<source lang="perl">
+
==== Breakdown ====
 +
 
 +
The following is a list and definition of all functions that can be used in the above, split by type and location.
 +
 
 +
<hr>
 +
 
 +
===== 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.
 +
 
 +
<hr>
 +
 
 +
===== 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.
  
 
<source lang="perl">
 
<source lang="perl">
  function Page::print_body() {
+
function Page::print_head()  
     """<h2>No Default Renderer</h2><p>There is no body renderer for viewtype <tt>$.view</tt> defined.</p>""";
+
{
 +
     print $.head_content;
 +
    $this->print_custom_head();
 
}
 
}
 
</source>
 
</source>
  
 
<source lang="perl">
 
<source lang="perl">
    function Page::print_module_section ( string section_name )  
+
function Page::print_custom_head()  
 
{
 
{
     """<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">""";
+
     # blank
     handle_module_group_array( $*module_sections{$section_name} );
+
}
     """</div>\n</div><div class="separator separator-after"><div class="inner"></div></div>\n</div>""";
+
 
 +
<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 />";
 +
    }
 +
}
 
</source>
 
</source>
  
===== Date Functions =====
+
For a breakdown of these functions including their classes, properties and variables in more detail, see [[Hierarchy: Head Functions]].
 +
 
 +
<hr>
 +
 
 +
===== 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.
  
 
<source lang="perl">
 
<source lang="perl">
     function Page::print_time() {
+
function Page::print_default_stylesheet()
     $this->print_time("","");
+
{
 +
     """<style type="text/css">""";
 +
    start_css();
 +
    end_css();
 +
    """</style>\n""";
 +
}
 +
</source>
 +
 
 +
This function gives the user a choice to use an external stylesheet or custom css added to the existing default stylesheet.
 +
 
 +
<source lang="perl">
 +
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>""";
 +
        }
 
     }
 
     }
  
    function Page::print_time(string datefmt, string timefmt) {
+
     if ($*linked_stylesheet != "") {
     if ($datefmt == "") {
+
         println safe """<link rel="stylesheet" href="$*linked_stylesheet" type="text/css" />""";
         $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>""";
+
     if ($*custom_css != "") {
 +
        println """<style type="text/css">""";
 +
        start_css();
 +
        println safe $*custom_css;
 +
        end_css();
 +
        println """</style>""";
 
     }
 
     }
 +
}
 
</source>
 
</source>
  
===== Page Navigation Function =====
+
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.]
 +
 
 +
<hr>
 +
 
 +
===== Title Functions =====
 +
 
 +
The third function in Layout refers to the title of the current view, such as Reading page, Recent Entries, and Year.
  
 
<source lang="perl">
 
<source lang="perl">
    function Page::print_navigation() {}
+
function Page::print_title()  
 +
{
 +
    print """<h2 id="pagetitle"><span>""" + $this->view_title() + """</span></h2>\n""";
 +
}
 
</source>
 
</source>
  
===== Head Functions =====
+
This prints the Journal's title on the page.
  
 
<source lang="perl">
 
<source lang="perl">
    function Page::print_head() {
+
function Page::print_head_title()  
     print $.head_content;
+
{
     $this->print_custom_head();
+
     if ($this.journal.journal_type == "I")
 +
     {
 +
    print """<title>""" + $this.journal.name + $*text_default_separator + $this->view_title() + """</title>\n""";
 
     }
 
     }
 
+
    else
     function Page::print_custom_head() {
+
     {
    # blank
+
        print """<title>""" + $this.journal.username + $*text_default_separator + $this->view_title() + """</title>\n""";
 
     }
 
     }
 +
}
 +
</source>
  
    function Page::print_linklist() {
+
Add documentation here.
     if (size $.linklist <= 0) {
+
 
        return;
+
<source lang="perl">
     } elseif (not $*linklist_support) {
+
function Page::view_title() [notags] : string
         return;
+
{
 +
     return lang_viewname($.view);
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
function Page::print_global_title()  
 +
{
 +
     if ($.global_title)  
 +
    {
 +
         """<h1 id="title"><span>""" + $.global_title + """</span></h1>""";
 
     }
 
     }
 +
}
 +
</source>
  
    foreach var UserLink l ($.linklist) {
+
<source lang="perl">
        if ($l.title) {
+
function Page::print_global_subtitle()  
            if ($l.is_heading) {
+
{
                "<b>$l.title</b>";
+
    if ($.global_subtitle)  
            } else {
+
    {
                "<a href='$l.url'>$l.title</a>";
+
    """<h2 id="subtitle"><span>""" + $.global_subtitle + """</span></h2>""";
            }
+
        }
+
        "<br />";
+
    }
+
 
     }
 
     }
 +
}
 
</source>
 
</source>
  
===== Print Entry =====
+
<source lang="perl">
 +
function Page::view_title() [notags] : string
 +
{
 +
    return lang_viewname($.view);
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
function Page::title() [notags] : string
 +
{
 +
    return $this->view_title();
 +
}
 +
</source>
 +
 
 +
<hr>
 +
 
 +
===== Wrapper Functions =====
  
This is how all the functions used for a basic layout fit together.  This function will affect how you see your Recent Entries, your Reading Page, and your individual entry page.
+
These functions are called wrappers.  They are preset with a variety of functions and properties in themDo not override these or try to change them.
 +
 
 +
<source lang="perl">
 +
function Page::print_wrapper_start()
 +
{
 +
    $this->print_wrapper_start( { "" => "" } );
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
function Page::print_wrapper_start(string{} opts)
 +
{
 +
    var string class = $opts{"class"} ? """class="$opts{"class"}" """ : "";
 +
    """<body class="page-$.view $*layout_type $class">\n""";
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
function Page::print_wrapper_end()
 +
{
 +
    """</body>""";
 +
}
 +
</source>
 +
 
 +
<hr>
 +
 
 +
===== 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>""";
 +
}
 +
</source>
 +
 
 +
<hr>
 +
 
 +
===== Modules =====
 +
 
 +
<source lang="perl">
 +
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>""";
 +
}
 +
</source>
 +
 
 +
<hr>
 +
 
 +
==== 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.
  
 
<source lang="perl">
 
<source lang="perl">
Line 344: Line 510:
 
</source>
 
</source>
  
==== Page View Properties ====
+
<hr>
 +
 
 +
==== The Breakdown ====
 +
 
 +
The following is a list and definition of all functions that can be used in the above, split by type and location.
 +
 
 +
<hr>
 +
 
 +
===== Date Functions =====
 +
 
 +
<source lang="perl">
 +
    function Page::print_time()
 +
{
 +
    $this->print_time("","");
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
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>""";
 +
}
 +
</source>
 +
 
 +
<hr>
 +
 
 +
===== Subject =====
 +
 
 +
<source lang="perl">
 +
function print_subject () [fixed] "Print the formatted subject for this entry or comment";
 +
</source>
 +
 
 +
<source lang="perl">
 +
function print_subject (string{} opts) [fixed] "Print the formatted subject for this entry or comment, gets hash of attributes - class and(or) style ";
 +
</source>
 +
 
 +
<hr>
 +
 
 +
===== Metatypes =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Time =====
 +
 
 +
<source lang="perl">
 +
function Page::print_time()
 +
{
 +
    $this->print_time("","");
 +
}
 +
</source>
 +
 
 +
<source lang="perl">
 +
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>""";
 +
}
 +
</source>
 +
 
 +
For a breakdown of these functions including their classes, properties and variables in more detail, see [[Hierarchy: Print Time Functions]].
 +
 
 +
<hr>
 +
 
 +
===== Userpic (Icon) =====
 +
   
 +
 
 +
<hr>
 +
 
 +
===== Poster (DW Username) =====
 +
   
 +
<hr>
 +
 
 +
===== Text =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Metadata =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Tags =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Entry Management Links =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Entry Interaction Links =====
 +
 
 +
 
 +
<hr>
 +
 
 +
===== Reply Container =====
 +
 
 +
 
 +
<hr>
 +
 
 +
=== Conclusion ===
 +
 
 +
And that concludes Crazy About Pages.  With just these two, you have successfully defined the look of your journal.
  
Paste Property explantion here and link to Properties page.
+
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?
  
==== Page View Classes ====
+
That will take a little more work, but if you got through this, it'll be a snap.
  
Paste Class explanation here and link to Class page.
+
[[Category: Styles]]
 +
[[Category: S2]]

Latest revision as of 20:08, 6 August 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.


Purpose

Each of these pages is specifically designed to follow a function from how it appears in a view page down to its root functions, variables, and properties. Basically, by the end, you should understand in theory why a function exists and how its put together. Eventually, you will also be able to understand how to alter, change, and even override the functions and both where their variables are stored and why they're there.


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 Classes

Below is a complete table of all the core2 Classes. These are the basis of core2 design.

A child is indicated by indentation below a class. A child class inherits properties from the parent class, so it can also be said to be an extension. This will be important later. A complete explanation of classes will be handled somewhere, I'm sure. For my purposes, they exist.

These are in no particular order yet.

Page
TagsPage
MessagePage
RecentPage
FriendsPage
DayPage
YearPage
MonthPage
EntryPage
ReplyPage
MonthDay
YearWeek
Comment
CommentInfo
Entry
Date
Datetime
Image
Link
ItemRange
UserLink
UserLite
User
Friend
Redirector
RecentNav
YearYear
YearDay
YearMonth
MonthEntryInfo
ReplyForm
PalItem

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.]


Builtin Functions

[Find a link to someone else talking about this.]


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

For a breakdown of these functions including their classes, properties and variables in more detail, see Hierarchy: Head Functions.


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

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


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

For a breakdown of these functions including their classes, properties and variables in more detail, see Hierarchy: Print Time Functions.


Userpic (Icon)

Poster (DW Username)

Text

Metadata

Tags

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.