Introductory Manual for WSN Links 4.1.x

Contents:

Testing

Sometimes you may want to test your site offline, so you can get things configured as you want or try changes without them being public. To do this you can install a web server on your own computer. With XAMPP the process is automatic, just double click the setup file. Read more about installing a web server with XAMPP.

If you wish you can create your whole site on your computer and upload it when you're done (be sure to change the directory url and file path settings in config.php when moving). Private installations which aren't available over a network don't require purchasing licenses, so you can do as many test directories as you want.

Installation

You need to have a database and a user with full access to it. If you have one already feel free to reuse it, WSN does not need a new database. If you don't know your database information, you may need to create it. Contact your web host to ask them about setting up a MySQL database. They'll probably tell you to use a tool such as CPanel to create one. In CPanel you'll find a "MySQL" section where you can type a name to create a database, and you'll also need to type a name and password to create a user who can access the database. Write these down since you'll need the info for the setup process. Once you create the MySQL user, be sure you assign it access to perform all actions on the database (check the "all" box and click a button that says something along the lines of "Grant Permissions," the exact text depends on your CPanel skin).

Download WSN Links from the customers area and extract the files anywhere on your own hard drive. Next, use your FTP client (if you don't have one, see wikipedia's list) to upload the entire directory to the location you want WSN Links installed at. It doesn't matter what directory name you use, and you can upload to the base directory of your site if you wish (if you're new to creating websites, though, realize that most hosts have your actual visible site start in the public_html or www subdirectory of where your FTP client will land you).

Once you've uploaded everything, use your web browser to visit the URL you uploaded to. It'll present you with a setup screen. After you accept the license you'll be presented with a series of questions. Follow the instructions on-screen. If your database info doesn't work, perhaps you've forgotten the prefix which your host automatically prepends to your database and user names. If you still have trouble, just request installation service (the service is free to customers).

During installation, you're prompted to select a simple or advanced configuration. The simple option is suited to a simple link directory which doesn't need any special features. The advanced option is a better starting point for all other cases — generally it's easier to turn switches off than on. Whichever you choose, though, you'll still have all the options on your switches page in case you should change your mind and want one.

If you supply your FTP info where requested, WSN will perform all needed FTP operations for you. If PHP is running as CGI or suExec is enabled then permissions can be handled automatically without FTP, but if your PHP version doesn't support FTP functions you'll see a list of instructions. If for whatever reason you choose not to supply your FTP info even though your server supports FTP, and the setup gives errors indicating it can't handle your permissions for you, then this is what you need to do: Rename your config.php.txt file to config.php. CHMOD it to 666. Set the base installation directory, /admin/, /attachments/, /cache/, /integration/, /javascript/, /languages/, /schemas/, and /temp/ to 777. Set attachments/avatars to 777. Set /templates/styles/default.css to 666. Go into your template set (either templates/default or templates/multilingual), use your FTP client's "select all files" option and set all the files to 666 – make sure you do not CHMOD the subdirectories to 666 while doing this. Finally, set the "custom" subdirectory of your template set to 777 and delete the template set which you aren't going to be using (if a multilingual install, delete default... if an English-only install, delete multilingual).

Some servers need 755 directory permissions instead of 777. Usually this is when PHP runs as CGI. If you get errors using 777, try 755 and be sure to tell it to use 755 from then on during setup or at Admin -> Settings -> System.

WSN uses FCKEditor as its WYSIWYG editing component. If you'd like to use the FCKEditor WYSIWYG editor's ability to upload links while composing a comment/PM/etc, this requires an fckattachments subdirectory of your web root with permissions set to 777 (or 755 on some servers). FCKEditor will attempt to create this automatically but in some instances with PHP running as an Apache module it won't be able to, leaving you to do it manually.

Getting Started With WSN Links

Once you've finished setup, go to your admin panel and find "Switches" in the settings group. The switches page allows you turn features on and off according to the needs of your site. Have a look though the options, click the ? icons by switches you don't understand, and set as desired.

In browsing your site you'll notice the logo in the corner says WSN Links. You'll want to change this to your own logo or text. In your admin panel find "Manage Templates" in the templates group. Then click "Wrapper," which is the first template in the list. Change the HTML img tag there to show your logo. You can also edit wrapper.tpl offline using your favorite HTML editor and then upload it, if you prefer. The image itself, if you want to overwrite it instead of changing the HTML, is at templates/images_default/logo.gif.

Next you'll probably want to change the colors. The self-explanatory color wizard in the templates section allows doing this quickly, and for more detailed work you can edit the stylesheet on the "Manage Templates" page. Click the 'edit' button next to the style selection box at the very top. If you haven't used one before, a stylesheet is basically a list of color and font values (and some other sorts of style details). The colors are specified either by their english names for the few simplest cases, or in hexadecimal (a simple format where the first two numbers are the amount of red, the second two the amount of green, and the last two the amount of blue -- you can use a hexadecimal color wheel if you want). The various elements of the stylesheet are named in ways that hint at what they're for, but you may often be unsure. You can use your operating system's search functionality to find instances of that name in the templates, or just submit your changes and reload to check what changed on your site. Note that you can hard-code color and font values into the templates if you insist, but you'll save yourself a lot of work in the long run if you keep them to the stylesheet with a clean CSS design.

Now you'll probably want to get started creating your categories. Add them using the 'Add New Items' option in your admin panel, and manage them with the 'Manage Categories' option.

If you're translating to a new language, or need to update an incomplete translation, go to your admin panel and click 'Languages' under the customizations area. This page allows you to replace English text with the language you desire. Note the useful 'show untranslated language' option. Also see the multilingual issues section later in this document.

SEO Considerations

If search engine optimization (SEO) is important to you, you'll probably want to turn on URL rewriting. If you're on an Apache server you can have your URLs be like your.com/category-name instead of your.com/index.php?action=displaycat&catid=1 , which is advantageous to your ranking since it puts keywords in the URL. Go to Admin Panel -> Settings -> SEO. On that page you'll find the options for URL rewriting. Where it asks if you want to use it, set it to "yes"... the rest of the options you'll probably want to leave as the defaults unless you know what you're doing. Submit your changes, browse your site and note the URLs.

If you're looking to use meta tags, note that you can set default meta tags on your SEO settings page. Be sure to type out the whole tag, such as <meta http-equiv="description" content="Blah." />. Note that you can use category template variables here, and conditionals as well, so you could do something like this to show one meta description for categories (based on the category's description), another for link details pages (based on the link's description) and another for everywhere else:

<IF {TID} contains displaylinks><meta http-equiv="description" content="{CATDESCRIPTION}" />
<OTHERWISE IF {TID} contains detail>
<meta http-equiv="description" content="{LINKDESCRIPTION}" />
<OTHERWISE>
<meta http-equiv="description" content="Blah." />
</IF>

If you want specific categories to have different meta tags which don't follow this scheme, edit the category and specify that in the appropriate box. Note that you'll have to include any of the default meta tags that you want to remain the same as well, all of them will be replaced if you put anything in the header information box for the category.

Understanding Templates

As already mentioned, at Admin Panel -> Templates -> Manage Templates you can change all of the output which is sent to visitors' browsers. You can customize these templates through the internal editor, or via your favorite HTML editor such as Dreamweaver if you prefer (but if you use a WYSIWYG editor it'll hide things from you, so those aren't recommended).

Templates break up your normal HTML page into two parts. The HTML which you'll wish to have shown on every page is in the "wrapper" template, which consists of both a header and a footer with a <-- BODY GOES HERE --> marker in the middle where the rest of the page will be inserted as appropriate for the location. The wrapper is where most of your customizations are likely to take place. The body content is controlled by all the other non-wrapper templates listed on your templates page. Bits which are used in a bunch of different templates are listed as subtemplates.

Templates are much like HTML pages and accept all HTML, but also have special template variables, controlling comments, template conditionals and includes. The template variables look like {VARNAME} and are replaced with the appropriate value at display time. For example, {LINKTITLE} is listed in templates to stand in for all possible link titles... at display time the title for the particular link being displayed is placed there. The controlling comments look like <!-- BEGIN AREA --> and <!-- END AREA --> (be sure you don't delete these). The content between the beginning and ending comments gets repeated a to-be-determined number of times – for example, <!-- BEGIN REGULAR --> in the 'show links in category' template indicates the area which has all the HTML which will be shown for each link, since all links look the same.

Since there are numerous places where links are shown which may as well look the same, your 'display links' template contains [INSERTFILE=linkbit] – this tells the software to insert everything from the link bit template (linkbit.tpl) here. The link bit is listed in your "sub-templates" section, being called by several different templates in this way. Likewise, custom fields which you add also get their HTML for the add/edit pages inserted into the subtemplates in the 'custom templates' section, which are called into the actual add/edit templates with [INSERTFILE=]. You can do such includes with your own custom templates if you wish, wherever you like.

Sometimes there are reasons why two links should show different bits of HTML, and this is where template conditionals come in. For example, suppose we want to make links with more than 200 views stand out. We do this by testing for the value of the applicable template variable:

<IF {LINKHITS} is greater than 200>
<blink>This is a super-popular link!</blink>
<OTHERWISE>
Just a plain old link.
</IF>

You can read more about template conditionals, and get a list of template variables, to learn how to make them show what you want to show. There are many template variables available which aren't in the templates by default, so you'll need to reference the lists to learn the possibilities open to you.

Adding Styles and Templates

Creating new stylesheets and template sets to give your visitors a choice couldn't be easier. Simply make a copy of your default.css renamed to something else and upload it to your /templates/styles directory and it'll automatically become available as an option. Upload a template set (again start with the default one and modify it) as a subdirectory of /templates/ and it will likewise automatically become available. If you don't want the template set to be seen by non-admins yet, put adminonly in the name (for example, mygreatadminonlytemplates).

To make it easier for visitors to switch between styles and templates (normally they have to edit their profile to switch), you can turn on the style selector and templates selector in your switches (Admin Panel -> Settings -> Switches). The selectors will only show up when you have multiple templates/styles available, so no space is wasted when you only have one option.

You can also add a packaged theme through the theme installer, or create one with the theme packager.

Multilingual Matters

To translate WSN Links to another language, just go to Admin Panel -> Customizations -> Language and begin translating all the items (presuming you've done a multilingual install).

Using multiple languages at once is slightly more complicated. At Admin Panel -> Settings -> Switches you can turn on the language selector to allow visitors to choose a language, but you still have the issue of the links and categories being in the language you (or others) submitted them in. You can work around this by adding new fields to handle the alternate language text. Suppose you want to show the description of a category in both English and German depending on which language the visitor is using. Go to Admin Panel -> Customizations -> Add Fields and add a new category field named germandescription. When adding a category, fill out the German description there. Now, in the main index and show links in category templates, use <IF {VISITORLANGUAGE} is English>{CATDESCRIPTION}<OTHERWISE IF {VISITORLANGUAGE} is German>{CATGERMANDESCRIPTION}</IF> to display the descriptions. Repeat this process for all desired fields.

Numerous links have text written in them, so you may want to have different links depending on the language being used. You can accomplish this by making a copy of templates/images_default named /templates/images_languagename, where languagename is the lowercase name of the language. If you have a language at /languages/italian.lng, the links would go at templates/images_italian.

Sponsorship

WSN Links allows you to do two sorts of sponsorship. You can have people pay to promote their links to a special link type or you can have them pay to promote their account to a special usergroup (whose submissions you may in turn choose to have automatically promoted to a special link type if you wish).

Payments can be handled through PayPal, 2checkout or NoChex. Before you get started configuring the sponsorship options you need to set up instant payment notification (IPN) or a product with your payment processor. For PayPal, login to your PayPal account and click "Profile" in the "My Account" area. Under "Selling Preferences" on the resulting screen, select "Instant Payment Notification Preferences" and set IPN to use http://yourinstallpath/paypal.php in your main WSN Links directory. If you're using 2checkout, you can set the approved url to http://yourinstallpath/2checkout.php when setting up your product. NoChex needs to use http://yourinstallpath/nochex.php.

See the knowledge base for more on link type promotion and usergroup promotion sponsorship.

The Administration Panel

Various items in your admin panel have icons next to them that look like a question mark in a circle. Click these icons to read an link about the feature the spot relates to.

The top section of the menu on the left side of your admin panel is "Common Tasks". This is where you can store the pages of your admin panel which you use the most. On any page you'll see an "add to common tasks" link at the top which you can click to add it to this top section. Once added, the page will contain a removal link. Also note that you can click the title of any section (group of menu items) to collapse the section, saving space if you rarely use those options. Just click the title again to reexpand.

The next section is "Additions", which has everything related to adding items to your site. "Pending Validation" lists submissions which are awaiting your approval. "Add New Items" offers you the chance to add categories, members and links. "Import" offers ways of importing large amounts of link and category data into your site (flatfile, XML).

Next up is the "Find and Edit" section, where you can go to search and modify. "Bulk Edit Categories" provides a convenient way to change a lot of categories at once, while "Bulk Edit Links" and "Bulk Edit Feeds" do the same for links and RSS feeds. The "Search Items" option allows you to do complex searches to locate items which you can then edit. It also offers quick links to view hidden items, deleted items and items whose effective date has not yet been reached.

The "Settings" section contains most of the hundreds of options at your disposal for changing how WSN Links works. "System Configuration" has basic site and server details and allows turning the site off for maintenance. It's also where you supply your customer email and password. The switches page, as already described, turns features (whole categories of options in many cases) on and off and thus has an impact on which settings you'll see available elsewhere. "General" lists settings which don't seem to fit well under all the other labels below.

The "Members" menu contains everything related to member accounts, registration, management and permissions. The settings option at the top (apologies for having settings which aren't in settings) contains member settings such as registration type, banned IPs and the terms of service. The registration defaults allow you to set how a member's profile should be configured if they don't select otherwise. "Manage Usergroups" is one of your most important sections, where you control which usergroups can take advantage of which features -- note that guests are considered a usergroup as well, besides members and administrators. "Administrator Permissions" allows you to limit what any other admins you've created can see. The remaining options are rarely used... "Merge Members" combines two member accounts into one, "Duplicate Members" finds people who have two accounts, moderator logs and notes help you and your team of editors keep track of things, "Show Banned" lists the members you've banned, and "Search IPs" allows you to find what members have an IP or what IPs a member has. "Member Ranks" are little titles along the lines of "novice" and "junior member" which you often find on forums. Finally we have the integration generator, which is useful if you have a pre-existing member system from another script which you'd like to have WSN Links use. This is only important if you're integrating with some other script and there isn't a preexisting integration option for that script — check Admin -> Settings -> Members for a preexisting option.

In the "Templates" section we find options relating to your templates, starting with a few basic settings. The color wizard allows rapid color changes, while "Manage Templates" offers complete control of your templates and styles. The toplist generator helps you create lists of items to place in your templates. Be sure not to leave the "Type the content of what you want displayed" box at the bottom blank – you need to fill it in with HTML and template variables to describe how you want the list shown. For example for a toplist of posts you might type At {COMMENTDATE} {COMMENTPOSTERNAME} wrote: <br />{COMMENTMESSAGE}</a> there for a simple list. The "Template Translation" option should be ignored by most people, but it allows replacing language items in templates with their actual values. The theme packager and installer allow you to create/use themes which can include templates, styles, language and fields.

Next we come to the customizations section. The language page allows you to translate, or just to rephrase various items to be more personalized to your site. "Page Titles" lets you set custom titles for any page of your site, including custom pages. Under "Add Fields" you can create new items to prompt for on submissions. The WSN Codes and Smilies pages let you create and customize markup codes which can be used in whichever fields you select to parse WSN Codes and smilies for at the bottom of your Admin Panel -> Settings -> General page. Finally, the modifications page allows you to generate/apply changes to WSN Links source code in cases where the modifications directory and plugins aren't sufficient.

There are four types of link checkers. The duplicate check makes sure you don't have the same link in your directory multiple times. The dead link check makes sure the sites are still active. The content checker allows you to make sure sites haven't changed to undesirable content such as a domain placeholder or undesired pornography. The reciprocal check makes sure those who've promised to reciprocate your link are still doing so.

The e-mail section begins with the preferences page which allows you to configure various sorts of notification emails, turn MIME (HTML) email on or off, and set a signature to be automatically appended to emails. Next you have the chance to edit the text of outgoing emails (note that if you're using multiple languages you're only editing it for your presently selected language). The "Send E-mails" page allows you to send bulk messages. You can bulk-email link submitters and include link template variables, perhaps telling people to sponsor their link or the like. You can also bulk-email your registered members and include member template variables. Note that if you're sending to thousands of recipients it will take some time after sending for the e-mail queue to process them all (and your site must be live – the queue only processes when people load pages). Also note that members who select in their profile to not receive emails from the administration won't get your bulk messages.

The help section (visible only when help is switched on) allows you to add help items and categories. This way your visitors have a reference to turn to in order to learn about your site and your expectations for them.

The maintenance section is where you go when something has gone wrong or you want to prepare in advance. We have the database backup options, where you can download a mysql backup, set automated backups or restore a backup. These options are no different from mysql's own backup options, and in fact simply call mysqldump via command line. Note that these backup options might not work in safe mode or on Windows hosts – if it doesn't work for you, you can just use phpmyadmin for backups instead and it makes no difference. Moving along, we have the "Regenerate" page. It's most commonly necessary to regenerate after moving categories around. These are the times when it's useful: when your site is listing the wrong number of links in a category, when an link lists the wrong number of comments, when url rewriting is on and a subcategory has become a dead link (due to some combination of moving and renaming leaving an outdated url), when the number of links or comments attributed to a member is off, and when the totals on your front page are off. "Unused Attachments" allows you to reclaim some disk space from files that are no longer needed. The CHMOD utility is almost never needed, but if you've got some files which have been generated by the script such that you can't CHMOD them via FTP you will be able to use this utility to do it.

The final section, cleverly dubbed "Miscellaneous," contains rarely used uncategorized options. The stats page gives you a basic idea of your site's recent activity. The search log shows what people have been searching for. The crons page allows experts to set timed scripts (ignore if not an expert). The advanced options page is useful for bulk alterations, especially replacing one bit of text with another across all templates or language. The censor/replace page can be used as a swear filter or even as an advertising tool to link keywords to sponsors. The "Manage Redirects" page controls what page people are sent to after they take various actions like submitting an link or editing their profile. The "Generate HTML" page allows you to create static HTML copies of important pages, though using the cache system (Admin -> Settings -> General) is far preferable if server load is your concern. The javascript export page allows you to generate javascript files showing the top items from your site, for use on pages outside of WSN Links. The static generation page allows you to make a static copy of any any desired URL (needn't be part of the script) and automatically keeps it fresh every 12 hours.

Strategies For Large Scale Deployment

If you're planning to deploy dozens of copies of WSN Links, you will of course be looking for ways to make each deployment go as quickly as possible.

From the resources area you'll want to download the autoinstaller. The autoinstaller allows you to do an installation without having to waste time downloading and extracting and uploading.

If the sites you're making should all look very similar to each other and/or share the same fields, you'll want to package a theme at Admin -> Templates -> Theme Packager. You can then install that theme (Admin -> Templates -> Theme Installer) at all subsequent sites you create. If category data should be shared you can use PHPMyAdmin to export the categories table data, then bulk-replace the table prefix with your text editor if necessary and import to the next install.

Using the Knowledge Base

The WSN Links Knowledge Base provides detailed links about most of the script's features and options, along with troubleshooting tips. You can find it at http://scripts.webmastersite.net/wsnlinks/wsnmanual410.

Getting Support

Don't be afraid to ask support how to do something.