saiyajin no gunshou (_tumblweed) wrote in component_help,
saiyajin no gunshou
_tumblweed
component_help

s2 - a breakdown tutorial for newbies

an s2 programming crash course, by _tumblweed.

I've seen a number of the same requests over the past month or so here, and decided that I'd follow kunzite1 and panda_cookie's leads and offer a small crash course in some basic s2 programming.  This tutorial will assume that you've read both the basic users guide and the idiot's guide, and will just serve to further clarify where certain codes go and why they are written a certain way.  If you start to read this and are utterly lost, also please check out skybound2's newbie's page.

This tutorial is not meant to give you code you plug in.  It's meant to teach you what to look for in the code so that you can edit the existing tutorials to suit your own needs.  Reading this document will teach you, if you have a little perserverence, to a) have both a header and a background image, b) change to a navigation component, c) change the scrollbar colors (IE ONLY), d) move page elements around, e) edit the hells out of everything.  However, I make no promises that you won't seriously screw up your layout by playing around.  I recommend backing up your code onto your harddrive first.  I also recommend playing around with a test journal rather than your own.

menu:
1. stylesheet and set commands
2. functions: curly brackets and triple quotes
3. what makes a component
4. where do i put this code?

STYLESHEET AND SET COMMANDS
The stylesheet is contained within the print_custom_head function and looks like this:
function Page::print_custom_head() {

"""
<style type="text/css">

CSS STUFF
ADDING DIV CLASSES
CHANGING VARIABLES OF EXISTING DIV CLASSES
ETC

</style>
""";
}

This is the complicated way to change simple things (and a simple way to change complicated things; I'll get to specifics later).  A list of the many things you can alter in the style sheet (including the color of the entry dash, the high- and low-lights of the headers, and the colors of the textarea fields where your drop-down menus show up) is here.  Notice that many of these are div classes.  They look like this:
.dkLine  { background-color: $dkLineString; }    /* misc borders (dark) */
where the name after the . is what the class is called and within the curly brackets are the attribute definitions for that class.  You can alter a lot just by changing these attributes in your stylesheet.

The simple way to change colors and things like the "Leave a comment?" field is through set commands.  To make life easier, it's best to seperate your set commands from your other edits.  When you use the LJ Customization Wizard, you are writing set commands to a user layer.  If you keep the set commands in your user layer and not your theme layer, you can continue to use the Wizard for these simple changes.  A list of set commands that you can change is located here (LJ Core) and here (Component).  For more info on user and theme layers, go here.

So what can you do with stylesheets and print_custom_head?  Well, you can add a background (you can also do this in the Customization Wizard for Component, but I like to be extra picky about placement for my bg, so I do it the hard way), change the way the links look when you hover over them, change your cursors, and change your scrollbar colors in IE only.  Google "css properties" or "css help" and you'll find all sorts of lists and tutorials for how to customize your stylesheet.  I constantly refer to Kali's Web Shoppe for filters and property tags, but there are a bazillion other places you can look.

FUNCTIONS: CURLY BRACKETS AND TRIPLE QUOTES
So you got this code from component_help, and it's got all these { { } and """ """; and you're getting errors like
Compile error: Unexpected token found.  Expecting: [TokenPunct] = ;
and you don't know what the hells happened.

Well, s2 code works this way.  Function calls are contained within curly brackets: { and }.  All functions begin with one and end with one.  It's like the capital letter and closing punctuation of a sentence: without such distinguishing features, the system can't parse your code when that happens it's like a giant run-on that just continues forever and the system has no idea how to even begin to scan for the next function after all, it's not like you included a period so the reader would know where to stop you know that can be kinda disconcerting and is equally incomprehensible to the system parser.  hence, curly quotes.

Now, the s2 language is not ordinary HTML.  So if you want to include ordinary HTML, you have to indicate to the system that you're doing so, sort of like a comma or a pair of parentheses in a sentence that sets off a clause.  You do this with the triple quotes.  Every time you include HTML, you have to encase the block of code in triple quotes, """sort of like this""", and that will tell the system to switch gears, so to speak.  And just like I included a comma there to indicate the reader should pause and prepare for the next phrase, the end of a triple-quoted block of HTML should have a semicolon after it to indicate to the system that it's done with that bit of code and can go on.  So, say you want to alter your page layout.  First, you tell the system that's what you're doing:
function page_layout(Page p)
and you put in your opening curly bracket:
{
Then, you include any variables you might need, like for corner colors, or whatever:
var string title = $p->title();
See how that ended with a semicolon (;)?  Again, you're telling the system to take a breath and go on to the next part of the code.  Now you need to write some HTML.  Break out the triple quotes:
 """
  <html>
  <head>
    <link rel="stylesheet" href="$p.stylesheet_url" type="text/css"/>
    $p.head_content
That $p thing is HTML, believe it or not, so it doesn't need anything special.  But the next line goes back to s2 language, so we need to close off this HTML with the triple quotes and a semicolon:
""";
Now we write our s2 put a semicolon, and finish up the HTML, enclosing it in the triple quotes and another semicolon:
$p->print_custom_head();
 """
<title>$title</title>
  </head>
  """;
There's more to this particular code, but pretend we're going to end here.  To close off the function we add a curly bracket
}
And we compile without errors because everything is properly parsed!  Yay!

WHAT MAKES A COMPONENT
In its simplest form, a component is
print_comp_header("A TITLE HERE");
  """ HTML """;
print_comp_footer();
Complicated ones have variables listed above the print_comp_header tag.  Components are self-contained within these tags, so if you place a tutorial for a component within a component, you'll end up with double headers and footers.  Kinda like putting on two pairs of underwear at once.  The adding components tutorial explains this pretty well.

WHERE DO I PUT THIS CODE?
After slogging through all the above, hopefully you'll know the answer to this.  If it's an additional component, you put the code within the function for whatever component you want it to come after.  For example, on my journal, I have only one component defined in the set commands: the free text one.  But my free text function looks like this:
function print_free_text(Page p){

print_profile($p);

print_comp_header("TITLE");
"""<div class="menufont"> BUNCH O' STUFF </div> """;
print_comp_footer();

print_links($p);

if (not viewer_is_owner()) {
print_comp_header("ANOTHER TITLE");
  """
HTML STUFF
  """;
print_comp_footer();
}

#print_nav_comp($p);

}
So what I'm telling the system is, I only want free text to be displayed, but within free text I want it to write the profile, then a custom component, then links, then some other custom component, then the nav component, and that's it.  But then, I decided I didn't want the nav component, so I commented it out with the handy #.  This tells the system to skip this line of s2 language.  Are you still with me?  Good, because my profile is pretty sparse.  I want to jazz it up.  So I'm going to alter its code directly by rewriting its function call.  First, we have:
function print_profile(Page p) {
Then a whole bunch of variable and logic stuff (NOTE: this is not the whole code of kunzite1's clock tutorial, just some stuff to give you an idea of what the code is made up of):
# set this to your time zone difference          
  var int k1Ctime_difference  = -5;
# set this to 1 if it is between spring and fall   
  var int k1Cdaylight_savings = 0;
var int k1Cyear  = $p.time.year;
var int k1Cday   = $p.time.day;
Notice how the instructions are commented out with # so the system doesn't think it's code.  Then we have the opening of the actual component:
print_comp_header($*profile_text);
and some HTML:
"""
<table cellspacing="0" cellpadding="0" border="0">
<tr><td valign="top"><div class="menufont">
<a href="http://www.livejournal.com/users/_tumblweed/">ENTRIES</a>
<br /><br /></td></tr>
<tr><td align="left">
<div style="font-variant: small-caps; line-height: 8px; text-align:justify;"><font size="-2">
...my first thought was he lied in every word, 
nothing beside remains...</font></div>
</td></tr></table>
""";
the end of the component:
print_comp_footer();
and the end of the function:
}

So, that's an in-depth look at what all that complicated coding stuff is.  Now that you can parse the tutorials down (complete with semicolons and brackets), go ahead and try different stuff out.  Who knows, pretty soon you'll be writing your own tutorials and helping all of us out.  Good luck!

Feel free to email me with specific questions, or post them to the community after you've looked through the tutorials.  Try to help yourself, and when you get stuck, we'll be more than happy to lend a virtual hand.
Subscribe
  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

  • 5 comments