What’s important for me is that I don’t want multiple versions of the code/package depending on the umbraco version but would like to handle that in the code/installer instead. So that I have a single package that can be used on both 4.0.X and 4.5.

Identifing what schema the site is running on

In the locator package there is an xslt file to transform the results and also in the code there are several actions that manipulate the content xml, so before I can do any updates I need to know what schema the current site is using.

In umbraco 4.5 there is a new setting UmbracoSettings.UseLegacyXmlSchema (which is pulled from the /config/umbracoSettings.config), this isn’t there in umbraco version older then 4.5, so if you try to get that value and it fails because of a MissingMethodException then it should be an older version then 4.5 (and thus on the old schema)

bool useLegacySchema = true;

try { useLegacySchema = Utility.UseLegacySchema; }

catch (MissingMethodException) { }

Updating the code

In the locator package I manipulate the content xml and add some nodes (extra properties on documents) on the fly so depending on the schema I need to add

<data alias=”myAlias”>value</data> (old schema) or simply <myAlias>value<myAlias> (new schema).

After the update the code that does that looks like this:

bool useLegacySchema = true;

try { useLegacySchema = Utility.UseLegacySchema; }

catch (MissingMethodException) { }

XmlElement distanceNode =

content.CreateElement(useLegacySchema ? "data" : "distance");

distanceNode.InnerText = distance.ToString(Utility.NumberFormatInfo);

if (useLegacySchema)

{

XmlAttribute aliasAttribute = content.CreateAttribute("alias");

aliasAttribute.Value = "distance";

distanceNode.Attributes.Append(aliasAttribute);

}

node.AppendChild(distanceNode);

Updating the package, installing the correct xslt file

The locator package installs an xslt file (LocatorResults.xslt) that is used to transform the search results. Depending on what schema the current site is using it needs to install the correct version, this is handled by a custom package action.

In the package I simply include an additional xslt file LocatorResultsNewSchema.xslt (the new schema version)

But I let the installer place this in the /data/packages/temp directory

So in the package.xml I have this part:

<file>

<guid>LocatorResults.xslt</guid>

<orgPath>/xslt</orgPath>

<orgName>LocatorResults.xslt</orgName>

</file>

<file>

<guid>LocatorResultsNewSchema.xslt</guid>

<orgPath>/data/packages/temp</orgPath>

<orgName>LocatorResultsNewSchema.xslt</orgName>

</file>

Which will copy the LocatorResults.xslt file(using the old schema) in the package to the /xslt directory and the LocatorResultsNewSchema.xslt(using the new schema) to the /data/packages/temp directory.

At this point the xslt using the old schema is installed in the /xslt directory, so now if the site is using the new schema I simply need to move the LocatorResultsNewSchema.xslt file to /xslt/LocatorResults.xslt.

That’s done with a custom package action

The package action Xml looks like this:

<Action runat="install" alias="addNewSchemaContentToFile">

<source>/data/packages/temp/LocatorResultsNewSchema.xslt</source>

<target>/xslt/LocatorResults.xslt</target>

</Action>

The source node contains the path to the new schema xslt file and the target node contains the path to the location of the xslt file to overwrite.

The package action then simply checks if the current site is using the new schema, if it is it deletes the existing xslt file (the one using the old schema) and then moves the xslt file that’s using the new schema to that location. If the site is on the old schema it will simply delete the new schema xslt file.

public bool Execute(string packageName, System.Xml.XmlNode xmlData)

{

string basePath = System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath;

string sourceFile = xmlHelper.GetNodeValue(xmlData.SelectSingleNode("source"));

string targetFile = xmlHelper.GetNodeValue(xmlData.SelectSingleNode("target"));

try

{

if (!Utility.UseLegacySchema)

{

if (File.Exists(basePath + sourceFile))

{

if (File.Exists(basePath + targetFile))

File.Delete(basePath + targetFile);

File.Move(basePath + sourceFile, basePath + targetFile);

}

return true;

}

else

{

File.Delete(basePath + sourceFile);

return true;

}

}

catch(MissingMemberException)

{

File.Delete(basePath + sourceFile);

return true;

}

}

That’s what it took to update the locator package (in this case it was all related to the schema changes), the new package is available on the locator project page at our.umbraco.org and sourcecode is available on codeplex.

Level 1 is running on 3-4 May and level 2 on 5-6 May.

These are the same courses taught throughout the world and will teach you everything you need to know to attain your Umbraco Certification.

Secure your seat today!
http://umbraco.org/training/training-in-benelux

You can find the free umbraco foundation videos on umbraco.tv

For site builders:

• Document types
• Templates
• Stylesheets
• What are macros
• Creating your first xslt macro

For developers

• Using .Net User Controls
• Macro Parameters
• Macro Caching
• Debugging

These should be your first stop when diving into Umbraco!

It turned out to be an amazing product! Detailed info and some screencast can be found on the official Contour product page.

You can also try Contour before buy, by installing a trial straight from the package repository.

But this can easily be changed.

You can target the richttext editor with the class

.mceContentBody

So by appending this to the related stylesheet, you have more control over the styling in the richttext editor datatype.

(make sure to clear your browser cache, to view the result)

So I’ve added the sourcecode to the poll project page on our.umbraco.org (attached files).

Enjoy!

So instead of releasing a package I’ll share the sourcecode and I’ll give an overview of how to use it.

Installation

Once you have ABCpdf installed (it’s possible to download a trail and you can also apply for a free license) the installation is just a mather of dropping some files in your umbraco instance.

• Drop PDFGen.dll in the /bin folder
• Drop PDFGen.aspx in the /umbraco
• Drop PDFGen.config in the /config folder

Setup

First you’ll need to define a pdf template, this can be done in the PDFGen.config file which should
be in the /config folder.
Lets look at an example config file:

<?xml version=”1.0″ encoding=”utf-8″ ?>

<PDFGen PermitPrint=”False” PermitExtractContent=”False”>

<!– Header–>

<Text FontName=”Arial” FontSize=”12″ FontColor=”0,0,0″ X1=”20″ Y1=”40″ X2=”500″ Y2=”700″

IsRecurring=”true”>my header text</Text>

<Image File=”/media/950/joblistpdfhead.jpg” X=”20″ Y=”670″ Width=”570″ Height=”100″ IsRecurring=”true”/>

<!– Content –>

<Property RequestParam=”test” PropertyAlias=”title;@createDate” FontName=”Arial” FontSize=”18″

FontColor=”0,0,0″ X1=”25″ Y1=”620″ X2=”500″ Y2=”650″ IsRecurring=”false”>{0} - {1}</Property>

<Property RequestParam=”" PropertyAlias=”info” FontName=”Arial” FontSize=”11″ FontColor=”0,0,0″ X1=”25″

Y1=”180″ X2=”530″ Y2=”630″ IsRecurring=”false”></Property>

<Property RequestParam=”" PropertyAlias=”linkURL” FontName=”Arial” FontSize=”11″ FontColor=”0,0,0″

X1=”40″ Y1=”715″ X2=”520″ Y2=”740″ IsRecurring=”false”></Property>

<!– Footer –>

<Text FontName=”Arial” FontSize=”6″ FontColor=”0,0,0″ X1=”25″ Y1=”20″ X2=”500″ Y2=”30″

IsRecurring=”true”>Copyright mysite 2009 — All Rights Reserved.</Text>

</PDFGen>

After the xml declaration (yes the config file is an xml file) you have the PDFGen root node.
On this node you can set wether the generated pdf files are printable and if it is possible to extract
content (copy,paste).

<PDFGen PermitPrint=”False” PermitExtractContent=”False”>

The child nodes of the root PDFGen node will be used to define the pdf. There are a couple of
possibilities:

• Text
• Image
• Property
• RenderedOutput

Text nodes

<Text FontName=”Arial” FontSize=”12″ FontColor=”0,0,0″ X1=”20″ Y1=”40″ X2=”500″ Y2=”700″

IsRecurring=”true”>my header text</Text>

A text node is used to add some static text on the pdf document it has several attributes

• FontName: name of the font family that will be used
• FontSize: size of the font
• FontColor: color of the font
• X1,Y1,X2,Y2: these are the coordinated used to define a box where the text will be placed
• IsRecurring: if this is set to true the text will appear on each page (used for headers and
  footers)
• The inner text is the static text that will be placed on the pdf (it is possible to add html).

Image nodes

<Image File=”/media/950/joblistpdfhead.jpg” X=”20″ Y=”670″ Width=”570″ Height=”100″ IsRecurring=”true”/>

An image node is used to add an image to the pdf document.

An overview of it’s attributes:

• File: path to the image
• X,Y: coordinated of the image
• Width: width of the image
• Height: height of the image
• IsRecurring: if this is set to true the image will appear on each page (used for headers and
  footers)

Property nodes

<Property RequestParam=”test” PropertyAlias=”title;@createDate” FontName=”Arial” FontSize=”18″

FontColor=”0,0,0″ X1=”25″ Y1=”620″ X2=”500″ Y2=”650″ IsRecurring=”false”>{0} – {1}</Property>

A property node is used to add umbraco content node property data to the pdf document.

An overview of it’s attributes:

• RequestParam: if this is empty the default request param id will be used, if you want to use
  another one define it here
• PropertyAlias: alias of the property (possible to add multiple separated by semicolon)
• FontName: name of the font family that will be used
• FontSize: size of the font
• FontColor: color of the font
• X1,Y1,X2,Y2 :these are the coordinated used to define a box where the text will be placed
• IsRecurring :if this is set to true the text will appear on each page (used for headers and
  footers)

The innertext can be used to add some static text around the property or if you have multiple
propertyaliases you must define how they will be placed (simular to string.format).

RenderedOutput nodes

<RenderedOutput RequestParam=”" Template=”" X1=”25″ Y1=”620″ X2=”500″ Y2=”650″ IsRecurring=”false” />

This will fetch the rendered output of a page, if no requestparam is used it will use the id one and if no template alias is defined it will use that default template of that page.

An overview of it’s attributes:

• RequestParam: if this is empty the default request param id will be used, if you want to use
  another one define it here
• Template: template alias to use, if this is empty the default template of the document will be used
• X1,Y1,X2,Y2 :these are the coordinated used to define a box where the text will be placed
• IsRecurring :if this is set to true the text will appear on each page (used for headers and
  footers)

Usage

Once installed and if you have a working config file. You can use pdfgen by calling /umbraco/pdfgen.aspx?id=1234 (the id is the id of the umbraco document).

If you have defined other RequestParams in your config file (like headerid) you just need to do:
/umbraco/pdfgen.aspx?id=1234&headerid=2345

It’s also possible to have multiple config files (just copy the pdfgen.config) if you want to use anohter config file you can do it like this:

/umbraco/pdfgen.aspx?id=1234&pdfconfig=pdfconfigcopy.config

pdfconfigcopy.config is the filename of the configfile (must be in the /config dir)

To make it easier to get started, I thought I would provide some starter sourcecode for a demo custom section.

Steps to get this running on your umbraco installation:

- Copy the assembly (CustomUmbracoSection.dll) to the \bin directory

- Copy the file custom.gif to \umbraco\images\tray\ directory

- Make a ‘custom’ directory in \umbraco and copy the editCustom.aspx page to \umbraco\custom directory

- Insert a new row in the umbracoApp table

INSERT INTO [umbracoApp]

           ([sortOrder]

           ,[appAlias]

           ,[appIcon]

           ,[appName])

     VALUES

           (9

           ,‘custom’

           ,‘custom.gif’

           ,‘custom’)

- Insert a new row in to umbracoAppTree table

INSERT INTO [umbracoAppTree]

           ([treeSilent]

           ,[treeInitialize]

           ,[treeSortOrder]

           ,[appAlias]

           ,[treeAlias]

           ,[treeTitle]

           ,[treeIconClosed]

           ,[treeIconOpen]

           ,[treeHandlerAssembly]

           ,[treeHandlerType])

     VALUES

           (0

           ,1

           ,0

           ,‘custom’

           ,‘custom’

           ,‘custom’

           ,‘.sprTreeFolder’

           ,‘.sprTreeFolder_o’

           ,‘CustomUmbracoSection’

           ,‘Trees.LoadCustomTree’)

- Update the \umbraco\config\create\UI.xml file, add:

  <nodeType alias=”initcustom”>

      <header>Custom</header>

      <usercontrol>/create/simple.ascx</usercontrol>

      <tasks>

        <create assembly=”CustomUmbracoSection” type=”Tasks.CustomTasks” />

        <delete assembly=”CustomUmbracoSection” type=”Tasks.CustomTasks” />

      </tasks>

  </nodeType>

After these steps are completed you will have to enable the new section for your user.

Then it should show up as the last icon in the sections (called custom, with a HAL’s camera eye icon).

In the custom section you’ll find this:

So just a sample node that will open a demo edit page.

Creating packages is easy, the built-in package creator makes it super simple and with package actions you can perform additional common tasks (like updating the xsltextensions) without having to write a single line of code.

It really takes a minimal effort to package something up that you made, even if it’s very project specific it should be possible to isolate the functionality and package it up.

Dare to share

Even a simple package can be a great help, so don’t hesitate and share

Naming

To avoid conflicts and overwriting other existing items when installing a package, make sure you have unique and meaningful names

• Assemblies

Starting these with your name or company name followed by a project name should be enough to make them unique
FE: Nibble.Umb.Poll

• Stylesheets, Scripts, Document types, Templates, XSLT files, Macros

A unique and meaningful name that links them back to the package, so it easy to see that they are part of a package
FE: not style.css but starrating.css
not list.xslt but bloglistposts.xslt       

• Usercontrols

placing these in a new unique folder inside the /usercontrols folder makes it easy to see that they are part of a package
FE: /usercontrols/Nibble.Umb.Poll/poll.ascx

• Config files

place these in the /config folder (again, with a unique and meaningful name)

Installation

Package are really easy to install but in some cases the package installation might fail. So it’s always great to provide some manual installation instructions, just in case.

Think ahead

You might have created a package with a simple site in mind, but don’t forget they can/will also be used on multilingual sites, site running a different database engine. Or in case it’s a datatype, will be used with Canvas, autoform, doc2form. It’s a great plus if this is taken into account.

What doesn’t work

If the package only works with a certain umbraco version and up or if it only works on sql server, don’t forget to mention this to avoid that people install it on non supported installations.

I’ve also added this post to the wiki on our.umbraco.org, if you have anything to add/change (or correct my bad spelling) please do so .

The package installs the following:

The document types (Polls, Poll, Poll Answer) will be used to setup the polls.

So you’ll have a Polls document that will contain several Poll documents and these will have several Poll Answer documents beneath it.

After you have setup a poll with some answers in your content area you can get the poll on your page.

First add a reference to the installed stylesheet (/css/Nibble.Umb.Poll.css) and then place the Poll macro on your template.

Please note that:

• The macro will have to be placed inside a form with runat=”server” attribute
• There has to be a scriptmanager on the page

The poll macro has several parameters:

• Poll Node Id: This is the id of the Poll content node that you want to display
• Display Only: Check this if you only want to display the results of a poll
• Submit On Select: Check this if you want to submit the vote when a user selects a answer
• Hide Submit: Check this if you want to hide the submit button
• Sort Results: Check this if you want that the results are sorted by number of votes
• Width Total Votes: Instead of the highest number of votes being equal to 100% width, the total number of votes is 100%
• Hide Question: Check this if you want to hide the question
• Random Poll: Check this if you want to display a random Poll, you’ll also have to update the Poll Node Id to the Polls document (containing the different polls)

So depending on the parameters (Submit On Select and  Hide Submit) your poll can look like:

or (with submit button)

The Results can look like this:

Sorted:

Width Total Votes:

You can download the package here: http://our.umbraco.org/projects/poll