The S2 HowTo Journal

Tips, Tricks, and Tutorials for Basic S2 Customization

Previous Entry Share Next Entry
[paidaccount] [advanced] Using arguments
howto_user wrote in s2howto
Paid Accounts Only
The following tutorial requires creating and editing a custom style, which in turn requires a paid, permanent, or early adopter account. Please read What are the paid account benefits? and How do I buy a paid account? to learn about the paid account benefits and how to buy a paid account.

Pre-requisites:
Knowledge of how to create and use custom layers.
Knowledge of how to create new functions or override the existing ones.


General Information

Arguments can be used to change the appearance of your journal or any of its elements "on the fly". If you wish to generally keep the appearance of the journal the same, but to be able to occasionally switch to a slightly different look or looks, arguments may be the solution for you. To use an argument you will need to modify the URL address of your journal by adding ?.arg_name=value or &.arg_name=value if the URL already contains a question mark, substituting arg_name with the name of the argument and value with one of the values that can be assigned to your argument. Note that due to the way S2 is designed, there must always be a dot before the argument name in the URL.

In the style, you will need to access args{"arg_name"}. Note that args is a member of a Page class, so if you need to access it from a function that is not in the Page class or one of its child classes (like RecentPage, FriendsPage and others), you will need to first define the Page class variable. The following is one way you can use an argument in the style:

function some_function() {
   var Page p = get_page();
   if ($p.args{"arg_name"} == "value") {
	   Commands to execute (if any) if ?.arg_name=value is appended to the URL
   } else {
	   Commands to execute (if any) otherwise
   }
}

You can leave off the section else{ ... } if there are no specific commands you wish to be performed normally. You can also add more options by using "elseif" statements:

function some_function() {
   var Page p = get_page();
   if ($p.args{"arg_name"} == "value1") {
	   Commands to execute (if any) if ?.arg_name=value1 is appended to the URL
   } elseif ($p.args{"arg_name"} == "value2") {
	   Commands to execute (if any) if ?.arg_name=value2 is appended to the URL
   } else {
	   Commands to execute (if any) otherwise
   }
}

The block of code in the curly braces following the "if" or "elseif" statements will be executed if the expression in the parentheses is evaluted to 'true' or in binary '1'.


Example 1—Reversing order of entries with arguments

The following example of use of argument is a slight modification of the tutorial on reversing the order of the entries and is subject to the same limitations. If you use one of the layouts listed in this tutorial, the following code will allow you to view your journal normally or reverse the order of entries by appending ?.reverse=1 to your journal URL. It will also work if you add ?.reverse=true to the URL.

function RecentPage::print_body() {
    if ($.args{"reverse"}) {$.entries = reverse $.entries}
    foreach var Entry e ($.entries) {
        $this->print_entry($e);
    }
}

As this is RecentPage class function, you don't need to define the Page class variable. You may also notice that the section relating to value is left off. If you append ?.reverse=1 or ?.reverse=true to the URL, the expression in the parentheses will evaluate to '1' or 'true' and therefore you can skip the comparison of values.


Example 2—Filtering entries by poster

With arguments it is possible to filter entries based on the poster's username, on what the entry subject starts with, or other criteria. Note that filtering applies only to each individual page; the entries on the page that do not match criteria will simply be hidden leaving just those that do. If no entries on a page match the criteria, none will be shown.

The following code will allow you to filter the entries based on the poster's username in A Sturdy Gesture, Unearthed, Notepad, Boxer and Component styles, but should be adaptable to any style:

function RecentPage::print_body() {
    foreach var Entry e ($.entries) {
        if ($.args{"poster"} != "" and ($.journal_type != "P" or $.view == "friends")) {
            if($.args{"poster"} == $e.poster.username) {
                $this->print_entry($e);
            }
        } else {
            $this->print_entry($e);
        }
    }
}

If this code is added to a community's style, then you will be able to filter both on the Recent entries and on the Friends pages; if it is applied to a personal journal style, then only on the Friends page. To view the entries posted by exampleusername, add to the URL address ?.poster=exampleusername or &.poster=exampleusername if necessary. Keep in mind that the user's entry(-ies) will appear only if he or she posted within the page.


There are many other creative ways in which arguments can be used. It is beyond the scope of this tutorial to show them. To mention a couple:

  • Arguments are useful for hiding certain entries. For example if your friends often post entries with malformed HTML, it is possible to modify your style in such a way that will allow you to hide the troublesome entry or entries, when you see them on your friends page.
  • Another way to use arguments is to create special-purpose pages with your desired content instead of entries, for instance a stylish version of your userinfo or a list of memorable entries.
Contributed by camomiletea.

Comments Disabled:

Comments have been disabled for this post.

?

Log in

No account? Create an account