Getting Started guide: component

kunzite1 in component_help

Getting Started guide

Sep 09, 2005 17:36

Please visit the new version here.

Guide for beginners.

Please read this till the end. We know it's a lot of information to take in so take your time.

We have tried to make this guide as clear as possible. If there's something you don't understand, don't hesitate to comment.

Contents:
Why is Component called Component? What are components?
Who can use Component? What is component_help about?
What are Style System 2 and Style System 1?
How do I customize my layout in Style System 2?
How do I create these layers?
What do I put in these layers?
What do I do with the code given in the tutorial?
What do I do to make my customizations appear?
Is there a way to preview my style without using it immediately?
Can I save the code from my layers?
I use a pre-made Color Theme. Is that a problem?
What do the colors mean in the tutorials?
What are all these # signs? What are comments? What does decommenting mean?
I can't make my code compile! What's the problem?

>>> Why is Component called Component? What are components?

Components are the customizable boxes you can have in your sidebar: the profile where you have your name and your userpic, the page summary, the mini calendar, the links list and the free text box. The navigation links can be displayed either as a horizontal bar at the top of your journal - and is then called the navigation bar - or as a box in your sidebar - and is then called the navigation component.

(top)

>>> Who can use Component? What is component_help about?

Component is reserved to Paid, Permanent and Plus Accounts.
Plus Accounts cannot use the Advanced Customization center. Most of the topics in here will be unavailable to Plus Accounts.
component_help deals with Style System 2 customizations - and especially advanced customizations.
To have more information about Style System 1, Style System 2 and how to switch from one to the other read FAQ #168.
If you're not familiar with the Customize page, read panda_cookie's excellent tutorial.

(top)

>>> What are Style System 2 and Style System 1?

Style System 2 (S2) and Style System 1 (S1) are the two systems used to customize a layout.
Style System 2 is a programming language. In fact it’s a mixture of HTML, CSS and a Perl-based language which is specific to LiveJournal.
Style System 1 is mainly HTML and CSS.
These 2 styles are not compatible meaning that S1 customizations won't work in S2 and vice-versa because things are written differently.
Advanced S2 is considered as more complicated than S1. You'll have to be patient and do things one at a time. You'll have to experiment, make errors, understand what went wrong - with or without our help - and try again. You'll have to be willing to learn.

(top)

>>> How do I customize my layout in Style System 2?

In S2, you have two types of customizations: basic customizations and advanced customizations.
- Basic customizations are those you make via a very user-friendly interface. This interface, which used to be called the Wizard, can be accessed via the Custom Options tab of the Journal Display area. You do not need to know the S2 code to use this interface. It's simply a matter of checking/unchecking boxes, entering text in a box or selecting a value in a drop-down menu.
- Advanced customizations are those you make in the advanced customization area. You do need to know the S2 code to make these. The code has to be inserted into a Layer. If you want to have further information about layers, read FAQ #176.

(top)

>>> How do I create these layers?

Creating a Theme Layer.
It is best to name the theme layer in the following convention: username_layout_customizations (e.g.: kunzite1_component_customizations).
Creating a User Layer.
Same as above except that you select 'User' for type in the create drop-down menu.
It is best to name the theme layer in the following convention: username_layout_user1 (e.g.: kunzite1_component_user1).
Note that this name will be removed if you save using the customization wizard.

(top)

>>> What do I put in these layers?

Let's learn a bit of S2 lingo...S2 can only be two things: functions or properties.

Functions

Functions look like this: function print_free_text () {

i.e. the word "function" then a name then parentheses then an opening curly brace { and a closing brace } at the end.

A function is like a definition of an element of a page. You have a function for the page itself, one for the entries, one for the profile component, etc.

When you want to modify one aspect of these elements, you need to rewrite the whole corresponding function in your theme layer. Rewriting a function is called "overriding" it.

You can't have the same function twice. When you want to modify a function you've already rewritten, you have to rewrite again the one you have.

Most of the tutorials you will find here are rewritten functions.

Properties

Properties are used to easily customize the text, the color, the size, the placement, etc. of certain elements.

Most of these customizations are generally accessible via the Edit Customizations interface.

When you want to write the code itself you use what is called "set commands".

Set commands look like this: set page_summary_text = "Summary";
i.e. the word "set" then a name then the = sign then a value then a semi-colon ;

This means that the text of the header of the Page Summary component will be "Summary."

A list of available set commands can be found here.

(top)

>>> What do I do with the code given in the tutorial?

Identify the layer the code should go into. Theme or User Layer?

Functions must go into 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.

Do not use both a User Layer and the Edit Customizations interface. LJ’s Customization Interface -aka the Wizard - automatically generates a User Layer when you hit the Save button which overwrites your current custom User Layer.
Identify the type of tutorial you're looking at. Do you have to copy/paste it or insert it into something else?

Set commands must generally simply be copied/pasted. Put them at the top of you layer, below the layerinfo lines.

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.

Remember that you can't have a function twice. So, if you've already got it, 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 }

(top)

>>> What do I do to make my customizations appear?

You need to tell LJ to use them. To do that, you're going to create a Style.
Go to the style page and scroll down to the Create box. Type a name. It is best to name the style in the following convention: username_layout (e.g.: kunzite1_component). Then click on the Create button. Choose Component as the layout in the drop-down menu then hit the Change button. Select your custom theme layer and your custom user layer if you have one in the drop-down menus. Hit the Save Changes button. It brings you back to the list of styles. Spot yours and click on Use. Ta-da!

(top)

>>> Is there a way to preview my style without using it immediately?

Yes! Click on the number next to the name of your style. This will link you to a preview of your LJ with your improved layout.

(top)

>>> Can I save the code from my layers?

Yes and you should do so before and after making changes.
PC aficionados can use Notepad (Start/Programs/Accessories in recent Windows OS) 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.

(top)

>>> I use a pre-made Color Theme. Is that a problem?

Yes, unfortunately. The code for the color theme is located inside a Theme Layer and you can't use two Theme Layers at the same time. You need to copy/paste the color codes into your custom Theme Layer or your custom User Layer.

Go to the Layer Browse page, click on the 10 children of Component then on your color theme.
In the new window, you can see a table called Properties Set. Something like this:

kunzite1 created a tool which can generate your color code for you here:
Copy/paste the table of colors into this, type your name, select your layout and the correct layer type and it will generate a complete layer.

(top)

>>> What do the colors mean in the tutorials?

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/maroon - 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/maroon 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.

(top)

>>> What are all these # signs? What are comments? What does decommenting mean?

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.
- - 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 to deactivate them again later on, simply put the # sign back at the beginning of the line. This is called "commenting".
- 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.
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.

(top)

>>> I can't make my code 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 doomtm """ 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. Make sure you have selected all the tutorial and that you haven't pasted it over existing code.

(top)

You have now reached the end of the guide. Thank you for taking the time to read it.

A final note: feedback and thanks make our hearts sing. Seriously. :)) posted by kunzite1.
original draft by uniquewonders.