WSN Directory
Features Demo Showcase Purchase Services Resources Support

Contents

Testing

You don't need to, but sometimes you may want to build or test a site offline (for ease of development, testing upgrades before applying to the live site, or whatever). To do this you can install a web server using XAMPP.

If you're moving from a localhost installation to a live server, be sure to change the directory url and file path settings in config.php. The usual moving rules apply.

Private installations which aren't available over the internet don't require purchasing licenses, so you can do as many test directories as you want.

Installation

If you don't want to be bothered with installation, have it done for you.

Download autosetup.php from the customers area and upload it to your website. It doesn't really matter where you upload as long as it's a directory which is accessible on the web, but its default assumption is that you've put it a directory above where you want the install to be. You can install anywhere.

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, or perhaps you've forgotten to grant that user access to the database. If you still have trouble, just request installation service (free to customers).

During installation, you're prompted to select a simple or advanced configuration. The simple option is suited to a simple listing 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 to activate or deactivate.

If you supply your FTP info where requested, WSN will perform all needed FTP operations for you. If PHP is running as CGI or suPHP is enabled then permissions can be handled automatically without FTP, and WSN will not ask for FTP info.

Getting Started With WSN Directory

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 Directory. 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.

Next you'll probably want to change the colors. The color wizard in the templates section allows rapid changes, 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 absolutely insist, but you'll save yourself many long hours of maintenance 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.

To get your directory filled up with listings you can use the various importers on the impoters page. The DMOZ importer, for example, allows you to import contant from dmoz.org's vast directory (subject to the terms of their license).

If you're translating to a new language, 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 which brings up everything you still have left to translate. 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 use URL rewriting. If you're on an apache server capable of running it, it'll automatically turn on when you install. This allows you to have URLs 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. In case you want to change some of the options, go to Admin Panel -> Settings -> SEO. On that page you'll find the options for URL rewriting... though if you're not sure what you're doing, leave them alone.

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 listing details pages (based on the listing's description) and another for everywhere else -- the default value does this already.

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.

For the rest of the SEO options, just click the help icons next to them on the SEO settings page.

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 listing titles... at display time the title for the particular listing 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 listings in category' template indicates the area which has all the HTML which will be shown for each listing, since all listings look the same.

Since there are numerous places where listings are shown which may as well look the same, your 'display listings' template contains [INSERTFILE=linkbit] – this tells the software to insert everything from the listing bit template (linkbit.tpl) here. The listing 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 listings should show different bits of HTML, and this is where template conditionals come in. For example, suppose we want to make listings 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 listing!</blink>
<OTHERWISE>
Just a plain old listing.
</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 Directory 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 listings and categories being in the language you (or others) submitted them in. You'll need to add new fields to handle the alternate language text. Go to Admin Panel -> Customizations -> Add Fields and add listing fields named [languagename]_title and [languagename]_description, where [languagename] is replaced with the name of the non-english language. Repeat for each language. The values of these fields will be automatically displayed in place of the normal {LINKTITLE}, {LINKDESCRIPTION} etc when their language is selected by the viewer. Then add category fields [languagename]_name and [languagename]_description. If there are more fields you want to handle in multiple languages, follow the same pattern.

Numerous images have text written in them, so you may want to have different images 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 images would go at templates/images_italian.

If you make use of the tagging system, you'll want to enable some extra characters for your language beyond the alphanumeric ones it accepts by default. You can do this by specifying $keepchars in tweaks.php.

Sponsorship

WSN Directory allows you to do two sorts of sponsorship. You can have people pay to promote their listings to a special listing 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 listing 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 Directory 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 listing 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 article 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 listings. "Import" offers ways of importing large amounts of listing 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 Listings" and "Bulk Edit Feeds" do the same for listings 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 Directory 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. The localization settings help you make everything fit with the conventions of the country you live in. "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 Directory 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 Directory source code in cases where the modifications directory and plugins aren't sufficient.

There are four types of listing checkers. The duplicate check makes sure you don't have the same listing 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 bounce detector allows you to avoid repeatedly sending mail to addresses which have died. The "Send E-mails" page allows you to send bulk messages. You can bulk-email listing submitters and include listing template variables, perhaps telling people to sponsor their listing 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 listings in a category, when an listing 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 listings 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 listing or editing their profile. The javascript export page allows you to generate javascript files showing the top items from your site, for use on pages outside of WSN Directory. 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.

Notes For Big and Busy Websites

If your website is exceptionally popular or has an exeptional number of categories/listings, be sure to read the KB's tips on handling large sites.

Strategies For Large Scale Deployment

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

The autoinstaller which you download from the customers area makes installs quick and easy. You'll want to download the the multi-site updater tool from the resources area. This allows you to run the automatic upgrades of all your sites at once and review a combined page of results (which will list templates needing alteration or the like).

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 Directory Knowledge Base provides detailed articles 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. That's what I'm here for.

Features Showcase Purchase Services Resources Support
Valid XHTML 1.0 Transitional
© 2010 by Paul Knierim
All rights reserved