Kimler Adventure Pages (http://randsco.com)

b2evo how-to: Blog Entry Sent via Email to a Friend

18-Oct-2007: Updated link for b2evolution versions 1.x or higher, which have a function name change - from "permalink()" to "permanent_url()".

This is a tough one to describe. Maybe it's better to come at it a different way. Say someone is visiting your site and likes a particular entry. "Hmmm," they might think, "Mary would really be interested in this." It's one thing to have that thought, quite another for them to be motivated enough to actually DO SOMETHING about it (fire off their email client, type an email, hunt down the permalink address to the specific entry, cut'n-paste it) ... that's a LOT of steps! Wouldn't it be convenient to have an "email a friend" link that does the same thing, but automatically and quickly? No email client, no cutting and pasting. Just click, add email addresses, maybe a short note and then BOOM - done!

If you think this might be a useful feature, then you've come to the right place! You can have a link like the one below that says, "Email Story", then pops up a form when clicked. No complicated b2evolution database changes or core file hacking. Three steps and you're done. You'll undoubtedly spend more time configuring the CSS to style the pop-up windows, than installing the thing. To get your very own 'email-this-entry' link, read on, brave blogger...

The Concept

The inspiration for this tool came, as it often does, from a question posted in the b2evolution forums. The fact that someone wanted this, led me to believe that such a tool hadn't been developed. Later, when someone asked the same question, I noticed that someone had posted a solution "CJ Send Page v2.0". I downloaded it, installed it and quickly realized a couple of things: The thing worked, but it wasn't optimized for b2evo, nor was it to my liking. First, the basic install didn't accommodate b2evolution (i.e. - the email link, by default, was index.php, not the particular blog entry). Second, it didn't notify the blog owner whenever someone emailed one of your entries.

So I modified it (several times, actually) and the latest solution is the one you see here. It is now significantly different from the original. I've left their credits in the PHP files, but have changed all external references to this site, because the original authors will not provide support for this enhanced version. The improvements I've made include the following:

• The off-the-shelf version uses three PHP files: "friend.php", "config.php" and "stylesheet.php". It's now all rolled into one - "friend.php", to keep the installation simple.

• It now supports individual b2evolution blog entries, via the permalink() function, rather than incorrectly pointing to just the site - "index.php".

• There's now a option to email you whenever someone uses the thing (you get all the juicy details, name, IP, email addresses and what they said about your blog entry).

• It has error-checking to help eliminate typos in the email or with field entry & they pop up in their respective form entry fields (without losing the data that has already been correctly entered). Nice.

• The style-sheet CSS has been expanded to control more elements. CSS variables have been eliminated, in favor of full control via normal, embedded style-sheets.

• The link rollover title attribute is uniquely designed for b2evo, showing as: [Send "Blog Title" to a Friend].

• The script degrades nicely if JavaScripting is turned OFF (instead of JavaScript pop-ups, the form opens in the current window and the JavaScript 'close window' buttons are replaced by link buttons that take the user back to the emailed blog entry). Accessible.

• Added 06-May-05 The pop up window allows for multiple email recipients & a succinct explanation of this feature has been added.

• Added 15-May-05 The ability to add a text-only copy of the actual blog entry, along with the email link, has been added. (With a spot reserved for sending HTML mail, though this is not yet functional).

• Added 11-Sep-05 A Spanish language version, with support for special character encoding and Spanish web display.

• Added 28-May-06 Anti-SPAM measures added. TABLES layout for forms pages have been converted to DIV/CSS layout and are valid to XHTML v1.0 (Strict) standards.

• Added 1-Sep-07 Graceful degradation when javascripting is disabled AND a visitor has elected to send a text-only copy of the post, in addition to the link, to a friend.

Wouldn't you know, after I finished, someone pointed to the fact that such a tool already exists. It's linked here as an option. I had a brief look at it. It works, but involves modifying the b2evo database (security issues), doesn't provide form error checking, doesn't email you when the someone uses it (though you probably could track usage via the database entries) & it cannot include a text copy of the actual entry. I'm glad that I didn't find this solution first, as I probably would have used it and not ended up with what I think is a superior solution.

3-Step Installation

The installation is pretty straightforward. There are two changes to your _main.php file. The first one is adding a one-line JavaScript function in the <head> area and the second involves placing the "mail-a-friend" link where you want it, on the page. In step three, you modify the friend.php file for your website specifics and uploaded it to a directory. (You might have to revisit step two, after step three, as the link must point to the friend.php file). That's it. If correctly configured, you should be up and running. Let's look at each step in more detail.

Step 1 - Defining the JavaScript function in the <head> area.

All you need to do for step 1 is insert the following code, somewhere between <head> and </head> in the _main.php for the skin(s) that you are using.

It validates as XHTML(strict) and provides pop-up window size/placement. (You may wish to change these values, which are highlighted above. Just cut'n-paste the above code and you're ready to move on to step #2.

Step 2 - Adding the "Email Story" link.

Keeping the _main.php file for your skin(s) open, you simply cut'n-paste the following code wherever you want the link to show up. (I've tested the cut'n-paste method with my own blog ... it works).

Stuff highlighted in blue you must do, stuff in green is up to you.

Note: Older b2evolution installs (0.9.x or lower) will need to change the two function calls in the link from "permanent_url()" to "parmalink()".

The above code is a thing of beauty, if I do say so myself. :) By providing a link that includes an HREF, ONCLICK and a RETURN FALSE statement, this provides elegant degradation if a visitor has JavaScripting turned off (about 10% of folks do). Further, the "&js=on" tells the "friend.php" script whether JavaScripting is enabled. Another little trick was to make the <a> tag "title" attribute of the form [Send "Blog Title" to a Friend]. Because the "Blog Title" might have double quotes already, a bit of PHP code was inserted to collapse any double quotes, which keeps the browsers happy and avoids a possible triple-nested double quote situation. Ugly!

Enough tooting! You can change/add/modify to the <a> tag "title" attribute, if you like. Also, you can change the "Email Story" link text, or insert an <img> ... whatever you want to do to style it for your site. Oh, the link to the friend.php file should be fully-qualified or absolute (i.e., href="http://yoursite.com/etc/friend.php") and not relative (i.e., href="../../etc/friend.php").

Step 3 - Adding & Editing the "friend.php" script.

The third and last step, is to get the friend.php script file. You can download it in one of the following zipped flavors:

NOTE 17-Mar-2006: The script links below, have been pulled from our site. SPAMMERS have hacked the script and IF your version comes under attack, the script can be used to send SPAM. When this happens, a spammer can make it look like YOUR SITE is the spamming location. NOT a good thing! When I code a fix ... the links will return. (Fix Coded)

NOTE 28-May-2006: Anti-SPAM measures are now included. Downloads remain unlinked. Getting a copy is easy though - just REQUEST ONE! (an English version will be sent, unless you request a Spanish version).

• ENGLISH - (self-extracting exe, if you don't have winZip compressed zip, if you have winZip).

• SPANISH - (self-extracting exe, if you don't have winZip compressed zip, if you have winZip).

OKAY ... Now that you have downloaded the file, you need to edit it - changing the variables to match your particular site. Most of the configuration stuff is at the beginning of the file. Each field is commented, so I think (hope) it should be obvious what needs to be done. Please email me if you have any difficulty or suggestions about how to make it easier to do.

Once you have the configuration stuff done, all that remains is to upload it to your site and test it. It doesn't really matter which directory you upload the friend.php to, but keeping it close to your root directory will help shorten the link. To test, you should be able to click the "Email Story" link on your blog, then pull up the pop-up window ... fill in the blanks and BOOM ... you've got 3 emails generated. One to the person you've sent the link to, one to the person sending the link (as a reminder, for the record) and one to yourself (webmaster numero uno).

Once all the mechanics are working as expected, then you can set upon the task of customizing it for your site ... colors, border, background, text, etc. The CSS properties for the two pop-up windows are at the bottom of the 'friend.php' file. I've commented where they begin and where they end. The CSS in between is up to you.

That ends the basic install tutorial. I hope you find both the tutorial and the email code useful. Feedback (especially POSITIVE feedback) and, of course, coinage, is always appreciated and gets TOP priority! :D

The Future

This space is reserved for additions and further detail, as warranted by feedback. Right now, there are a couple comments that I'd like to make:

1) The 'friend.php' code is a tables-based construct that isn't XHTML(strict)-valid. I'd like to change that to a DIV-based construct that HAS been validated. Frankly, the thing works and that was the original goal, so it may be some time before it's changed. DONE (28-May-2006)

2) I'd really like to add an option (a check-box) that allows visitors to send the text-version of the blog entry, along with the link, in the email. The feedback I get about this will determine how rapidly this happens, if at all. DONE (15-May-2005)

Cheers, Scott