This means you can create a template in Umbraco, and then insert the following line(s) of code to get an instant forum:

<form runat="server">
    <yaf:Forum runat="server" ID="forum" />
</form>

This was also possible because we do not need to share Membership information between Umbraco and YAF.  It may well be possible to share membership, and it’s something I’d like to look into if I ever get the time!

YAF Install Steps

1. Install Umbraco as usual, for instance into C:\Inetpub\wwwroot

2. If required, create a new database for YAF.  Alternatively, YAF can share the same database as Umbraco.

3. Create a directory for YAF, e.g. wwwroot/yaf

4. Unzip YAF files into wwwroot/yaf

5. Temporarily rename umbraco web.config to _web.config

6. Rename wwwroot/yaf/default.config to wwwroot/yaf/web.config

7. Enter a DB connection string into yafnet.config, into the <connstr/> tag. If sharing the database with the Umbraco install, copy the DB connection string from the “umbracoDbDSN” element in web.config into yafnet.config.  Note the “datalayer” keyword is not supported.

For example, if the Umbraco web.config contains the entry:

<add key="umbracoDbDSN" value="datalayer=SqlServer;Server=.\sql2005;Database=umbraco;
    User ID=umbraco_user;Password=password;Trusted_Connection=False" />

Then copy the connection string but do not include the datalayer section, e.g. yaf.config should contain:

<connstr>Server=.\sql2005;Database=umbraco;User ID=umbraco_user;Password=password;
    Trusted_Connection=False</connstr>

7. Still editing yaf.config, add a <root>/yaf</root> element.

8. In IIS create a new virtual application on the wwwroot/yaf directory:

• Right-click on the /yaf directory in IIS
• Choose “Properties” from the context menu
• Click the “Create” button on the Properties dialog
• Click OK

NOTE: at this point on the Umbraco website will stop functioning.  It will begin working again once the YAF application is removed (later in this guide).

9. Open a web browser, and navigate to http://www.mywebsite.com/yaf/install.  Follow the YAF installation wizard instructions.

10. Navigate to http://www.mywebsite.com/yaf and check that the forum is working.

Get Umbraco Working again

11. Right click on YAF, choose properties, click the “Remove” button to disable the YAF application.

Note: The Umbraco web application will now begin working again.

12. Move the yaf.config file to the root website directory e.g. wwwroot/

13. Rename wwwroot/_web.config back to web.config

14. Rename wwwroot/yaf/web.config back to wwwroot/yaf/default.config

15. Update web.config with config settings from the /yaf/default.config

 <section name="yafnet" type="yaf.SectionHandler,yaf"/>

 <yafnet configSource="yafnet.config"/>

 <authentication mode="Forms">
    <forms name=".YAFNET_Authentication" timeout="525600" />
</authentication>

 <customErrors defaultRedirect="error.aspx" mode="RemoteOnly"/>

Note that you will need to comment out the following line in the web.config file:

<forms name="yourAuthCookie" loginUrl="login.aspx" protection="All" path="/" />

16. Copy or move wwwroot/yaf/yaf.dll to wwwroot/bin/yaf.dll

17. Copy or move wwwroot/yaf/framehelper.aspx to wwwroot/framehelper.aspx

Add the forum to your website.

Create a document type and a template.  The template will look something like this:

<%@ Register TagPrefix="yaf" Namespace="yaf" Assembly="yaf" %>
<%@ Register TagPrefix="yc" Namespace="yaf.controls" Assembly="yaf" %>
<asp:Content id="Forumcontent" ContentPlaceHolderID="ContentPlaceHolderDefault" runat="server">
    <form runat="server">

        <yaf:Forum runat="server" ID="forum" />
    </form>
</asp:Content>

A Problem

Unfortunately there is a problem.  The YAF User Control will not work properly – it will attempt to reference default.aspx which is ‘owned’ by Umbraco.  This can be fixed using UrlRewriting.

A solution

To get around this:

1) Obtain the nodeId of the forum.  One way to do this is to log into the Umbraco Backend, place your mouse pointer over the forum node, and look at the browser status bar.  This will contain the node id.
For the purpose of this tutorial, we will assume the Node Id is 9999.

1) Update urlRewriting.config with the following (Note the Node Id in bold should be replaced with your node id):

        <!-- Redirect any requests for the-forum.aspx to forum.aspx -->
        <add name="forum-redirect"
                    virtualUrl="^~/the-forum.aspx"
                    rewriteUrlParameter="ExcludeFromClientQueryString"
                    destinationUrl="~/forum.aspx"
                    ignoreCase="true"
                    redirect="Application"
                    redirectMode="Permanent" />

        <!-- Internally rewrite the url -->
        <add name="forum-rewrite"
                    virtualUrl="^~/forum.aspx"
                    rewriteUrlParameter="ExcludeFromClientQueryString"
                    destinationUrl="~/9999.aspx"
                    ignoreCase="true" />

2) Ensure that the page (node) in Umbraco which contains the forum is called “Forum” and resolves to the url, “/forum.aspx”.

Note: Alternatively you could add a property to the Document Type called “umbracoUrlName” and set the value of that property to “the-forum”.

3) Ensure that there is NOT a page in Umbraco which resolves to “forum.aspx” (perhaps add to the list of reserved names?)

4) Ideally, any links (in templates, xslt etc) to the forum should link to “/forum.aspx” – NOT “the-forum.aspx”.  This means when linking to the forum, avoid using umbraco.library:NiceUrl(…)

Note: This is a recommendation rather than a necessity.  The “forum-redirect” rule above will ensure that all links to the forum will work.

Thats it – we’re done.  The forum should now be visible at www.mywebsite.com/forum.aspx , embedded into an Umbraco page.

Reserved Paths

You will also need to add /framehelper.aspx to the list of reserved paths in web.config

<add key=”umbracoReservedPaths” value=”/umbraco,/install/,/bingo,/framehelper.aspx” />

Also, if you wish to place the forum in a directory other than the root of your website, you will need to add a url rewriting rule for framehelper.aspx.

E.g. if you place the forum in /subdir/forum.aspx, you will need the following rule in urlRewriting.config:

<add name=”forum-reply-rewrite”
virtualUrl=”^~/subdir/framehelper.aspx”
rewriteUrlParameter=”ExcludeFromClientQueryString”
destinationUrl=”~/framehelper.aspx”
ignoreCase=”true” />

References

In fairness I should mention that most of the implementation details on how to embed YAF are actually covered on the YAF website.  Also, once I had worked out how to integrate YAF into Umbraco, I stumbled across this post by Skiltz on .NET, Integrating YetAnotherForum.net into Umbraco.  This post is concerned with Umbraco v3 but the steps are much the same so it’s great to see that others have been able to get this to work.  In this case, YAF was recompiled to get around the default.aspx issue – I solved this problem using UrlRewriting.  If you’d rather not use the UrlRewriting, you could try using the yaf.dll file provided by Skiltz instead.

Also thanks to Lars (see comments, below) for his tip on the use of the NodeId in the URL Re-write.

Basically I have a gallery of images and some meta data (descriptions, titles) etc defined in the Umbraco Media section.

Document Type

In my Document Type I have a Media Picker which allows you to select the Media. The alias for my field is ‘gallery’.

I have modified XSLTSearch so that it can be configured to treat certain fields as Media and will search the Media section.

XSLTsearch Macro

You will need to add a new field to the XSLTSearch Macro with an alias of “mediaFields” in which a comma separated list of fields containing media can be placed.

Here is a sample macro statement from Umbraco v4:

You will also need to replace the XSLTsearch macro with the one I have modified (based on the latest v2.7 of the macro).  Download the modified XSLTsearch here.

Umbraco GetMedia Bug

Incidentally there appears to be a possible bug/feature in Umbraco if you want to be able to select a Media Folder in the Media Picker.  The Umbraco function “umbraco.library:GetMedia” will not work unless you add an Upload field to the Media “Folder” data type, with an alias of “umbracoFile”.

It was also an opportunity to pick up some helpful hints and tips, which I’ve documented in this post.

Since I am barely a .NET developer (I have taught myself .NET in around 3 days !) I was quite apprehensive about how much I would understand.  Fortunately, there were 2 different streams – intermediate and advanced.

I attended the intermediate streams on Day 1 and found that they were generally very good, although (surprisingly!) they were aimed at real beginners: I’d been using Umbraco for a couple of weeks and some of the subjects (XSLT for example) I had already experienced at home.

That said, for those who had not yet felt some of that pain, I am sure it was a welcome introduction!

The announcement of Umbraco v4 was extremely welcome.  It looks as though the v4 enhancements will not only be welcome, but will make Umbraco a more serious tool.

In particular, the ability to roll between environments is a “must have” and I can’t wait for that functionality to be released!

Hints and Tips

While at Code Garden I captured some helpful hints and tips which I’ve documented below.

Control your URLs

It is possible to override the default url generated by Umbraco (based on the document Name).  To do this, you must add a field named “umbracoUrlName” (of data type “Textstring” to your Document Type).

When entering/editing content, the value entered for “umbracoUrlName” will be used to create the filename portion of the URL (“filename.aspx”).

Multiple URLs for the same document

If you add a field named “umbracoUrlAlias” to the Document Type, this can be used to specify alternative URLs for a document.  Again, this field should have the “Textstring” datatype.  Multiple aliases can be specified – they can be comma-separated.

Tokens in Templates

Umbraco allows you to specify tokens when passing information to Macros within templates.  Tokens are then replaced at runtime with suitable content.

Tokens are placed inside square brackets [...].  The tokens which were discussed were:

• [#pageID]
  This token will be replaced with the ID of the current page.
• [#key]
  Pull the dictionary item with the specified key
• [@name]
  return the value of Request(name); for example, from either the query string or from a POST request
• [%name]
  return a value from Session.  Session information can be set using XSLT if required, using the umbraco library functions.  For example,

  <xsl:variable name="sessionVar" select="umbraco.library.setSession('name','value')" />

• [$recursive]
  returns the value of a field named “recursive”.  If this field is not found, or is empty, Umbraco will search for a parent document which has a field named “recursive” which is not empty. I cannot get this to work so have struck this from the post.
  

Recursive Fields

When inserting a field into a template, the dialog has a “Recursive” check box.  If this is ticked, the [$recursive] functionality described above is activated: If this field is not found, or is empty, Umbraco will search for a parent document which has a field named “recursive” which is not empty.

Struggling with XSLT? Take a peek at the Umbraco XML file

You can view the XML which is parsed by the XSLT processor.  Simply locate the “data/umbraco.config” file on the Umbraco IIS server.  This can be used to develop and even debug XSLT in Visual Studio.

umbracoNaviHide

Many XSLT functions and templates refer to a document property called “umbracoNaviHide”.  If you include this property (as a true/false data type) in your documents, you can hide the document/content node from XSLT queries which adhere to this convention.

Multiple Domains

You can have multiple domains point to the same Umbraco site.  Right-Click on the site root node, choose Copy, and tick the “Relate” check box.  The copied site can then be associated with a different domain name.  Updates to the copy/original site will be mirrored in the original/copied site.

Multilingual Sites

Insert an Umbraco field into a template.  The name of the field should begin with the ‘#’ character.  The rest of the field name will be treated as a dictionary key, and the dictionary value will be used in place of the field.

Scheduled Tasks

Scheduled tasks can be configured by editing the web.config file.  This will cause a particular aspx page to be executed at a regular interval.

Insert Images without using XSLT

It is possible to insert images without using XSLT! Unfortunately, my notes on this one turned out to be innaccurate.  So I asked the guys on the Umbraco forum for help and this is what they came up with:

<img src='<umbraco:Item field="umbracoFile" nodeid="1072" runat="server"></umbraco:Item>' />

It should also be possible to use “insertTextBefore” and “insertTextAfter”, however this is not currently working on my copy of Umbraco v4.  The modified syntax would then be:

<umbraco:Item field="umbracoFile" nodeid="1072"

              insertTextBefore="<img src='"

              insertTextAfter="' />"

              runat="server"></umbraco:Item>

http://umbraco.org/blog/

http://umbraco.org/blog/2007/12/2/dec-2-resources-and-where-to-find-help
http://umbraco.org/blog/2007/12/3/dec-3-umbraco-basics-document-types
http://umbraco.org/blog/2007/12/6/dec-6-document-types-part-ii
http://umbraco.org/blog/2007/12/7/dec-7-templates-part-i—the-introduction
http://umbraco.org/blog/2007/12/12/dec-8-adding-page-information-to-templates
http://umbraco.org/blog/2007/12/13/dec-9-using-master-templates

Right now all I want to do is render a Blog Description in a “Home Page” template but I cannot figure out how to do it.  Umbraco uses a lot of XSLT which I am not too hot with – something else I need to address.

The initial learning curve for developing in Umbraco seems to be much steeper than Joomla!

Well, following some of the tutorials on the Umbraco website seems to have helped: the information is there if you need it!

The CMS of choice is Umbraco – a .NET based open source system.  As I am a J2EE developer, I’m going to need to cross-train toot suite!