Darren Ferguson - Blog
27 January 2012 at 15:25
Ferguson Moriyama and Umbraco 5
Before I begin, a dedication - I wouldn't have got through this blog post unless I had the wonderful Matt Brailsford, Doug Robar and Sebastiaan Jansen as Skype contacts - these guys are MVP for a reason! #h5yr
Yesterday I started to build the new Ferguson Moriyama website in Umbraco 5, and as promised in my previous blog post I've documented the process.
I've started out by designing the document types for the new Ferguson Moriyama site as I usually would. As people maybe following this as a tutorial I've done a better job of documenting these than I usually would for a normal internal project.
The document types are deliberately as minimal as possible my current site suffers from bloat where I put in fields for edge cases that never emerged - things like alternative titles to be used in place of node names and alternative dates to be used in place of the default publish date. This time I'll start with as little as possible and build up. I'm told that deletion of document type properties in Umbraco 5 is recoverable by rollback which is great in terms of being agile with your document types.
(You can click on the image above to view the Google document that I created)
As an aside I'll talk a little about my process. The document above is expected to change during the process of the build. I'm a firm believer in agility and in fact I believe it is almost impossible to specify exactly what you want before you start building. As I already mentioned, on a typical project I wouldn't maintain such a document. I see Umbraco document types as "self documenting" and for clients who demand formal specifications I'd normally just generate the documentation from the real Umbraco document types. Interestingly (possibly) this is how PDF creator for Umbraco came into being.
The document above contains a few areas which are TBD (to be determined) but I deliberately make assumptions based on Umbraco 4 knowing that I can return later as my knowledge of version 5 increases.
Creating the document types
So I head off to the settings section of Umbraco 5 armed with my document type specs and everything looks reassuringly familiar.
I hesitate slightly creating a document type called Master because it sounds a little too generic and has some connotations of .net master pages but I let it slide. As an aside I'd normally put a site specific prefix in front of my document types but in this case I'm confident that this instance of Umbraco will only ever host the Ferguson Moriyama site.
The first new feature that I notice is stricter control over document type inheritance; I like that by checking Inheritable Only on the Composition tab that I can say that this document type cannot be directly created as an instance of a node. Being a pedant I'm also pleased to see the Generic Properties tab is now called General Properties :)
After 30 minutes or so of playing, Umbraco 5 looks to be in a satisfyingly familiar state. I hit one or two snags - the one that sticks in memory is that I couldn't add properties to inherited tabs but I am told that this is just a temporary glitch.
Create some nodes
Document type hierarchy all worked in a familiar way - I headed over to the Content section and created a Document of type Home with two child nodes of type Text Page.
Again, everything is looking pretty much as I'm used to.
Add some templates
For now I decided to just add a Home Page template and output a property or two, then I'll move on to versioning what I've built to date. No CSS or anything to make the pages look pretty yet, just some ugly markup.
Associating templates with document types is again a very familiar experience to those of you who are familiar with Umbraco 4 - the big difference comes when creating templates, which are no longer master pages but Razor views.
I spent a bit of time messing around here, and I understand that some of the objects exposed to the view by default are subject to change.
Umbraco 5 has a default template (or View) called _Layout.cshtml which is in ~/Views/Umbraco this is synonymous to a Master page in Umbraco 4 and will be familiar to those who have adopted ASP.net MVC prior to looking into Umbraco v5. I'm not sure if it is bad from to modify the default view but I do so.
At this stage I'm finding the terminology a little confusing, the Umbraco 5 UI still uses the terminology master and template -I guess to remain familiar to Umbraco 4 developers but there is a bit of internal conflict as my mind thinks about Views.
I end up with the following layout which does a few familiar things:
- Output document title
- Output a (recursive) document type property
- Render a child view
Back it up
So I've achieved a lot in a short space of time but before I go I want to make sure that my customisations to Umbraco 5 are versioned and separated in a way that I can roll them out to a new version of Umbraco or revert to a previous version should I break anything.
Or maybe not
I take a precursory glance over the database and the file system and it isn't easy to figure out how document types are stored. I find some information relating to my document types in a table called AttributeSchemaDefinition but the data model uses GUIDs as identifiers and there appear to be some quite complex relationships between the tables. It certainly isn't a 5 minute job to work out how it all hangs together.
My Umbraco HQ contacts aren't on Skype and I feel like I've harassed them enough for today so I decide to quit for the day.
For now I'll backup my SQL CE database - after all it is just a file - and I'll come back to this later when I have a bit more energy. I'm really hoping that moving document types between instances was a design consideration of Umbraco 5. Perhaps this is where Courier vNext will come into play?
Next Time
I'll look at adding CSS and JavaScript to Umbraco 5 and completing my homepage. I'll also look into how to create my top navigation.
17 January 2012 at 00:00
Building the new Ferguson Moriyama website in Umbraco 5
So I need to learn how to use Umbraco 5 - because in a couple of months of time I'll be teaching it to others. I've played with version 5 during development and contributed a few bits of information back to the community but now is the time to get real.
I always find that there is nothing like a real project when learning a technology. I'd spent the last couple of weeks deciding what would be my proof of concept project, a little afraid to commit a client to such as breaking piece of tech and then it hit me.
Gathering dust in a folder somewhere on my laptop was a set of mock-ups for the new Ferguson Moriyama website. So why not? Ferguson Moriyama on Umbraco 5 and blog and screencast about it step by step so others can benefit from my experiences during the process.
A little project background
FergusonMoriyama.com has served me well since 2005 and Umbraco version 2.0.6. My company website is (and always has been) a secondary channel when it comes to new business. I'm fortunate enough to have enough repeat business that I rarely have to convince people that we can help them out.
Having said that the site does need a little TLC, In the 7 years that the site has been in service we've diversified the types of work we do and that obviously impacts the content we serve. From being a pure services company we now sell some products and as we provide training for which we need to take bookings.
In performing this technology refresh we'll get rid of some of the "shoe-horning" and hacking of content that has gone before. It used to be just me updating my Umbraco sites but now there are a few of us, it'll be nice to remove those "special pages that only Darren can edit".
The Starting point
The mark-up that I had built can be viewed on my preview server:
When I undertook the refresh of the look and feel I had the following criteria.
- Consistent positioning of content
- Navigation to depth of 3 levels
- Adding a standard form template
- Adding a product template
- Making our contact details more prominent to encourage people to call us
- Re-writing lots of the copy to focus on a smaller set of services that we want to provide
One concern is that I didn't really consider mobile devices very well. In the last year I've started to use tablets and phones to browse the site and I'm now kicking myself at the omission. Still I've decided to move forward with what I have and address it as the first issue post go live.
The blog series
I'll aim to write each step of this development up as I work on it. I'll do my best to use screencasts and screen grabs where appropriate. The aim is to make things fairly simple to follow and the target audience will be people who are familiar with Umbraco 4.
I understand that I'm working with a product that is maturing and expect to hit issues along the way - these will of course be logged and reported. I'm not going to put a timescale on this or commit to update the blog at regular intervals - I'm phenomenally busy just now.
Part 1
In part 1 of this series (coming sometime soon) I'll look at two things:
- Designing and implementing my document types
- Versioning my development
The versioning part will also consider a release process - Once I've versioned my development I'll need to be able quickly release iterations to multiple environments. At the end of each blog post I'll plan to have the site public facing so you can follow my progress.
Getting started
So before we start the build let's get a development environment set up. This is really simple as I have the Microsoft web platform installer and WebMatrix already on my machine.
Here are the steps:
- Download Umbraco 5 RC 2
- Extract to a folder
- Right click and choose Open as a website with Microsoft WebMatrix
- Click run and choose a browser - in my case Chrome
- On the splash screen click the launch installer link
- When prompted choose SQL CE as the database - I'll change this later.
That is all, an empty vanilla Umbraco 5 up and running. This leaves me ready to start building my site.
The screencast below illustrates the steps described above. There is no sound.
Note: I installed the wrong version of Umbraco in the cast but the process is the same.
15 January 2012 at 09:00
Umbraco 5 UK course FAQ
With the release of Umbraco 5 upon us a there will be some changes to the certification courses. Doug Robar and I receive daily emails with questions about this so I thought I would blog to clear up what will be happening.
The information in this course applies to UK courses only - it is probably accurate for other courses too, but please check with your local trainer before booking anything.
So without further ado, here is the Umbraco 5 training FAQ:
Will you stop teaching Umbraco 4?
Yes, we will stop running public Umbraco 4 courses in the UK - those listed for February will be the last, we won't schedule any after that. Both Doug and I will be happy to teach Umbraco 4 at your company office upon request.
When will you start teaching Umbraco 5?
March. We've scheduled some courses which are listed at http://umbraco.com/products/training/schedule.aspx
Will my existing Umbraco certification become invalid?
No you are still an Umbraco certified developer; you will still be listed on the Umbraco site. If you are a company that holds solution provider status you will continue to do so.
What is the Umbraco 4 to Umbraco 5 upgrade course?
For a very limited period we will be able to offer upgrade courses. You will need to hold an existing Level 2 certification to attend.
The courses are designed to quickly update certified developers knowledge of Umbraco 4 so that is applicable to Umbraco 5. The course runs two days and covers topics originally in the Level 1 and Level 2 courses.
Both Doug an I will teach this course. I'm really excited about working with Doug - Without wishing to blow my own trumpet I think this is a great opportunity to work with both of us over two days. We'll take you for a beer too!
Can you do onsite Umbraco 5 training?
Yes, I'll be happy to book in dates for on-site Umbraco 5 training with you.
I have another question!
Just post your question in the comments here and I'll add it to this post an answer it.
03 January 2012 at 09:25
2012 Year of the writer
For some reason it is traditional at the end of each year to reflect, self-criticise and create a personal development plan for the coming year. The colloquial term - I believe - is new year resolutions. I've resisted doing this all of my life, knowing myself far too well to believe that I would ever stick to any half arsed commitments - with me it has to be something that I truly want to achieve.
I do something slightly different - each year for the past 3 or 4 years I've written a list of goals. At first glance they may appear to be just another set of resolutions but I have a few rules.
A goal needs to be positive and free of any negative connotations, thinks like "I must not" or "I will not" don't work for me. I also try and avoid any binary goals that could be failed by a single action - I will exercise every day can be broken by a day of abstinence I will exercise regularly cannot.
For me my goals for the year should all be achievable, gradual, measurable and inspirational - by gradual I mean a goal that I can work on measuring success along the way and take small amounts of satisfaction from my progress therefore keeping me inspired.
So why am I telling you about this?
My 1st goal for 2012: To write and Present more.
In 2011 one of my goals was to conquer a long term fear of public speaking. The idea of standing up in front of a crowd of people terrified me. The only way I knew to overcome this was to put myself into the situation that scared me and confront it head on.
Last year I spoke at CodeGarden 11 about multi-language websites in Umbraco and at the Umbraco UK festival about building commercial Umbraco packages and the Umbraco deli.
The result? I'm still alive. Although I could never describe the experiences as being fun and comfortable I've re-assured myself that I'm capable. Teaching the Umbraco Level 2 course prepared me by getting me used to presenting to small groups of people. Some of my worries about public speaking were even addressed in the classes, forgetting what I was going to say, hecklers etc.
In 2012 I'd like to get better at speaking in public, to be more confident about it and maybe even to enjoy myself a little. The second part of the goal is to write more.
When I was a kid I wanted to be a writer, all early school and college reports stated journalist as my intended career. Then something went wrong, my inner geek was somehow exposed and I ended up programming computers. When I sat down to write out my goals for this year I couldn't figure out how, when or why that happened but I do remember that I loved to write.
I think that over the years my ability to write has been blunted after churning out many hundred inane technical "specification" documents. The goal for 2012 is to get back to loving to write, to strike a balance between sound technical documentation and creative and informative articles.
So that is why you are reading this. I'm not going to do anything silly like commit to blogging once a week - rewind to my explanation offailure in a single actionearlier in this post. I'll wrap up here and go and find some subject matter for these upcoming blog posts.
2012: To write and Present more.
14 November 2011 at 21:40
Simple PDF generation from Umbraco with Razor or XSLT
The screencast below demonstrates PDF Creator for Umbraco 2.0. I've dropped the XSL prefix from the package title as you can now use the templating language of your choice to output PDF.
This tool does not mimic your HTML layouts in PDF format but allows you to define rich, unrestricted layouts suitable for printing using FO.
- PDF files are created as Umbraco templates
- PDFs are created using your templating language of choice, Razor, XSLT or your favourite.
- Easily embed Fonts, Images and SVG.
PDF Creator is a commercial package.
New features in version 2:
- No custom Macro required - just use standard Umbraco templates to output FO.
- Use Razor and other template languages.
- Force the browser to download a PDF with a specific file name.
- Big performance gains, both memory and CPU.
- Newer version of PDF rendering engine with better FO support.
- Improved user manual.
For examples of PDF files generated using PDF creator please have a look at the Vizioz Umbraco case studies page.
I've also written a blog post on how to get started with the package.
12 November 2011 at 17:12
PDF From Umbraco in 3 Minutes
Here is a quick demonstration of how to generate PDF files from Umbraco using PDF Creator for Umbraco. The whole process should take less than 3 minutes. You can click on the screenshots below for larger versions.
- Navigate to the Developer section of
Umbraco.
- Expand the packages node in the tree and
click "Umbraco package repository".
- Type PDF Creator in the search dialogue.
- In the search results hover over PDF creator and then click Install Package
- On the resulting screen check the
checkbox labelled Accept License.
- Click the Install Package button.
- Wait for package installation to be
confirmed.
- Navigate to the settings section of Umbraco.
- Expand Document Types in the tree.
- Choose a Document type.
- In the Allowed templates control check one or more
sample PDF templates.
- Go to the Content section of
Umbraco.
- Open a document of the type you set up a PDF template for.
- Associate one of those templates with your document.
- Click Save and Publish
- When you open the document it is rendered as a PDF.
By default this works for any document type that uses bodyText as the alias for the main Rich text content area.
PDF output can be fully customised by modifying the templates.
09 November 2011 at 21:02
Umbraco 5: Adding Dashboards via plugins
I'll add this post to the Umbraco 5 wiki in due course.
This blog post will describe how to add dashboards to Umbraco 5 via a plugin - before starting, consider the following useful background reading:
- http://blog.mattbrailsford.com/2011/09/30/automating-umbraco-v5-package-creation-using-msbuild/
- http://shazwazza.com/post/Umbraco-Jupiter-Plugins-Part-1.aspx
At time of writing (9th November 2011) some of the techniques used here require you to work from the latest Umbraco Jupiter source code - the example won't work with the latest alpha release.
Sample source code for the techniques described here are available at: http://umbraco5contrib.codeplex.com/ and you can get the source (mercurial) by cloning: https://hg01.codeplex.com/umbraco5contrib
The solution that this article refers to is in Source\Dashboard.HelloWorld.sln. Please read ReadMe.txt in the project root before building.
Obective:
To display a (Razor) view on and Umbraco 5 dashboard - using a custom controller provided by an Umbraco 5 plugin.
Plugin folder structure:
Plugins go in: App_Plugins\Packages\ for now we'll be copying from Visual Studio to this location using post build events. To package and redistribute a plugin you'll want to read Mat's article which is linked above.
In Dashboard.HelloWorld.csproj you will need to modify the following XML to specify where you are running Umbraco 5 from.
<PropertyGroup>
<Umbraco5Dir>C:\Users\Darren\Source\Umbraco\Source\Web Apps\Umbraco.CMS.Web.UI</Umbraco5Dir>
</PropertyGroup>
If you build the solution and browse to:
App_Plugins\Packages\MyPackage.1.0 you should see the following child folders:
- lib (DLL files from your plugin)
- Views\Partial (Razor cshtml files from your plugin)
You'll also have a web.config at the root of your plugin folder. If you refresh the Umbraco back office you should see a Hello world view on your dashboard.
What makes this work:
The dashboard is defined in your plugin web.config - Umbraco Jupiter uses a technique known as deep config which means plugin cofig is merged with the main application configuration.
The dashboard snippet looks like this:
<umbraco.cms>
<dashboard-groups>
<group>
<applications>
<addapp="*"/>
</applications>
<dashboards>
<addtab="Hello There people"type="childAction"name="Dashboard.Index"/>
</dashboards>
</group>
</dashboard-groups>
</umbraco.cms>
The configuration above defines the following things:
- The Umbraco application/section to add the dashboard to (in this case * which means all)
- The tab title "Hello There people"
- The type - childAction for a controller - you can use partialView to display a Razor file directly.
- name - references the controller in the format Name.Action
How Umbraco 5 finds plugins:
In the solution open up AssemblyInfo.cs and note the inclusion of the following:
[assembly: AssemblyContainsPlugins()]
This attribute tells Umbraco to look inside this assembly for plugins.
Modifications to the controller:
Consider the controller in our project:
[Editor("960d4aaf-8fae-44da-a3ff-5a2430ee6e4a", HasChildActionDashboards = true)]
public class DashboardController : BaseEditorController
{
public DashboardController(IBackOfficeRequestContext requestContext)
: base(requestContext)
{
}
[ChildActionOnly]
public ActionResult Index()
{
return View("HelloWorld");
}
}
The changes we've made in order for this to work on the dashboard are:
- Decorate the class with the Editor attribute and provide a GUID
- In the Editor attribute pass in true to the HasChildActionDashboards property
- Inherit from the base class BaseEditorController
- Mark your action with the ChildActionOnly attribute
21 October 2011 at 19:19
Workflow for Umbraco decision tasks
In the latest in a series of screencasts abour Workflow for Umbraco I explain decision tasks. Decision tasks make the workflow runtime stop and wait for user input before continuing.
Out of the box you have a Group decision task and a user decision task. The screencast also explains how to write your own decision tasks.
The sample code in the screencast is available in the sample source code repository.
Click below to watch the screencast:
In summary:
- The user decision task allows a list of specified Umbraco users to transition a task
- The group decision task allows a list of specified Umbraco user types to transiton a task
- To create your own decision tasks implement IDecisionTask
- The runtime will ask if a user can transition a task by calling the CanTransition method of IDecisionTask
- If you want to write your own GUI (aspx) to perform the transition override the TransitionUrl property of IDecisionTask a sample is provided in the code accompanying the screencast.
21 October 2011 at 08:37
Using and creating delay tasks in Workflow for Umbraco
Following on from my three previous screencasts - this short 5 minute cast shows how to utilise the default delay tasks in Workflow for Umbraco and also how to implement your own.
As usual the code that accompanies the screen cast is available from the sample code repository.
To summarise the screencast:
- A delay tasks causes the workflow to pause.
- To implement your own you just implement IDelayTask
- The runtime willl tell your task what time it was started by setting the StartTime property.
- The runtime will periodically ask your delay task whether it is complete by calling the IsComplete Method.
- You can use the StartTime property to perfome time based calculations or collect user properties as with runable tasks.
- Delay tasks can be good for delayed publish, tweet etc and allow you to specify when subsequent tasks should happen.