Reflection

This post is part of a series, this being the fourth, and last part, if you're interested, read the first part here, the second part here, and the third part here.

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.

This post is part of a series, this being the third part, if you're interested, read the first part here, and the second part here.

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.

This post is part of a series, this being the second part, if you're interested, read the first part here.

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

This is the first post in a series elaborating on my presentation at the Umbraco 5th birthday event in Stockholm, excellently arranged by Milagro.

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