How To Build Your Own Plug-in to Switch Languages "On the Fly!"

Step 1: Create a new .asp page that 20/20 DataShed (or any other ASP page/product) can execute. The new script will produce hyperlinks that your visitors can use to view your web site in any language of their choice.

1. Open a text editor such as NotePad. You may also use an HTML editor and select the option to edit the "HTML source" directly.
2. Save the new document as "_Free2020ChooseLanguage.asp" to your hard drive. (You may wish to save it to a specific folder if you keep a local copy of your web site on your own computer.) Note, if you save the file using Notepad, then Microsoft Windows might append the .TXT extension to your file. Please ensure that the file is called "_Free2020ChooseLanguage.asp" and not "_Free2020ChooseLanguage.asp.txt" -- to do this you might need to alter the "Folder Options" in Windows Explorer so that the file extensions are not hidden.
3. With NotePad still open, copy-n-paste the following code into the new document.

   <%@ Language="VBScript" ENABLESESSIONSTATE="False" %>
<%
Option Explicit
response.buffer = true

dim booleanIsParentFolder
    booleanIsParentFolder = True
%>
<!--#include file="_globals.asp"-->
<%
CONST booleanWriteImages = False

dim dictLanguages
set dictLanguages = getLanguages

     IF dictLanguages.Count > 1 THEN
     %>
     <ul class="chooseLanguagesUL">
     <%
     dim strLanguageID

          FOR EACH strLanguageID IN dictLanguages
          %>

          <li id="<%=StripNonWordCharacters(strLanguageID)%>LI">
          <a href="<%=CreatePostBackLink(False,"listings.asp?","strLanguage>"& strLanguageID)%>">

               <% IF booleanWriteImages THEN %>
               <img src="<%=MapFullURL("images/"& strLanguageID &".gif")%>" />
               <% END IF %>

          <span><%=dictLanguages(strLanguageID)%></span>
          </a>
          </li>

          <% NEXT %>
     </ul>
     <%
     END IF

set dictLanguages = nothing




FUNCTION getLanguages

dim dictTemp
set dictTemp = Server.CreateObject("Scripting.Dictionary")

dim objXML
set objXML = Server.CreateObject("Microsoft.XMLDOM")
    objXML.async = False
    objXML.load(MapPhysicalPath("xml_rss/languages.xml"))

     IF objXML.parseError.errorCode <> 0 THEN
     response.write("Error: "& objXML.parseError.errorCode &"<br />")
     response.write("Line: "& objXML.parseError.line &"<br />")
     response.write("Reason: "& objXML.parseError.reason)
     END IF

dim listCultures
set listCultures = objXML.documentElement.selectNodes("language/culture")

dim objCultureNode

     FOR EACH objCultureNode IN listCultures
     dictTemp.Add objCultureNode.text,objCultureNode.parentNode.selectSingleNode("friendlyName").text
     NEXT

set getLanguages = dictTemp

set dictTemp = nothing

END FUNCTION
%>

   In the next section, we'll examine this code thoroughly.
4. Save the file.
5. Upload it to your web site to the parent folder of 20/20 DataShed. (Please...if you already have a file named "_Free2020ChooseLanguage.asp" then give this file a different name before uploading it to your web site.)
6. The script is now complete but should be tested. Open your web browser and visit this new page by typing the URL into your web browser's address bar.

   Example: http://www.YOUR_WEB_SITE.com/folder-names/_Free2020ChooseLanguage.asp

   You should see a list of hyperlinks which display the language names available in 20/20 DataShed on your web site. If you see an error message, then please restart this tutorial and pay close attention to the instructions.
7. If the script does not produce an error message, then move on to the next section: Step 2.

Step 2: Explanation of the code.

<%@ Language="VBScript" ENABLESESSIONSTATE="False" %>

This line contains the language declaration (Language="VBScript") and identifies the file as an ASP document (<% %>).

This line also instructs the web server to disable "sessions": (ENABLESESSIONSTATE="False"). This instruction is optional. We have chosen to disable sessions throughout 20/20 DataShed because doing so saves a considerable amount of overhead on the web server and DataShed doesn't require sessions for any internal features.

If your purposes require sessions, then you could rewrite this line as follows: <%@ Language="VBScript" %>

Option Explicit
response.buffer = true

We have used the option explicit declaration throughout 20/20 DataShed. We recommend that you use this option in your own scripting as well.

The response.buffer is set to "true" throughout 20/20 DataShed. Unless you have good reason to alter this property, then we suggest you leave this line as it is.

Note that you might be tempted to write additional headers to the file, such as the following:

• response.expiresAbsolute
• response.CacheControl

We recommend that you do not use these headers in an .asp document such as this (i.e. one that will be executed using the Server.Execute() method) unless you know exactly what you're doing and have good reason for including these options. In our experience, we have found that these properties of the "Response" object can cause runtime errors if they conflict with the processing of the "calling" page (i.e. the page/script which is executing this external code.)

dim booleanIsParentFolder
    booleanIsParentFolder = True

The booleanIsParentFolder variable is used by functions and script in the _globals.asp file. It helps the scripts determine which folder they're operating in without having to figure it out on the fly.

Note that the variable is set to True. This indicates to the _globals.asp that it should assume that the calling page is currently in the parent folder.

This variable should be set to False if you intend to place this new page in one of the product's sub-folders.

This variable must be present and explicitly defined either True or False in all pages which include the _globals.asp file. And the variable must exist in the code before the #include declarations.

<!--#include file="_globals.asp"-->

This line declares that the _globals.asp file should be included in this new script.

We have chosen to include this file in this new script so that we can access some of 20/20 DataShed's very cool functions.

CONST booleanWriteImages = False

This constant will be used later to tell the script whether or not you want to display images with the links.

dim dictLanguages
set dictLanguages = getLanguages

The dictLanguages variable will store a Dictionary object (which we'll create using the "getLanguages()" function).

The "getLanguages()" function is discussed later...but essentially it will grab information from one of 20/20 DataShed's XML files and build a "dictionary" of languages that we can use later.

IF dictLanguages.Count > 1 THEN
...
END IF

This bit of logic might be self-explanatory. But in English, it means "If the dictionary of languages has more than one language, then process me and write out the list. otherwise, ignore me because there's no need to give the user an option to change the current language."

<ul class="chooseLanguagesUL">
...
</ul>

We have chosen to write the links into an unordered-list using the <UL> element.

Note the class name! You can style this list however you wish by addressing it like this in your CSS.

ul.chooseLanguagesUL { ...your styles... }

ul.chooseLanguagesUL li { ...your styles... }

dim strLanguageID

    FOR EACH strLanguageID IN dictLanguages
    ...
    NEXT

First, we've created a variable called strLanguageID which will represent each key in the dictionary of languages as we loop through the languages using the FOR...NEXT syntax.

Then we loop! "FOR EACH thing in the dictionary, do something, then move to the next thing".

The dictionary object will have "keys" and "values". The "keys" in the dictionary will be strings like this: en-au, en-ca, en-gb, en-us, fr-ca, fr-fr, sp-sp. And the "values" will be things like: "English (Canada)", "English (Great Britain)", "Spanish (Spain)", etc. This is discussed more later with the "getLanguages()" function.

<li id="<%=StripNonWordCharacters(strLanguageID)%>LI"></li>

For each language available on the web site, we'll write a list item to the page.

Note that we've provided the list items with an "id" so that you can address the elements by Javascript or CSS.

The "id" is created using the strLanguageID value. (i.e. en-ca or sp-sp or tr). Note that the value is stripped of non-word characters by using the StripNonWordCharacters() funtion in the _globals.asp file. So, a string like "en-ca" will be stripped of the hyphen and become "enca".

An example of a real "id" would be:

<li id="encaLI">

Roughly translated, that means "english canadian List Item"

<a href="<%=CreatePostBackLink(False,"listings.asp?","strLanguage>"strLanguageID)%>">
<span><%=dictLanguages(strLanguageID)%></span>
</a>

This code will write a hyperlink to the page.

We've decided to create the URL using the CreatePostBackLink() function in the _globals.asp file. This function allows us to generate a complex hyperlink without having to know anything about the current page. For example, if your visitor is already searching your web site or browsing your listings, then they should be able to switch languages and return to the same page! This function will help us do that.

Note that the CreatePostBackLink() function will produce something like this:

http://www.YOUR_website.com/listings.asp?strLanguage=en-ca

But it also reads the current querystring and other page parameters...so it's also capable of remembering which item the visitor is currently viewing and/or which search keywords the visitor is currently searching for. Like this:

http://www.YOU_website.com/listings.asp?strLanguage=en-ca&strKeywords=Fireplace&strCurrentPage=4&strPageSize=1

By using the CreatePostBackLink() function, we can reasonably assured that the link will be formed correctly.

<% IF booleanWriteImages THEN %>
<img src="<%=MapFullURL("images/"& strLanguageID &".gif")%>" />
<% END IF %>

Inside the hyperlink we've created an optional image!

If the booleanWriteImages constant at the top of this script is set to True, then an <img> tag will be written to the page.

This script assumes that it will find a GIF image in the images folder with the same name as the current language. For example:

en-ca.gif
sp-sp.gif
fr-ca.gif

We recommend that these GIF images could be national flags!

The MapFulURL() function from the _globals.asp file is used here to produce the src attribute. This will create a URL that looks like this:

http://www.YOUR_website.com/images/es-ar.gif

This code assumes that you have Argentina's flag (es-ar.gif) in your images folder.

Phew! That's a lot of information.

Take a break...then come back and read about the "getLanguages()" function.

FUNCTION getLanguages
...
END FUNCTION

These two lines delimit a function that we've created to read one of 20/20 DataShed's XML files and build a list of available languages.

dim dictTemp
set dictTemp = Server.CreateObject("Scripting.Dictionary")

The first task in this function is to create a dictionary object that can use to store the information that we'll retrieve from the XML file.

dim objXML
set objXML = Server.CreateObject("Microsoft.XMLDOM")
    objXML.async = False
    objXML.load(MapPhysicalPath("xml_rss/languages.xml"))

Our second task is to create an XML object that we can use to parse and navigate the languages.xml file.

The "async" option is set to False because we do not want this object to process in asynchronous mode. In other words, we need the object to go get the data...and we'll wait until it returns with the data.

The "load" method then grabs the file.

We've used the MapPhysicalPath() function from the _globals.asp file to ensure that the full-physical path to the XML file is used. This function, in conjunction with the booleanIsParentFolder variable is smart enough to: a) know where to find the xml_rss folder and; b) determine exactly where on the web server's hard drive the languages.xml file resides.

IF objXML.parseError.errorCode <> 0 THEN
...
END IF

The above logic adds some small relief if an error occurs while processing the languages.xml file.

If an error occurs, this snippet will print out the error's details so that you can debug.

dim listCultures
set listCultures = objXML.documentElement.selectNodes("language/culture")

The listCultures variable is created and stores a "nodeList" object.

The nodeList is created by navigating into the languages.xml file and selecting all nodes within the document element that match the "language/culture" pattern.

In other words, this line creates a list of all the available "cultures". Examples: "en-ca", "ar-dz", "hu" which represent Canadian English, Algerian Arabic, and Hungarian.

dim objCultureNode
     FOR EACH objCultureNode IN listCultures
     dictTemp.Add objCultureNode.text,objCultureNode.parentNode.selectSingleNode("friendlyName").text
    NEXT

The FOR...NEXT structure above will loop through all the available "cultures" and add them to our dictionary object.

For example, if your languages.xml file might contain three languages (below). So the languages will be added to the dictionary like this:

Culture ID	Friendly Name
Dictionary KEY	Key VALUE
en-ca	English (Canada)
is	Icelandic
es-cl	Spanish (Chile)

set getLanguages = dictTemp
set dictTemp = nothing

Cleanup.

Step 3: Edit the template.html to instruct 20/20 DataShed when/where to execute the new ASP script.

In the previous sections we created an ASP file -- a "stand-alone" script which produces a list of hyperlinks that your visitor can use to view your web site in any language of their choice. Now we will show you how 20/20 DataShed's skinning engine can execute ("include") that file within your template.

1. Access your web site with an FTP application such as CuteFTP, FTP Explorer, or Windows "My Network Places".
2. Download template.html from the templates folder of this application to your local computer.
3. Open the file in a text editor such as Notepad or a WYSIWYG editor. (If you choose to use an editor, then please ensure that you select the option to edit the "source" directly.)
4. In that file, find the area in which you want to "include" the list of links.
5. Place the following token in your template where you want the list of links to appear:

   [2020Execute__Free2020ChooseLanguage.asp]

   In the example code below, you can see that we'll include the list of links in the "footer" of the file and we've added some simple CSS to apply some pleasant formatting to the list.

   <html>
<head>
<title></title>
<style type="text/css">
ul.chooseLanguagesUL li { list-style-type:circle;display:inline;padding-left:15px; }
</style>
</head>
<body>

<!-- HEADER STUFF -->
    <h1>Welcome!</h1>
<!-- END OF HEADER STUFF -->


<!-- BODY (Main Content) STUFF -->
    ... content...
    ... content...
    ... content...
<!-- END OF BODY STUFF -->


<!-- FOOTER STUFF -->
[2020Execute__Free2020ChooseLanguage.asp]
<!-- END OF FOOTER STUFF -->


</body>
</html>

6. Save the file.
7. Upload the file to your web site using the FTP application and overwrite the existing "template.html" file.
8. Reload the listings.asp, newuser.asp, or login.asp page and include the "?objApplication=RemoveAll" querystring in your URL to force 20/20 DataShed to flush out the old template from the server's cache (and reload this new one).

   Example: http://www.your_domain.com/listings.asp?objApplication=RemoveAll

   You should see a new list of links on your page which allows you to switch languages on the fly.