Nibble

Archive for April, 2012

Moving from Umbraco V4 to v5 : Installation 1

First post in a hopefully large series on the differences and similarities between Umbraco v4 (webforms) and Umbraco v5 (MVC). So this assumes you’ve already used Umbraco v4 and are starting with Umbraco v5 (although it should also be valuable if you don’t have previous experience and just want to get started with Umbraco v5).

As an obvious first post we’ll take a look at the installation of Umbraco v5.

There are different ways to install Umbraco but here I’ll outline my preferred option, downloading the latest stable release from codeplex and using webmatrix to get up and running.

To get details on different installation methods( iis and web platform installer, nuget, visual studio template, manually, …) check out the getting started page on the v5 documentation.

Downloading

You can always find the latest stable release on http://umbraco.codeplex.com/releases, at the time of this blogpost that’s Umbraco 5.0.1. So simply download the recommended download (the web application).

image

There is also an option to get a nightly build (so a work in progress version) you can find those at http://nightly.umbraco.org/ (of course there is no guaranty that the version you’ll download will work 100% since it’s a current development version).

Once the download is successful you should end up with an archive if you unzip that you should have a file structure similar to the following screenshot.

image

Firing up

Now to get Umbraco running I’ll be using WebMatrix, if you don’t have it installed you can get it at the following site http://www.microsoft.com/web/webmatrix/ (basically WebMatrix will make it easy to get up and running without having to worry about all the dependencies, you might have to install Umbraco once trough the web gallery to make sure the dependencies get installed).

WIth webmatrix installed I can simply fire it up and have it ready to run my site if I open the context menu on the Umbraco web application archive folder.

image

After hitting the ‘”Open as a web site with Microsoft WebMatrix” option you should end up with an instance of WebMatrix that has the Umbraco site open (tree at the middle left should show you the files).

image

So all that’s left is to hit the run button in the webmatrix toolbar.

image

Webmatrix will open a new browser window or will add a new tab to an existing window and you should see the following

image

So now we’ll have to launch the Umbraco installation wizard by clicking 1 of the 2 links.

Installation wizard

The installation wizard looks pretty much the same as it did in Umbraco v4 with the big difference being that there are less steps in the installation process (no license and no skins step).

image

After hitting “Lets get started!” We need to specify the db that we want to use. Currently you can choose for SQL Server 2008 (and higher versions), SQL CE 4, or a custom connection string.

Still pretty similar to the v4 installer just that SQL Server 2005 isn’t supported and that there isn’t support for MySQL at this point. If you choose the SQL CE 4 option you won’t need to add additional files like you needed when installing v4 on SQL CE. So to get up an running without having to worry about the db simply choose SQL CE 4 and hit install.

image

After hitting install you should see the installation progress and once it’s finished you can continue to the next step.

image

In the create user step you’ll have to specify the admin user details (this is exactly the same as on v4).

image

After the user step you’ll be able to install a starter kit, this will install a sample starter site. Currently there is only 1 you can choose and there is no option to choose a skin for it (so different to v4 at the moment).

image

Once that step is completed the installation is done

image

Accessing Umbraco

After a successful installation it’s possible to go to the Umbraco backend and that’s still located at /Umbraco

image

So after providing the user credentials (that where setup in the create user section) you should have access to the Umbraco backend (again looking very familiar).

image

Conclusion

If you have experience with setting up an Umbraco v4 it al feels very familiar and you should be up and running in a couple of minutes.

Extending Umbraco Contour 2.0 for Umbraco 5, creating a custom field type 3

Like mentioned in the previous post there are some changes in Contour 2.0 when creating custom field types for Contour running on Umbraco v5. So in this post I’ll show a first complete example.

A custom field type consists of 2 main things:

  • A class containing the definition
  • The view that will be used to render the fields of the custom field types

Fieldtype class

So similar to how it is when extending Contour 1.x you’ll need a class that inherits from Umbraco.Forms.Core.FieldType (need to reference Umbraco.Forms.Core).

public class CustomFieldType: FieldType


In the constructor you’ll need to set the id of the provider.

this.Id = new Guid("4EF14104-2334-42F4-85D2-C426CA2800C8");


And some stuff that will be used by the form designer, the name (will appear in the field type selector of the form designer), the icon (also shown in the form designer).

this.Name = "Custom fieldtype";
this.Icon = "../../../../ExampleFieldType/Content/Images/custom.png";


Will result in the following (assuming that the icon is located at \App_Plugins\Packages\ExampleFieldType\Content\Images~\custom.png

image

You’ll also have to specify the html code that will be shown as a preview in the form designer

 public override string RenderPreview()
{
    return "<input type=\"text\" class=\"textfield\" value=\"custom preview\" />";
 }

Will result in the following preview shown on the form designer:

image

Here is the full code snippet (you can download the source at the bottom of this post)

using System;
using System.Collections.Generic;
using Umbraco.Forms.Core;
 
namespace ContourV5.ExampleFieldType
{
    public class CustomFieldType: FieldType
    {
        public CustomFieldType()
        {
            this.Id = new Guid("4EF14104-2334-42F4-85D2-C426CA2800C8");
            this.Name = "Custom fieldtype";
            this.Description = "Renders an example fieldtype";
 
            this.Icon = "../../../../ExampleFieldType/Content/Images/custom.png";
            this.DataType = FieldDataType.LongString;
        }
 
        public override string RenderPreview()
        {
            return "<input type=\"text\" class=\"textfield\" value=\"custom preview\" />";
        }
 
        public override string RenderPreviewWithPrevalues(List<object> prevalues)
        {
            return RenderPreview();
        }
 
 
    }
}

 

Fieldtype view

Another part that is needed is a view that will be used to output the fields of your custom fieldtype.

The minimum, so important here is to use the FieldViewModel (need to reference Umbraco.Forms.MVC) and that the name of the input is set to @Model.Name since this will be used to fetch and save the value.

@model Umbraco.Forms.MVC.Models.FieldViewModel
 
@{
    Layout = null;
}
 
<input type="text" name="@Model.Name" id="@Model.Id" class="text" value="" />

 

If you also want to support record editing and showing the stored value when moving back and forth in multi step forms you’ll need to check if there are already record values and then set the value of your control

@model Umbraco.Forms.MVC.Models.FieldViewModel
 
@{
    Layout = null;
 
    string val = string.Empty;
   
    if(Model.RecordValues != null)
    {
        val = Model.RecordValues.First().ToString();
    }
}
 
<input type="text" name="@Model.Name" id="@Model.Id" class="text" value="@val" />

 

And in order to support client side validation there are also some additions to be made (extra attributes)

@model Umbraco.Forms.MVC.Models.FieldViewModel
 
@{
    Layout = null;
 
    string val = string.Empty;
   
    if(Model.RecordValues != null)
    {
        val = Model.RecordValues.First().ToString();
    }
}
 
<input type="text" name="@Model.Name" id="@Model.Id" class="text" value="@val"
@{if(Model.Field.Mandatory) 
{
      <text>data-val="true" data-val-required="@Model.RequiredErrorMessage"</text>
}
}
/>

 

Adding the custom fieldtype

You’ll of course need to have Contour installed first, once that is installed you can add your custom fieldtype. To keep a clean overview of the extensions installed on your Umbraco v5 site simply create a new folder in the /App_Plugins/Packages directory

image

Once that is created drop your assembly in the lib subfolder (create it first)

image

You can then drop other resources like the field type icon in your custom directory (make sure this matches the path of the icon property on your fieldtype).

image

The view however needs to go in the

/App_Plugins/Packages/Contour/Views/Partial/ directory and needs to be named following the convention FieldType.FieldTypeClassName.cshtml

image

Porting existing fieldtypes to Contour 2.0 for Umbraco v5

Basically you’ll just have to create the view and if you want to do some additional processing of the value(s) also override the ProcessValue method on your field type class.

Download the example project

Extending Umbraco Contour 2.0 for Umbraco 5 1

Like it’s possible to extend Contour for Umbraco v4 with custom providers you can of course also do this with Contour 2.0 for Umbraco v5.

Since the engine behind Contour is still the same there are a lot of things that also stayed the same. There is no difference in creating custom data source types, prevalue source types, workflow types, export types, record action types, recordset action types for Contour on v4 or v5 of Umbaco. So if you already have custom ones running on Contour 1.x you should be able to reuse those instantly on Contour 2.0.

The 2 things that will be a bit different are creating custom field types and custom field setting types I’ll get some examples up of those in one of the next blog posts.

Introducing the AssemblyContainsContourProviders attribute

A small difference is that you’ll need to mark your assembly with a specific attribute if it contains Contour providers. This will make sure Contour only looks in the marked assemblies for plugins (performance boost).

So basically you’ll need to add the following line to your AssemblyInfo.cs of the project containing the Contour providers

[assembly: Umbraco.Forms.Core.Attributes.AssemblyContainsContourProviders]

Adding comment functionality to your Umbraco v5 site with Contour 1

Contour v2.0 for Umbraco v5 ships with a couple of methods that makes it really easy to fetch and output Contour records on your site as a quick example here is how you would add a comment form and a list of comments to your Umbraco v5 site with Contour.

Step 1: Creating the form

Go to the Contour section (of course you’ll need to install Contour first) and bring up the create page for Forms.

image

Give the form a name and select Comment Form as a template, this will already populate your form with the necessary fields.

image

After hitting the next button you should end up with a comment form

image

Step 2: Placing the form on your template

Navigate to the settings section and select the template where you want to place the comment form (I’m using the v5 starter kit and placing it on the textpage template).

image

Hit the insert macro button on the template editor toolbar

image

Select the ‘insert form from umbraco contour’ macro

image

Then select the Comment form and hit ok

image

You should now end up with an extra line in your template similar to:

@Umbraco.RenderMacro("contourForm", new { formId = "b32ef480-003f-4e93-9641-f60042a0bc33" })

After saving the template you should have a comment form on the pages that use the template with the macro on it.

image

And you can submit new comments…

Step 3: Adding the code that will output the comments

To output we’ll add some additional logic to the template

First a using statement

@using Umbraco.Forms.Core.DynamicObjects;

This is the namespace that contains the dynamic object we’ll be using to make it easy to output our Contour records.

Now to fetch the records we’ll use the method GetApprovedRecordsFromPage feeding it the current page id.

This methods returns a dynamic record list, so it’s easy to access fields on those records simply by using the dot notation like .Comment, .Name, … (depending on your field captions)

Here is the full snippet:

<ul id="comments">
@foreach (dynamic record in Library
           .GetApprovedRecordsFromPage(DynamicModel.Id))
  {
     <li>
          @record.Created.ToString("dd MMMM yyy")
          @if(string.IsNullOrEmpty(record.Website)){
             <strong>@record.Name</strong>
          }
          else{
             <strong>
               <a href="@record.Website" target="_blank">@record.Name</a>
             </strong>
          }
         <span>said</span>
        <p>@record.Comment</p>
     </li>
  }
</ul>

The end result:

image

Want to give this a try, go download Contour RC

Custom markup on your contour forms 12

The last couple of months I’ve been working on the v5 port of Umbraco’s official form builder Contour, today the RC version is out and it won’t be long now before the actual release.

A big plus compared to the v4 webforms version is that it’s possible to have complete control of the form markup that Contour will generate (a much requested feature that was super easy to add due to the move to the MVC framework).

To try this I downloaded a website template that contains a contact form, the contact form page looks like this:

StaticTemplate

You can check out the html here . As you’ll see the form html is pretty simple and different to what Contour normally generates but now you are able to mimic this with Contour.

Step 1: Creating the form

Of course you’ll need to install Contour first and then create a form that has the fields you want (in this case that’s name, email, subject and message).

CreateForm

Step 2; Replacing the static html with the Contour form

If I then place the Contour macro in place of the static form markup I get the following result

ContourFormWithDefaultMarkupAndStylesheet

Because the form markup generated by Contour is different from the form html in the template I get a strange result. Of course you could add additional css rules to make it look the same but I want to output the same html as the static html template

Step 3: Customizing the form markup

As outlined in the RC blogpost you can either choose to customize all your forms at once or you can do this for a specific form.

Do customize it for a single form we need to know the form id, the id is available on the settings tab of the form designer.

FormId

Now in order to control the generated html we’ll need to create the folder:

~/App_Plugins/Packages/Contour/Views/Forms/2f2d7355-2a0d-416e-b36f-99d331b163cf/

2f2d7355-2a0d-416e-b36f-99d331b163cf being the form id

There we’ll copy the default form view from

~/\App_Plugins\Packages\Contour\Views\MacroPartials\ContourForm.cshtml

to

~/App_Plugins/Packages/Contour/Views/Forms/2f2d7355-2a0d-416e-b36f-99d331b163cf/ContourForm.cshtml

This shouldn’t result in any changes yet but if you now make changes to the ContourForm.cshtml view you’ll notice these in the output.

If you then want to make changes to a specific fieldtype it’s just a mather of copying the default views to the form directory and making your changes…

CopyFieldTypeViews

End result

Once the changes have been made I’m outputting the same html,my form is styled correctly and I have a working form!

EndResult

To give this a try go test the Contour v2.0 RC

UPDATE
If you want to take a look at the customized views you can download them here:
http://dl.dropbox.com/u/886345/UpdatedViews.zip