Difference between revisions of "Hierarchy"

From Dreamwidth Notes
Jump to: navigation, search
(Formatting Fix 1 - global title still breaking out.)
m
 
(35 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 class and 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 classes and functions associated with view.  Each child is listed below and to the right of the parent.
+
<hr>
  
 +
=== 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 ===
 
=== Table of Classes ===
  
:Date
+
Below is a complete table of all the core2 Classes.  These are the basis of core2 design.
::DateTime
+
 
:Image
+
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.
:Link
+
 
:ItemRange
+
These are in no particular order yet.
:CommentInfo
+
 
:UserLink
+
:UserLite
+
::User
+
::Friend
+
:EntryLite
+
::Entry
+
::Comment
+
:Tag
+
::TagDetail
+
:Redirector
+
 
:Page
 
:Page
 
::TagsPage
 
::TagsPage
Line 31: Line 37:
 
::EntryPage
 
::EntryPage
 
::ReplyPage
 
::ReplyPage
 +
::MonthDay
 +
:YearWeek
 +
:Comment
 +
:CommentInfo
 +
:Entry
 +
:Date
 +
::Datetime
 +
:Image
 +
:Link
 +
:ItemRange
 +
:UserLink
 +
:UserLite
 +
::User
 +
::Friend
 +
:Redirector
 
:RecentNav
 
:RecentNav
 
:YearYear
 
:YearYear
 
:YearDay
 
:YearDay
::MonthDay
 
:YearWeek
 
 
:YearMonth
 
:YearMonth
 
:MonthEntryInfo
 
:MonthEntryInfo
Line 41: Line 60:
 
:PalItem
 
:PalItem
  
=== Explanation of Classes ===
+
<hr>
  
=== Table of View-Related Functions ===
+
=== All About Functions ===
  
:Page
+
For the purposes of this explanation, Views refers to the actual pages that you use to read your DWJ, your Reading Page, or Archive.
::TagsPage
+
::MessagePage
+
::RecentPage
+
:::FriendsPage
+
::DayPage
+
::YearPage
+
::MonthPage
+
::EntryPage
+
::ReplyPage
+
::MonthDay
+
:YearWeek
+
:Comment
+
:CommentInfo
+
:Entry
+
  
=== Explanation of View-Related Functions ===
+
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.
  
=== Function: Page ===
+
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.
  
Page is the center of core2 design.  Changes to anything in a Page function affects all layouts unless they are edited separately.  Below is a list of all functions associated with Page.
+
This page will cover the first two types.
  
In each function associated with View, there's a function Name::xfunction. This is to tell xfunction what View it is affecting.
+
<hr>
  
==== CSS Functions ====
+
==== Simple Functions ====
  
This adds CSS to all layouts in your theme.
+
[Replace this with an actual useful code.]
  
    function Page::print_default_stylesheet()
+
Example:
    {
+
<source lang="perl">
    """<style type="text/css">""";
+
function print_words ()
    start_css();
+
{
    end_css();
+
enter things here
    """</style>\n""";
+
}
    }
+
</source>
  
If you have specific CSS to code onto all themes using this layout, override print_default_stylesheetIf 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 propertyOverriding this function is NOT RECOMMENDED. Overriding this function could prevent sitewide improvements to styles, accessibility, or other functionality from operating in your layout.
+
Breaking it down, I create a function I named print_wordsThen 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 pageInstead of writing out all those things, I just use print_words every time that is supposed to happen.
  
    function Page::print_stylesheets()
+
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.
    {
+
    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 != "") {
+
Or maybe I want to do this.
        println safe """<link rel="stylesheet" href="$*linked_stylesheet" type="text/css" />""";
+
    }
+
  
    if ($*custom_css != "") {
+
[Replace this with an actual code.]
        println """<style type="text/css">""";
+
        start_css();
+
        println safe $*custom_css;
+
        end_css();
+
        println """</style>""";
+
    }
+
    }
+
  
 +
<source lang="perl">
 +
function run_things()
 +
{
 +
function_a();
 +
function_b();
 +
function_c();
 +
}
 +
</source>
  
 +
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.
  
==== Title Functions ====
+
<hr>
  
Using standard CSS, print the journal title. If you want to change the way this looks, modify the CSS.
+
==== Methods of a Class ====
  
    function Page::print_title()
+
[Replace with a simpler code.]
    {
+
    print """<h2 id="pagetitle"><span>"""+$this->view_title()+"""<span>
+
    </h2>\n""";
+
    }
+
   
+
  
   
+
Example:
    function Page::print_head_title()
+
<source lang="perl">
    {
+
     function Image::as_string(string{} opts) [fixed] : string
    if ($this.journal.journal_type == "I")
+
</source>
    {
+
    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""";
+
    }
+
    }
+
  
 +
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. 
  
    function Page::print_global_title()
+
Here is an example from core2 v2's source.
    {
+
    if ($.global_title)
+
    {
+
        """<h1 id="title"><span>""" + $.global_title + """</span></h1>""";
+
    }
+
    }
+
  
    function Page::print_global_subtitle()
+
<source lang="perl">
    {
+
class Link
    if ($.global_subtitle) {
+
"A link or button"
        """<h2 id="subtitle"><span>""" + $.global_subtitle + """</span></h2>""";
+
{
     }
+
    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 Page::view_title() [notags] : string
+
     function print_button
     {
+
     "Output this Link as a clickable button using [member[Link.icon]]";
    return lang_viewname($.view);
+
    }
+
  
     function Page::title() [notags] : string  
+
     function as_string() : string
     {
+
     "Return the button HTML link.";
    return $this->view_title();
+
}
    }
+
</source>
  
==== Wrapper Functions ====
+
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::print_wrapper_start()  
+
<source lang="perl">
    {
+
function Link::as_string() : string
    $this->print_wrapper_start( { "" => "" } );
+
</source>
    }
+
  
    function Page::print_wrapper_start(string{} opts)  
+
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>.
    {
+
  
    var string class = $opts{"class"} ? """class="$opts{"class"}" """ : "";
+
[Okay, this explanation is going to need some work and actual examples.]
    """<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."
+
<hr>
  
    function Page::print_wrapper_end()
+
==== Builtin Functions ====
    {
+
    """</body>""";
+
    }
+
  
   
+
[Find a link to someone else talking about this.]
==== Layout Functions ====
+
  
This is the layout of your entire dw journal.
+
<hr>
  
 +
=== 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.
 +
 +
<hr>
 +
 +
==== 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.
 +
 +
<source lang="perl">
 
     function Page::print()
 
     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""";
+
     """<!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_head();
 
     $this->print_stylesheets();
 
     $this->print_stylesheets();
Line 202: Line 184:
 
     $this->print_wrapper_start();
 
     $this->print_wrapper_start();
 
     $this->print_control_strip();
 
     $this->print_control_strip();
     """
+
     """<div id="canvas">
    <div id="canvas">
+
    <div class="inner">
        <div class="inner">
+
    <div id="header">
            <div id="header">
+
    <div class="inner">""";
                <div class="inner">
+
    $this->print_global_title();
                    """;
+
    $this->print_global_subtitle();
                    $this->print_global_title();
+
    $this->print_title();
                    $this->print_global_subtitle();
+
     """</div><!-- end header>inner -->
                    $this->print_title();
+
     """
+
                </div><!-- end header>inner -->
+
 
             </div><!-- end header -->
 
             </div><!-- end header -->
 
             <div id="content">
 
             <div id="content">
Line 219: Line 198:
 
                         """;  
 
                         """;  
 
                         $this->print_body();
 
                         $this->print_body();
     """
+
     """</div></div><!-- end primary and primary>inner -->
                    </div></div><!-- end primary and primary>inner -->
+
                     <div id="secondary"><div class="inner">""";
                     <div id="secondary"><div class="inner">
+
                        """;
+
 
                         $this->print_module_section("one");
 
                         $this->print_module_section("one");
     """
+
     """</div></div><!--  end secondary and secondary>inner -->
                    </div></div><!--  end secondary and secondary>inner -->
+
                     <div id="tertiary"><div class="inner">""";
                     <div id="tertiary"><div class="inner">
+
                        """;
+
 
                         $this->print_module_section("two");
 
                         $this->print_module_section("two");
     """
+
     """</div></div><!-- end tertiary and tertiary>inner -->
                    </div></div><!-- end tertiary and tertiary>inner -->
+
 
                 </div><!-- end content>inner -->
 
                 </div><!-- end content>inner -->
 
             </div> <!-- end content -->
 
             </div> <!-- end content -->
         </div> <!-- end canvas>inner -->  
+
         </div> <!-- end canvas>inner -->""";
    """;
+
 
      
 
      
     """
+
     """<div id="footer">
    <div id="footer">
+
         <div class="inner">""";
         <div class="inner">
+
      print safe """<div class="page-top"><a href="#">$*text_page_top</a></div>
            """;
+
            print safe """
+
                <div class="page-top"><a href="#">$*text_page_top</a></div>
+
 
         </div><!-- end footer>inner -->
 
         </div><!-- end footer>inner -->
 
     </div><!-- end footer -->
 
     </div><!-- end footer -->
   
+
     </div> <!-- end canvas -->""";
     </div> <!-- end canvas -->
+
    """;
+
 
     $this->print_wrapper_end();
 
     $this->print_wrapper_end();
 
     """</html>""";
 
     """</html>""";
 
     }
 
     }
  
    function Page::print_body() {
+
</source>
    """<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 ) {
+
<hr>
    """<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>""";
+
    }
+
  
 +
==== Breakdown ====
  
==== Date Functions ====
+
The following is a list and definition of all functions that can be used in the above, split by type and location.
  
    function Page::print_time() {
+
<hr>
    $this->print_time("","");
+
    }
+
  
    function Page::print_time(string datefmt, string timefmt) {
+
===== HTML and CSS =====
    if ($datefmt == "") {
+
        $datefmt = "med";
+
    }
+
    if ($timefmt == "") {
+
        $timefmt = "short";
+
    }
+
  
    var string ret;
+
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.
    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>""";
+
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.
    }
+
  
==== Page Navigation Function ====
+
<hr>
  
    function Page::print_navigation() {}
+
===== Head Functions =====
  
==== 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() {
+
<source lang="perl">
 +
function Page::print_head()  
 +
{
 
     print $.head_content;
 
     print $.head_content;
 
     $this->print_custom_head();
 
     $this->print_custom_head();
    }
+
}
 +
</source>
  
    function Page::print_custom_head() {
+
<source lang="perl">
 +
function Page::print_custom_head()  
 +
{
 
     # blank
 
     # blank
    }
+
}
  
function Page::print_linklist() {
+
<source lang="perl">
     if (size $.linklist <= 0) {
+
function Page::print_linklist()  
 +
{
 +
     if (size $.linklist <= 0)  
 +
    {
 
         return;
 
         return;
     } elseif (not $*linklist_support) {
+
     }  
 +
    elseif (not $*linklist_support)  
 +
    {
 
         return;
 
         return;
 
     }
 
     }
 
 
     foreach var UserLink l ($.linklist) {
 
     foreach var UserLink l ($.linklist) {
         if ($l.title) {
+
         if ($l.title)  
             if ($l.is_heading) {
+
        {
 +
             if ($l.is_heading)  
 +
            {
 
                 "<b>$l.title</b>";
 
                 "<b>$l.title</b>";
             } else {
+
             }  
 +
            else  
 +
            {
 
                 "<a href='$l.url'>$l.title</a>";
 
                 "<a href='$l.url'>$l.title</a>";
 
             }
 
             }
Line 316: Line 280:
 
         "<br />";
 
         "<br />";
 
     }
 
     }
 +
}
 +
</source>
 +
 +
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">
 +
function Page::print_default_stylesheet()
 +
{
 +
    """<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>""";
 +
        }
 
     }
 
     }
  
==== Print Entry ====
+
    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>""";
 +
    }
 +
}
 +
</source>
 +
 
 +
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">
 +
function Page::print_title()
 +
{
 +
    print """<h2 id="pagetitle"><span>""" + $this->view_title() + """</span></h2>\n""";
 +
}
 +
</source>
 +
 
 +
This prints the Journal's title on the page.
 +
 
 +
<source lang="perl">
 +
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""";
 +
    }
 +
}
 +
</source>
 +
 
 +
Add documentation here.
 +
 
 +
<source lang="perl">
 +
function Page::view_title() [notags] : string
 +
{
 +
    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>
 +
 
 +
<source lang="perl">
 +
function Page::print_global_subtitle()
 +
{
 +
    if ($.global_subtitle)
 +
    {
 +
    """<h2 id="subtitle"><span>""" + $.global_subtitle + """</span></h2>""";
 +
    }
 +
}
 +
</source>
 +
 
 +
<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 =====
 +
 
 +
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.
 +
 
 +
<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 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.
+
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">
 
     function Page::print_entry(Entry e)  
 
     function Page::print_entry(Entry e)  
 
     {
 
     {
Line 356: Line 508:
 
     $e->print_wrapper_end();
 
     $e->print_wrapper_end();
 
}
 
}
 +
</source>
 +
 +
<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.
 +
 +
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.
 +
 +
[[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.