Muneeb's Blog

Learning Umbraco in a week - Day VI

2011-07-21T20:17:00.218+05:00

This is my sixth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

Introduction to Umbraco API
Working with the Umbraco Document API
Working with the Umbraco Node Factory
Introduction to Umbraco Events
Working with Umbraco Member API

Working with Umbraco User API
Working with Umbraco Relationship API

Introduction to Umbraco API

The Umbraco API give you programmatic access to everything in the Umbraco CMS. There are many ways to interact with the Umbraco API. From creating user-generated content from your web front-end via the Document API. To manage complex content relationships via the Relationship API. You can even represent the API as REST-Full Web Service Endpoints for use by your custom HTML Forms or web services.

Working with the Umbraco Document API
The Umbraco Document API provides programmatic access to Umbraco CMS Documents. The API provides the Document data which is stored inside the database.

1. Using the Umbraco Document API
For using the Umbraco Document API, add the cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

using umbraco.BusinessLogic;
using umbraco.cms.businesslogic.web;

2. Creating an Umbraco Document
The following Code Snippet creates an Umbraco Document and publish it.

//First of all, we need to get the appropriate Document Type

DocumentType docType = DocumentType.GetByAlias("Home");

// Here we will get the appropriate creator of the Document.
User author = User.GetUser(0);

//For creating a Document we also need to mention the parent node
//As this is the root document, we will use -1
Document doc = Document.MakeNew("Hello World", docType , author, -1);

//The Document has been created
// We will now publish the Document
doc.Publish(author);

//We will ask Umbraco to update the Document Cache
umbraco.library.UpdateDocumentCache(doc.Id);

3. Modifying Document Properties
The following Code Snippet get an Umbraco Document, modifies its properties and publish it.

//First of all, we will get the appropriate Document
Document doc = new Document(786);

//Get the appropriate properties and modify the values
doc.getProperty("bodyText").Value = "<p>Hello World!</p>";

//The Document has been modified
// We will now publish the Document
User author = User.GetUser(0);
doc.Publish(author);

//We will ask Umbraco to update the Document Cache
umbraco.library.UpdateDocumentCache(doc.Id);

4. Enumerating Documents Children
The following Code Snippet get an Umbraco Document and enumerates its children.

//First of all, we will get the appropriate Document
Document doc = new Document(786);

//We will check the Document's HasChildren property
//before enumerating through the Children array
if (doc.HasChildren) {
    //Now we will enumerate through the Children array
    Document[] children = doc.Children;
    foreach (Document childDoc in children) {
      Response.Write(childDoc.Text);
    }
}

5. Attaching Document Event Handlers
The following Code Snippet attach to the Document beforePublish event.

protected void Page_Load(object sender, EventArgs e) {
     Document.BeforePublish +=
        new Document.PublishEventHandler( Document_BeforePublish );
}

void Document_BeforePublish(
    Document sender, umbraco.cms.businesslogic.PublishEventArgs e ) {
    Response.Write(sender.Text + " is being published");

    //We will set the EventArgs.Cancel = true, i.e. for cancelling the event
    e.Cancel = true;
}

6. Moving a Document
The following Code Snippet moves an Umbraco Document beforePublish event.

//First of all, we will get the appropriate Document
Document doc = new Document(786);

//Move the document the new Parent Node
int newParentNode = 1234;    doc.Move(newParentNode);

//We will ask Umbraco to update the Document Cache
umbraco.library.RefreshContent();

Working with the Umbraco Node Factory
The Umbraco Node Factory is a strongly type presentation of the in Memory XML Cache optimized for reading (it's read-only). Which means it's very fast and only includes published content. The API provides the Node data which is published (and stored inside the Umbraco.config).

1. Using the Umbraco Node Factory
For using the Umbraco Node Factory, add the interfaces.dll, cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

using using umbraco.NodeFactory

2. Retrieving an Umbraco Node
The following Code Snippet retrieves an Umbraco Node.

Node node= new Node(786);
//Use Node.GetCurrent() method to get the Current Node
string bodyText= node.GetProperty("bodyText").Value;
string nodeName = node.Name;
DateTime nodeCreationDate = node.CreateDate;
string nodeUrl = node.NiceUrl;

Introduction to Umbraco Events
For registering events in Umbraco, ApplicationBase class is used, as it is called automatically when Umbraco loads.

1. Using the Umbraco Events
For using the Umbraco Events, add the cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

using umbraco.BusinessLogic;
using umbraco.cms.businesslogic;
using umbraco.cms.businesslogic.web;

2. Registering Events in Umbraco
The following Code Snippet extends the ApplicationBase class and registers the event in the default constructor.

public class AppBase : umbraco.BusinessLogic.ApplicationBase {

    public AppBase() {
      Document.BeforePublish +=
        new Document.PublishEventHandler(Document_BeforePublish);
    }

    void Document_BeforePublish(Document sender, PublishEventArgs e) {
      //TODO
    }
}

3. Overview of All Events
Events can be attached with the following Umbraco objects.

Document
Access
DocumentType
Domain
StyleSheet
StyleSheetProperty
Member
MemberGroup
MemberType
CMSNode
Dictionary
Media
MediaType
DataTypeDefinition
Language
Macro
CreatedPackage
InstalledPackage
Template
ContentControl
BaseTree
User
Content

Working with the Umbraco Member API
A Member in Umbraco is an external person, who has a profile on the website. Members are distinct from Umbraco Users, meaning that a Member do not have access to the Umbraco back-end. The Member API provides access to the Members data which is stored inside the database.

1. Using the Umbraco Member API
For using the Umbraco Member API, add the umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

using umbraco.cms.businesslogic.member;

2. Creating a Member

The following Code Snippet creates an Umbraco Member and sets a property.

//First of all we will have to select the appropriate Member Type
MemberType memberType = MemberType.GetByAlias("standard");

//Create a member

Member member =

Member.MakeNew("Awan", memberType, new umbraco.BusinessLogic.User(0));

//Set a property value on the member

member.getProperty("city").Value = "London";

//We will ask Umbraco to update the Member Cache

member.XmlGenerate(new System.Xml.XmlDocument());

//Save the Member

member.Save();

3. Adding Member to a Group

The following Code Snippet add an Umbraco Member to a Group and then removes it.

//First of all we will have to select the appropriate Member

Member member = Member.GetMemberFromEmail("muneeb@email.com");

//Get the appropriate Member Group

MemberGroup memberGroup = MemberGroup.GetByName("admin");

//Add Member to the Group

member.AddGroup(memberGroup.Id);

//Remove Member from the Group

member.RemoveGroup(memberGroup.Id);

Working with the Umbraco User API

Umbraco provides access of Umbraco Back-End via Umbraco User API for writers, translators, editors and administrators.

1. Using the Umbraco User API

For using the Umbraco User API, add the umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

using umbraco.BusinessLogic;

2. Creating a User and allow Access to Umbraco Section

The following Code Snippet creates an Umbraco User and sets a property.

//First of all we will get the appropriate User Type
UserType userType = UserType.GetUserType(123);

//Create a new User
User.MakeNew("Awan", "awan", "secrectPass", userType);

//Get the User via Login
User user = new User("awan");

//Add User Email
user.Email = "muneeb@email.com";

//Allow access to Umbraco Section
user.addApplication("settings");

//Save the User
user.Save();

Working with the Umbraco Relationship API

The Umbraco Relationship API enables associations or links between Typed NodeIds be defined. For example, you may wish to make a connection between Members and Email (Document) etc.

1. Using the Umbraco Relationship API

For using the Umbraco Relationship API, add the umbraco.dll to your project. Then we need to defien an Umbraco Relation Type

A row first needs to be added into the UmbracoRelationType Table in the Database (Detail available below).
The Relation Types Package can used to define a type of link.

It's then possible to progmatically add / remove and quickly select relationships between typed Ids. We can now add references to the following namespaces at the top of your .cs file.

using cms.businesslogic.relations

2. Object GUIDs for Creating Relation Types

To setup a RelationType in Umbraco, we will need the exact GUID of the appropriate Types, e.g, Document to Member, Member to Media, Media to Media.

A list of all the built Object Types and their GUIDs is below.

ObjectType	Description
C66BA18E-EAF3-4CFF-8A22-41B16D66A972	Document
B796F64C-1F99-4FFB-B886-4BF4BC011A9C	Media
6FBDE604-4178-42CE-A10B-8A2600A2F07D	Template
39EB0F98-B348-42A1-8662-E7EB18487560	Member
A2CB7800-F571-4787-9638-BC48539A0EFB	DocumentType
366E63B9-880F-4E13-A61C-98069B029728	MemberGroup

For a complete his list of Object Types please visit, Hendy Rachers Blog.

That's all for this post, in the next post (Learning Umbraco in a week - Day VII) we will have a look at LINQ to Umbraco.

Learning Umbraco in a week - Day V

2011-07-21T20:17:00.022+05:00

This is my fifth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

What are .Net Macros in Umbraco?
How to use .Net User Controls in Umbraco?
How to Parametrize a Macro?
Communication between Umbraco and User Control
How to Debug a Macro in Umbraco?
How to Cache Macro result in Umbraco?

What are .Net Macros in Umbraco?

.Net Macros are Umbraco's means of inserting .Net Controls into templates or content, to start. They are also the carrier for custom .NET controls.

How to use .Net User Controls in Umbraco?

Using .Net Controls in Umbraco is a two phase process, the phase are listed below.

Phase 1 - Copying Files

First you need to copy your control. Whether it’s a User Control or a Custom Control you’ll need to copy the assembly (dll) into the /bin folder of your Umbraco installation.
If it’s a User Control you’ll need to copy the .ascx file as well.
Your installation already contains a / User Controls folder which is recommend to be used, but you’re free to place them anywhere in your application.

Phase 2 - Registering a .Net User Control as Macro

Go to Umbraco Default Page (Admin Page) > Sections > Developer
Right click on the Macros folder, and select Create.
You will receive a dialog where you can specify the name of the Macro to be created.
Specify the name of the new Macro, check Create Macro. Click Create.
Now select the macro from the list "Browse usercontrols on server…".
You have now created the Macro for rendering the content.

How to Parametrize a Macro?
It is possible to pass values from to a Macro in Umbraco. Values can be passed through the following ways.

Current Page node
Request collection
Cookies

To pass the Current Page's property with the alias "bodyText", the following syntax is used.

<umbraco:macro alias = "RenderProperties" pagevalue = "[#bodyText]" runat = "server"/>

Syntax for passing parameters through different ways is as follows.

To insert page value: [#propertyAlias]
To insert recursive page value: [$propertyAlias]
To insert cookie value: [%cookieValueKey]
To insert value from request collection: [@requestValueKey]
For passing multiple values <umbraco:macro value = "[#propertyAlias], [#propertyAlias2], my static string" />

Communication between Umbraco and User Control

Communication between Umbraco and User Control is done by creating Public Properties in your control and match them with Macro elements. Umbraco will even create the UI when inserting the Macro.

It’s important to note that the Alias of your Macro element matches the Name of your Public Property. Moreover, be aware of case sensitivity.

How to Debug a Macro in Umbraco?
NET controls are wrapped in Umbraco Macros and suddenly is out of the hands of Visual Studio doesn't mean you cannot use your favorite debugging practices, i.e. you can always utilize the Microsoft Visual Studio "Attach to Process" feature and debug .Net Macro.

For example, if Umbraco is hosted on Microsoft IIS then you will have to attach to "w3wp.exe", and if Umbraco is hosted on Microsoft WebMatrix then you will have to attach to "WebMatrix.exe".

How to Cache Macro result in Umbraco?
If you are using a User Control or XSLT, and have the Macro set to cache, it will cache the results of the control for the determined time.

That's all for this post, in the next post (Learning Umbraco in a week - Day VI) we will have a look at the Umbraco API.

Learning Umbraco in a week - Day III

2011-07-21T20:16:00.200+05:00

This is my fifth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

Introduction to XSLT
Introduction to XPath
Basic Structure of XSLT
How to link XSL Stylesheet to an XML Document?
How to apply XSL Transform?

Introduction to XSLT

XSLT is a document that is applied programmatically to an XML Document to manipulate the data. However, the structure of XSLT resembles that of XML, and contains specialized tags to perform specific actions to the data.

Introduction to XPath

XPath is a language for navigating in XML documents. Moreover, XPath is used by XSLT to find information in an XML document.

Basic Structure of XSLT

The structure of XSLT resembles that of XML, and contains specialized tags to perform specific actions to the data.

1. Top Declarations

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE xsl:stylesheet [ <!ENTITY nbsp " "> ]>
        <xsl:stylesheet version="1.0"
            xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
            xmlns:msxml="urn:schemas-microsoft-com:xslt"
xmlns:umbraco.library="urn:umbraco.library"
exclude-result-prefixes="msxml umbraco.library">
        <xsl:output method="xml" omit-xml-declaration="yes" />

2. The XML declaration
    <?xml version="1.0" encoding="UTF-8"?>

3. The root element that declares the document to be an XSL style sheet is <xsl:stylesheet> or <xsl:transform>.
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    or
    <xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

4. Parameter Declaration
    This is optional but a very important declaration, as it is the default link to the content published in the site.

    <xsl:param name="currentParam" />

5. Template Declaration
    This is the portion that is responsible for the processing and the output.

    <xsl:template match="/">
    …
    </xsl:template>

6. Closing the Style Sheet
    We close out the stylesheet, since this is XML, everything must be properly structured.

    </xsl:stylesheet>
    or
    </ xsl:transform >

How to link XSL Stylesheet to an XML Document?
To link XSL Stylesheet to an XML Document, add the XSL style sheet reference to the XML document, e.g. "sample.xml".

    <?xml-stylesheet type="text/xsl" href=“sample.xsl"?>

How to apply XSL Transform?
The most easiest way to apply XSL Transforms over an XML Document or Node is by using the Template Element.

A sample XML Document or Node used in the examples.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <catalog>
        <cd>
            <title>Empire Burlesque</title>
            <artist>Bob Dylan</artist>
            <country>USA</country>
            <company>Columbia</company>
            <price>10.90</price>
            <year>1985</year>
        </cd>
        . . .
    </catalog>

A list of XSL Elements commonly used in Transformations are listed below.

1. The <xsl:template> Element
A template contains rules to apply when a specified node is matched. The match attribute is used to associate a template with an XML element. The match attribute can also be used to define a template for the entire XML document. The value of the match attribute is an XPath expression (i.e. match="/" defines the whole document).

For example

    <xsl:template match="/">
<h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            …
        </table>
    </xsl:template>

2. The <xsl:value-of> Element
The <xsl:value-of> element is used to extract the value of a selected node. The select attribute contains an XPath expression. An XPath expression works like navigating a file system; a forward slash (/) selects subdirectories.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <tr>
                <td>
                    <xsl:value-of select="catalog/cd/title"/>
                </td>
                <td>
                    <xsl:value-of select="catalog/cd/artist"/>
                </td>
            </tr>
        </table>
    </xsl:template>

3. The <xsl:for-each> Element
The <xsl:for-each> element allows you to do looping in XSLT. Filtering the output by adding a criterion to the select attribute in the <xsl:for-each> element.

   <xsl:for-each select="catalog/cd[artist='Bob Dylan']">

Legal filter operators in XSLT are listed below.

= (equal)
!= (not equal)
< less than
> greater than

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <xsl:for-each select="catalog/cd">
                <tr>
                    <td><xsl:value-of select="title"/></td>
                    <td><xsl:value-of select="artist"/></td>
                </tr>
            </xsl:for-each>
        </table>
    </xsl:template>

4. The <xsl:sort> Element
The <xsl:sort> element is used to sort the output. To sort the output, simply add an <xsl:sort> element inside the <xsl:for-each> element. The select attribute indicates what XML element to sort on.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <xsl:for-each select="catalog/cd">
                <xsl:sort select="artist"/>
                    <tr>
                        <td><xsl:value-of select="title"/></td>
                        <td><xsl:value-of select="artist"/></td>
                    </tr>
                </xsl:sort>
            </xsl:for-each>
        </table>
    </xsl:template>

5. The <xsl:if> Element
The <xsl:if> element is used to put a conditional test against the content of the XML.

<xsl:if test="expression">
    ...some output if the expression is true...
</xsl:if>

The value of the required test attribute contains the expression to be evaluated.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
              <th>Artist</th>
          </tr>
            <xsl:for-each select="catalog/cd">
                <xsl:if test="price > 10">
                    <tr>
                        <td><xsl:value-of select="title"/></td>
                        <td><xsl:value-of select="artist"/></td>
                  </tr>
              </xsl:if>
            </xsl:for-each>
        </table>
    </xsl:template>

6. The <xsl:choose> Element
The <xsl:choose> element is used in conjunction with <xsl:when> and <xsl:otherwise> to express multiple conditional tests.

<xsl:choose>
    <xsl:when test="expression">
... some output ...
    </xsl:when>
    <xsl:otherwise>
        ... some output ....
    </xsl:otherwise>
</xsl:choose>

The value of the required test attribute contains the expression to be evaluated.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
      …
            <xsl:for-each select="catalog/cd">
                <tr>
                    <td><xsl:value-of select="title"/></td>
                    <xsl:choose>
                        <xsl:when test="price > 10">
                          <td bgcolor="#ff00ff"><xsl:value-of select="artist"/></td>
                    </xsl:when>
                    <xsl:otherwise>
                        <td><xsl:value-of select="artist"/></td>
                  </xsl:otherwise>
                  </xsl:choose>
                </tr>
            </xsl:for-each>
        </table>
    </xsl:template>

7. The <xsl:apply-templates> Element
The <xsl:apply-templates> element applies a template to the current element or to the current element's child nodes. If we add a select attribute to the <xsl:apply-templates> element it will process only the child element that matches the value of the attribute. We can use the select attribute to specify the order in which the child nodes are processed.

For xample

   <xsl:template match="/">
       <html>
            <body>
                <h2>My CD Collection</h2>
                 <xsl:apply-templates/>
            </body>
        </html>
    </xsl:template>

    <xsl:template match="cd">
        <p>
            <xsl:apply-templates select="title"/>
            <xsl:apply-templates select="artist"/>
        </p>
    </xsl:template>

    <xsl:template match="title">
        Title: <span style="color:#ff0000"><xsl:value-of select="."/></span>
        <br />
    </xsl:template>
    <xsl:template match="artist">
        Artist: <span style="color:#00ff00"> <xsl:value-of select="."/></span>
        <br />
    </xsl:template>

That's all for this post, in the next post (Learning Umbraco in a week - Day IV) we will have a look at the XSLT Macros in Umbraco.

Learning Umbraco in a week - Day IV

2011-07-21T20:16:00.170+05:00

This is my fourth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

What are Umbraco Macros?
How to use Macros as building blocks in Umbraco?
How Umbraco uses XSLT?
Creating XSLT Macro
Understanding the "currentPage" parameter
Understanding the XML Document Schema (v4.7)
XPATH Axes in Umbraco
A look at XSLT Macro Snippets

What are Umbraco Macros?

Macros are used to get and display data from Umbraco. For example, site maps, navigation, and news lists. This can be done using XSLT. Umbraco includes several pre-built XSLT Macros, and you can also create your own.

Umbraco Macros can also be used to wrap .NET user controls or custom controls, to include those in your Web Page.

How to use Macros as building blocks in Umbraco?

In Umbraco, Macros are small building blocks of functionality that can be dropped into an editor. Each Macro encompasses a piece of functionality, and provides a simple interface to be able to modify the macro to you requirements. Importantly, Macros can be placed in transforms, templates, and rich-text, and the Umbraco GUI provides a button for this in the relevant section.

How Umbraco uses XSLT?
Umbraco utilizes XSLT to dynamically render content such as navigational structures, lists, and nearly anything you can dream of. This is accomplished through the use of Macros.

Creating XSLT Macro
Creating a Macro in Umbraco is very easy.

For creating an XSLT Macro in Umbraco, follow the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Developer > XSLT Files.
Right click on the XSLT Files node, and select create.
You will receive a dialog where you can specify the name, select an XSLT template, and specify if you want to automatically create the Macro for this template.
Specify the name of the new XSLT file, check Create Macro, and select a template if you desire. Click Create.
You have now created the XSLT file and the Macro for rendering the Content.

Understanding the "currentPage" parameter

The currentPage parameter is the complete XML document of the published site, and is how we reference the data stored in each document.

It is important to note that, by default, the context of the XML document is set to the requested Web Page. The XML document, as mentioned before, contains all the content of the published documents. This data is stored in the XML document structured in the same manner as your tree is laid out in Umbraco. So, documents are nested to create the hierarchy that we can easily use.

An Umbraco Node (The "currentPage" parameter) consists of several common pieces of data, and they are listed below.

id
version
parentID
level
writerID
creatorID
nodeType
template sortOrder
createDate
updateDate
nodeName
urlName
writerName
creatorName
nodeTypeAlias path

All these are store as Attributes of the Document (Also called "Node").

Moreover, the Properties that are added to the Document in Umbraco, and what the user edits are referenced as "Data". Data consists of a couple common pieces of data, which are Attributes on the data elements. These are listed below.

alias
versionID

Understanding the XML Document Schema (v4.7)

In Umbraco, each Document Type has it's own Node using the Document Type alias - <Home> as opposed to the previous convention <node documentTypeAlias="home">.

Each Property has it's own Node underneath the Document Type node <umbracoNaviHide> as opposed to the previous convention <data alias="umbracoNaviHide">.

It is important to note that, the difference between a Document Type Node and a Property Node is that the Document Type Node has the blank attribute isDoc <home isDoc"">

XPATH Axes in Umbraco
XPATH works on the premise of Axes, which is how the data relates to the Current Node in Umbraco as well.

Self Axis - While it is rarely used, the self axis actually returns the node in reference.

$currentPage/self::node

Child Axis - The child axis select the nodes immediately below the node in reference. While the verbose method is rarely used, it is here for reference.

$currentPage/child::node
$currentPage/node

Parent Axis - The parent axis allows us to see the node immediately above the node in reference.

$currentPage/parent::node
$currentPage/../

Descendant Axis - The descendant axis retrieves all nodes below the node in reference no matter the depth.

$currentPage/descendant::node
$currentPage//node

Descendant-or-Self Axis - The descendant-or-self axis returns all nodes below the current node, but also returns the node in reference to the command..

$currentPage/ descendant-or- self::node

Ancestor Axis - The ancestor axis selects all nodes that are ancestors, or the parent, and the parent's parent, and so on, to the node in reference..

$currentPage/ancestor::node

Ancestor-or-Self Axis - The ancestor-or-self axis selects all nodes that are ancestors, or the parent, and the parent's parent, and so on, including the node in reference.

$currentPage/ancestor-or-self::node

Preceding Axis - The preceding axis selects all nodes no matter the depth, that are located on parent-level and who are also located before (preceding) its parent of the node in reference.

$currentPage/preceding::node

Preceding-Sibling Axis - The preceding-sibling axis selects all nodes that are located on the same level who are also located before (preceding) the node in reference..

$currentPage/ preceding-sibling ::node

Following Axis - The following axis selects all nodes no matter the depth, that are located on parent-level and who are also located after (following) its parent of the node in reference.

$currentPage/following::node

Following-Sibling Axis - The following-sibling axis selects all nodes that are located on the same level who are also located before (following) the node in reference.

                             $currentPage/following-sibling::node

A look at XSLT Macro Snippets
For a practical understanding of XSLT Macros, a list of XSLT Macro snippets is provided below.

1. For each child Node of a specific Document Type Alias

<xsl:for-each select="$currentPage/NewsItem"> </xsl:for-each>

However for whatever reason if you want to have a document type alias and a document type property with the same alias it would select both.

<xsl:for-each select="$currentPage/NewsItem [@isDoc]"> </xsl:for-each>

2. For each child Node excluding a specific Document Type Alias
<xsl:for-each select = "$currentPage/*[not(self::NewsItem)]" > </xsl:for-each>

3. For each child Node

<xsl:for-each select="$currentPage/* [@isDoc]"> </xsl:for-each>

This example selects all xml nodes underneath the currentPage item using the * selector.

However without the [@isDoc] section it would select all nodes including those which are just document type properties.

4. For each child Node via a selectable source

This example shows you how to list childnodes from the nodeID of the contentpicker.

<xsl:param name="Source" select = "$currentPage/mySource" />
<xsl:for-each select = "umbraco.library:GetXmlNodeById($Source)/DocType">
</xsl:for-each>

5. For Each node of a specific Document Type Alias

<xsl:for-each select="$currentPage/ancestor-or-self::Home//MyDocumentType [@isDoc]">
</xsl:for-each>

This example walks upto the top level node/dcoument type with the alias of Home. So this is a fairly expensive XPath call.

Then it looks through all the child nodes no matter how deep to find the node (document type) with the alias of MyDocumentType.

6. Using a Macro parameter to get a Document Type Property

<xsl:value-of select="$currentPage/* [name() = $myMacroParameter and not(@isDoc)]" />

This example selects the child node where it's name matches the value in myMacroParameter and checks to see if that it does not have the isDoc attribute.

7. Using GetMedia Umbraco Method to load Images

This code loops through the images in a media folder as specified by a media picker.

<xsl:for-each select="umbraco.library:GetMedia($images, true())/Image">
    <xsl:variable name="picFile" select="umbracoFile"/>
    <xsl:variable name="picW" select="umbracoWidth"/>
    <xsl:variable name="picH" select="umbracoHeight"/>
    <img >
        <xsl:attribute name="src">
            <xsl:value-of select = "$picFile"/>
        </xsl:attribute>
    </img>
</xsl:for-each>

That's all for this post, in the next post (Learning Umbraco in a week - Day V) we will have a look at .Net Macros in Umbraco.

Learning Umbraco in a week - Day II

2011-07-21T20:15:00.192+05:00

This is my second post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

Introduction to Umbraco Document Types
Creating Umbraco Document Type
Setting up Umbraco Document Type
Introduction to Umbraco Content
How to create a Web Page or Content in Umbraco?
How to Templatize Umbraco?
Introduction to Umbraco Data Types

Introduction to Umbraco Document Types

Before creating a web page in Umbraco, you must first create a Document Type. Then when you do create the web page, you will specify which Document Type it is based on.

Document Types are the heart of the content structure of Umbraco and they define which properties the content elements have in detail and the data that a web page will use. It also defines the interface you will see when creating the web page. A Document Type specifies which kind of data, fields (web controls), and content can go on the web page. Document Type have nothing to do with web page presentation or layout - that is handled in Templates. Document Types can be accessed by following the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Settings > Document Types.

Creating Umbraco Document Type
To create a Document Type in Umbraco follow the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Settings.

Right-click on the Document Types folder and enter any name.

Setting up Umbraco Document Type
To set up a Document Type in Umbraco, access the Document Type follow the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Settings

In the Main Panel (on the right in your browser) you will see the tabs where you define that type.

Info - Info tab primarily entails the display options for the Document Type, and which templates can be used.
Structure - The Structure tab is where you control the hierarchy of your site by creating child documents.
Generic Properties - The Generic Properties tab is where you specify what kind of content can go on web pages that are based on this Document Type. These Properties determine which fields and controls can appear on your web page.
Tabs - Tabs tab is where you specify the tabs that will show up when you create a web page based on this Document Type. After you create a tab, you can assign Properties to it in the Properties tab.

Introduction to Umbraco Content

Content or Web Pages in Umbraco are based on Document Types, i.e. before you can create a Content or Web Page, you must have a Document Type for the type of page you want. The Content or Web Pages can be accessed by following the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Content.

How to create a Web Page or Content in Umbraco?
To create a Web Page or Content in Umbraco follow the steps below.

If you do not yet have any Web Pages or Content, create one by right-clicking on Content and choosing Create.
Enter a name for the Web Page and click Create. The page will show up under the Content folder (refresh your browser page if you need to).
Click on your new Web Page. In the right panel, you will see the tabs that allow you to set the Content that will appear on the page.
Enter the Content for the Web Page, by entering Content in the tabs in the main panel. If you want your Web Page to contain more types of Content than are allowed here, you must edit the Document Template which is used by the page. To see which Document Type the page uses, go to the Properties tab for the Web Page.
When you’re done, click the "Save and Publish" button in the tool bar.
To see how your Web Page looks in Umbraco, go to the Properties tab for that page, then click the "Link to Document" url at the bottom of the tab.

How to Templatize Umbraco?

Templates define the layout and presentation of a web page. Templates are where you define the design and layout, which CSS to use for the page, etc. By default, when you create a Document Type, a Template is also created for that Document Type, unless it is not desired. To access Umbraco Templates follow the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Settings > Templates.

Templates are actually ASP .NET Master Pages. Moreover, nesting of Templates is same is nesting Master Pages in ASP .NET, i.e. Templates can be based on other templates.

Introduction to Umbraco Data Types
A Data Type in Umbraco is an editor type associated to the Property. Data Types are not the same as those in computer programming.

A common Type used is "Rich Text Editor", selecting this type will display a rich text editing control to the user during content editing of this Property.
To access Umbraco Data Types follow the steps below.

Go to Umbraco Default Page (Admin Page) > Sections > Developer > Data Types.

That's all for this post, in the next post (Learning Umbraco in a week - Day III) we will go through XSLT & XPATH.

Learning Umbraco in a week - Day I

2011-07-21T20:14:00.037+05:00

This is my first post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

What is a Content Management System?
What is a Web Content Management System?
A look at some famous Content Management Systems
Introduction to Umbraco
History of Umbraco
Why Umbraco?
A look at some famous Umbraco based web sites
How to install Umbraco?
A look at Umbraco root directory
A look at Umbraco Content Management System

What is a Content Management System?

A content management system (CMS) is the collection of procedures used to manage work flow in a collaborative environment.

Below are some benefits of a typical content management system.

Low cost
Easy customization
Easy to use
Workflow management

Below are some of the overheads, one has to bear by having a content management system.

Cost of implementation
Cost of maintenance
Storage volume
Latency issues
Tool Mixing

What is a Web Content Management System
A web content management system (WCMS) is a software system that provides website authoring, collaboration, and administration tools designed to allow users with little knowledge of web programming languages or markup languages to create and manage website content with relative ease.

A look at some famous Content Management Systems.
This is a list of famous content management systems that are used to organize and facilitate collaborative content creation. Many of them are built on top of separate content management frameworks.

Below is a list of few proprietary content management systems available.

SharePoint Server (MOSS)
DotNetNuke Professional Edition
Oracle ECM Suite
IBM Enterprise Content Management
Sitecore Professional Edition
OpenText Web Experience Management
Day Communiqué WCM
EMC Documentum ECM
Contegro

Below is a list of few open source content management systems available.

Liferay
Composite C1
DotNetNuke Community Edition
mojoPortal
Umbraco
Joomla!
Drupal
SilverStripe
eZ Publish
Geeklog

Introduction to Umbraco
Umbraco is an open source content management system for publishing content on the web and intranets. It is written in the Microsoft .Net (C#) and off course deployed on a Microsoft based infrastructure (i.e. MS Windows, MS IIS etc).

History of Umbraco
Umbraco was developed by Niels Hartvig in 2000 and released as open source software in 2004. In 2009, CMS Wire described it as one of the leading .NET-based open source CMS systems. This proved to be the turning point in Umbraco CMS history, and In 2010, with thousand downloads a day, Umbraco was in the Top five most popular downloads via the Microsoft Web Platform Installer.

Why Umbraco?
Umbraco is the choice of many organizations because of the following benefits.

Free
Open source
Easy to learn and use for content writers
Built on .Net
Supports XML & XSLT for Web Developers
Supports ASP .Net development standards
Easy to extend
Easy to integrate with other systems
Strong support community

A look at some famous Umbraco based web sites.
Below is a list of some famous Umbraco based content management systems deployments.

http://www.warnerbros.com.au/
http://www.asp.net/
http://computerfriend.dk/
http://www.vogue.co.uk/
http://www.heinz.com/
http://www.sandisk.com/
http://www.redroof.com/

How to install Umbraco?
The easiest and recommended for installing Umbraco on IIS 7, is by using the Microsoft Web Platform Installer. The Web Platform Installer can be found at the following location:

http://www.microsoft.com/web/gallery/Umbraco.aspx

A look at Umbraco root directory
Unlike other content management systems, the Umbraco root directory looks like a typical ASP.NET application root directory. And most of the content created in Umbraco, actually appear as physical files, rather than records in the database. For example, templates or master pages will appear in the masterpage folder, and stylesheets will appear in the css folder.

Below is a list of most commonly used folders in the Umbraco root directory.

Umbraco - This folder contains all the Umbraco CMS files.
Master Pages - This folder contains the Templates or Master Pages created in Umbraco.
CSS - This folder contains the Stylesheets created and used in Umbraco.
Scripts - This folder contains the JavaScript files created in Umbraco.
XSLT - This folder contains the XSLT Macro files created in Umbraco.
User Controls - This folder contains the User Control Macro files created in Umbraco.
Config - This folder contains the Umbraco specific Configuration Files.
Application Data - This folder contains the Umbraco specific Data Files.
Application Code - This folder may contain the Code Behind Files referred in User Control Macros or Templates.

A look at Umbraco Content Management System

Once Umbraco is installed, you will probably be redirected at the Umbraco default page.

However, if you are not on the Umbraco Default Page, please point your browser to http://<YourSite>/umbraco/umbraco.aspx. If you are not logged in, you will first be redirected to the Umbraco login page.

The Umbraco default page has three main panes, which are listed below.

Content Listing (Top Left)
Sections Listing (Bottom Left)
Main Panel (Large Panel on the Right)

The Content panel on a default empty install will show a only Content folder with the Recycle Bin folder under it.

Below is a list of Umbraco Sections.

Content - This section is shown by default, and is used for creating and managing the content in Umbraco.
Media - This section is used for managing media files / items in Umbraco.
Users - This section is used for managing Umbraco users, user types, user permissions related to content creation and management.
Settings - This section is used for controlling the Umbraco settings related to content management.
Developer - This section provides useful features for techies, as it is related to development of portal in Umbraco.
Members - This section is used for creating and managing portal members, member groups and member types in Umbraco.

That's all for this post, in the next post (Learning Umbraco in a week - Day II) we will go through the Umbraco CMS.

Running Umbraco on .Net Framework 4.0

2011-06-14T11:03:00.002+05:00

This post is about an unusual configuration issue that, many Umbraco developers face when they first try to upgrade their Umbraco installation to .Net Framework 4.0. It is unusual in a sense that over the last few framework releases there has been a norm that the web.config schemas were backward compatible and it was never required to update the configurations during an upgrade.

.Net Framework 4.0 has been launched with a new machine.config file, and off course it doesn't override the earlier machine.config in use by previous frameworks. The following changes have been done in the new machine.config:

ASP .NET Tag Sections
ASP .NET AJAX
ASP .NET Dynamic Data
ASP .NET Routing
ASP .NET Chart Control

So, we will need to omit all the above mentioned items form our web.config, so that Umbraco starts working with .Net Framework 4.0.

Set the web site's Application Pool to ASP.NET v4.0.
Remove/Comment the sectionGroup named "system.web.extensions" under configSections tag.
Change the compilation tag and set the targetFramework attribute to 4.0
<compilation defaultLanguage="c#" debug="true" batch="false" targetFramework="4.0">
Delete the whole assemblies section below that compilation tag.
Remove/Comment the controls having "asp" tagPrefix, under system.web/pages/controls tag.
Remove/Comment all handlers and modules specific to "ASPNETAJAX", under system.webServer and system.web tags.
Most importantly, search for "Version=3.5.0.0" text in you web.config and replace it with "Version=4.0.0.0".
Finally, make sure you have the "Microsoft.Scripting.ExtensionAttribute.dll" in Umbraco bin directory, i.e. most probably at "c:\inetpub\wwwroot\bin".

That's all folks, enjoy Umbraco development on .Net Framework 4.0.

CTrayIcon - System Tray Icon Wrapper

2011-02-19T22:59:00.000+05:00

Introduction

The system tray icon notification area -- or "systray" or "taskbar notification system area" -- is a section of the taskbars in the Microsoft Windows desktop user interface. This section displays the clock and the icons of certain programs so that a user is continually reminded that they are there and can easily click one of them. Unfortunately, MFC does not contain a class to wrap system tray functionality. So, I decided to write one and put it up for public use.

Background

The system tray is a section located at the one end of the taskbar in Windows 9x, and NT (Family). Icons that are often installed in the system tray include the volume control for sound, anti-virus software, and a system resources indicator. When more icons are installed in the system tray than can fit in the space allotted, the system tray becomes horizontally scrollable or expandable. To interact with a program in the system tray, you select an icon with your mouse and double-click or right-click the icon. When you minimize the program after using it, it shrinks back into the system tray instead of into the main part of the taskbar.

What makes a system tray icon special is that, when installed, it can have a customized message appear when the mouse is hovering over it. The menu that appears when you right-click it can be customized and the action that occurs when you double-click it can also be customized. For example, the double-click action for Internet Explorer could be to launch (start, or open a window for) the program, but the double-click action for a desktop icon could be to "View desktop," i.e. remove the active windows and show the underlying desktop.

An icon can be placed in the system tray when a program is installed by making an entry in the system registry. It can also be placed later by creating a shortcut to a program and dragging the shortcut icon to the system tray. An icon can be removed by deleting the registry entry or by right-clicking it and selecting Delete on the pop-up menu. The clock is removed by deselecting the show clock option in the taskbar Properties.

About CTrayIcon

CTrayIcon lets VC++ developers add icons to the Windows system tray. This quickly makes any VC++ application more attractive and intuitive to Windows users.

CTrayIcon can display pop-ups. This allows developers to modify the look and feel and add powerful menu items.

With CTrayIcon, tray icons can have Tool Tip Text that appears during a mouse-over. In addition, a cool mouse-hover effect is provided.

CTrayIcon class summary

This class is a wrap around the system tray icon notification. It adds a specified set of icon-pairs -- i.e. icons & hover-icons -- and tooltips to the system tray notification area, as well as a callback notification handler for mouse message handling.

CTrayIcon construction

Syntax

// Use if notification messages are to be

// sent to the parent window.

CTrayIcon(

    CWnd *pWnd,

    unsigned int uNotificationMessage,

    MouseMsgHandlerPtr *pMouseMsgHandler,

    unsigned int uHandlersCount,

    IconDataPtr *pIconData,

    unsigned int uIconsCount,

    int nSelectedIconIndex,

    unsigned int uElapsed

);

// Use if notification messages are to

// be sent to the CTrayIcon class.

CTrayIcon(

    MouseMsgHandlerPtr *pMouseMsgHandler,

    unsigned int uHandlersCount,

    IconDataPtr *pIconData,

    unsigned int uIconsCount,

    int nSelectedIconIndex,

    unsigned int uElapsed

);

Parameters

pWnd: Pointer to the window that receives notification messages associated with an icon in the taskbar status area. If the pWnd parameter is not provided, then the function CTrayIcon::OnNotifyIcon will be called whenever the icon sends a notification message.
uNotificationMessage: Message identifier for handling proper mouse notification messages associated with an icon in the taskbar status area. If a uNotificationMessage parameter is not provided, then a new window message is registered -- i.e. ::RegisterWindowMessage(_T("NotifyIcon") -- and is used as a default notification message identifier.
pMouseMsgHandlerPtr: An array of pointers to objects of classes derived from CTrayIconMouseMsgHandler to handle mouse messages.
uHandlersCount: Indicates the number of handlers in the array pointed to by pMouseMsgHandlerPtr.
pIconDataPtr: An array of pointers to objects of CIconData -- i.e. units of icons, hover icons, and tool tips -- to be added to the taskbar status area.
uIconsCount: Indicates the number of icons in the array pointed to by p IconDataPtr.
nSelectedIconIndex: Index of the selected icon in the array pointed to by p IconDataPtr.
uElapsed: Indicates the elapsed time for the taskbar status area icon animation timer.

CTrayIcon getters and setter

// Sets the notification message target window

void SetTargetWnd(CWnd *pWnd);

// Sets the notification message identifier

void SetNotificationMsg(unsigned

int uNotificationMsg);

// Sets the selected icon index

void SetSelectedIconIndex(int nIconIndex);

// Gets the selected icon index

int GetSelectedIconIndex() const;

// Sets the mouse message handler

void SetMouseMsgHandler(

    MouseMsgHandlerPtr *pMouseMsgHandler,

    unsigned int uHandlersCount);

// Gets the mouse message handler

MouseMsgHandlerPtr* GetMouseMsgHandler()

const;

// Sets timer elapse

void SetTimerElapse(unsigned int uElapse);

// Gets timer elapse

int GetTimerElapse() const;

// Sets icon data

void SetIconData(IconDataPtr *pIconData, unsigned

int uIconsCount);

// Gets icons data

IconDataPtr* GetIconData()

const;

// Indicates whether animation is in progress

BOOL IsAnimating () const ;

CTrayIcon methods

// Dispalys a hidden icon

BOOL ShowIcon();

// Hides a visible icon

BOOL HideIcon();

// Refreshes icon

BOOL RefreshIcon();

// Shows the hover icon

BOOL HoverIcon();

// Starts icon animation

BOOL StartIconAnimation();

// Stops icon animation

BOOL StopIconAnimation();

CTrayIcon events & callbacks

OnTaskBarCreated

This is used to process the WM_TI_TASKBARCREATED message for verifying taskbar status icon creation.

Syntax

// Callback handler for the taskbar created event

LRESULT OnTaskBarCreated(

    WPARAM wParam,

    LPARAM lParam

);

Result

Returns the LRESULT after verification.

OnNotifyIcon

This is used to process the WM_TI_NOITIFYICON message for proper mouse message handling.

Syntax

// Default callback handler for

// taskbar notification message event

LRESULT OnNotifyIcon(

    WPARAM wParam,

    LPARAM lParam

);

Result

Returns the LRESULT after verification.

WindowProc

This provides a Windows procedure for a CTrayIcon object. The WindowProc function is an application-defined function that processes messages sent to a window.

Syntax

// Callback handler for the window procedure

LRESULT WindowProc(

    unsigned int uMsg,

    WPARAM wParam,

    LPARAM lParam

);

Result

Returns the LRESULT after verification.

OnTimer

This is used to process the WM_TIMER messages, triggered as soon as the elapsed time has passed.

Syntax

// Callback handler for the timer elapsed event

void OnTimer(

    unsigned int uIDEvent

);

CTrayIconMouseMsgHandler class summary

This class stands as an abstract base-class for handling mouse notification messages. Classes derived from CTrayIconMouseMsgHandler should handle mouse notification messages and must implement the pure-virtual MouseMessageHandler() method.

CTrayIconMouseMsgHandler construction

Only a single parameter constructor is available that takes a Window message to be associated with it for receiving other system tray icon notification messages.

Syntax

// Single paramenter constructor, a

// mosue message identfier has to be passed

CTrayIconMouseMsgHandler(

    unsigned int uMouseMsgID

);

Parameters

uMouseMsgID Windows messages that the OS generates when the user performs any action with the mouse over the system tray icon. For example, the pressing or releasing of the mouse buttons, etc.

CTrayIconMouseMsgHandler getters and setters

// Gets the mouse message identifier

unsigned int GetMouseMsgID() const;

// Sets the mosue message identifier

void SetMouseMsgID(

    unsigned int uMouseMsgID

);

CTrayIconMouseMsgHandler events & callbacks

MouseMsgHandler

This method is a pure-virtual method and must be defined in the derived classes for handling system tray icon mouse notification messages. This event is generated by the CTrayIcon::OnNotifyIcon() method.

Syntax

// Pure-virtual callback mouse message handler,

// necessary to be implemented by the derived class,

// for handling system tray icon notifications.

virtual void MouseMsgHandler() = 0;

CTrayIconMouseMsgHandler synonyms

MouseMsgHandlerPtr

// Synomym for CTrayIconMouseMsgHandler pointer

typedef CTrayIconMouseMsgHandler* MouseMsgHandlerPtr;

CIconData class summary

This class encapsulates a set of icon-pairs -- i.e. icons & hover-icons -- and tooltips for the system tray notification area. It wraps the basic functionality to switch between icon & hover-icon, as well as between two different CIconData objects along with their respective tooltips.

CIconData construction

For object creation, a quad parameter constructor is available that takes icon-pair (icon & hover-icon) identifiers -- where hover-icon is optional -- a tooptip and an optional handler to an icon.

Syntax

// Quad parameter constructor

CIconData(

    unsigned int uDefaultIconID,

    LPSTR lpToolTip,

    unsigned int uHoverIconID = 0,

    HICON hIcon = NULL

);

// Copy constructor

CIconData(

    const CIconData &pIconData

);

Parameters

uDefaultIconID: Application-defined identifier of an icon, to be showed in the system tray icon notification area.
lpToolTip: Pointer to a null-terminated string with the text for a standard ToolTip. It can have a maximum of 64 characters, including the terminating NULL.
uHoverIconID: Application-defined identifier of an icon, to be showed in the system tray icon notification area during mouse-hover.
hIcon: Handle to the icon to be added, modified or deleted. To avoid icon distortion, be aware that notification area icons have different levels of support under different versions of Microsoft Windows. Windows 95, Windows 98, and Microsoft Windows NT 4.0 support icons of up to 4 bits per pixel (BPP). Windows Millennium Edition (Windows Me) and Windows 2000 support icons of a color depth up to the current display mode. Windows XP supports icons of up to 32 BPP.

CIconData getters and setters

// Gets the selected icon's identifer

unsigned int GetIconID() const;

// Gets the default icon identfier

unsigned int GetDefaultIconID() const;

// Sets the default icon identifier

void SetDefaultIconID(unsigned int uIconID);

// Gets the hover icon identifer

unsigned int GetHoverIconID() const;

// Sets the hover icon identifier

void SetHoverIconID(unsigned int uIconID);

// Gets the tooltip

LPSTR GetToolTip() const;

// Sets the tooltip

void SetToolTip(LPSTR lpToolTip);

// Gets the icon handler

HICON GetIconHandler() const;

CIconData methods

// Selects and loads the speciifed icon into memory

bool LoadIcon(unsigned int uIconID);

CIconData synonyms

IconDataPtr

// Synomym for CIconData pointer

typedef CIconData* IconDataPtr;

How to use

Let's go step-wise to accomplish our task.

Step 1 - starting

Create an application and add the TrayIcon.h, TrayIcon.cpp, TrayIconMouseMsgHandler.h, IconData.h, Utilities.h and MouseMsgHandlerImpl.h files to the project.

Step 2 - pre-empting reusability

It is always beneficial to set up a global header library of reusable utility methods that can be used anywhere in the project.

// Utilities functions

// Shows a window

BOOL ShowWnd(CWnd* pWnd)

    return pWnd->ShowWindow(SW_SHOW);

// Hides a window

BOOL HideWnd(CWnd* pWnd)

    return pWnd->ShowWindow(SW_HIDE);

// Shows a popup menu

void ShowPopupMenu(CWnd* pWnd,

    unsigned int uResourseID, int nSubMenuPos)

    CPoint aPos;

    GetCursorPos(&aPos);

    CMenu aMenu;

    aMenu.LoadMenu(uResourseID);

    aMenu.GetSubMenu(nSubMenuPos)->TrackPopupMenu(

        TPM_RIGHTALIGN | TPM_RIGHTBUTTON,

        aPos.x,

        aPos.y,

        pWnd,

);

Step 3 - setting up mouse message handlers

In this phase, we will set up a few classes derived from CTrayIconMouseMsgHandler to handle mouse notification messages.

Setting up left mouse double click message handler

// Left mouse button double click message handler

class CLeftMouseDblClickMsgHandler:

    public CTrayIconMouseMsgHandler

    public:

    CLeftMouseDblClickMsgHandler() :

CTrayIconMouseMsgHandler(

        WM_LBUTTONDBLCLK){}

    void MouseMsgHandler()

        ShowWnd(AfxGetMainWnd());

};

Setting up right mouse click message handler

// Right mouse button click message handler

class CRightMouseClickMsgHandler:

    public CTrayIconMouseMsgHandler

    public:

    CRightMouseClickMsgHandler() :

CTrayIconMouseMsgHandler(

        WM_RBUTTONDOWN){}

    void MouseMsgHandler()

        ShowPopupMenu(AfxGetMainWnd(),

IDR_TASKBAR_MENU,

0);

};

Setting up mouse hover message handler

// Mouse hover message handler

class CMouseHoverMsgHandler:

    public CTrayIconMouseMsgHandler

    public:

    CMouseHoverMsgHandler(CTrayIcon* pTrayIcon) :

CTrayIconMouseMsgHandler(

        WM_MOUSEFIRST)

        m_pTrayIcon = pTrayIcon;

    void SetTrayIcon(CTrayIcon* pTrayIcon)

        m_pTrayIcon = pTrayIcon;

    void MouseMsgHandler()

        m_pTrayIcon->HoverIcon();

    private:

    CTrayIcon* m_pTrayIcon;

};

Step 4 - declaring

Add a member to your class that points to CTrayIcon.

// Declarying CTrayIcon object pointer for adding

// an icon to the system tray notification area

CTrayIcon* m_pTrayIcon;

Step 5 - initialization

In this phase, we will initialize the CTrayIcon object to add icon to the system tray notification area.

// Declare an array of MouseMsgHandlerPtr of size 3,

// to handle three types of mouse events

MouseMsgHandlerPtr *pHandler = new MouseMsgHandlerPtr[3];

// Define an object for handling right mouse button

// click events

MouseMsgHandlerPtr rbcHandler =

    new CRightMouseClickMsgHandler();

// Define an object for handling left mouse button

// double click events

MouseMsgHandlerPtr lbcHandler =

    new CLeftMouseDblClickMsgHandler();

// Define an object for handling mouse hover events

MouseMsgHandlerPtr mhHandler =

    new CMouseHoverMsgHandler(m_pTrayIcon);

pHandler[0] = lbcHandler;

pHandler[1] = rbcHandler;

pHandler[2] = mhHandler;

// Declare an array of IconDataPtr of size 2,

// to add two sets of icons. Only one will be

// active though.

IconDataPtr *pIconData = new IconDataPtr[2];

// Define an object of Blue MFC icon

pIconData[0] = new CIconData(IDR_MAINFRAME,

_T("CTrayIcon Blue Demo"),

    IDR_MAINFRAME_HOVER);

// Define an object of Green MFC icon

pIconData[1] = new CIconData(

    IDR_MAINFRAME_GREEN,

_T("CTrayIcon Green Demo"),

IDR_MAINFRAME_HOVER);

// Define the CTrayIcon object

m_pTrayIcon = new CTrayIcon(pHandler,

3,

pIconData,

2,

0,

SECOND);

// Refer the CTrayIcon object to the

// CMouseHoverMsgHandler object, for handling

// mouse events

((CMouseHoverMsgHandler*)mhHandler)->

SetTrayIcon(m_pTrayIcon);

Step 6 - setting up functionality

In this phase, we will set up functionality to hide, show and animate the system tray notification icon.

Showing the tray notification icon

void CCTrayIconDemoDlg::OnBnClickedBtnshowicon()

    m_pTrayIcon->ShowIcon();

Hiding the tray notification icon

void CCTrayIconDemoDlg::OnBnClickedBtnhideicon()

    m_pTrayIcon->HideIcon();

Starting the tray notification icon animation

void CCTrayIconDemoDlg::OnBnClickedBtnstartani()

    m_pTrayIcon->StartIconAnimation();

Stopping the tray notification icon animation

void CCTrayIconDemoDlg::OnBnClickedBtnstopani()

    m_pTrayIcon->StopIconAnimation();

Minimizing the window to the tray notification icon

void CCTrayIconDemoDlg::OnBnClickedBtnminimize()

    m_pTrayIcon->ShowIcon();

    HideWnd(this);

Showing the window from the tray notification icon

void CCTrayIconDemoDlg::OnShow()

    ShowWnd(this);

Step 7 - the finishing touch

Once we are done, we release the resources gracefully.

void CCTrayIconDemoDlg::OnCancel()

    delete m_pTrayIcon;

    CDialog::OnCancel();

Alternate step - the other way around

In the above steps, we saw how efficiently we can handle the system tray notification icon messages by using the CTrayIcon class. What if you want to handle those messages in you own CWnd class? Implement this phase if you'd like to handle the system tray notification icon messages in you CWnd or CDialog class. In this example, that class would be the CCTrayIconDemoDlg class. Go to the header file and register a Window message to be handled once the system tray notification icon is created.

const unsigned int WM_TI_NOTIFYICON =

    ::RegisterWindowMessage(_T("TaskBarCreated"));

Go to AFX_MSG and add the line in bold.

//{{AFX_MSG(CCTrayIconDemoDlg)

virtual BOOL OnInitDialog();

afx_msg void OnSysCommand(UINT nID, LPARAM lParam);

afx_msg void OnPaint();

afx_msg HCURSOR OnQueryDragIcon();

afx_msg void OnNotifyIcon(WPARAM wp, LPARAM lp);

//}}AFX_MSG

Then go to AFX_MSG_MAP and add the line in bold.

//{{AFX_MSG_MAP(CCTrayIconDemoDlg)

ON_WM_SYSCOMMAND()

ON_WM_PAINT()

ON_WM_QUERYDRAGICON()

ON_REGISTERED_MESSAGE(WM_TI_NOTIFYICON, OnNotifyIcon)

//}}AFX_MSG_MAP

Replace the CTrayIcon object creation with the following code.

// Define the CTrayIcon object

m_pTrayIcon = new CTrayIcon(

    this, WM_TI_NOTIFYICON, pHandler,

    3, pIconData, 2, 0, SECOND);

Finally, redirect to the CTaskIcon method.

void CCTrayIconDemoDlg::OnNotifyIcon(WPARAM wParam,

LPARAM lParam)

    // TODO

    m_pTrayIcon->OnNotifyIcon(wParam, lParam);

History

23 August, 2004 -- Original version posted
6 June, 2007 -- Article and downloads updated

Reference

http://www.codeproject.com/KB/shell/CTrayIcon.aspx