THE UMBRACO INSTALLATION COMPONENTS

As you know by now an Umbraco installation is made from a series of components. In this section you'll read more about which ones make up this sample application and how they function in relation to your Umbraco installation.

Before you install, you need to configure your Visual Studio project to reference the following Umbraco libraries, as shown in Figure 15-1.

• businesslogic
• cms
• interfaces
• umbraco

FIGURE 15-1

Now that you have the libraries configured, you'll need to set up the document types, templates, macros, and event hooks that will run the example. These are outlined in the following sections.

Document Types

A few document types are needed to support the classified ads. This section shows how to use them and how they relate to the overall website. Table 15-1 describes each document type in detail.

Templates

Because you are leveraging one of the standard Umbraco skins, very little template work is involved in this sample application. Only one master page template is required in this case, and you use this master to output the details of a classified ad. Instead of starting from scratch and reworking the layout of the site, you can use the available Textpage template as a parent masterpage and inject the output from the ClassfiedAdDetails.xslt macro. Listing 15-1 contains the simple template code that was added to the Textpage.master file.

TABLE 15-1: Classified Ads Document Types

FIGURE 15-2

LISTING 15-1: Textpage.master

<%@ Master Language=“C#” MasterPageFile=“∼/masterpages/umbMaster.master”
AutoEventWireup=“true” %>
<asp:Content ID=“Content1”
        ContentPlaceHolderID=“cp_content” runat=“server”>
    <div id=“subNavigation”>
        <umbraco:Macro ID=“Macro1” Alias=“umb2ndLevelNavigation”
runat=“server”></umbraco:Macro>
    </div>
    <div id=“content” class=“textpage”>
        <div id=“contentHeader”>
          <h2><umbraco:Item ID=“Item1” runat=“server”
field=“pageName”/></h2>
        </div>

        <umbraco:Item ID=“Item2” runat=“server” field=“bodyText” />
        <asp:contentplaceholder id=“ClassifiedDetails”
runat=“server”></asp:contentplaceholder>
    </div>
</asp:Content>

The highlighted code snippet in Listing 15-1 shows what was added to the skin file. All this does is provide a target region to add the classified ad details to. Listing 15-2 shows what the added template, ClassifiedAdDetails.master, looks like.

LISTING 15-2: ClassifiedAdDetails.master

<%@ Master Language=“C#”
   MasterPageFile=“∼/masterpages/umbTextpage.master”
   AutoEventWireup=“true” %>
<asp:content ContentPlaceHolderId=“ClassifiedDetails” runat=“server”>
    <umbraco:Macro Alias=“ClassifiedAdDetails”
 runat=“server”></umbraco:Macro>
</asp:content>

The key to this file is the inclusion of the ClassifiedAdDetails macro, which renders all the properties of the individual classified ad that is currently displayed to the user.

Macros

As mentioned, you need a number of macros to support this level of customization. The XSLT that you use is a straightforward output with various filters. The .NET user control is how the user submits an ad without logging into the Umbraco backoffice and how you can instruct Umbraco to programmatically create a node using the Umbraco document API. Table 15-2 describes the features and functionality of each of the XSLT-powered macros.

TABLE 15-2: XSLT Macros

The .NET portion of this application takes care of creating the submitted classified ads and uses the Umbraco document API to accomplish this task. Table 15-3 provides an overview of what each component does in the ClassifiedAd .NET user control–powered macro.

TABLE 15-3: ClassifiedAd .NET Macro

You must pay attention to several things in the ClassifiedAd ascx.cs file:

• Public Properties: The properties defined in the class scope of this file are used to capture the macro parameters that are set in the Umbraco macro. The code uses these values for storing the submitted classified ad in the right place in the content tree and also for storing the accompanying image if one is uploaded.
• Reading Configurations: Lines 30–44 are all about reading the configuration file that is located in the <install root>/config folder.
• Display Custom Data Type Values: Lines 46–78 query Umbraco for the custom data types and loop over the returned XML to parse and set list items for the HTML form.
• Creating the Classified Ad: The submit_click method does all the heavy lifting for creating the Umbraco node. Line 87 calls the document API and creates the document using the public properties passed in using the macro parameters, as well as locally set parameters. Each property is then saved to the newly created document via the getProperty method. You then skip the publishing of the new document because you want it to be reviewed in the backoffice first. Finally, you see a redirect to the Thank You page, which was also passed in using the macro parameters.

Event Hooks

Chapter 12 covers the Umbraco event model. In the sample application, you tap into the event hooks made available to you when a node is published (or in this case before it's published).

The code folder in the sample application Visual Studio project contains the code that executes when a node is published, as shown in Figure 15-3.

A couple of things to note when you open this file:

FIGURE 15-3

• The SetClassifiedAdExpiration class extends umbraco.BusinessLogic.ApplicationBase. Extending this class forces Umbraco to run it every time an action is performed in the Umbraco backoffice. This is what allows you to tap into the Umbraco event hooks and inject functionality to the backoffice without rewriting or changing the Umbraco source code. Cool, huh? The code in this case attaches to the umbraco.cms.businesslogic.web.Document.BeforePublish event.
• Make sure that the published node is of document type ClassifiedAd. If it's not, then the process continues.
• Make sure that the parent of the published node is currently the Unreviewed Ads node, as shown in Figure 15-4.

FIGURE 15-4

All this code executes when a user clicks the Save & Publish button located in the top toolbar in the Umbraco backoffice.

Of course, many other things can happen in this type of event hook that have not been implemented here; for example, sending an email notification to the user who submitted the ad with a message that the ad is now live.