[plugin] PBTS_XTRA - Mulitple Content Areas in Template

[carterco]

I’ve just written a plug-in, PBTS_XTRA, now available in a beta form to do this.

Overview
This plugin extends phpList's Template functionality by allowing you to define multiple Content Regions within your Templates.

You are also able to include or exclude sections of your Template based on whether one of these Content Regions is empty or not.

Finally, the plug-in automatically creates an editor for your Content Regions based on settings you provide.

Installation

Moderate level of experience, or at least a DIY attitude will have this running in about ten minutes. (see install.txt for complete notes)

You do need to modify a core file, so please, please, please backup sendemaillib.php BEFORE making the manual code change required to use this.

RFC

This is a new plugin and I’d truly appreciate feedback and suggestions. Particularly from some experts who might have a thing or two to say about where I’ve modified send email (between you and me: I anticipate changing where this hooks in).

I'm not married to the syntax, so if you have suggestions or have seen something better, please, post your ideas.

Also, how to better integrate with standard, out-of-the-box phpList functions would be appreciated.

Sample

Just to give a heads-up, here is what you would put into your Template:

Code: Select all

[PBTS_XTRA name="MyNewColumn"]


That is all of that’s required. If you do choose to include some of the extra parameters you’ll be rewarded with a better Editor. These parameters are basically what you use for HTML form elements;

Code: Select all

[PBTS_XTRA name="MyNewColumn" displayname="Joke of the Day"
    type="textarea" rows="6" cols="45"]


OK. Hope this helps.

As a last tease, the conditional processing:

Code: Select all

[pbts_if condition="not_blank" name="Urgent_Action"]
  <h5>Urgent Action</h5>
  [pbts_xtra name="Urgent_Action"]
  <p>For how you can get involved contact Bob ...</p>
[/pbts_if]


Stuff inside the IF and /IF only is emitted if the custom tag inside this template named "Urgent_Action" is not blank. Lot's of uses for this -- mainly, fewer but smarter templates.

I’ll be watching the forums for problems and suggestions. Thanks.

Oh, you still retain the option of using “normal” templates:
I've modified sendmaillib.php where it generates the text and HTML versions of the email (where it does the CONTENT substitution into your template). If the template contains at least one PBTS custom tags it parses the message's CONTENT and stuffs it into the appropriate places within the template otherwise it uses phpList’s normal replacement.

My email, if you have questions (though the forum is great), is: buz carter aht hotmail doht com.

I've setup a page on my website here:
http://pizzabytheslice.com/phplist/pbts_xtra/

Oh, debt of gratitude is owed Karl Hedner whose been testing this for me and providing tremendous feedback and encouragement.

[frigginbone]

I could not get this plugin to work (from a non-programmer.) I believe I followed all directions in the txt file. I'll try to remember all problems:

- couldn't get past the missing [CONTENT] at first, finally looked at example template more closely.

- never had the pbts_xtra editor. Manually used a PBTS tag, found in my template, in the message area.

- added the example template as a new template, also edited my own template. Tried to send both to my test group, and the processqueue hung every time.

- when saving the template in the queue, the next screen would be incomplete (I guess), no menu on the right. And the screen seemed wrong, seemed too short.

Obviously a great plugin, very powerful. I'll continue to watch the development. I wish I could offer help, but I don't have the skills. I would love to get this to work!

[carterco]

Well, first, don't own the problems so quickly, it's most likely my instructions were wrong or unclear .

Let me take a stab at some of these:

The pages "looking short" sounds suspiciously like a php error (you can't see the errors as they're trapped by phpList -- something i'll learn more about shortly i suspect, as this has made my life troublesome, too).

This, I am fairly certain, is also why "processqueue hung" -- it isn't hung, it's broked-acated!

Fortunately (hoping here) the problem is :

1. you didn't add the include instruction to the top of the sendemaillib.php file, or
2. the path to the plugins directory is wrong, or
3. the plugin path is not set to anything in config/config.php

Of these three I'm betting it's the config -- when you say you didnt' "get the pbts editor", well, on any page of phpList on the right sidebar you should see, at the bottom, your installed plugins. phpList ships with two, and if you've added this one as well you should see "pbts_xtra" on this list.

also, on main page, you should see links at the page's bottom to the options supplied by the plugins, pbts_xtra, if available and installed, should show two

If you do not see these then you need to follow the instructions and make phpList aware of your plugins directory.

If you do see them, then the problems are that phpList is not able to find the plugin's library, again, that's set by the "include" comman you've added to the top of sendemaillib.php

Check all of this and let us know if any of them help, either way would love to hear back.

it is NOT your fault -- and if you're having a problem a half dozen others are, too, but didn't post it, so Thanks! We'll get you going in no time.

[carterco]

PS. I really glossed over your comment about [CONTENT] tag which was stupid of me, you've raised an excellent point.

Yes, phpList requires that every Template have, somewhere, anywhere, one [CONTENT] bucket.

Now, pbts_xtra does not really respect the content tag as much as it, well, frankly, just nukes it. Pbts_xtra only deals with pbts_ tags.

Recall, the pbts flavor of the "send email" processing ONLY occurs if one or more [pbts_ ] tags are present, if none are, then normal phpList processing ensuses.

Thus, if you have a Template with only the Content tag, well, normal sending is followed, otherwise, pbts_ processing is used, and the [content] tag is stripped out, replaced with nothing. (that's an important point, by the way)

I hope I haven't confused you more, but I did this stripping out of the CONTENT tag because phpList requires the content tag, but pbts_ doesn't need it.

What I do/did in that sample is placed the [CONTENT] in a comment at the tolp of the HTML, just to satisfy phpList and to get it over with.

Code: Select all

<!-- [CONTENT] -->

It's the "serving two masters" conundrum; gotta satisfy phpList behaviours first, then get to xtra's desires.

Again, thanks for helping make this a better plugin.

[frigginbone]

carterco, thanks for the response! I reloaded your plugin, changed the files and got it in the right-side menu. It was a plugin location problem. I wanted to use a folder outside of phpList but can't seem to get the syntax right, so put it in the internal folder instead.

Ultimately, I haven't gotten an email to 'send' with the new tags. Here's a step-by-step listing of what I did and the results:

Main Page (admin)

Send a message
- fill in subject to identify later
"Save" the message

pbts_xtra (from right menu, under plugins)
"Edit A Message"

Draft Messages - choose and "edit"
- fill in "Subject,' 'From Line,' 'Template' (didn't test changing this), 'field name'

"Save" (button above "subject' line)
- tags and content shown in purple box below

Edit this Message with standard phpList Editor (scheduling, etc)
- Make the usual choices

"Send Test Message"
- leads to short incomplete screen, no right-side menu. Says 'message saved'

OR
"Send Message to the Selected Mailinglists"
- displays 'message saved,' 'Message queued for send'

"Process the message queue"
- Screen shows:
Started; message 88; 3 users to process; Finished, Nothing to do; Finished, All done

Messages (right menu)
(choose message)
- screen shows:
Sent
Message Info:
Entered: 2005-12-04 18:50:51
Embargo: 2005-12-04 18:50:00
Status: inprocess; 3 still to process; ETA: (blank); Processing 0 msgs/hr; "Suspend Sending"; Action: 0 sent


I can review the template with PBTS tag info (somewhere in the process) so I know the info gets where it needs to go.

Made a discovery when reviewing. Be careful when choosing tag names. Best to show with an example:

[PBTS_Article]
[PBTS_ArticleCopyright]
[PBTS_ArticleBlogEntry]
- All three tags use the one entry for [PBTS_Article]. [PBTS_Article] was first in the template, don't know if that affected which entry was used. Regardless, it appears to be best to choose completely different tag names.

My two cents so far.

[carterco]

In answer to the question you didn't want answered:

The path to the plugin file, as given in the installation notes, is predicated on the notion that you've installed your plug-ins UNDER the phpList install.

Code: Select all

include_once dirname(__FILE__).'/plugins/pbts_xtra/pbts_xtra.inc.php';


The first part of that statement, the dirname(__FILE__) part, roughly translates to "under the directory where phpList admin is installed start looking for a "plugins" directory, and under that, etc. etc.

This dirname(__FILE__) is commonly something like:
/home/user/public_html/lists/admin/

But no matter. You can get creative with your file locations.

So, if you don't have plugins under phpList's admin directory just give the complete path, for example, it might be something like this:

Code: Select all

include_once '/home/usr/my_plugins/pbts_xtra/pbts_xtra.inc.php';


Note that I've removed the "dirname(__FILE__)" reference. Hope that helps.

Oh, now I'll dig into your real question

[carterco]

Wowzers, frigginbone! So, let me make sure I'm reading this (in horror) correctly:

The tag name matching is "lazy" in that it takes the simplest and first matches, in your case it matched:

Code: Select all

[PBTS_Article]
[PBTS_ArticleCopyright]
[PBTS_ArticleBlogEntry]


with the same field: PBTS_Article

Amazing. Amazing in that my regular expressions are so pathetic, accepting a partial match so quickly! I'll recreate your bug-find and fix this first thing in the morning (PST). Thanks for your patience and help ... and for the workaround.

[carterco]

Just proved you right, frigginbone. You used the shorthand method, however, and I (happily, somewhat) found that if the longer tag syntax is used instead -- the one with more options (see below) -- this bug does not manifest itself:

Code: Select all

[PBTS_XTRA name="Article" type="textarea"]
[PBTS_XTRA name="ArticleCopyright"]
[PBTS_XTRA name="ArticleBlogEntry"]


The above works as expect, no problems.

Shall have a fixed version -- for the shorthand -- available in the morning. Again, many thanks.

[carterco]

Just uploaded new version, 0.04, that fixes the above issues with tag names. This release has also been tweaked to enable replacement of the built-in phpList Message editor with the Template-driven PBTS editor (optional, should you so choose). Additional assembly required (hand tweaks to code). See included install file for notes or visit the project page on pizzabytheslice.com.

[bluelotus]

Hi,
I just installed the pugin and I thought I followed the instructions step by step, but then when I go the templates section to import my newsletter template there is no editor. It's basically a blank window and there is nowhere to add the new html.

What did I do wrong?

Thanks for any help/advise!

[carterco]

Forgive me if I ask the obvious:

...there is no editor. It's basically a blank window and there is nowhere to add the new html.

So, two questions: which page are you on? Are you on the "add/edit Template" page (the standard phpList Template section) or are you on the pbts_xtra -> Templates page?

You must use the phpList editor to create Templates. Period. You then may, however, choose to use either editor (built-in phpList Template editor or the pbts_xtra Template editor) to modify the Template. The advantage of using the pbts_editor for Templates is that it has some nice features for managing, previewing, and verifying your custom fields/placeholders.

Second question: the blank page... that's really odd. No textarea? Nothing?

Based on this and my reading of my snickerdoodle entrails I'd say that you are on the pbts_xtra page before you've created a Template. Make the Template as you would normally, then head into the xtras if you like.

Also, if you haven't already, I recommend doing the extra step of integrating the pbts_xtra editor for your mail messages. If yo do this then you'll never need to venture back over into the nether-realm of pbts_xtra again, that is, you'll be able to edit a message in the normal flow.


I'll clarify and emphasixe these steps better in the help section. I've been sitting on an update for a few weeks until i could test. I'll include this in the FAQ. I'll also put some screen shots up. People love screen shots.

Let me know if you have problems, we'll get you going in a jiff.

reach me through: http://pizzabytheslice.com

[carterco]

Just threw up some screenshots (one per tab) of the Tools available for working with your enhanced Templates:

http://pizzabytheslice.com/phplist/pbts ... nshots.htm

[bluelotus]

Sorry for my lack of clarity. I'm on the regular template page of PhPList. I am not even sure how to access the pbts_extra one...

There is a text window but the editor doesn't have any of the usual text editing tools. So, it is basically where you would add the "content" and at the bottom is has the "Check that all links have a full URL," etc.

I uploaded a template I made on GoLive and its html appears on the window but when I click on "save" it won't save it. It just says. "Some errors were found. Template not saved!"

So I am wondering, did I installed the plugin wrong, or what am I doing wrong now?

Thanks for your help!

[carterco]

You're right -- this is unrelated to the plugin, but no matter, you ask a fair question.

In order to get started using Templates... looking for that faq, nevermind, you must have:

Code: Select all

[CONTENT]

Somwhere in your Template HMTL... I'm guessing this was your error, no?

Trying to recall whether other Placeholders are required... perhaps the footer.

If the problem persists, check the forums/faq for required Placeholders.

[jwatts001]

First, carterco, let me just say that this plugin is awesome, and thank you SO much for writing it and distributing it freely! It really has allowed me to make some great looking newsletters for my company.

I am running into a small problem, and i'm really not sure if it is related to your plugin, but i don't think it started until after i installed it. But either way, maybe you could offer your opinion. The problem is that, even though i specify to send the newsletters HTML-only, they still always send out as both html and text. Do you know what this could be about?

I appreciate any help you could offer, and again, thanks for a great plugin!

-Justin