How to Set and Use Cookie-based Preferences

Free-Conversant Support / How to Set and Use Cookie-based Preferences

Home

Hosting

Support

XML-RPC

Support Home

Documentation

Search Support Site

Discussion Group
  Ask a Question
  Recent Topics
  Message Calendar

Membership
  Logon
  Join Now!

Subscribe via Email
Unsubscribe via Email

Documentation >> Outline of How-To Docs >> Cookie-based Preferences

How to Set and Use Cookie-based Preferences in Conversant

Conversant provides a number of macros and conditionals for setting, getting, and testing cookies.

This how-to guide will not use them all. We'll use only the setCookie macro (to set the value of a cookie), and two conditionals: cookie.[name].exists (to make sure the cookie has been set) and cookie.[name].value (to test the value of the cookie).

Overview

In the process of learning about the cookie macros and conditionals, we're going to reproduce a feature of the free-conversant support site. Specifically, we're going to make it easy for members of your site to specify whether or not they want to use the WYSIWYG message editor.

The same techniques covered here can be used for any cookie-based prefs. (You could even let the user pick their favorite site template, or their favorite stylesheet, or background image, or almost anything else.)

We'll start out with a quick overview of the steps we're going to take. This may be all that the experienced users need. Detailed explanations will follow.

Note: You can follow along by performing all of the same steps on your own site.

Create two Bound Message pages, each containing the #setCookie value. The first sets the cookie's value to 'true', the second sets it to 'false'.
Edit the Full Page template, to wrap the #htmlarea.header macro (which inserts the WYSIWYG editor's javascripts and stylesheet) in a conditional macro that tests the existence and value of the cookie.
Edit the message-editing template, this time wrapping the #htmlarea.initEditor macro (which inserts a line of javascript to convert a textArea into a WYSIWYG editor) in a conditional macro, same as the previous step.
Edit the Nav Bar to include links to the pages for setting the pref to true or false.

Create Two Bound Message Pages

Create a new message.
1. Set the subject to "WYSIWYG Editor: On"
2. Set the body of the message to something which explains the preference that has just been set. Here's an exact copy of the text we use on the support site, including all tags and macros:
  <h2>WYSIWYG Editor: On</h2> <p> <a title="The coolest software ever!" href="http://conversant.macrobyte.net/">Conversant</a> supports WYSIWYG message editing via a plugin built on <a href="http://www.interactivetools.com/products/htmlarea/">HTMLArea</a>, from InteractiveTools.com. HTMLArea works in Internet Explorer 5.5 or greater (Windows), Mozilla 1.3a or greater (any operating system), and Mozilla Firebird 0.6.1 or greater (any operating system). </p> <p>By visiting this page, you have specified that you wish to use the WYSIWYG HTML editor. If you change your mind,click on the "WYSIWYG off" button in the sidebar. </p> 
3. Save (submit) the message
Notice the last line of the message is the #setCookie macro. This is the line that does all the work, everything else is just explanation for the user.

If your site is in a subfolder (rather than at the root of the host name: this includes all free-conversant sites), then you should add the 'path' attribute to the setCookie macro, like this:

Publish the new message.

Using the "Bind message to URL" form in the Admin Box at the bottom of the message's page, publish the message to this path in your site: wysiwyg/on
Go back to the message in step 1, and reply to it.
1. Set the subject to "WYSIWYG Editor: Off"
2. Set the body of the message to something which explains the preference that has just been shut off. Here's an exact copy of the text we use on the support site, including all tags and macros:
  <h2>WYSIWYG Editing: Off</h2> <p> <a href="http://conversant.macrobyte.net/" title="The coolest software ever!">Conversant</a> supports WYSIWYG message editing via a plugin built on <a href="http://www.interactivetools.com/products/htmlarea/">HTMLArea</a>, from InteractiveTools.com. HTMLArea works in Internet Explorer 5.5 or greater (Windows), Mozilla 1.3a or greater (any operating system), and Mozilla Firefox 0.6.1 or greater (any operating system). </p> <p> By visiting this page, you have specified that you <span style="font-weight: bold;">do not</span> wish to use the WYSIWYG HTML editor. If you change your mind, click on the "WYSIWYG on" button in the sidebar, at any time. </p> 
3. Save (submit) the message
Notice the last line of the message is the #setCookie macro. This is the line that does all the work, everything else is just explanation for the user.

If your site is in a subfolder (rather than at the root of the host name: this includes all free-conversant sites), then you should add the 'path' attribute to the setCookie macro, like this:

Publish the new message.

Using the "Bind message to URL" form in the Admin Box at the bottom of the message's page, publish the message to this path in your site: wysiwyg/off

Now when anyone visits one of these pages on your site, they'll get a cookie to turn the WYSIWYG editor either on or off (depending on which page was visited).

Edit the Full-Page Template

In order to use the WYSIWYG editor, you've already followed the instructions to add the #htmlarea.header macro to your full page template. This macro inserts links to various javascripts and stylesheets used by the WYSIWYG editor.

The point of this step is to make sure that those javascripts and stylesheets are only linked into the web page if the user actually wants to use the WYSIWYG editor. (Otherwise, we waste time and bandwidth by downloading files that aren't used.)

Go to the admin area, and open your conversation's template editor.
Click on your full page template (if you have more than one, make sure you select the one that's used when you are editing messages).
Find the #htmlarea.header macro. It should look something like this:


Wrap it in a conditional macro to make sure that the htmlarea.header macro is run only if: the cookie does not exist, or the cookie is set to true.


Save the template.

You may already have a conditional macro surrounding the #htmlarea.header macro in your full page template. That's ok: either combine them (if you know how), or simply put the above code in place of just the macro. So this:

... becomes this:

Edit the Message-Editing Template

This step is similar to the previous one. You will find the #htmlarea.initEditor macro in your message-editing template, and wrap it in a conditional macro so that the macro only runs if the user's cookie pref doesn't exist or is set to true. (The default value for the pref is "true", so that if the user hasn't set the pref yet and doesn't have a cookie, we still show the WYSIWYG editor.)

Go to the admin area, and open your conversation's template editor.
Click on the link to your message editing template.
Find the #htmlarea.initEditor macro. It should be right after the #msgBody macro, and look something like this:


Wrap it in the same conditional macro that we used in the full page template, like this:


Save the template.

Edit the Navbar

For this last step, we're going to add links in your site's navbar to the pages created in the first step for turning the preference on and off.

We only want the links to appear to logged-in members of the site, since only members can use the message-editing form anyway. For this, we're going to use yet another conditional.

By default, new sites on Free-Conversant store the navbar in a message. You, as the site's owner, just need to click on the title of the navbar box to edit the correct message.

If you have changed your site so that the navbar is stored in a template, or built some other way, that's fine. It doesn't matter where you keep your navbar or how it is built, just open it in the editor now.

Insert the following text into your navbar. Feel free to edit the content and layout in any way you see fit.

<!--#if condition="userIsMember"-->
<div style="border: 1px solid black; padding: 1em; text-align: center;">
    <b>WYSIWYG Editor:</b>
<br />
    <!--#if condition="cookie.wysiwygEditor.exists && (cookie.wysiwygEditor.value == 'false')"-->
      <a href="/wysiwyg/on">On</a> | <b>Off</b>
    <!--#else-->
      <b>On</b> | <a href="/wysiwyg/off">Off</a>
    <!--#endif-->
  </div>
<!--#endif-->

Note that | is displayed by the browser as a vertical separator (a.k.a. pipe: |). We use the html entity code because the pipe is Conversant's resource delimiter, and every time it sees one it tries to find a resource. This slows down the page-rendering time. Use the html entity to avoid this minor performance issue.

Finished

That's it, you're done. Four significant steps to building and using a new cookie-based preference.

View in DG