WSN Gallery - Cobrandingguide

It's strongly recommended that the server on which the release tools and development copies are placed should have suPHP/CGI mode, rather than plain apache mode PHP, in order to avoid permissions issues. If the server where the release tools are placed runs Microsoft Windows, you'll need 7-zip installed on it.

You may -- or may not -- want an HTML and/or PHP editor. If you're on Linux or BSD, gPHPEdit is a good simple PHP editor and Quanta Plus is a full web development program for HTML, PHP or most anything. IBM's Eclipse also has a PHP plugin, though it's probably overkill here. The normal text editors of KDE and Gnome (kwrite and gedit) also have syntax highlighting and enough features to get by. If you're in Microsoft Windows, Notepad is rather lacking so you'll probably want to look into something like Notetab. Using Macromedia Dreamweaver is discouraged -- it's been known to alter templates in odd ways to break things (might have been user error, no way to know when I haven't used it myself, but it seems to be dangerous). If you're on a Mac, you probably have a favorite editor already or can run the Linux ones in X11 mode.

2. Setup

On request, I'll set up everything for you on your server and do future updates to the release tools on your server. That's by far the easiest way to handle things. These instructions are still provided just in case you'd rather work on your desktop. Follow these steps:

Install a copy of WSN Links to http://localhost/yourscriptname/. Do a multilingual installation -- even if you have no intention of making translations, working from multilingual will allow your users to do so and will make it easier to share templates if you do multiple scripts. Easier-to-read english-only templates are automatically generated at time of release, requiring no work from you, whereas multilingual templates can't be derived from english-only.
Cut and paste the /distributables/, /releasetools/ and /site/ directories from the cobranding package to your localhost directory (NOT within the WSN Links install). If you don't have a sales website yet: upload the contents of /site/wsnlinkssite/ from the cobranding package. If you do already have a sales website, upload site/filecomparison/ to it. This will be used by the file comparison tool which helps people update their tempates to new versions. We'll deal with the sales site in more detail later, in section C.
Rename releasetools/wsnconfig50.php.dist to releasetools/wsnconfig50.php
Open releasetools/wsnconfig50.php in your text editor. Change the values fit your environment. The paths (/var/www/x/) are the file paths, which on Windows will be c:/some/thing/ -- use forward slashes rather than backslashes (both work on Windows, and forward avoids irritating escaping issues). The FTP information is to allow the release tool to upload to your website. The $downloadfile value can be left as it is or changed as you like, it's just a random filename to prevent non-customers from guessing where the .zip is. Finally, you need to fill out the administrator login for the localhost WSN you installed in step 1, and also your WSN Links customer downloads area account login (which is needed so that the cobrander updater tool can retrieve new versions of WSN Links to sync your script with).
Bookmark or create a desktop shortcut to http://localhost/releasetools/. That page will serve as your interface to all the tools.

Section B: WSN

1. Changing Basic Info

WSN files are designed to serve many purposes, since the same source is used for WSN Links, WSN Forum, WSN Gallery, WSN Classifieds and WSN KB. The file scriptinfo.php contains the essential data you may find it useful to change. You will want to update $version to reference your script's name (the number is set by the release automation tool so you don't have to worry about it each time), and of course $fullscripttitle should be changed to the name of your co-branded script. $manualpath can be changed to point at your own script's customized knowledge base rather than at the generic WSN Links knowledge base (this is discussed in a later section). There's also a $pathtoorigtemp value which specifies where the 'show original template' option in the template editor should load the default template from -- this should be the filecomparison directory of your sales site, which I'll have set up and specified in the scriptinfo if you requested setup.

Changing the template variables is also possible here, but it's inadvisable since it's an extreme pain to update the templates accordingly (it's not as easy as bulk-replacing since several admin panel setting template variables start with {IMAGE). You'd also have to update all documentation, so it's wiser to just leave it as {IMAGE, {CATEGORY, {COMMENT etc.

The $simpleswitches list allows you to choose which switches will be on when someone selects to do a simple installation during setup. Since they want something simple, you shouldn't list many here. The default is fine.

You should leave everything else as it is, be sure not to change the $scriptname = 'wsnlinks'; line -- that value is used by the script to decide whether it should execute Links code, Forum code, etc. The value is not displayed anywhere, except for being used in a setup template as the default tables prefix where you can easily write it out of the template. The $nameforlink etc values can be translated in languagextras.php, not scriptinfo.php.

2. Changing Default Settings and Incorporating Custom Fields

Don't over-think this, and don't try to edit sql/wsn files manually (they aren't made for manual editing, they're autogenerated). Just configure your directory the way you want it to be configured for all users. The release automation tool will take care of writing the schemas to make all your current settings, fields and the like become the defaults for a new install (or additions on upgrade). There's nothing else to it.

3. Miscellaneous Language

Some text like admin panel redirects and error messages isn't in the templates or language file. All such text is in the file includes/languageextras.php, so if you wish to customize it look there. This is of course more likely to be important for people doing translations, though there are concievably other reasons to want to re-word the items there.

5. Overview of Translating

To fully translate WSN for cobranding purposes, you need to translate these areas:

The language pack, which controls all user-side language and which you should edit at Admin Panel -> Customizations -> Language or if you prefer a text editor then via the /languages/ directory.
The admin panel templates, in /templates/admin/, which you can also access at Admin Panel -> Customizations -> Templates by clicking "show" next to "Admin CP Templates".
includes/languageextras.php, which contains various language shown to admins only and thus not worth cluttering up the regular language files with.
Other files to translate: readme.html, license.txt, filelicenses.txt, servertest.php

Be sure to set your character set encoding with the language item 'charset'.

Note that the "english-only" installation option will become your language only, insted of english.

Section C: Sales Website

1. The Downloads Area

You got an email with information for accessing the WSN member downloads area, and your customers will need to get similar emails. The member downloads area is simply an installation of WSN with a few minor template customizations and one field added.

I'll do this for you to make things easy, but here's a setup procedure. On your sales site, install a copy of WSN or your cobranded version in the downloads subdirectory. Upload the customized templates provided in this package at site/downloadtemplates to your templates/default directory. Go to the add fields page and add a new integer member field named 'licenses' . Create a category for the downloads, and edit the category to set custom/downloads.tpl as its custom template. Then go to Admin -> Settings -> Categories and set it to remove the main page and skip to that category. Next, edit the usergroup permissions to disallow guests from viewing. Finally, update the templates to fit your branding. Be sure to customize the support contact form so that it sends emails to you instead of to WSN's support email -- the support contact form is simply WSN FormEmail, download it and see the readme file included in it for instructions.

2. Payment Processing

For manually giving someone a license, you have an option on your cobranding tools page. For automatic processing, you'll find the file paypal.php in the 'site' subfolder of this guide package. Paypal.php can be used to automatically add customers who purchase through paypal. You will need to configure your paypal account to activate IPN (Instant Payment Notification) and use this script as its IPN url. Open up the file in your text editor and insert your database info, email text and other requested items in the configuration area at the top.

3. The Knowledge Base and Manual

You'll probably wish to run your own copy of the WSN Links knowledge base and customize the article text to describe your script's functions better. This, again, is something I'll set up for you.

You'll notice that the KB uses [links] instead of links, [WSN] instead of WSN, et cetera, and then uses the censor to insert the proper value. This is so that Links, Gallery, KB and Forum can use the same manual. Also, the 'only show articles where' option is used along with a scripts field to filter out articles that don't apply to the script whose manual is being viewed. An [internalarticle=x]title[/internalarticle] WSN code is used for internal linking so that it links to the correct copy of the manual.

Your cobrander update tool will allow you to keep track of additions and changes in the knowledege base so that yours stays current.

In addition to the knowledge base, there's also an introductory manual in HTML format. Get the latest copy at http://scripts.webmastersite.net/wsnlinks/manual50.html, adapt and place it where you want.

4. Postal Code Data Files

WSN's ZIP code range searching functionality relies on a very hefty database of latitudes and longitudes for each postal code. Pre-including this database would make the script unreasonably large and would cause the installation to timeout and hit memory errors. So, instead, whenever someone turns on the ZIP range searching they're prompted to load the data files for the countries they need.

The scriptinfo.php $postalcodesurl line references the data location. It's strongly recommended that you keep it as $postalcodesurl = 'http://scripts.webmastersite.net/postalcodes/'; to avoid the hassle of trying to mirror all the data properly. If there's a country you'd like added, find a free database with latitude, longitude and postal codes and I'll add it.

5. Everything Else

In case you want a quick and easy way to create your whole sales site, the files that run wsnlinks.com been included in this package's site/wsnlinkssite directory -- you must change the graphics and style to make your site visually distinct, though. You need to open wsnlinks/scriptinfo.php and set values as appropriate. This structure is set up for running all the WSN script sites, so generic text is in the base content directory while specific-script text overrides that in the content directory for the script.

To change the design of the sales site, edit header.txt and footer.txt to place your own HTML in them. Also see the stylesheet at default.css. To edit the content of specific pages, edit the .txt files in the 'content' subdirectory. Of course you need to change each of those files so that you're using your own content instead of that of wsnlinks.com -- no duplication allowed (but translation is fine).

Section D: Upgrading and Releasing

1. Upgrading Advice

An unstable co-branded version could cause headaches, especially with the delays in support likely to be associated. Stability should be a high priority for you. That in mind, it's probably best to wait a bit before moving to a new series. I'll do series updates for you to make sure they go correctly. Regular in-series updates are easy, you can do them yourself.

2. WSN Automation Tools

Automation tools for doing upgrades and releases have been provided to you. You can find them linked near the top left of your releasetools control page. Both use info you set in releasetools/wsnconfig50.php.

3. Updating

What the automation tool does for upgrades:

It takes your cobranded script and brings it up to date with the current WSN version. It leaves your templates unchanged but gives you instructions for updating them, along with instructions for languageextras.php and servertest.php. It can also tell you about new manual entries.

What it DOESN'T do:

It doesn't auto-apply template changes. It doesn't auto-retrieve new knowledge base entries until you tell it to. It doesn't save PHP customizations unless they're in the modifications or plugins directory (if you want to do PHP customizations, please contact support to discuss how to make them upgradable).

4. Releasing

What the automation tool does for releases (it's not important that you understand this, it's just to satisfy curiosity you may have):

It prompts you to update the upgrade instructions. It sets the version number for you in scriptinfo.php and at the top of the readme.html. It copies languages englishonly/fullenglish/English/deutsch (if existing) into the /setup subdirectory (more can be handled on request). It creates the setup and upgrade schemas so that your current fields and configuration are what your users will get. It creates the stylesheet schema based on your templates/styles/default.css so that your users will get their style upgraded with anything new you've added. That's all it does to your existing directory, but it then creates copy in the distributables directory. In that copy it empties out attachments, attachments/avatars, languages and javascript. It renames config.php to config.php.txt. It creates a .zip and a .tar.gz and uploads them, along with file comparison and original template data, to the appropriate places. Finally it writes the new version number and release date to your website.

5. Updating the Automation Tools

If a revision of the automation tools comes out, I'll be happy to apply it for you. If you want to do it yourself, just overwrite your releasetools directory with the new one. The distributed config file has a .dist appendage to prevent it from overwriting yours. You'll only need to update the config file if specifically directed to.

6. Release Notes

The admin panel lists changes since the user's current version. These changes are drawn from the releasenotes.txt file on your site. Make the file ascending, lowest version number first, and start each version list with "4.1.8:" (where 4.1.8 is replaced with the actual version number).

If you want to let people look at the release notes with a link, tack format=html onto the query string. For example, http://scripts.webmastersite.net/releasenotes50.php?script=wsnlinks&format=html.

Releasenotes50.php and .txt are in your /site/ subdirectory of the cobranding tools and will be uploaded for you during cobranding setup. The URL to your versions of them needs to be specified in the scriptinfo.php of the cobranded script, which will also be done by me during cobranding setup.

Section E: Other Tools

1. Multi-Site Updater

The WSN multisite updater tool allows people who run many copies of the script -- I have several dozen myself -- to upgrade all of them at once. Just download the WSN tool and offer it to your customers.

2. Automatic Setup

The automatic setup tool allows people to install without manually uploading more than one file. This removes the installation steps where people can make mistakes.

currentdownload50.php?format=autosetup allows downloading a copy of the autosetup script. It expects you to have the copy two levels above its own location, named as autosetup50.txt. The advantage of having it up two levels is that it's shared between all the scripts. The .txt is just to prevent it from being executed on the server.

You will want to edit the autosetup to reflect your brand and/or language. Just open up autosetup50.php and you'll see HTML for customization at the top.

3. Resources/Themes Area

WSN Links' resources area is just another installation of WSN Links, with categories for various stuff. One category is for themes, and this is read by the WSN Links admin panel's theme installer page.

To have your own themes appear on the theme installer page, first change the $themefeed line in scriptinfo.php to specify your own feed URL. You can use rssfeed.php?type=links&thecondition=catid=1&custom=yes&TID=themerss (where the catid 1 changes to whatever your theme category id is) or you can make a static copy of that as themefeed.xml using WSN's static file generation tool, as I have.

The themerss template is located at site/themerss.tpl in the cobranding package. Upload it to the custom subdirectory of your template set. You will need to have fields named "price" and "version" added on the add fields page.

Don't worry about themes if you don't want to.

Section F: Running Multiple Cobranded Scripts at Once

1. Introduction

Most customers tend to want something that already does exactly what they want out of the box, and just being able to edit it to do what they want with a few hours work isn't good enough. In order to appeal better to each sub-niche within your niche, you may release separate scripts for each sub-niche with their own settings, templates, language or other customizations.

One of your scripts will need to be considered the original, which the others will look to for updates. This should be the most generic of the scripts.

2. Procedure

I can do this for you,, but in case you want to do it yourself:

Install new copies of your original script in new subdirectories, named for the names of your new additional scripts. Use the same administrator username/password in all the localhost script installs as you do in your original.
Edit the scriptinfo.php of each copy to give it the new details.
On your sales website, find the filecomparison directory. Add a new subdirectory named for each new script. It should be the same name as $zipfolder in scriptinfo.php.
Also on your sales website, copy the directory of your original script (which contains version50.txt, releasenotes50.php, etc) to create ones for the new scripts. Delete the member downloads area subdirectory copies and install a fresh one with no members.
Open wsnconfig50.php in your releasetools, and add entries for the new scripts. Copy the group that has the index 0 and change the index to 1, then 2 for the second new script, etc.

3. Syncing

So that you don't have to do the same thing twice, parts of the scripts which should remain the same as the original script are synced to the original. This is done automatically for PHP, and automatically for every admin panel template except the "recommend" one (where you want to make your admin panels look different, use template conditionals like <IF WSN Gallery is Script 2>script 2's stuff</IF>).

With user-side templates, you have to determine which of them you want to make unique and which to keep generic. The easy way to do this is to simply make customizations to all the templates you want to have customizations in, and then use releasetools/templatesharing.php to get a list of what you haven't customized. Those are the ones you're likely to want to sync. Copy and paste the output which releasetools/templatesharing.php gives you to wsnconfig50.php, after removing any in the listthat you intend to have diverge in the future. Please keep in mind that if you decide to make a template diverge in the future you're going to have to edit the list in wsnconfig50.php to avoid having your changes constantly reverted.

For clarification: please remember that when we're talking about customized templates above we're talking about customizations relative to your original script -- not relative to WSN. Even if all your templates are different from WSN's, you can still keep them synced to your own original script.

At release time, every other script will be automatic synced to script #0 defined in wsnconfig50.php. sync50.php does this work. Often, while working, you may want to make sure they're in sync with each other before testing something. You can use the sync link on the releasetools control page to get them all synced.

Personally, I've placed a button on my KDE panel which launches this simple shell script:

#!/bin/bash
wget "http://localhost/releasetools/sync50.php?filled=1&todir=all"
unlink "sync50.php?filled=1&todir=all"

So whenever I click that button I know the files are up to date in all scripts.

4. Reminders

If you want to add the same new field to all your scripts, your cobranding control page links you to a "universally add fields" page where you can avoid the repetition.
Always do your editing in script #0 unless the edit is going to be unique to one of the other scripts (and if it's an admin panel edit, still do the edit in script #0 even then).
Your admin panel will be based on the original script with the one exception templates/admin/recommend.tpl. So, be sure to edit only the original admin panel and not the others. You can conditionalize spots to make them show up for particular scripts. Example: <IF WSN Gallery is Script 2>Script 2's stuff<ELSE IF WSN Gallery is Script 3>Script 3's stuff<ELSE>stuff for all the other scripts</IF> WSN already does a bunch of these conditionals like <IF wsngallery is wsngallery>, but all your wsngallery values are going to be wsnlinks so you'll need to test WSN Gallery (which will be unique) instead.
If you seem to be mysteriously losing template changes, it probably means you need to remove a template from the sync list in wsnconfig50.php.

Section G: License Obligations

Some files included in WSN are differently licensed. See filelicenses.txt for a list of those. The only license you really need to worry about is the LGPL, which obligates you to offer a copy of the source code for the flash video player which WSN uses. Download the copy linked in filelicenses.txt and upload it to your own server, then change the link in your filelicenses.txt to point to your copy (linking to another server's source doesn't technically fulfill LGPL obligations).