Marker Kentico Business Library

Marker have created a complete business layer facade for working across the kentico document apis. Why would we do such a crazy thing? Well, we found that on larger and more complex web applications that we had a certain amount of trouble with the standard approach.

When you use custom document types in Kentico, your rows are either returned as a CMS.TreeEngine.TreeNode or a System.Data.DataRow depending on what part of the api you are using. So the first main driver for our business layer was to be able to have a business entity class that mapped directly to a custom document type in Kentico. This means we know exactly  how a particular document type is represented in our application and know exactly what properties it has.

Also, you have different apis depending on whether or not you are using workflow/versioning or not.  All of the recommended development articles within the Kentico documentation generally assume you are working with published documents on your site which might not always be the case.

It should be noted that this approach is really for aspx template advocates looking to get the maximum control and performance from Kentico. This approach is likely overkill for smaller sites and is not applicable for the portal engine approach.

This article will focus on the basics of creating an entity class mapping to your custom document type and using the generic repository to perform some standard operations. There’s a lot of functionality in the MKB library beyond what is shown here and we doubt there is anything you can do with the kentico document api that you can’t do more easily and cleanly with the MKB library, if there is, let us know!

This library works against v5 with the 5.0.5 hot fix applied only. Just drop it in your bin folder and off you go..

Let’s create our first document entity class…

You can see a sample entity below which maps to a custom document type in our application. You will need to create this for each custom document type in your application. Note that we are currently working on code generation which will automatically generate these classes for you against the Kentico database. We think this would be a great feature to have within Kentico itself at some point.

Make sure you entity class inherits from the DocumentEntity class (Marker.Kentico.Business.Entities.DocumentEntity). This class includes all the core fields for a kentico document instance.

Next, you should apply a special table attribute. The table attribute allows you to set the class name (maps to kentico document type’s class name) and default alias path (the default alias path which forms the basis of all data access for the entity by default). In addition (not shown below) there is the possibility of setting the default site code (default site code for all data access for the entity by default if required with multi site solutions and also a default wildcard alias key (for automatically loading the entity based on a wildcard alias. If you don’t set this it’s the name of the entity lowercased, in this case ‘supplier’).

Next, apply special field attributes for each property you want to map to a kentico document type. Note that your property names can be different from the underlying field if you want, and you can specific the nature of the binding (read, insert, update, all) as required.

This is all that is required to start using MKB, create a simply entity and move on to the next step, where the fun begins!

using Marker.Kentico.Business.Attributes;
using Marker.Kentico.Business.Enumeration;
using Marker.Kentico.Business.Entitie;
using Marker.Kentico.Business.Attributes;
using Marker.Kentico.Business.Enumerations;
using Marker.Kentico.Business.Entities;

    public class Supplier : DocumentEntity
    {

        private string _companyName = string.Empty;

        public Supplier()
        { }

        [Field("CustomerCode", FieldBindingType.All)]
        public string CustomerCode { get; set; }

        [Field("CompanyName", FieldBindingType.All)]
        public string CompanyName {
            get { return _companyName; }
            set
            {
                _companyName = value;
                this.DocumentName = value;
            }
        }

        [Field("ImageThumb", FieldBindingType.All)]
        public Guid ImageThumb { get; set; }

        [Field("Url", FieldBindingType.All)]
        public string Url { get; set; }

        [Field("Address", FieldBindingType.All)]
        public string Address { get; set; }

        [Field("Phone", FieldBindingType.All)]
        public string Phone { get; set; }

    }

Let’s work with our entities using the document repository…

All you need to do is to put a using statement to the entities and repository namespaces

using Marker.Kentico.Business.Repository;
using Marker.Kentico.Business.Entities;

Then you can retrieve a strongly typed repository to work with your supplier entities as follows. This retrieves a singleton instance of the repository class, it could also be created using dependency injection if preferred, but this is the simplest api to be offered.

var repository = RepositoryFactory<DocumentRepository<Supplier>>.Instance;

Once you have your repository you can then load entities or get the current entity (if it is a supplier otherwise it will be null)

Supplier supplier = repository.Load(string aliasPath);
Supplier supplier = repository.GetCurrent();

Here are some other thigns you can do…

Saving and Deleting

Just update your entity’s properties and call the save method

supplier.Url = "http://newurl.com";
repository.Save(supplier);

Deletion is just as easy:

repository.Delete(supplier.DocumentID);

Custom Query Support with Paging!

You can see below that our repsitory enables querying with paging support (returning the total results)

var searchCriteria = new QueryFindCriteria();
searchCriteria.QueryName = "FindSuppliers"; // set the query name here
searchCriteria.SelectOnlyPublished = false; // let's include unpublished nodes
searchCriteria.Take = 10; // take 10 rows
searchCriteria.Skip = 10; // start at row 11
int totalCount = 0;
List<Supplier> suppliers = repository.Find(searchCriteria, out totalCount);

To support this you must be running SQL 2005 or above and simply structure your query as follows.

WITH AllResults AS
(

-- core paged query should go in here

select SupplierView.*, Row_Number() over (order by ##ORDERBY## as RowIndex
FROM View_SMS_Supplier_Joined as SupplierView
##WHERE##
)

SELECT (SELECT COUNT(NodeID) FROM AllResults ) As TotalResults, *
FROM AllResults
WHERE RowIndex > @skip AND RowIndex <= (@skip + @take)

Criteria objects (not overloads)

You will likely have noticed that Kentico has dozens of overloads for it’s core methods. MKB gets round this by having a limited number of overloads with criteria objects that contain properties with sensible defaults for all core operations.

For example, the QueryFindCriteria mentioned above has the following properties.

• SiteName (defaults to current site)
• CultureCode
• Where
• TopN
• SelectOnlyPublished
• OrderBy
• CheckUserPermissions
• QueryName
• Parameters

And there is a simpler TreeFindCriteria accepted as an overload to the Find method on any repository with these properties:

• SiteName (defaults to current site)
• CultureCode
• Where
• TopN
• SelectOnlyPublished
• OrderBy
• CheckUserPermissions
• AliasPath
• CombineWithDefaultCulture
• MaxRelativeLevel
• SelectLatestVersion – allows you to work with latest version of document under workflow, no need to change your api!

We hope you can see how much simpler this is as you just need to set the properties you explcitly need for any query rather than being forced to use a particular overload.

Conclusion

We are sharing this library because we believe that it will be of value for kentico developers and partners to assess and make use of. We hope that it will also be useful for Kentico themselves who might consider the development of such an api to make it easier to work with Kentico.

This code base is provided as is and we recommend you use it for testing purposes at this stage (although we feel the api coverage is pretty good). We’ll support and answer questions as best we can. There’s lots not covered here that is offered with the library that i’ll cover in future posts if the interest is there!

Get the code!

We are providing a debug compiled version of our business assembly to solicit feedback on the apis offered. If there is sufficient interest we will release the code base on codeplex.

Download the latest version here: Marker.Kentico.Business.v3

Marker is Kentico Site of the Year Finalist

Marker is a finalist in the Kentico Site of the Year contest for our work on Yellow Maps.

We are the only Kiwi company in the battle for prizes so every vote counts in the online voting that will be carried out this month.

Please vote now, there are 12 categories to vote for and we are on Page 9 of 12 under the “Best Other/At Large Site” on the right hand side under ‘Yellow Maps’.

Culture Options – UI and Content Cultures

The Administration > Users section allows the setting of the Preferred content culture and the Preferred user interface culture. These values normally set at (default) but what does all this actually mean?

It is recommended to not explicitly set the culture for users and to let the defaults be used. Unless a user explicitly wishes to override, assuming this culture is supported.

Content Culture

Content cultures determine the actual content culture stored against Kentico documents as they are saved. If you have a multilingual site there are multiple documents stored for each culture against a single ‘node’.

N.B There is always a default content culture for a Kentico site.

List of all content cultures

The available list of all available content cultures are at Site Manager > Development > Cultures. All major cultures are provided here and you shouldn’t need to modify this list.

Setting the default content culture

You can set this in two ways (both have the same effect).

• Site Manager > Sites > [Site Instance] > Default content culture
• Site Manager -> Settings -> (select site) -> Web site -> Default culture of the content

What this means is that the default culture for all documents will be this value (e.g. en-NZ). If a user has (default) saved against their ‘Preferred content culture’ they will then see the default content culture for the Site they are viewing if they are logged in.

The default content culture should be set first in any Kentico implementation.

Setting the default visitor culture

You can set this in the following ways:

• Site Manager > Sites > [Site Instance] > Default visitor culture
• Site Manager > Sites > [Site Instance] > Domain Aliases > [Domain Alias Instance] > Default visitor culture

What this means is, if a user comes to the site anonymously, this is the culture that will be used by default to display to visitors and this can be managed on a domain alias level also.

For a site without multilingual capabilities it would normally be the same as the default content culture, but one may wish to have a French version of a site under a different domain in which case the default visitor culture setting would be set to French.

If this is not set, then the user’s browser settings will be used to determine the default visitor culture.

It is recommended that the default visitor culture always be set to match the default content culture by default.

Site manage > Sites > [Site Instance] > Cultures

This section allows you to set all the cultures that are being supported for a particular Kentico site. Note that this will affect the selectable cultures from within the cmsdesk administration interface for a particular website.

It is recommended that these values always be explicitly set when setting up a Kentico instance. If not a multilingual site allow only a single culture which matches the supported default content culture.

UI Culture

The UI Culture is the culture of the CMSDesk administration interface. Out of the box (OOTB), Kentico uses en-us (US English).

UI Cultures are stored within Site Manager > Development > UI Cultures. You will see there is an ‘English’ option, but this actually corresponds to en-us (US English). If you want to allow users to select between this and UK English for example within CMSDesk you should create a new UI Culture called English (NZ) and set the code to en-NZ.

If a user has (default) saved against their ‘Preferred user interface culture’ they will then see the CMS Desk interface using the culture defined in the AppSetting.config file for that website (there doesn’t appear to be a corresponding value within Site Manager). This value should be set to a sensible default to avoid users having to change it themselves. For a site managed from New Zealand it should be:

<add key=”CMSDefaultUICulture” value=”en-NZ”/>

It is recommended that this value always be explicitly set when setting up a Kentico instance.

Base System Requirements: IIS 7.0 with .net 3.5 SP1 on a Windows Vista dev machine or Windows 2008 server to utilise extensionless urls.

Firstly, install the marvellous IIS 7.0 URL Rewrite Module
Get it here: http://www.iis.net/downloads/default.aspx?tabid=34&g=6&i=1692
Learn about it here: http://learn.iis.net/page.aspx/460/using-url-rewrite-module/

Now, make sure Kentico is configured not to interefere with things…

Kentico automatically applies a filter to the form tags. You need to disable this here:

• Site Manager > Settings > Output Filters >
• Ensure the ‘Excluded output form filter URLs’ value is set to a single forward slash.. /
• Site Manager > Settings > Urls>
• Ensure the Friendly Url Extensions value is blank

There is currently no way of ensuring that automatically generated urls from Kentico contain a trailing slash. The user must set the Document UrlPath for each page in Page > Properties > Urls to include the trailing slash. However the trailing slash is enforced via in IIS 7 rewriting rule. It is hoped that a future version of Kentico will allow for this to avoid the extra 301 redirect.

Now apply the following website configuration….

Place the following code in the Page_Load of your master page.
            // ensure we fix up the form action if required
            if (!String.IsNullOrEmpty(Request.ServerVariables["HTTP_X_ORIGINAL_URL"]))
            {
                form1.Action = Request.ServerVariables["HTTP_X_ORIGINAL_URL"];
            }

This ensures that Asp.Net postback and ajax work correctly with the IIS7 URL Rewrite Module

Now all you need to do now is apply whatever special rewriting rule syou like within the web.config, utilising the IIS Rewrite Module’s capabilities as you need them. (Note that you don’t need to do anything within IIS, you can manage everything within the web.config and simply deploy it out to target servers without worrying about any additional configuration).

For example, the EnforceTrailingSlash rule below will ensure that a trailing slash is added to all urls without extensions, performing a 301 redirect in the process. This is so to avoid multiple urls (ones with and without slashes) returning the same content which isn’t ideal from an SEO perspective.

The TrailingSlashToAspx rule below will ensure that a trailing slash is rewritten internally to .aspx, so that the kentico rewriting engine can take over. Note that the Kentico CMS folders are ignored (ones starting with CMS..)

<system.webServer>
        <rewrite>
            <rules>
                <rule name=”EnforceTrailingSlash”>
                    <match url=”^(.*)$” ignoreCase=”false” />
                    <conditions>
                        <add input=”{REQUEST_FILENAME}” matchType=”IsFile” negate=”true” />
                        <add input=”{REQUEST_URI}” negate=”true” pattern=”(.*)\.([a-zA-Z]+)(\?.*)?$” />
                        <add input=”{REQUEST_URI}” negate=”true” pattern=”(.*)/$” />                       
                    </conditions>
                    <action type=”Redirect” url=”{R:1}/” redirectType=”Permanent” />
                </rule>

                <rule name=”TrailingSlashToAspx”>
                    <match url=”^(.*)/$” />
                    <conditions>
                        <add input=”{REQUEST_FILENAME}” matchType=”IsFile” negate=”true” />
                        <add input=”{REQUEST_URI}” negate=”true” pattern=”/cms(.*)$” />
                        <add input=”{REQUEST_URI}” negate=”true” pattern=”^(.*)/\.aspx[#\w=\|\&amp;%-]*$” />
                    </conditions>
                    <action type=”Rewrite” url=”{R:1}.aspx” />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>

And so there you have it, a relatively painless way to get yourself all SEOd with IIS 7.0 and Kentico CMS 4.0.

My good friend Nigel Parker over at Microsoft beat me to the post with his excellent blog post on Marker Studio‘s new search site for Yellow and customised IE8 browser experience:

The launch has been very successful with over 10,000 downloads of the Yellow IE8 browser in the first 2 days!

To add a bit of technical detail to Nigel’s post we made heavy usage of the Google Search Ajax APIs. I kind of wish they still had the SOAP apis as it would have been easier in many respects using .net to bind the results using server side asp.net rather than be forced to work primarily with the ajax apis. Also, the ajax apis come with handy code snippets http://code.google.com/apis/ajaxsearch/ but they assumed things like ajax calls for paging requests which means the user can’t bookmark the urls. Aside from that a few workarounds here and there got us enabling Google integrated search quite easily. I would like people to note that the Live Search apis were superior in terms of the range of ways one could consume search services, and relevance in my book is very comparable between the two.

We made use of Linq to XML when consuming the core Yellow listings api which is REST based. This made the consumption and binding of the search results to the page using a standard asp.net repeater much easier. In fact, i cringed to think of the additional effort that was involved before Linq for XML in navigating XML Documents with the .net 2.0 xml apis which I never found particularly intuitive.

There is also some Salesforce integration for helping to manage competition entries where we created custom lead objects in Salesforce. It’s kind of nice to have the ability to regenerate the wsdl for the web service after you make changes in the gui to core field information. It would be even nicer to have this discoverable at runtime so i could just regenerate proxies using a url rather than having to download the wsdl and re-run svcutil across the wsdl locally.

And let’s not forget our good friend JQuery, and loving that Intellisense support in Vs.Net 2008;) Also a shout to facebox for those obligatory modals with rounded corners.

Oh, and the whole thing is powered by Kentico CMS. Kentico CMS is a powerful, flexible and affordable content and document management system that i have been personally recommending to all and sundry since i first came across it in 2005. At Marker <shamelessPlug>we have a great team of experienced Kentico developers should you be looking in this direction. Please give me a yell if you would like to discuss further</shamelessPlug>. ]]> http://www.markerstudio.com/marketing/2009/03/marker-and-yellow-partner-to-bring-ie-8-first-in-new-zealand/feed/ 1