In previous articles we discussed how to extend the native FarCry objects and how to create a form to manage these new objects. Today we will discuss what we modified to allow users to see the form.
Since we needed to use a new form for users to update their profile, and we wanted it to appear in the main content area rather than in a pop-up window, we needed to not only modify the menu, but some files in the core code. Whenever you are customizing or extending native FarCry objects, you should avoid modifying any code in the ‘core’. Any code you modify in the core can, and most likely will, be overwritten with any updates to the code base.
First, we needed to identify which files we were going to need from the core, and copied them to our project directory, mimicking the directory structure. To get users to be able to edit their profile using our new form, we needed to copy over the ColdFusion page that is displayed in the side bar when you first log in to the admin. We simply copied the {FarCry Core}/admin/overview directory to {Project Directory}/customadmin. Lastly, we copied {FarCry Core}/packages/types/_dmProfile/displaySummary.cfm to {Project Directory}/packages/types/_dmProfile/displaySumamry.cfm.
The first change we need to make is in displaySummary.cfm. We simply need to change the ‘Edit Your Profile’ link to open our new form in the main content area, rather than opening the old form in a pop-up window. Here is what the old code looked like:
<a href="##" onClick="javascript:window.open('#application.url.farcry#/edit.cfm?objectID=#session.dmProfile.objectID#&type=dmProfile', 'edit_profile', 'width=459,height=500,left=200,top=100,scrollbars=yes'); startTimer(#application.config.general.sessionTimeOut#)" title="#application.adminBundle[session.dmProfile.locale].editProfileLC#">#application.adminBundle[session.dmProfile.locale].editProfileLC#</a>
And here is the new code.
<a href="#application.url.farcry#/conjuror/invocation.cfm?objectid=#stObj.ObjectID#&typename=dmProfile&method=edit" title="#application.adminBundle[session.dmProfile.locale].editProfileLC#" target="content">#application.adminBundle[session.dmProfile.locale].editProfileLC#</a>
The new URL tells FarCry that we are editing an object with an objected of ‘stObj.ObjectID’ and that the object type is ‘dmProfile’.
The next change we need to make is to sidebar.cfm. By default, when a user logs in for the first time, the edit profile form opens in a pop-up window. So, we need to change the code to open our new form in the main content area.
Old code:
<cfif session.firstLogin>
<cfoutput>
<script type="text/javascript">
profileWin = window.open('#application.url.farcry#/edit.cfm?objectID=#session.dmProfile.objectID#&type=dmProfile', 'edit_profile', 'width=385, height=385, left=200, top=100'); alert('#application.rb.formatRBString(application.adminBundle[session.dmProfile.locale].firstTimeLoginBlurb, "#application.config.general.siteTitle#")#'); profileWin.focus();
</script>
</cfoutput>
<cfset session.firstLogin="false">
</cfif>
New code:
<cfif session.firstLogin>
<cfoutput>
<script type="text/javascript">
parent.content.location = "#application.url.farcry#/conjuror/invocation.cfm?objectid=#session.dmProfile.objectID#&typename=dmProfile&method=edit"; alert('#application.rb.formatRBString(application.adminBundle[session.dmProfile.locale].firstTimeLoginBlurb, "#application.config.general.siteTitle#")#');
</script>
</cfoutput>
<cfset session.firstLogin="false">
</cfif>
The last piece of this puzzle is how we load the new page into the side bar. We do so by editing the {project directory}/customadmin/customadmin.xml file. With this file, we have the ability to create new menu options, as well as overwrite, or append exitsing menu items. In our case, we needed to overwrite the section named ‘Overview’. Here is how our XML block looked for this:
<webtop>
<!--change Overview tab-->
<section id="home" label="application.adminBundle[session.dmProfile.locale].overview" labelType="evaluate" mergeType="merge" permission="MainNavMyFarcryTab" sequence="1000">
<subsection content="overview/home.cfm" id="overview" label="application.adminBundle[session.dmProfile.locale].overview" labelType="evaluate" sidebar="admin/customadmin.cfm?module=overview/sidebar.cfm"/>
</section>
...
</webtop>
As you can see below, most of this is very similar to the original XML, found in {FarCry core}/config/webtop.xml.
<webtop>
<section id="home" label="application.adminBundle[session.dmProfile.locale].overview" labelType="evaluate" permission="MainNavMyFarcryTab" sequence="1000">
<subsection content="overview/home.cfm" id="overview" label="application.adminBundle[session.dmProfile.locale].overview" labelType="evaluate" sidebar="overview/sidebar.cfm"/>
</section>
...
</weptop>
Let’s break down the XML a bit and explain what everything means.
The ‘section’ will tell FarCry to display a tab in the top navigation. The important attributes here are mergeType, permission, label and labelType. MergeType tells FarCry how to handle the menu if duplicate items exist. In this cacse, we are telling FarCry to merge our item with the default item. Permission tells FarCry what permissions a use must have in order to view the tab and its contents. Label is what will be displayed in the tab. Finally, labelType tells FarCry how to handle the label. By default, labelType is ‘text’ which means that the label value is treated as a literal. In our example, its treated as a variable and is evaluated to display to value of the variable specified.
The ‘subsection’ refers to any items shown in the drop-down box at the top of the sidebar. If only 1 subsection exists, no drop-down box will be displayed and that subsection will be displayed by default. The important attributes shown are sidebar and content. Each of these tells FarCry what pages should be displayed in the sidebar and content frames when that item is selected.
There is more to learn about with the web top, but I will save that for a future post as I wanted to discuss specifically what we did for our custom profile form.
So, by breaking down our new XML, you can see that we are merging our item into the section labeled ‘Overview’, and that when that tab is clicked, it will load ‘admin/customadmin.cfm?module=overview/sidebar.cfm’ into the side bar frame and ‘overview/home.cfm’ into the content frame. So now, when a user logs in they will see our custom sidebar.cfm page and when they login for the first time or click to edit their profile, they will see our new custom form loaded in the main content area.
As you can see, in FarCry, just about everything can be extended or customized. In the last few entries we discussed how to extend a native FarCry object, namely dmProfile, how to create a form that will allow users to edit the new properties and finally, how to edit the menu system and some core files that will let users see the form.
It may have been easier to edit the core file to fit our needs, but then these changes would have been universal for every FarCry site on the server. By moving the necessary files from core into out project, we are able to have our customizations without worrying about them being overwritten or affecting other FarCry sites running on our server.
Up next will be a post discussing creating a custom content type from scratch.
DougHughes.net 