kunzite1 said in a previous post, this is one of the documents I've been working on. I'll try to limit the spamming to what is as complete as possible.As usual, I'd love to know what you think - good and bad - so please comment. And if you do find this helpful, you're welcome to bookmark it or petition to have it added to the 'official' documentation. 0:-)
As this hasn't been made part of the official documentation, comments have been disabled.
Reading and using a tutorial
One question which always comes up is "Where should I put the code?" or "I copied and pasted the code but I keep getting errors. What's the problem?" Hopefully this guide will help you understand how tutorials should be used so that you won't have to ask this type of question.
>> Have you read the Getting Started Guide?
No? Well you should have. Please do read it before using any tutorial and don't hesitate to comment if you have any question.
>> Make sure this is the latest version of the tutorial, especially if somebody has linked you to it.
Tutorials are often updated to improve the code and/or add additional customizations and it's more practical to post a new entry than to edit the old post. So go to the tutorials list, find your tutorial and compare your version to the one that's there.
>> Identify the type of information you're given in the tutorial. Functions or set commands?
S2 can only be two things: functions or set commands.
Functions look like this:
function print_free_text () {i.e. the word "function" then a name then parentheses then an opening curly brace {
At the end of the function there must be a closing brace }
Set commands look like this:
set tags_aware = true;i.e. the word "set" then a name then the = sign then a value then a semi-colon ;
S2 code must be one or the other. If you're given code which is neither a set command nor a function then it means that it should be inserted into a function. The poster always indicates somewhere into which function it should be inserted or links you to another tutorial where you'll find the function.
>> Identify the layer the code should go into. Theme or User Layer?
Functions must go into your Theme layer (How do I create a Theme Layer?).
Set commands must go into your User layer if you have one. Otherwise, use the Edit customizations interface (LJ Homepage/Manage/Customize/button at the bottom) or put set commands into your Theme Layer, at the top.
>> Identify the type of tutorial you're looking at. Do you have to copy/paste it or insert it into something else?
Remember that code can only be set commands or functions. Set commands must generally simply be copied/pasted.
If the code isn't a set command then it has to go inside a function. If the code starts with the word "function" and ends with a } sign then you generally just have to copy/paste it. If it doesn't start with the word "function" then it has to be inserted into one. The name of the function and the place within the function it has to be inserted into are always mentioned.
>> Look at the name of the function which is edited then look at your layer. Have you already got it?
If that's so, you can't have a function twice. So don't copy/paste the whole function again. Either you have to replace it with the new code or you have to insert the code into it. Be careful not to paste it over existing code or to paste it after the closing }
>> Always read the instructions and the code carefully before doing anything.
We know that S2 isn't easy to read and understand, especially if English isn't your native language. However, having some sort of idea of what you're going to have to do before copying/pasting things blindly truly makes a difference. It's also a good idea to ask a question beforehand rather than dealing with compiling errors and frustration because you can't make it work.
>> Save your code as a .txt file before and after doing anything.
PC aficionados can use Notepad (Start/Programs/Accessories in recent Windows Operating Systems) or TextPad. Mac devotees can use textedit or whatever the program is. In the compiler window, right-click on select all then copy then paste into your empty .txt file and save as. Don't forget to update this file regularly.
>> Take your time. Do things step by step and save and compile before going further.
Keep in mind that we can help you better if we know at which point you got an error.
>>
component_help also frequently use color codes in tutorials. What are these?black - code that doesn't need to be changed to make the enhancement work.
green - very important comments explaining the operation of code, and further customization that you can make. It explains code that is in the following three colors.
red - either a variable value to change to customize your look, or code that you can play with to affect layout of items.
blue - active lines that can be removed to remove functionality.
pink - inactive lines that can be activated to enable functionality.
To sum it up:
- green code is text you should read because it gives you explanations and instructions.
- red code is code you may have to modify to suit your needs. For example, a percentage or a number of pixels or a value like true/false, left/center/right, etc. or even an URL for an image or text you have to enter.
- blue and pink code is code you need to activate or deactivate to suit your needs. It's called commenting and decommenting a line of code. The following section will give you further explanations about this.
>> Most tutorials also have # signs. What are these?
Text or code written with # signs at the beginning are called "comments".
You have two types of comments:
- Those which are optional code you may choose to activate or not. Lines which can be activated are in pink. Lines which can be deactivated are in blue.
- And those which are meant to explain what the code is for and where you should put things. These are in green in the tutorials. Do not delete them.
How do I activate and deactivate a line of code?
By default the lines of code starting with the # sign are deactivated. When you want to activate them, delete the # sign at the beginning. This is called "decommenting". If you want deactivate them again later on, simply put the # sign back at the beginning of the line. This is called "commenting".
Comments are also used to create headers at the beginning of functions. Something similar to this:
###############################
# SHRINKING AND CENTERING #
# kunzite1, component-help/248593 #
# overrides page_layout(Page p) #
###############################Do not delete it. It reminds you what this portion is meant to do, who wrote the tutorial (and consequently who you may need to ask questions to), where you found it (component-help/248593 = http://community.livejournal.com/component_help/248593.html) and what function it edits.
It also makes it easier to find code and functions.
Do not hesitate to add your own comments to help you remember what the code is for, what modifications you've made, etc... whether it's at the beginning of a tutorial or inside a tutorial.
elfwench also made an excellent suggestion using commented text: writing, at the top of your layer, a history of your customizations with the title of the customization, its date, its author, its source, the name of the edited function.Something like this:
########################################
# 12 Dec 2005 Began with S&C W/Rounded Navbar #
# by kunzite1 #
#component_help/669901.html #
# #
# added function:#
# page_layout() #
########################################
########################################
# 12 Dec 2005 Added CUSTOMIZING THE ENTRIES (V3.0) #
# by kunzite1 #
# component_help/869795.html #
# #
# added properties: #
# tags_aware = true; #
# text_meta_mood = "Current Mood:"; #
# text_meta_music = "Current Music:"; #
# #
# added functions: #
# Entry::print_metadata() #
# CommentInfo::print() #
# Entry::print_linkbar() #
# print_entry() #
########################################
########################################
# 12 Dec 2005 - Added Spiffy Date Format #
# by kunzite1 #
# component_help/870069.html #
# #
# added function: #
# Page::print_custom_head() #
# #
# altered function: #
# print_entry() #
# altered entry_header portion #
########################################This is very useful when you want to redo a layer or when you want to know if you've already edited a function. You can keep track of all the modifications you've made and in what order.
>> I can't make it compile! What's the problem?
The most common source of errors has to do with the following signs.
* semicolons ; at the end of most lines.
* parentheses ( ) especially after the words 'if' and 'elseif'.
* the triple-quote of doom™ """ is also a very frequent source of errors.
* pretty curly braces { } after the words 'function', 'if', 'else', 'elseif'.
Cutting out one of these or on the contrary adding an extra one will cause errors and prevent you from implementing changes. If the compiler tells you that there is a mistake, make sure that the code you have in your layer is the same as the one in the tutorial. Pay special attention to all these little signs.
>> I don't get any errors but my layout won't change. What did I do wrong?
You probably have simply forgotten to tell the system to use your brand new custom layer. You have to create a style using this layer then apply it to your journal. Step 3 of this beginners' tutorial will tell you how to do so.