SwedeGarden is aimed at swedes going to CodeGarden, but all attendees are of course welcome to join in.

You can read more over at SwedeGarden.

Please note, that this is a social event, no 'puters allowed. Leave your geeky stuff at the hotel, and just bring your geeky self. We'll have a few beers, network, and be merry. Also note, that SwedeGarden is in no way affiliated with Umbraco or CodeGarden.

See you there!

In EPiServer, we get all PageData objects from the DataFactory, since EPiServer implements a factory pattern. It's also implemented as a singleton, making it very simple to interact with. We get the page by passing a PageReference to the factory, getting the page we want. By default the DataFactory returns the currently published version of a page. In Umbraco, we instead call the constructor on the Document object, by passing it an ID of the page we want. A big difference here is that the Document API by default returns the latest version of that page, regardless if it's published or not, if a certain version is required, specify it by passing the version Guid.

Another difference between the PageData and Document objects, is caching. The PageData object you get from the DataFactory is always cached (except when getting pages with FindPagesWithCriteria, but more on that in another post), whereas the Document object is never cached. For this reason, we only work with the Document API when we want to programatically change data. For a cached page in Umbraco, we use the Node API.

In EPiServer, the PageData object is read-only, when we want to change a page, we call CreateWritableClone() on the PageData object, getting a writeable copy of our object, that we can change all we want. When we're done, we pass it back to the DataFactory for saving and/or publishing. In Umbraco, this is not as straight-forward. The Document is always open for changes, and changing a property will persist that change to the database immediately. Properties for an EPiServer PageData object is accessed throught its index property, by property name, like MyPageData["MyProperty"]. Getting a property on the Document object is done with a call to MyDocument.getProperties("MyProperty"), however, this performs a call to the database as soon as you access the Property.Value property. What this essentially means, is that each proeprty is saved as soon as you set its value, calling Document.Save() fires the BeforeSave and AfterSave events, updates the UpdateDate property, and the preview XML. This is important to know. Calling Document.Publish() performs different task related to publishing, but it doesn't push your data to the content cache, for this you need to call umbraco.library.UpdateDocumentCache(int) passing it the ID of the Document. This also ensures that any other servers, if your site uses load balancing, also performs the cache update.

There are a number of methods to get cached content in Umbraco, the old-school way is to use the Node API, most commonly used via XSLT in Macros, but it's also available from code. Another way is to use Linq2Umbraco, that gets cached, typed, instances of your content. It has excellent performance, and if you're more comfortable with using C#/VB for your coding, this is probably the way for you. As I write there is also support for using Razor in Umbraco, and I dare say that it may make XSLT in Umbraco obsolete. It's the new black, and it's friggin' awesome :)

There's a great set of wiki-articles called The Umbraco API Cheat-sheet. Amongst others, it clearly describes the difference between a Node and a Document.

As usual, all and any comments, suggestions and additions are more than welcome.

The default sections of Umbraco are Content, Media, Users, Members, Settings, and Developer. When you first log in to Umbraco, what you see is normally the "Content" "section", this roughly translates to the EPiServer CMS Edit-mode, and it features the functionality needed to edit, save, publish and work with permissions for content. WHen you have a clean install of Umbraco, there won't be anything here, since, just as in EPiServer, you need DocumentTypes (PageTypes) in order to have Documents (Pages).

The Media section is an ordered structure for Media, i.e. files and folders, that can be used , and re-used, from Documents. It's the equivalent of the file browser in EPiServer, although, not implemented in the same way.

The Users section is where Users for the Umbraco UI are managed, and their respective access rights.

The Members section is where Users for the website are managed. In Umbraco, this is the MembershipProvider that you configure. The Members section is used to manage Members, and it can be used to edit both the User, called a Member, and the Profile for that User.

The Settings section is where you edit the base for your website, such as Document Types, Media Types, Languages and Globalization and Templates. It can also be used to manage Stylesheets and Scripts for your website.

The Developer section is used to manage the most technical parts of the website, such as Data Types and Macros.

The rationale behind the decision to divide the building blocks for your site in Settings and Developer, can be discussed, in fact I can imagine it has been on several occasions. One could argue that Macros are on par with Templates in technicality, but I suppose there had to be a line drawn somewhere, and here it is.

There is also a dashboard, that roughly corresponds to the EPiServer OnlineCenter Dashboard, where you can load custom controls and functionality for each section, however, it doesn't have the same granular security features that EPiServer has, nor does it rely or ASP.NET MVC to build these "gadgets", they are simple (or, in some cases, not so simple) UserControls, but they can be used for really powerful stuff. Your imagination sets the limits here.

To sum it all up, coming from EPiServer, the Content- and Media sections corresponds to the EPiServer CMS Edit-mode, and Users, Members, Settings and Developer correspond to the Admin-mode. Also note, that some tasks that are handled in EPiServer configuration, are done from the UI in Umbraco, and vice-versa. I'll try to amek sure to point these out as I get there.

In my experience Umbraco is seen as a competent OSS alternative to EPiServer. In my opinion, EPiServer is a very competent product, although, the license costs often excludes it from consideration by many organizations. Umbraco, too, is very competent. They employ similar patterns for some of their functionality, and completely different approaches for some.

I've planned the disposition for the series according to the list below, but it may change as I write. I'll update this post as the series progresses.

Part 1. The administration user interfaces.

Part 2. Document vs. PageData

Part 3. DocumentType vs. PageType

Part 4. DataType vs. PropertyType

Part 5. Property vs. PropertyData

Part 6. Media vs. the VPP

Part 7. Members vs. Users

Part 8. Event hooking

Part 9. Scheduled tasks

Part 10. Building a Custom DataType, vs. Building a Custom PropertyType

Part 11. Extending and customizing the UI.

Part 12. Template vs. PageTemplate

Part 13. Macros vs. DynamicContent

Part 14. Macros (XSLT/Razor/UserControl/Python) vs. WebControls/UserControls

Part 15. Searching with Examine vs. FindPagesWithCriteria

I have been working with both platforms for many years, and I think both offer excellent performance and functionality. However, regardless of that experience, I may have gotten some things wrong, and I hereby invite anyone to correct me, add information, or otherwise express their opinions.

• The base object for Umbraco content is CMSNode, it is constructed with an ID, and that goes to the database.
• Content is derived from CMSNode
• The Content.getProperty methods goes round-trip to the database. All derivatives of the Content class (e.g. Document, Media, Member),and thus behave the same way.
• Members. The Member object itself can be cached, but getting property values is just the same as for any Content.
• Media is also a derivative of Content. (As Jeroen Breuer mentioned in his comment, when working with Media in XSLT (via the umbraco.library.GetMedia method), the returned XPathNodeIterator is cached).
• Document is Content. But it can be published, and thus pushed to the Node API, which is cached.
• Templates. Programmatic access to the templates always result in a round trip to the database.
• ContentType.GetByAlias and GetAll goes to the database, getting it by ID via ContentType.GetContentType is cached.
• PropertyType.GetPropertyType is cached, but all other ways of instantiation goes to the database.

I'll edit this list as needed, I haven't worked wnough with 4.6.1 to know what's changed, so this applies to 4.5.2, at least.

As Jeroen Breuer accurately pointed out, there's a big difference between a Node and a Document

In the previous part, I told you how I rendered the material template to the client, using XSLT, JavaScript, jQuery and jQuery UI. This time, I'm going to show you how I get that data back to the server for generation of an actual PDF. This is where the "ClientObjects" come in, might be a stupid name for them, but there are three different kinds of objects in play, and that was the best name I could think of at the time.

In .NET I have 2 kinds of objects, ClientObjects and DataObjects. Again, naming isn't my strong suit. Basically, the client (the UI), knows of one type, and that's the ClientObjects, they are small, lightweight and versatile, in the way that they have a Data property, that contains XML, so I could send whatever I wanted with it. Essentially, the JavaScript version of the ClientObject is the same as the .NET version of it. Why? Well, I get instant, no hassle, deserialization, of the object into .NET. But I'm getting ahead of myself.

The communication is done via a WCF Service, that expects JSON serialized data, and since I have jQuery on the client side, I simply serialize my ClientObject to JSON, and send it to my service with the jQuery ajax() method, leaving my user experience intact.

Once the actual data is on the server, I convert it in two steps. Basically the idea was to minimize the data sent between the client and the server, and to ensure that if one part was to be replaced later, it could easily be done without having to change everything else.

In the conversion from a ClientObject to a DataObject, the properties in the ClientObject are validated against the data stored in Umbraco, and it's also made sure that properties that the editor has disabled editing of, aren't modified, and if they are, reset their values to what the editor set them to, this is mainly done by mapping properties, and converting values, from one data type to another. It's also here that certain values from the client, e.g position, is converted from a percentage, to a fixed point value. This was done so that the preview area could have the same size, regardless of the size of the material being edited. I accomplished this by setting the preview area to 420x595 pixels. As a coincidence, this just happens to be the size, in points, of a portrait A5. From there it's just a matter of knowing the algorithm for converting between An sizes, and you're all set.

Once we have a DataObject, an object that contains all the aspects of what output should be generated, we're ready to generate a PDF from that. Again, conversion is done into the objects that DynamicPDF understands, but could just as easily be done for any of the other components I mentioned earlier, provided you want to work around the whole bottom-up issue.

Once the PDF is generated, it's all just a matter of saving the file to disk on the server, where it can be accessed by the client, and returning the path to the client. It's really simple actually.

In closing, I would like to mention that this project was very fun. Albeit, not very structured and thought through, it gave me the opportunity to learn a lot. Since I developed this entire application in five weeks, there where a lot of corners that were cut. Since then, I've developed a new version, with far more thought going into the design of things. It will feature a new UI, built using Adobe Flex, and the architecture of the server side is very modular, enabling easy extension. It has been built using Umbraco 4.1 as a template engine, but the communication between the server and the UI is done with Flex Remoting, using FluorineFx. It will be totally awesome once it's ready. I've been given permission (since I don't own the code) to showcase that at Codegarden '10, if I can only muster the courage to speak in front of so many people. If you're attending, and interested, please let me know.

In Umbraco, when rendering the UI, the standard ASP.NET approach with MasterPages apply. However, from there on, there are several different approaches, including standard .NET controls, custom WebControls, custom UserControls, (in 4.1 there is LINQ support), and finally, XSLT. To many developers XSLT is like the bastard sibling you never want to meet, but once you get around that "I don't know you, so I don't want to play with you" feeling, it's actually a very powerful tool for presentation. Since it's a fairly brutish language, it can't "operate heavy machinery", but that's where the combo Umbraco - XSLT really stands out. By enabling you to add your own code to the XSLT processing, through XSLT Extensions, you can do pretty much whatever you want with your data. Those are the calls in the XSLT that begin with "umbraco.library" (built-in), or "xsl.lib" (my own). To all you MVC fans, yes, that would be like doing logic in your view, and yes, that's a big no-no, I'm saying you can, not that you should. (Yes, I know, I do in the examples.). But I digress.

When rendering the application UI to the client, I've used MasterPages and POSH (Plain Old Semantic Html) up until the step where the users selects which material the would like to modify. I use XSLT to render the list of campaigns, and the list of materials, but that's just lists with links. Once the user selects a material, it's all JavaScript. I want my application to be a smooth user experience, and not something that'll make them call the marketing department asking what the hell they were thinking.

In most cases, XSLT is used to render markup, however, I've also used it to render the JavaScript used both for the editor controls, as well as for the preview. Since each material is unique, the basis for how they should work is shared, but the implementation is specific. The real XSLT is fairly large, and thus hard to show here, but I've provided snippets that explain the jist of thing.

In the image above, you can (hopefully) see how I iterate all child objects, rendering the JavaScript object implementation code. I've shortened the example for brevity, omitting most of the variable declarations, but if you really want to see the whole shabang, get in touch, and maybe I'll share :). There are two more parts, the jQuery preview code, and the editor control code, but we'll get to those soon enough. Maybe you're wondering why the hell I have two JavaScript objects for each region? Well, one, what I've chosen to name the ClientObject, is used as a data carrier in communication with the server, and the jQuery object is used in the editing and previewing on the client. Yes, I could use the jQuery object for both, but this way is faster. Not in terms of performance, but rather in terms of me not having to think or care so much. Although this is another discussion completely, let me just say it. I really want to do the best solution possible, but I have yet to meet the client willing to pay for that, most clients settle for "Does it work?" (in some cases even for "Does it compile?", but let's not go there.)

So, in the sample above, I create a DOM element, with a wrapper function called createElement, it has a signature like this: createElement(tagName, id, style, text). What the XSLT template does is, it creates a DOM element, and if the editor has tagged the region as moveable, registers it as draggable (jQueryUI), it also retains its original position as data on the DOM element, so that it can easily be reset. The example above is for a text element, either a Formatted or Simple Text. In the case of a text element, the different available font sizes are saved as data on the DOM element as well.

Finally, we render the editor controls, enabling the user (if allowed by the editor), to modify different aspects of a region. I've shortened it a bit here as well, but it shows the general idea anyway, in this case, it's a Simple Text Region.

And this is what it looks like. On the left are the editor controls, on the right, the preview controls, and in the browser memory, a JavaScript object structure representing what you see, and any changes that you have done. As soon as I can get my son to sleep longer than 45 minutes at a time, I'll try to write the next part, as this post has been written, sporadically, over the course of the past six and a half hours.

Next up: Sending modifications to the server.

As in every Umbraco project, the first thing to do is set up the Document Types, as they are the containers for data.

Since Umbraco supports inheritance through Master Document Types, I set mine up so that they reflect the different kinds of content available for users (beside the types needed for the UI). My base type is called ContentRegion, it has properties for size and position. Inheriting from ContentRegion is ColoredRegion, with properties for colors, it then in turn has different regions inheriting from it, like FormattedTextRegion and SimpleTextRegion, where the formatted region is a HTML editor, and the simple one is just a text string.

There's also an ImageRegion, with the derived types Image and Upload, where Image is the templated version used by editors, and Upload enables end-users to upload their own content for inclusion in the final PDF. Finally, I created a SelectiveRegion type, that has no content of its own, but will enable end-users to select a child to use and edit.

Editors create "templates" of materials, by specifying the size and position of different regions on a page, the hierarchy determines the order, or z-index, that the regions are rendered, enabling overlapping and covering, if desired.

This makes it fairly easy to create and edit templates, enabling editors to create multiple types of content that end-users can edit and output as pdf's.

Next up: Getting the data to the end-user

Through Milagro, I was tasked with developing a PDF Creation Tool, the project brief was something along the lines of the following:

"Editors should be able to create campaign materials, in the form of posters, folders and flyers, in sizes ranging from A5 to A3. End users should then be able to modify these materials according to parameters set by the editors. The output should be a high resolution PDF, ready for printing."

Time was short, and the whole time allotted, from our initial meeting, to launch day, was just under six weeks. At the time of the meeting, nothing had been done. No pre-studies, no proof of concept, no design, no nothing. You could think this is unusual, but unfortunately, it's quite common. As this project had come to them as a last-minute thing, all of their developers were busy in other projects, I was tasked with doing a short pre-study to select a PDF creation component, while Åsa, their designer at the time, did the design and started on the front-end development.

I began by looking at ABCpdf, ITextSharp and DynamicPDF. A funny thing about the PDF format, is that it's drawn from the bottom left corner and diagonally up to the right, instead of, as everything else is, from the top left and down to the bottom right. I ran into all sorts of issues because of this, and as DynamicPDF is the only component that encapsulates this behavior, I went with that one. I did some quick proof-of-concept, just to see if the component was able to do what I wanted it to. Obviously, it did.

Very early in the project, I mentioned Umbraco to the project manager, as I have been working with the CMS since version 2.1 (that's 2006, if you didn't know), and to me, it all sounded like shuffling data between the client and the server (isn't everything?), and Umbraco is an excellent tool to do just that, in addition to create and store information. If you have no idea what Umbraco is, I suggest you look it up, you won't regret it. Anyway, no one at Milagro had worked with Umbraco, so I started evangelizing it from the get go (if I got a penny every time I said how good Umbraco is, I'd be filthy rich). Since I was the only developer on the project, I got to choose, but that was the only perk.

So, there we had it. Umbraco, DynamicPDF, a half-finished UI, and five weeks 'til deadline.

Next up: Creating the PDF Templates in Umbraco

First we covered the basics of installation, followed by Document Types, Master Document Types, and how they connect to Templates. Just before lunch we added content, and covered the umbraco:Item WebControl.

After lunch we covered Macros in XSLT and .NET, the Node and Document API:s, and the major differences between the two. I even managed to squeeze in XSLT Extensions and EventHandlers.

Luckily, they all had a good grasp on XSLT before we started, as that's usually a major hurdle for new Umbracians.

This was all done as a warm-up for tomorrow's MeetUp here in Stockholm, celebrating Umbraco's 5th birthday. I can't say I've been along for the ride for all that time, but I've seen Umbraco grow from a young version 2.1 to an almost grown up 4.1, that's almost 4 out of the 5 years it's been around as Open Source. It's been fun so far, and I see no reason to quit.

Tomorrow, we celebrate.

Oh, and if you for some reason want me to come and show you the ropes in Umbraco, get in touch.