919 - 926 - 9847

My First Farcry Plugin... it's done, and here it is

Alrighty. I've created a zip of the plugin, and it will be available from here to download.

Installation instructions:

1) Install the latest version of FarCry Beta from either Jeff Coughlin's site or from the FarCry CMS page. Pertinent installation information can be found at their respective sites.

2) Modify your project//www/Application.cfm so that the plugins list includes massMailer in the list. This is a comma delimited list.

3) Open the FarCry admin and click on the Admin tab. Select COAPI from the dropdown list, and then click types. Deploy the three massMailer types. Next click rules, and deploy the massMailer rule.

Usage

Example 1: You want to have a form add a user to an email distribution list.

1) Open the FarCry admin and click on the Mass Mailer tab.

2) Click (in the left hand pane) the Mass Mailer List to create a new list.

3) Click Add to create a new List. Each List has two properties, a name, and a list of emails. We'll only worry about the name for now. Give the List a name, and Save.

4) Open a window to view your FarCry site. Switch to Design Mode, and click on a container where you'd like the new form to reside.

5) Choose the Mass Mailer Rule from the list, and add it to the container using the Commit button. This should take you to the next step. From here, select the Display Method (one is supplied for you), and use the Open Library to add a list. You can add only one list per rule! I'm thinking of modifying this in the future, but for now it stays. Save the results.

6) Refresh the page, and you should now see a form containing the Name and Email fields. Complete the form, and once submitted, it will add a new entry to your list (as well as create a new massMailerUser object). To verify, open the FarCry admin/Mass Mailer Tab and edit the Mass Mailer List you just created.

Example 2:

1) Follow steps 1-3 above. While still in the open library, you can choose to attach a new object.

2) Otherwise, click Mass Mailer User, add the new user, and then attach using the open library from Mass Mailer List.

Sending Mail

1) Open the FarCry admin, and click the Mass Mailer tab.

2) Click on the Mass Mailer link in the left hand pane. And then click Add from the top navigation.

3) Fill out the form fields as required. You need, at minimum, the Subject and List (open library). You can add as many lists as you like to the email.

4) There is a plan to add an attachment to the emails, but that's slated for the next release.

5) Save the object. Then select the object, and from the top/central navigation buttons, click Send.

The end! Tomorrow (or as time permits) I'll break down the objects and the "Why" of it.

My First Farcry... well, plugin is the term now, take 3.1

Alright. We have successful email creation in place. You can also assign a rule and a webskin to the rule. The final piece is adding the massMailerUser object to the massMailerList object via an online form. This should be completed tonight, family willing, and I'll start the break down/analysis of what each file does, and why. Thank you ray for the use of code tags, which ya'll will see extensive use of tomorrow ;).

Update: so close to the finish I can almost taste it... however, it's late. I need to sit in on performance tests tomorrow morning, so it will need to wait until tomorrow afternoon to finish up. The good news, though, is it works! I need to cull the deadwood of copied functions from the core/admin/facade/library.cfm that will not be used, but it appears that everything is working as it should. Yay!

My First FarCry library take 3

I finally got some free time to move this project towards completion. And then things went to heck in a handbasket when Daemon decided to change around the code base ;). So, what has changed is that farcry_core is now just core. Projects have moved to a projects folder. And farcry_lib is now plugins. That last is what really affected me. I had to change my customadmin and customlists to reflect this change.

As Stephen mentioned in previous comments, Formtools is just too sexy for itself. I went the easy route for the time being, but will climb the hard road in time.

My three objects still exist, one calling the other using the open library feature of Formtools. The only drawback I can fore see is there is no way to select multiple objects at a time. I'll see if anyone has extended this yet. This is now working smashingly.

Next up, setup the special columns required to send mail through the admin. Then, finally, adding users to lists via the web signup form.

Update: And we have success! You now create a user. Assign the user to a list(s). Assign that list to an email to be distributed, and then send. Full source to be fourth coming as soon as the rule (which can be dropped into a page) and webskin templates are setup. Maybe tonight, maybe tomorrow.

Update 2: The rule for adding the massMailer to a page has been created (which was pretty simple). Now the tough part... adding the formtools functionality to the webskin. Since we're attaching a new objectid into the massMailerList object, seems to be the most practical way of doing so. Of course, we could do it by straight database manipulation, but where's the fun in that ;).

My First FarCry library take 2

So, I'm going to need three different objects to accomplish this task. One massMailer, massMailerList and massMailerUser. The massMailer object is the main object, and it contains fields for From, Body, To (shown as a dropdown, but really a link to the massMailerList object), etc. The massMailerList object contains a title, and an array of massMailerUser objects. The massMailerUser object contains things like name, email, date added. Whew. These objects have been deployed, and their associated table data has been created.

Next up, creating the display methods and tweaking code so that Formtools displays the object properties correctly. However, given the lateness of the hour, it's not happening tonight.

Update: Sorry to those who are watching in anticipation of an early completion. Due to sick family members, I can't really finish this up until tomorrow night. On that note... sleep awaits.

Next up on deck... My First FarCry lib!

I'll add to this post, hopefully to completion, tomorrow. At one point, I had a fairly decent mass mailer set up in FarCry 2.x/3.x. I left that employer but still have most of the code required. It was a modification of the dmEmail object to allow for the a list of emails to be inserted into a variable via CFFILE. You'd upload the list to the server, then import said list to an array.

So, I'm working on site for my son's preschool, and it would be helpful to have similar functionality. But, with a twist. I want the library to capture emails into subscription pools, then use these pools to send out the various emails. The idea being that those looking to get updates from the preschool will join one (or more) of the mailing lists, then receive updates based on the list that was joined. I'll be placing this into the new FarCry 4.0 library feature and making the code available here, and on the FarCry lists/wiki.

Update: I've seriously underestimated this task. Much has changed under the hood of FarCry that I'm only just getting back into. At the moment, the extension to formtools has been created. Dang is that a cool new feature ;). I've got the main display item for Mass Mail distribution 90% complete. But, I've run into an issue of making aObjectIDs for the underlying list emails that gets called. This has REALLY changed, and will take a little more time to deconstruct. It's late, I'm off for now.

Update2: Please bear with me. There's not much going to be accomplished today. I'll try finishing up tonight, but we'll take the day as it comes.

Installing FarCry as a virtual site in IIS

This is specific to the FarCry 4.0 release. At the time of this writing, you can grab it from http://www.jeffcoughlin.com/?pg=11. From this site, be sure to get farcry_core, fourq, farcry_mollio, farcry_lib.farcrycms.

First, our directory structure. Unzip the zips into
C:\farcry40\farcry_core
C:\farcry40\fourq
C:\farcry40\farcry_mollio
C:\farcry40\farcry_lib\farcrycms

You will need to create a project folder. Create a copy of farcry_mollio, and place it into either: C:\farcry40\somesite Or C:\websites\somesite

If the folder is placed outside of the FarCry root, additional steps will need to be followed. Those steps will be listed below. Follow the steps below to complete the installation. Please note that the folder paths used are merely provided as an example.

  1. Open the IIS administrator. Add the virtual site somesite off of your main domain website. Eg. Mainsite.com/somesite. To do this, right click the website to modify, and click New->Virtual Directory.
  2. Fill in the Alias as somesite, click Next. Path will be either C:\farcry40\somesite\www, or the optional folder outside of farcry at C:\websitse\somesite\www.
  3. Choose access permissions as appropriate for your environment. Click Next then Finish to continue.
  4. Create a new virtual directory in a similar fashion for farcry. Right click the newly created somesite folder and click New->Virtual Directory. The alias is farcry and the path is C:\farcry40\farcry_core\admin.
  5. Create a new database user/schema/database/etc to hold the FarCry table information. This document is database agnostic, and assumes the user has some means of affecting these changes. Regardless, FarCry should have its own schema/database to reside in.
  6. Log into the ColdFusion (CF for short) administrator and create mapping for a logical path of /farcry and directory path of C:\farcry40.
  7. Optional - if the project folder is outside of the FarCry folder, create a mapping for a logical path of /farcry/somesite and a directory path of C:\websites\somesite.
  8. Create a new CF datasource called somesite_farcry pointing to the database/schema created in step 5.
  9. And, this was submitted to the FarCry list... change somesite\www\install\FlightCheck.cfc to:
    <cfinclude template="/#arguments.siteName#/install/ping/index.cfm" />
  10. At this point you should now be ready to run the FarCry installation scripts. Open a browser to mainsite.com/somesite/install. If running from somewhere other than localhost, be sure to edit C:\farcry40\somesite\www\install\Application.cfm (or C:\websites\somesite\www\install\Application.cfm) to reflect your IP.
  11. Fill in the required fields. The application name must match the folder name you've created. In this case it is somesite. Fill in the DSN name, and the database type. The website mapping should be /somesite and the FarCry mapping should be /somesite/farcry. Choose to install the farcrycms library, and if in production, remove the installation folder.
  12. At this point, everthing should be ready to go. Click Install and watch the output of the screen. If any errors occur, either report them back to the FarCry mailing list, or investigate where the installer indicates there to be a problem.
  13. Add this line to somesite\config\_serverSpecificVars.cfm: <cfset application.url.webroot = "/somesite">

FarCry installation on a linux/Plesk shared host

First, just a little “this is WHY we do this” (and only a little, I promise!).  Everyone seems to get a touch freaked out when going over the FarCry install and its various mappings.  The thing to keep in mind is that the mappings and folder structure exist because FarCry relies heavily upon CFCs and extension of these CFCs.  Even your site, eg. “Project”, relies upon being able to map to these CFCs in a preordained fashion.  The easiest way to pull this off is to have everything reside inside the main FarCry root.

Now, that was the 3.0 and lower builds.  FarCry 4.0 introduced the ability to have the “Project” folder reside completely separately from the FarCry core.  Or, at least that’s my understanding from the new features document.  I’ve not tried this with 3.x (but I do have another method for that!)  Anyway, if this is done, you must make sure that you create a CF mapping to these files in a way that FarCry can reach them.  Since FarCry assumes that the “Project” folder resides in the FarCry root, you need to make a CF mapping that imitates that.  Thus, you need to make the normal CF mapping for FarCry (something like /farcry c:\farcry40) and a mapping to your site, pre-pending farcry to it (/farcry/somesite c:\websites\somesite).  This mapping MUST match what you called the site when installing FarCry.  So, a call to farcry.somesite.whatever will work correctly.  All is good with the universe.

So let’s do an example of this for FarCry 4.0 and the linux shared host out on the interweb using Plesk. 

  1. Upload FarCry (and all of it’s supporting libraries farcry_core, fourq, farcry_lib) to one of your domains httpdocs directory.  Doesn’t matter which, really.  One you know will not be deleted.  Ever.
    eg /home/httpd/vhosts/mainsite.com/httpdocs/farcry40
  2. Ask the CF admin of your box to create a CF mapping like:
    /farcry /home/httpd/vhosts/mainsite.com/httpdocs/farcry40
  3. Upload the mollio template (renamed to somesite) to the domain that will be hosting a FarCry site:
    /home/httpd/vhosts/somesite.com/httpdocs/somesite
  4. Ask the CF admin of your box to create a CF mapping like:
    /farcry/somesite /home/httpd/vhosts/somesite.com/httpdocs/somesite
  5. Now, this is really, REALLY handy.  Ask the CF admin to create a vhost.conf file for your somesite domain.  This file will never be over written by Plesk and can be used to override the values Plesk sets.  The file should contain:
    DocumentRoot "/home/httpd/vhosts/somesite.com/httpdocs/somesite/www"
    Alias /farcry /home/httdp/vhost/mainsite.com/httpdocs/farcry40/farcry_core/admin
  6. Create a database to hold your FarCry information, and ask the CF admin to create DSN pointing to this database
  7. Once Plesk gets restarted, browse to www.somesite.com/install and fill in the values as required.  App name in this case is “somesite”, and the project web mapping and farcry web mapping should not be changed.  Click install once all fields are complete
  8. Repeat per domain as necessary. Make sure everyone and every group can write into the FarCry plp and tmp directories.

Now let’s do an example of this for FarCry 3.1 and the linux shared host out on the interweb using Plesk

  1. Upload FarCry (and all of it’s supporting libraries farcry_core, fourq) to one of your domains httpdocs directory.  Doesn’t matter which, really.  One you know will not be deleted.  Ever.
    eg /home/httpd/vhosts/mainsite.com/httpdocs/farcry31
  2. Ask the CF admin of your box to create a CF mapping like:
    /farcry /home/httpd/vhosts/mainsite.com/httpdocs/farcry31
  3. Upload the mollio template (renamed to somesite) to the farcry31 directory:
    /home/httpd/vhosts/mainsite.com/httpdocs/farcry31/somesite
  4. Now, this is really, REALLY handy.  Ask the CF admin to create a vhost.conf file for your somesite domain.  This file will never be over written by Plesk and can be used to override the values Plesk sets.  The file should contain:
    DocumentRoot "/home/httpd/vhosts/mainsite.com/httpdocs/farcry31/somesite/www"
    Alias /farcry /home/httdp/vhost/mainsite.com/httpdocs/farcry31/farcry_core/admin
  5. Create a database to hold your FarCry information, and ask the CF admin to create DSN pointing to this database
  6. Once Plesk gets restarted, browse to www.somesite.com/farcry/install and fill in the values as required.  App name in this case is “somesite”, and the project web mapping and farcry web mapping should not be changed.  Click install once all fields are complete
  7. Repeat per domain as necessary.  Make sure everyone and every group can write into the FarCry plp and tmp directories.  Make sure everyone and every group can read farcry directories.

The end! I much prefer the first method since it means each domain has its own files reside within the normal directory struture. Much more secure, much easier to manage. Better all around.

How to set up muliple instances for just one website

Now, I'm going to preface this with a note. If you multiple websites (eg multiple domains), you are in a much better position than I am. There are caveats to watch out for with multiple instances for just a single site, which will be detailed later on.

My day job is working as a government contractor, and the clients in our shared environment are only given virtual directories off the main domain root. And we're talking about about 50 total applications.

After (finally) getting FusionReactor installed in-house, we have started finding a trend about which applications have been causing problems with our environments. Since we were already using CF installed as J2EE applications, we decided to pull the trouble application into its own instance.

Now, we don't have much clout when it comes to making changes within the environments, so moving this one site into its own domain would/will require lots of paper work, approvals, and time. However, customers don't won't to hear an answer like that, so we came up with a way to work within the system, but didn't require moving a mountain.

So, the steps to get you where you're going:

  • First, I usually have a default cfusion-ear file waiting to roll. However, making a copy of your existing cfusion-ear works fine as well. Create a new folder within your {jrunroot}/servers directory for this new instance. We'll call it instance2. Copy the cfusion-ear file into this directory.
  • Log into the JMS, or click the ColdFusion Enterprise Manger if you have CFMX 7 installed in multiserver mode. Create a new instance and give it the same name as the folder you just created. So, instance2 for example.
  • If this is part of a cluster (mine are), create an instance on the other machine(s). CAUTION: Make certain that each instance, if it's to be part of a cluster, MUST have a unique name. I did not know this until it bit me and caused all kinds of replication issues.
  • If this is part of a cluster, create the cluster and add the instances. Otherwise, skip this step.
  • Start IIS admin (I haven't tested this on apache yet) and create a new website. Doesn't really matter where it points to, or the port that it exists on. This has been tested on IIS 5/6.
  • Start up the JRun website configurator. I generally call the jar file directly as the default JVM is 1.3 on our systems, where the ColdFusion JVM is 1.4 which is required. Add a new site, and select the instance/cluster you just created and map it to the website you just created. Make sure to check to the box to install the ColdFusion connector.
  • You now have a new numbered directory in {jrunroot}/lib/wsconfig. You can now map the virtual directory to use this connector instead of the default connector. Open the properties of the virtual directory, select Configuration from the Directory tab. If you're using IIS 6, you can merely change the filter in one spot. If you're using IIS 5, you need to change the filter for each CFM type file.


Restart IIS and you should be good to go. So how do you know it's working? Well... you could install SeeFusion or FusionReactor. You could check the HTML headers to verify the JSESSIONID. The first four characters should match the {jrunroot}/servers/{instance}/server-inf/connector.properties. You could put code into your application that makes a call to serviceFactory that reports the instance information. And on and on.

So, the caveats:

  • Doing this WILL break CFCHART. In fact, anything that makes a call to /CFIDE that is interpreted by the web.xml file will be affected. There is a solution to this, and it will be the subject of my next blog post
  • You might have issues if you use session replication if the instances are in clusters. Let me give you an example. User visits your www.somesite.com/whatever. There is a link from there to the site in its newly created instance. The JESSIONID from the /whatever site still exists. Uh oh. You'll receive errors about failed session replication in the logs, and the user will get round-robined across the new cluster. This is especially a pain if there is any session information holding user values. The information will not be propagated across the cluster, and the users session will appear to be timed out. The only solution I've found to this is to either destroy the JESSIONID cookie, or pull the instance into its own website.