WSN Knowledge Base
Showcase Demo Purchase Features Services Resources Reviews Support

WSN Knowledge Base 7.0 Introductory Guide

Contents

Installation

To install WSN Knowledge Base, download autosetup.php and upload it to the directory you want to install to. Then visit it in your web browser and follow the instructions on-screen. If you have trouble, just request free installation service to have it done for you. If your web host doesn't meet all the requirements or recommendations, send your host a support request linking them to the autosetup.php page asking if they can tweak your hosting settings accordingly -- most hosts can.

During installation, you're prompted to select a simple or recommended configuration. The simple option is suited to a very simple site which doesn't need many features. The recommended option is the normal recommended configuration which 95% of users should leave selected. No matter which setup mode you choose, you'll still have all the options on your switches page to activate or deactivate later. You should just leave it as recommended unless you're sure.

When installing the 7.0 series or later, you'll see a checkbox to include geolocation data. Geolocation will enable you to autodetect what city the viewer is near, show everything in their timezone, and optionally show toplists of listings near their location.

When prompted to choose english-only or multilingual, make sure that you choose multilingual if your site will ever involve a language other than English -- even if it'll only have one language.

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 Knowledge Base

When the installation completes, you'll be directed to the guided start area. This shows you common getting-started tasks and guides you through them. You can do all these tasks in the regular admin panel too, of course.

At any time, you can use the Admin Panel -> Settings -> Switches page to 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. If unsure, just leave things as they are.

In browsing your site you'll notice the generic site name logo in the corner. You'll want to change this to your own logo or text. You can do this using the "Logo Designer" option (part of the guided start, and also available in the customizations section of the admin panel). You can specify text for a text logo or upload an image you've made for a graphical logo. For more fine-grained control you can go to Admin Panel -> Templates -> Manage Templates and click "Wrapper," which is the first template in the list, to customize all the HTML to your desires. You can also edit templates/yourset/wrapper.tpl offline using your favorite HTML editor and then upload it, if you prefer.

If you know CSS, you can edit your site's stylesheet via the Admin Panel -> Templates -> Manage Templates page option at the top -- or use a text editor on /templates/styles/default.css. To figure out what style element you're looking for, you can check the HTML source of a page in your browser and see what element is referenced with class="elementname" or id="elementname", then search for that elementname in the stylesheet. If you don't know any CSS, have a look at the available pre-packaged themes (Admin -> Templates -> Theme Installer) and see if there's one close to what you'll want. You can also try a WYSIWYG CSS editor tool on the templates/styles/default.css file.

Now you'll probably want to get started creating your categories and listings. You can add them in bulk, or individually with more fine-grained control, at Admin Panel -> Additions -> Add New Items. Once added, manage them with the Admin Panel -> Find and Edit -> Bulk Edit Categories option.

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 should 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 the meta tags scheme on your Admin Panel -> Settings -> SEO page instead of going into the wrapper template. The default content pre-filled into your SEO settings page uses conditionals to say that the meta description tag will be the category description when in a category, the listing description when viewing a listing, and the site description (from Admin Panel -> Settings -> System Settings) anywhere else.

If you want specific categories to have different meta tags which don't follow this scheme, edit the category and specify that in the "Header Insertion" 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 insertion box for the category.

You can change the meta tags scheme to test for any other page and give it a special value. For example, changed to add in a "List of site members." meta description for memberlist.php pages: 

<IF {TID} contains displaylinks>
<meta http-equiv="description" content="{CATDESCRIPTIONSTRIPPED}" />
<OTHERWISE IF {CURRENTURLCONTAINS[action=detail]}>
<meta http-equiv="description" content="{ARTICLEDESCRIPTIONSTRIPPED}" />
<meta http-equiv="keywords" content="{ARTICLETAGSSTRIPPED}" />
<OTHERWISE IF {CURRENTURLCONTAINS[memberlist.php]}>
<meta http-equiv="description" content="List of site members." />
<OTHERWISE>
<meta http-equiv="description" content="{SITEDESCRIPTION}" />
</IF>

If you want to set keywords for categories by editing the category, just go to Admin -> Customizations -> Add Fields and add a 'keywords' category field. Then add <meta http-equiv="keywords" content="{CATKEYWORDS}" /> to the meta tag scheme in the category section.

To change page titles or set titles for new pages, go to Admin Panel -> Customizations -> Page Titles.

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, {ARTICLETITLE} 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. For places that show listings in a tabular format (the member home area, subscriptions and new listings page) there's the Article Columns Bit and Article Tabular Bit subtemplates which you can use to change the look of all those spots at once.

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 [INSERTFILE=]s with your own custom templates also if you wish, wherever you like -- create custom templates at the bottom of the manage templates page and use [INSERTFILE=yourcustomtemplatename] to call them in. This will help you keep your customizations separated from the standard design and easy for you to find, instead of having to search through a long template each time to figure out which part you customized.

Tip: Although there are lots of templates, most people only want to customize up to 6 templates: wrapper, main index, show listings in category, listing details, standard listing bit and submit listing. These few templates control the most important places people navigate through on your site.

Sometimes there are reasons why two listings should show different bits of HTML from each other, 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 {ARTICLEHITS} is greater than 200>
<blink>This is a super-popular listing!</blink>
<OTHERWISE>
Just a plain old listing.
</IF>

To add dynamic data into your templates, go to Admin Panel -> Templates -> Toplist Generator more about toplists).

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

Most people will only use one look for their site. If you don't want a user-customizable look, skip this section. Sometimes, however, you may want to have multiple looks and let visitors choose.

Creating new stylesheets and template sets to give your visitors a choice is easy. Just go to Admin Panel -> Templates -> Manage Templates -> "Create a new stylesheet called" and type in the name of the new stylesheet you want to make. It'll appear in the styles list at the top of the page for editing. The images for it will be in templates/images_yourstylename.

For a new template set, copy templates/default or templates/multilingual (whichever exists, depending on whether you did an english or multilingual install) to a new name. It will 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 Knowledge Base 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 languagenametitle and languagenamedescription, where languagename is replaced with the name of the language. For any languages you don't create special fields for, the regular fields (title, description, etc) will be used -- so you shouldn't create extra fields for your default language, only for your 2nd 3rd 4th etc languages. For a Spanish title you'll use spanishtitle and the Spanish description field will be spanishdescription. For French it'd be frenchtitle and frenchdescription. The values of these fields will be automatically displayed in place of the normal {ARTICLETITLE}, {ARTICLEDESCRIPTION} etc when their language is selected by the viewer. You can do the same thing with category fields by create spanishname, spanishdescription, frenchname, frenchdescription. If there are more fields you want to handle in multiple languages, follow the same pattern -- it'll work with custom fields you add as well.

Some images may 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 Knowledge Base allows you to do two sorts of sponsorship. You can have people pay to promote their listings to a special listing type (or to submit any listing at all) 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) or to register at all.

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 Knowledge Base 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

Your admin panel has two modes: simplified and advanced. Switch between them by clicking the options on the top left in the menu panel. The simplified mode strips things down to the menu items you're likely to want to use, while the advanced mode shows all your options. Use simplified when you're feeling overwhealmed.

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 Topics" 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 "Revenue" section contains everything that makes you money -- sponsorship and ads. You can enter ad code, set up sponsorship levels, review payments, or enter a payment recieved offline.

The "Settings" section contains most of the hundreds of options at your disposal for changing how WSN Knowledge Base 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 type manager helps you set up different types of listings with a special look for each, and also lets you choose which type of listing should appear above or below which other types.

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 categories. Finally we have the integration page, which is useful if you have a pre-existing member system from another script which you'd like to have WSN Knowledge Base use. You can select amongst pre-made integrations or create a new one with the wizard.

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 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 Knowledge Base source code in cases where the modifications directory and plugins aren't sufficient.

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 Knowledge Base. 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 Knowledge Base, you will of course be looking for ways to make each deployment go as quickly as possible. The autoinstaller makes installs quick and easy, and as of the 7.0 series sites keep themselves up to date by default -- so you won't have to waste time running upgrades or risk missing security updates.

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.

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.

Do not hide your site behind an .htaccess password prompt while testing! Doing so will prevent WSN from loading its own URLs, which it needs to do for various things ranging from geocoding to PAD updates to feed fetching and more.

To move from a localhost installation to a live server, see the moving procedure.

Private installations which aren't available over the internet don't require purchasing additional licenses, so you can do as many test directories as you want. If you want to test something on a full copy of your site, use the clone utility at Admin Panel -> Miscellaneous -> Clone Utility.

Using the Knowledge Base

The WSN Knowledge Base Knowledge Base provides detailed articles about most of the script's features and options, along with troubleshooting tips. You can find it at http://www.wsnkb.com/manual.

Getting Support

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