UNIT 11 - Plugins I

Objective

By the end of this unit, we should have an understanding of how FarCry navigates our project and plugins to find both content type metadata and relevant webskin locations.

Plugins

Every aspect of a project can be repackaged and used in another project as a plugin. This might be the entire project or just a small part of it. Most applications are combinations of several plugins. Community plugins include solutions for Google Maps, blogging, content management, free-text search engines and many, many more.

In essence, any FarCry application is a seamless merger of the core framework, the library of plugins associated with the application and the project itself. The project inherits everything represented in the collection of core, plugins and project code bases and is available in the running application. Importantly, if the same code is present in more than one location, a cascade model comes into play so that developers can change or override the behaviour of inherited functionality.

The order of the cascade is as follows:

• core; the framework itself is loaded first
• plugins; plugins are loaded in the order they are listed
• project; the project code base is the final arbiter of how the application behaves

Aspects of the framework that participate in this cascade include:

• content types
• webskins or views
• webtop configuration
• publishing rules
• formtools (components used to render form elements)
• components (effectively content types without database persistence)

Installing Plugins

If you nominate a plugin during the initial installation of your project, its code and content types should be automatically registered and deployed. However, if you are deploying a plugin to an established project you will need to get your hands just a little bit dirty.

To add a new plugin to your application you need to register the pluginname in the plugin list of the project's farcryConstructor.cfm file in the project's web root:

<cfset THIS.plugins = "farcrycms,googleMaps,farcryxud" />

After changing the plugin list you always need to refresh the application to register your changes.

Walkthrough: Installing Google Maps Plugin

1. Download the Google Maps Plugin
2. Copy the code base to the plugins folder of your installation
3. Update your farcryConstructor.cfm configuration file to include GoogleMaps
4. Re-initialise the application
5. Go to the Admin > Developer Utilities > COAPI Tools > Types and deploy the Google Maps content types
6. Go to the Admin > Developer Utilities > COAPI Tools > Rules and deploy the Google Maps publishing rules
7. Login to the webtop and update the Config for Google Maps with your API key
8. Create a publish a Google Map

Plugins & Content Types

Now that we understand the cascading relationship between FarCry Core, Plugins and a Project, the order of initialisation of the metadata for a particular content type is straightforward.

A good example is the Super Hero content type we created:

1. FarCry will find our content type definition (cfc) in /farcry/core/projects/superheroes/packages/types/superhero.cfc
2. It will then add all the property metadata into the application scope (application.stcoapi.superhero.stprops)
3. It will then introspect the content type that it extends (in this case it is /farcry/core/packages/types/types.cfc)

So it adds all the property metadata it finds here into our application.stcoapi.superhero.stprops. As a result we have application.stcoapi.superhero.stProps filled with the combination of all the properties in both those content types. We can see this using the COAPI Scope Dumper located in the webtop Admin > Developer Utilities > Scope Dump.

Walkthrough: Extending the News Content Type

Using this concept, we are going to extend the dmNews.cfc found in the farcrycms plugin and add some new properties.

1. Create a new file in projectName/packages/types/dmNews.cfc
2. Paste the following:

   <cfcomponent
     extends="farcry.plugins.farcrycms.packages.types.dmNews"
     displayname="News"
     hint="Dynamic news data">
   <cfproperty
     name="author" type="string"
     ftSeq="10" ftFieldset="Publishing Details" ftWizardStep="General Details" ftLabel="Author" />
   </cfcomponent>
   

3. Notice the value of extends: this says we are extending the properties and functionality found in farcry.plugins.farcrycms.packages.types.dmNews
4. Deploy our new property
5. Update our COAPI Metadata
6. Create a new News item in the webtop from "Content / CMS Content / News"
7. Notice our new author property now located in the correct position in the wizard

Webskin Inheritance

Once all of the types have been initialized in the fashion above, FarCry then finds all the webskins that are relevant for each type.

In the case of the superHero.cfc above, FarCry trawls through the folders in a predefined order to find any relevant webskins.

At this point it is important to remember that we have included 2 plugins into our project (farcrycms and farcrygreybox), so this process will include those plugins in its search to find relevant webskins.

In this case it will look in the following order for webskins for superhero.cfc:

/farcry/projects/superhero/webskins/superhero
/farcry/projects/superhero/webskins/types
/farcry/plugins/farcrygreybox/webskins/superhero
/farcry/plugins/farcrygreybox/webskins/types
/farcry/plugins/farcrycms/webskins/superhero
/farcry/plugins/farcrycms/webskins/types
/farcry/core/webskins/superhero
/farcry/core/webskins/types

Therefore ALL webskins in any of those locations will be available to the superHero content type. It is also important to note that only the FIRST webskin of the same name will be used. So, if we have a displayTeaserStandard in two of these folders, the first one the process comes across will be the one the project uses.

This allows us to override behaviour defined in core or a plugin and so on.

Lab: Override the displayPageFull News Webskin

Go ahead and update the full page display webskin for dmNews to include the new author property.