919 - 926 - 9847

FarCry plugin breakdown - Part I

I promised a breakdown, and so it shall be writ. This first segment is going to analyze the newly created objects. If I have wherewithal to finish tonight, we'll move along to the administrator addon.

Let's start with our objects then:

  • massMailer - This object will hold all the information about our email. Things like message body, subject, from, to, and the massMailerList objects.
  • massMailerList - This object contains the name of the list, and holds massMailerUser objects.
  • massMailerUser - This object contains the name, email address, and dateTime stamp when the object was created.

Now let's look at the code. We'll start with the massMailerUser.

<cfcomponent extends="farcry.core.packages.types.types" displayname="Mass Mailer Users" bFriendly="1" hint="Mass mailer object to hold the users" bobjectbroker="true" objectbrokermaxobjects="1000">
type properties
<cfproperty ftSeq="11" ftFieldset="User Details" ftWizzardStep="General Details" name="Title" ftLabel="Name" type="string" hint="Users Name" required="no" default="">
<cfproperty ftSeq="12" ftFieldset="User Details" ftWizzardStep="General Details" name="Email" ftLabel="Email" type="string" hint="Email Address" required="no" default="">
<cfproperty ftseq="13" ftFieldset="User Details" ftWizzardStep="General Details" name="DateAdded" type="date" hint="The date user was added" required="yes" default=""ftDefaultType="Evaluate" ftDefault="now()" ftType="datetime" ftDateFormatMask="mm dd yyyy" ftTimeFormatMask="hh:mm tt" ftToggleOffDateTime="false" ftlabel="Date Added" />

object methods

Hmm... so what does THAT mean?? Let's break this object down. Formtools will generate our object administration page for us, but it needs some help to get along.

  • ftSeq - Numeric sequence that you wish the fields to be displayed in
  • ftFieldset - Gives "groups" within a given page. Usually denoted by a horizontal line
  • ftwizardSet - Should give pagination, but it isn't working (for me) at this time
  • name - Name for the object to be created in the database
  • ftLabel - Label to displayed in the admin
  • type - Type for database creation
  • hint - Typical component hint. Although I think there's a way to give context sensitive help, I just haven't explored it yet.
  • required - No need for explanation, right?
  • other ft types - Not going to into these in detail. There are several examples in the core for working with date/time types with the supplied date/time picker.

Next up, our massMailerList object

<cfcomponent extends="farcry.core.packages.types.types" displayname="Mass Mailer List" bFriendly="1" hint="Mass mailer object to create the lists" bobjectbroker="true" objectbrokermaxobjects="1000">
type properties
<cfproperty ftSeq="11" ftFieldset="List Details" ftWizzardStep="General Details" name="Title" type="string" hint="Title of object." required="no" default="">
<cfproperty ftSeq="12" ftFieldset="List Details" ftWizzardStep="General Details" name="aObjectIDs" type="array" hint="Holds objects to be displayed at this particular node. Can be of mixed types." required="no" default="" ftLabel="Users" ftJoin="massMailerUser">

object methods


Pretty much more of the same, EXCEPT, for this little gem. Notice that my aObjectIDs is of type array. This type MUST have an ftJoin attribute applied. You would specify a component here that you would like to have data populated from. In our case it is massMailerUser. But it could easily be dmImage (default supplied image library) or dmFile (default supplied file library). Heck, it can even be a comma separated list of any of these things.

So what happens when you add this type of field? Formtools will generate a button for you to click, called open library. This will pop open a window, and you will be given a choice of various tabs. In the main view, you can drag the massMailerUser (or image, or file, or whatever) objects from the right hand pane to the left hand pane. And that's it, you're done. You've now attached objects as an array to your massMailerList object. And you didn't even have to write any code!

This leaves us with massMailer

<cfcomponent extends="farcry.core.packages.types.types" displayname="Mass Mailer" bFriendly="1" hint="Mass mailer object to send to lists created by Mass Mailer List" bobjectbroker="true" objectbrokermaxobjects="1000">
type properties
<cfproperty ftSeq="11" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="Title" type="string" hint="Title of object." required="Yes" default="">
<cfproperty ftSeq="12" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="aObjectIDs" type="array" hint="FarCry Groups to send email to" required="Yes" default="" ftLabel="Lists" ftJoin="massMailerList">
<cfproperty ftSeq="13" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="fromEmail" type="string" hint="From email address" required="Yes" default="">
<cfproperty ftSeq="14" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="replyTo" type="string" hint="Address(es) to which the recipient is directed to send replies" required="no" default="">
<cfproperty ftSeq="15" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="wraptext" type="string" hint="Specifies the maximum line length, in characters of the mail text." required="no" default="">
<cfproperty ftSeq="16" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="failTo" type="string" hint="Address to which mailing systems should send delivery failure notifications. Sets the mail envelope reverse path value" required="no" default="">
<cfproperty ftSeq="17" ftfieldset="Mailer Details" ftWizzardStep="General Details" name="charset" type="string" hint="Character encoding of the mail message, including the headers" required="no" default="UTF-8">

<cfproperty ftSeq="21" ftfieldset="Text Body" ftWizzardStep="Text Body" name="Body" type="longchar" hint="Main body of content, text only." required="no" default="">
<cfproperty ftSeq="31" ftfieldset="HTML Body" ftWizzardStep="HTML Body" name="htmlBody" type="longchar" hint="Main body of content, to be sent to users as HTML" ftType="richtext"
    ftImageArrayField="aObjectIDs" ftImageTypename="dmImage" ftImageField="StandardImage" required="no" default=""
    ftTemplateTypeList="dmImage,dmFile" ftTemplateWebskinPrefixList="insertHTML"

<cfproperty name="bSent" type="boolean" hint="Flag for email being sent" required="yes" default="0">

object methods

<cffunction name="send" access="public" output="true" hint="Prepares and sends email to members">
    <cfargument name="objectid" required="yes" type="UUID">
    <cfset stObjMail = createobject("component", application.types.massMailer.packagepath)>
    <cfset massObj = stObjMail.getData(objectid=arguments.objectid)>        
    <cfinclude template="send.cfm">


Again, more of the same. Except we also used a rich text for generation of our "Pretty" email body. Examples of such types exist in the core. Two things worth noting is the send function and the array of massMailerList(s). I plan to fully expound upon this in part II or III, but for now, know that it's there for us when it comes time to send out our mass mail!

Oh, and thank the heavens for FireFox's built in spell checker... it at least keeps these posts from being slightly more legible than I could manage without it.

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
Matthew Bryant's Gravatar Hey Matthew,

Love your work. Just little update

"ftwizardSet - Should give pagination, but it isn't working (for me) at this time"

1. Should be ftWizardStep ;)
2. Their needs to be more that 1 ftWizardStep value for it to become relevent. You notice that in the massMailerUser cfc all values of ftWizardStep are "General Details". If you added another property and gave its ftWizardStep a value of "Advanced" for instance, the default administration edit page would become a wizard with 2 steps, "General Details", and "Advanced".

Cheers, Mat.
# Posted By Matthew Bryant | 2/22/07 5:12 PM
Matthew Williams's Gravatar Ah! Well, I'll have to try this later tonight (and make updates as appropriate). I thnk I only really tried this in massMailer, to split up the various email body steps. Thanks much, and if ya'll keep producing good code, I'll keep documenting how to use it!
# Posted By Matthew Williams | 2/22/07 6:33 PM
Matthew Williams's Gravatar Mat,

If you look at massMailer.cfc, it does have separate steps, but it places them all in the same page for me. Am I missing an include somewhere?
# Posted By Matthew Williams | 2/23/07 10:08 AM