---------------------- WSN Links Version 2.43 ---------------------- Requirements: PHP 4.06+, MySQL 3+, cookie-enabled browser (for administration login, and member logins) If you encounter a bug, please report it at http://forums.webmastersite.net/index.php?act=SF&f=19 to get a quick fix for yourself and also help improve the next WSN Links release. You can also make feature suggestions or ask for help with any aspect of the script at that URL. ---------------------- New Install (not uprade) ---------------------- To install WSN Links 2.43: (1) Extract files from the ZIP. (2) Upload all the extracted files to your hosting space. (3) Rename config.php.txt to config.php, and then CHMOD 666 that file. (4) If you wish to use online template editing, CHMOD 666 all files in your /templates directory and it's subdirectories. (Do NOT chmod 666 the directories themselves, just the files.) (5) CHMOD 777 the directory 'attachments'. (6) If you don't already have a database created, create one using your host's provided tools. (You may use an existing database if you like, if you have one. If you plan to integrate your member system with another script, install in that database.) Also be sure you've set up a username and given the username access to this database. (7) Using your web browser, visit setup.php (in the directory you uploaded it to). (8) Follow the instructions on screen, supplying your database info and creating an administrative username and password -- be sure to write down your password as you'll need it to administrate your links. (9) Visit index.php to browse your links directory as a visitor, or /admin/ to administrate it. You may wish to update your settings (admin/prefs.php) to customize them to your site. ---------------------- Upgrading from previous versions (no data is lost in any of these conversions) ---------------------- Note regarding all upgrades: config.php is the one file you need to keep and not overwrite, as it contains the information for how to access your database. The file in the download is named config.php.txt specifically to prevent you from accidentally overwriting your config.php during an upgrade. If by chance you've renamed it to config.php to do some testing on localhost, be careful not to upload this file over your existing one. If you do overwrite your config.php, however, see the FAQ thread on the WSN Links discussion forum for information on how to re-create it. You can do a simple and quick upgrade by overwriting all files except attachments (including templates (be sure to use /templates/default to overwrite your /templates directory)) and then running the appropriate upgrade scripts in ascending order. (To upgrade from 2.10, for example, run upgrade2.1-2.2.php and then upgrade2.2-2.3.php and then upgrade.php.) However, if you've customized your templates a lot and wish to only lose the minimum number of templates which you have to lose, follow the procedure below to see which templates to overwrite: To upgrade from 2.42: (1) Overwrite all files EXCEPT your attachments directory and templates directory. (2) Overwrite the 'admin' subdirectory of your templates directories. (3) Overwrite, or adapt to include {INCOMPLETE} somewhere, these templates: editmembers.tpl, edit.tpl, editcat.tpl, editcomments.tpl (4) Overwrite searchadvanced.tpl (5) For MULTILINGUAL versions, overwrite your viewcomments.tpl file. (6) IF you're using member system integration to integrate with another script (if not, skip this step): the integration system has changed to now be run in the admin panel settings area instead of requiring file edits, so you will have to temporarily switch back to the normal wsn links members table for upgrade. Be sure that if you deleted your members table you re-create one (see forum for help if needed). Then follow steps 8-10 in this upgrade procedure, then go to your settings and select your integration system from the list. (7) Visit upgrade.php in your web browser and run the upgrade. (8) If you allow attachment uploads, update your usergroup permissions to reflect this and adapt your suggestlink.tpl to use the new uploads code. To upgrade from 2.40: (1) Overwrite all files EXCEPT your attachments directory and templates directory. (2) Overwrite your viewprofile.tpl template. (3) If you're using attachments, change
section of your header template and replace 'templates' with {TEMPLATESDIR} on the stylesheet line, or overwrite your /templates/header.tpl with the new one. (5) Either replace your /templates/displaylinks.tpl, or edit your old one to incorporate the related links area near the top, the option to order by last edited date at the bottom, and the inclusion of the last edited date on the link listings. (6) Overwrite /templates/suggestlink.tpl and suggestcat.tpl (7) Run upgrade2.2-2.3.php in your browser. (8) Update your usergroup permissions and settings via your admin panel, and enjoy. To upgrade from 2.1x to 2.2x: (1) CHMOD 666 your config.php file (2) Overwrite files except for your templates directory. (3) Replace all the files in your templates/admin directory (4) Replace /templates/search.tpl, /templates/register.tpl (5) Place {CATHEADERINFO} in the section of your header template and replace 'templates' with {TEMPLATESDIR} on the stylesheet line, or overwrite your /templates/header.tpl with the new one. (6) Either replace your /templates/displaylinks.tpl, or edit your old one to incorporate the related links area near the top, the option to order by last edited date at the bottom, and the inclusion of the last edited date on the link listings. (6) Either replace /templates/suggestlink.tpl, or adapt your old one to include the registration option if you wish to have that option, and in your templates directory upload login.tpl, register.tpl and showvotecode.tpl. You'll also want to incorporate the login/logout link code from the new footer.tpl... place it in whatever template you like. (4) Visit upgrade2.1-2.2.php and supply your prefix and password. To upgrade from 2.0x to 2.1x: (1) Overwrite old files with those from the new zip, **except for the templates directory**. (2) In your /templates/admin/ directory, overwrite admin/main.tpl, admin/password.tpl and admin/prefs.tpl with the new versions. If upgrading from 2.00 or 2.01, also overwrite admin/edit.tpl. You may keep your customized versions of all other templates from version 2.00+. (3) Visit upgrade2.0-2.1.php and supply your password. That's all. Note, upgrading from 2.00 on up will not damage any custom fields you may have. To upgrade from versions 1.x directly to 2.4 (you will not need any of the other upgrades): (1) Delete all old files **except config.php**. You must delete all of your templates. (2) CHMOD 666 config.php (3) Upload all files and directories extracted from the zip file. (4) CHMOD 666 your config.php file. (5) CHMOD 666 all the files in your templates directory and templates/admin directory to allow online editing. (6) Visit upgrade1.x-2.4.php in your web browser, to import your data to the new version. (7) Update your settings through your admin section (now located at /admin/, instead of the old admin.php)... you will need to click 'update counters' on your admin panel to get category totals displayed correctly. (8) Customize your templates and enjoy. --------------------------------------------------------- Important Note: Limiting Levels for the Category Selector --------------------------------------------------------- If you decide to limit the number of levels in your category selector in order to prevent clutter (see the settings page in your admin section), be aware that you must change your 'suggest link', 'suggest category', 'edit link' and 'edit category' templates. These templates make use of the category selector, and so submitting a new link or subcategory to a category deeper than the number of levels you allow would not work (it would force you to select a higher level category). To fix this you will have to make the tradeoff of taking away the ability to select the category manually on these pages. These are the changes you will need to make if you limit the levels of the category selector: In suggestlink.tpl, change to . In suggestcat.tpl, change to . In edit.tpl, change to . In editcat.tpl, change to . ---------------------- Administration ---------------------- To login to your admin center, use the username and password you created during the setup process. After you login, you'll see all the settings you can change. At the top of the screen you'll see any links, categories, etc. submitted by users which are awaiting validation. Below that are the main administration links, where you can change your settings, language, templates, etc. Be sure to change your settings after you install. If you want to add a new field to be displayed for your links or categories, you can do this here as well -- be sure to use one word field names only, as a space will cause errors. Further down you have the option of selecting links, categories, comments or members to edit. Select terms from the dropdowns and write in values to form the query you want, and if there are multiple matches you'll then have a chance to select which one you want. Editing also allows you to delete. ---------------------- Customizing ---------------------- Basic colors and font can be changed all at once by editing style.css, which is in your /templates directory. Familiarity with CSS is useful, but the file is organized so that playing around with the existing color values should make it easy to change the colors of page elements. WSN Links is fully customizable. 100% of HTML displayed to visitors (as well as most of the administrative HTML) is in template files, which can be edited using any text editor or through the online interface. These files are stored in your /templates subdirectory, and are named with the .tpl extension. To edit templates, either use the interface in your admin section or use your favorite text or HTML editor to load the .tpl file which you wish to edit as plain text. You can edit this just like any other HTML, but with one difference: there are template variables involved. Template variables look like this: {VARNAME}. Their function is to serve as a place holder for the dynamic content which the php files will generate. For example, a variable {LINKURL} in a template might be a place holder for the URL of each particular link in your directory. Customize the HTML around this by imagining an actual URL... for example, you could use the HTML {LINKURL} to display a URL in italics with a hyperlink to link the visitor to the page. In your online template editing section, you can click to view a list of some of the template variables. Experiment, see what they do. You may use multiple template sets simply by uploading the files and then adding through the 'manage templates' area of your admin section. ---------------------- Custom Templates ---------------------- If you wish to add custom templates, this is a simple process. You can make an existing WSN Links page use a template other than the normal one, or you can add a new page which will use the WSN Links header and footer but will be otherwise new content. In notepad or some other text editor, simply create a file and give it the name you want, then upload it to your templates directory. Use it anywhere by adding &custom=yes&TID=yourtemplatefilename to the URL. This works for any .tpl file... for other extensions, use &custom=yes&TID=yourtemplatefilename&ext=yourotherextension For a new template where the file is called example.tpl, for example, you might use http://yoursite.com/links/index.php?custom=yes&TID=example&ext=tpl If you want a specific category to have a unique template, just edit that category and fill in the template name in the 'custom template' field. If for whatever reason you don't want the header and footer to show around your custom template, use &headerfooter=no at the end of your URL. Add these custom templates to the template editing section of your administrative area by editing the 'templates' template... put the link to the custom templates in the same form as the URLs of the others, but with the TID being your template file's name. Note that to indicate a subdirectory there you'll need to use - instead of / ---------------------- Toplists ---------------------- You can place a toplist in any template (including custom templates), excluding in the adminstrative section. Use this code: links,rating,10,descending,votes>5,0 {LINKTITLE} The config section there controls the type of toplist you get: type,field,number,order,condition,start. The last two items are optional, leave them off if you don't want to filter and you want to start at the beginning. The example config line above makes a toplist of links ordered by their rating, showing 10 links in descending order, excluding any links which have less than 5 votes, and not skipping past any of these defined results. The first term in the example specifies that this is a list of links. You could put comments or categories there instead to make a list of those. The 2nd term specifies the field which we're ordering by... in this case, the link rating. The third term specifies that we want to display the top 10 -- a list of 10 links. The fourth term says that we want to start with the highest rating and go down... if we wanted to display the lowest ratings instead (for some reason), we'd use ascending. The fifth term is optional -- you don't have to use it, but if you do it lets you filter the display by a condition. In this example, we've filtered to only show links with more than 5 votes. The sixth term is also optional, and lets you specify to skip over x number of results. If you wanted to split this into multiple pages, for example, you could want to start at 10 for the 2nd page. If you want more than one toplist on the same page, the 2nd one must use the number 2 in the beginning and end declaration... and the third uses 3, et cetera. If they're on different pages this doesn't matter and you can just use 1. If you want to show randomly selected links, use rand() in place of the field. For example, links,rand(),10,ascending would display 10 random links. Be careful to check after changing a toplist to be sure it worked. If you make a little mistake, you'll end up with errors on the page... thus, always be prepared to change it back and don't assume that you couldn't have made a typo. Of course it won't cause any problems that can't be fixed by simply changing/removing the toplist, but it's not good for visitors to see such errors. ---------------------- Link Groups ---------------------- By default, you have two types of links: regular and reciprocal. Suppose you wish to create another group called 'mylinkgroup'. First, go to your admin panel and click 'manage settings'. Scroll down to 'Link Groups' near the bottom. Add a comma after the 'regular,recip' you see there, and type your new group (do not leave a space). In this case, we'll now have 'regular,recip,mylinkgroup'. Save your settings. Next, edit your 'show links in category' template. In order to create a unique style for this link type (by default it shows with the same HTML as regular links), copy the style which has been used for regular and recip links and change it to fit what you wish for your new group. For example: Extra special type of link: {LINKTITLE}
---------------------- Custom Permissions ---------------------- You may wish to restrict a page to only be visible to particular usergroups. For example, you may have a custom template page which you only want registered members to be able to view. This can be done very simply by placing a comment like this at the very top of the template: Change 2,3 to the numbers of the usergroups you wish to allow to view the page. Separate each usergroup number with a comma, no spaces. By default, of course, pages are visible to all groups (except where usergroup permissions specify otherwise). ---------------------- PHP in templates ---------------------- PHP can be used in any template, including custom templates. Simply put at the end of your PHP section. The one main point to be aware of is that you should not put any database or password info in this templated php -- if you need to use important info, save it in a file with a .php extension and then include that file into your template. Only files with .php extensions are safe... it would be easy for anyone to come along and read your template file by looking for /templates/yourtemplate.tpl on your site. To use any preexisting variables from the script you will have to declare them as global first (example: global $onevar,$another;). When using your own variables, as of course the majority of users would be, this is a non-issue. ---------------------- File Uploads ---------------------- Since it's not useful for every directory, the file upload option is not shown by default. To enable uploads, go to your admin panel and select "manage usergroups". Check the "can upload files" box for each group you wish to allow to attach files. If all the uploaded files are going to be images, you may wish to automatically display the images whenever one is attached. Edit your 'show links in category' template and find " just below it. Note that if PHP is running in safe mode you may have some troubles with uploading. Also note that you must specify the path to your attachments folder, in your settings, before uploads will work. ---------------------- Integrating Member Databases ---------------------- If you wish to use an existing member database, such as one from a forum, you will need to install WSN Links in the same database as the script whose member system you will be using. Then, have a look at the pre-made integration scripts in your 'integration' subdirectory. You may adapt these files to integrate with other scripts, if you can follow the php code well enough to see what values you'll need to change. To make your new integration script selectable from the settings page, edit the lists at the top of admin/adminfunctions.php: $integrationscripts = ", vbulletin, invision, phpbb"; $integrationscripttitles = "None, vBulletin 3.00, Invision Board, phpBB"; To add on an OpenBB convertor which you have named openbb.php, you would change the above to $integrationscripts = ", vbulletin, invision, phpbb, openbb"; $integrationscripttitles = "none, vBulletin 3.00, Invision Board, phpBB, OpenBB"; If the script you're integrating with uses a method other than md5 to encode passwords, you will need to make an encoder file similar to the one for vBulletin which has been provided. You must name this with the same name as your main integration file plus 'encoder', the same naming style as used with the vbulletin example. Please note that you will need to remove the edit profile and register links, the memberlist link, and the profile links from your templates (the links are in footer.tpl, main.tpl, and viewcomments.tpl respectively) -- those features will not function correctly when you're using the foreign member database, it's up to the script whose member database you're using to handle those tasks. You may wish to replace the links in the WSN Links templates with direct links to the other script's registration, memberlist, profiles and profile editing sections. If the username field is not 'name' you will also need to change {MEMBERNAME} in your footer tempate to {MEMBERNEWNAME} (where NEWNAME is whatever the name field has now become). If you wish to be able to track the number of links, comments, hits in and hits out per member while using a custom member database, you must add these fields to your script's database table: links, comments, totalhits, totalhitsin Then add these lines to your integration script below "$newemail = 'email';": $newlinks = 'links'; $newcomments = 'comments'; $newtotalhits = 'totalhits'; $newtotalhitsin = 'totalhitsin'; The same procedure applies if you're using multiple languages and template sets and wish to allow users to select those. Note: If you're integrating with another WSN script (WSN Guest, etc.) then registration should work seemlessly and if you add $newlanguage = 'language'; and $newtemplate = 'template'; in addition to what's described above then all fields will work and the member list and profiles will function just as if it were the natural members table. Of course if you do this you must first make sure your template and language names are the same in both scripts. ---------------------- Submitting to multiple sites ---------------------- A few people may wish to allow visitors to submit the same link to multiple links directories at once. To make this possible, just put this HTML somewhere between in your suggestlink.tpl template: List your sites in there. Use the path to the WSN Links directory, '/' included, as in the example. Do not list the current site on the list -- that's automatically submitted to, listing it again would get it submitted twice. Note that this will of course only work if all of the links directories involved are WSN Links directories. ---------------------- Moving config.php ---------------------- For extra high security, you may wish to move your config.php file outside of your site's root. (If your web server is running properly it should be protected anywhere, but if there's a problem with the server at some point your config file might be exposed.) You'll need to make just two file edits after moving the config.php file. Near the top of start.php and admin/adminstart.php, correct the path for the require 'config.php' to match where you've put the file. Use ../ to indicate going up one directory level. ---------------------- Other Documentation ---------------------- If you're wondering how to do something or don't understand a feature, be sure to check the online HTML manual at http://www.iamkizer.net/wsn_manual/ . The manual was created and is maintained by Kizer, and is getting a bit out of date, but might answer your question. Failing that, ask around on the forum: http://forums.webmastersite.net/index.php?act=SF&f=19 ... be sure to check the forum FAQ and do a search of previous posts as well. If you've encountered an error, be sure to read the pinned bug report procedure thread since without the information requested there it is impossible to know anything about the nature of the error. (The php/mysql warnings are not useful, since they always point to database.php regardless of where the real problem is.) ------- Thanks for purchasing WSN Links