Tuesday, June 30, 2015

Ektron adding a widget to the smart desktop (admin desktop)

To get a widget added to the smart desktop (aka the admin desktop) of an Ektron web site, you must follow different steps than adding a normal widget which can be added to pages.
  1. Create a widget and save it under /Workarea/Widgets/
  2. In the workarea, navigate to Settings > Configuration > Personalizations > Widgets and click on "Synchronize widgets from /widgets/ folder". This is a misleading button naming, but also syncs the workarea (admin) widgets.
  3. In the workarea navigate to Settings > Configuration > Personalizations > Widget Space and select the "UserSmartDesktop" widget space, here you can select which widgets can be added to the smart desktop.
  4. Now you can go to the "Desktop" tab in the workarea and add the widget to the smart desktop.

Sunday, June 28, 2015

Using the Ektron Framework API (service) from command line or application

The Ektron Framework API provides an interface to interact with an Ektron web site - this may be via another web site or in an application of some kind. Using the service you can access content, users, commerce, settings, search and so on using CRUD (Create, Read, Update and Delete) commands.

Ektron has provided a console application which leverages this framework API, which can be found here. This particular sample is made to work with version 9.1 of Ektron, however it should easily work with any later versions.

Getting the sample solution working

  1. Replace the DLL files with latest versions
    1. Remove all references from the solution
    2. Add the refrences again from the following path: C:\Program Files (x86)\Ektron\CMS400v91\startersites\3TierMin\Content\bin
  2. Replace the ektron.cms.framework.unity.config and instrumentation.config files
    1. The replacements can be found in: C:\Program Files (x86)\Ektron\CMS400v91\startersites\3TierMin\Content
  3. In the app.config change the "ek_ServicesPath" variable to the location of your Ektron installation
  4. In the main program class file, you will need to enter admin credentials to authenticate with the CMS.
The sample solution should then build and when run will create a piece of sample content. From here you are able to modify the code to interact with the Ektron Framework API as required.

Ektron accessing smart form content from code and displaying in a widget

Ektron smart forms are a great way to provide a content structure which is easy for content authors to use. When it comes to displaying the content on your Ektron web site, XSLT is one option, however accessing the content programmatically (via the Ektron API) gives the developer more control over how the data is transformed and displayed.

Create a C# class of the smart form

The first requirement is to create a C# class of the smart form being accessed. This is done by downloading the XSD file (an XSD file is the definition of XML data - in this case the Ektron smart form which is stored in XML) of the smart form - found on the data definition section of the smart form configuration.

Windows has a built in tool (called XSD.exe) which can automatically generate a class based on the XSD. Open up the command line and focus it on the following directory;
c:\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\bin\NETFX 4.0 Tools\x64
Once in there, run the following command:
xsd.exe c:\temp\MySmartform.xsd /c /language:CS /outputdir:"c:\temp" 
In this case it is creating a C# class of the MySmartform.xsd (found in c:\temp) and outputting in the same location. The class is automatically named root, we can give this a better name (such as news) and include a definition so that it will map correctly from the Ektron service.


Now place this class in the App_Code folder in your Ektron web site, this will allow it to be used in code

Accessing Ektron smart from data via the API

In this case, we have an folder in the Ektron folder which contains items of this smartform type. We simply set the API criteria to that folder ID and the content (smartforms) inside will be returned.


Publication in this case is the name of the smartform class (created earlier). This code will then give a list of these publications which can then be transformed and displayed as required.

Friday, June 26, 2015

Ektron Smart Forms - rich text field outputs as "Rich"

When using the XSD output of an Ektron smart form and converting this to a C#/VB class, rich text content will generally output as the string "Rich". This is because rich text is not a standard .NET data type, and it will need a small fix to work correctly. In the class file (generated by XSD.exe) look for the rich class - "public partial class rich".

We are going to add in the following ToString extension which will give us the correct rich text.
Simply add in the "public override string ToString()" method and the rich text will begin to render correctly.

Tuesday, June 23, 2015

Ektron widget is not available to insert on the page editor

For a widget to be insertable on the page editor in Ektron it first needs to be selected as an "available widget" on the template used by the page. To edit these available widgets, in the Ektron workarea navigate to Settings > Configuration > Template Configuration and then select the template you wish the widget to be available on.

Select the widget(s) you wish to be available for content editors to add to pages of this template type in the content editor.

If the widget is missing from the available widgets your Ektron widgets may be out of sync. In the Ektron workarea navigate to Settings > Configuration > Personalizations > Widgets and click the "Synchronize Widgets from /widgets/ folder" button at the top of the page. The widget should now appear in the list on this page and be available for selection on the template configuration screen.


Browser print the content on popup modal and not parent page

If a modal window is active, the browser print function can produce less than ideal results where the parent page shows in the background and the modal on top (much like it appears in the browser). The following CSS trick when placed on the modal content, will allow only the modal to print and not the parent page.

Simply place a div with the class "printable" around the modal content to be printed and the CSS will make that area visible with the rest of the page hidden.

Saturday, June 13, 2015

Ektron Subscriptions Overview

Introduction

The most important resource to any web site are the users, they are the whole purpose of it's existence and are the one who read the content and purchase goods or services. Growing user traffic is no simple task (especially organically) so any way to encourage existing users to visit again is a cost effective way of keeping user numbers up - and targeted users at that. This is where the Ektron subscriptions feature comes into play.

Ektron Subscriptions is a feature which allows users of an Ektron web site to sign up to areas that interest them, and then receive a notification (via email) when relevant pages are updated. This is not only an automated way to keep users informed of content updates and bring them back to the web site, but you are actually building a user database which contains user-defined categories of interest.

How it works

Firstly you need to define what subscriptions will be available, these are simply a textual description such as cars, trucks, motorbikes and so on. You will also define which email address(es) the subscriptions will be sent from, each piece of content allows you to specify which email is used, so it's possible to be very granular in this regard. You can also pre-define a number of messages, which can be used for the main content of the notification email, or unsubscribe/opt out in it as well.


Then you create a subscribe page which will allow a user to sign up and select subscriptions they are interested in. This page will actually create a community user in the Ektron system, so at a minimum the page will need to collect: first name, last name, email address, password (you can set this in the code behind if the users will never need to login) along with their subscription choices. An unsubscribe page is also required, this page will collect an email address and unsubscribe the user with that address from receiving notifications.

Pages will also need to be assigned to a subscription(s) so that they will notify the subscribed users when changes are made. In the editor for content, there is a web alerts tab, this is where subscriptions are defined. The main option for alerting are notify always, notify never and notify only on initial publication. When publishing the author is also able to override these options and not notify in that instance (which is handy when making a minor change such as fixing up a spelling mistake. A subject for the notification email is set, as is the email address it will be sent from. The content of the email is built up from selecting any number of options, an unsubscribe message is required, but the rest of the content could be made up of a message defined earlier, the item's summary or even another piece of content. Finally you select which subscription(s) the content applies to, it can be any number of them.These web alert settings can be set on a folder and inherited to child content, so it's important to ensure that web alerts are carefully defined so that the entire content tree is not set to one alert - this would lead to a lot of unwanted notifications to users.



Conclusion

The Ektron subscriptions/web alerts feature is a great way to keep engaged with the visitors of a web site. It allows users to ensure they stay up-to-date with content relevant to them, whilst allowing the web site owner to build a user database of motivated, and segmented customers. The configuration process takes a very granular approach which allows for well defined and setup subscriptions that can simply be inherited or defined with custom settings at a single content item level.

Monday, June 8, 2015

Ektron Object of type 'System.Int32' cannot be converted to type 'System.Web.Security.Cryptography.Purpose'

The following error may occur on versions before 8.7 of Ektron:
Object of type 'System.Int32' cannot be converted to type 'System.Web.Security.Cryptography.Purpose'
It occurs if you have installed version 4.5 of the .NET framework. The following solutions are available to fix this error:

  • Upgrade to Ektron 8.7 (or beyond)
  • Downgrade from version 4.5 of the .NET framework to version 4
  • Disable cookie encryption in the web.config of Ektron

Tuesday, June 2, 2015

Tutorial: Creating a Sitecore 8 Website Part 5 - Layouts and Sublayouts With Templates

Sitecore Layout

A layout is basically a master page for Sitecore, it is required for Sitecore items to render in the browser and has placeholders for sublayouts to render as well. To define a layout, load up Sitecore administration and then the content editor. In the content tree expand the Layout item and right click Layouts and click Insert > Layout. Give the layout a name of "MainLayout" and click Next, then click Next again twice as the default locations are okay. Now to connect this layout with the file you created in the visual studio project, change the Path to "/Layouts/MainLayout.aspx".

Select the ContentPage template's standard values from the content tree and then select Details (under presentation) off of the top menu. Now on the layout tab (after clicking edit under default) select the MainLayout created in the previous step. By setting this value, by default (because of standard values) any ContentPage item in Sitecore will use the MainLayout layout.

Do the same for the Destination template's standard values file.

Sitecore Sublayouts

Sitecore sublayouts can be thought of as widgets (or web parts in SharePoint), they distinct items (with code behind) that can be added to Sitecore layout. A Sitecore item can only have one Layout (although it can be different based on desktop, mobile or print), but can have many sublayouts - even multiple copies of the same one.

To define a sublayout, load up Sitecore administration and then the content editor. In the content tree expand the Layout item and right click Sublayouts and click Insert > Subayout Folder and name it "TravelSite". Right click the newly created folder and click Insert > Subayout, give the sublayout a name of "MainContent" and click Next, for the location select the folder "TravelSite", click next.

Click the create value, because we don't need to create the ascx files. Now to connect this sublayout with the file you created in the visual studio project, change the Ascx file to "/Sublayouts/MainContent.ascx".

Do the same for the Navigation and DestinationContent sublayouts, and your content tree  should look like the following:

Sitecore Placeholder Settings

In the main layout aspx file in visual studio, 2 Sitecore placeholders were referenced. We now need to reference these in Sitecore to allow them to be used. In the content tree expand the Layout item and right click Placeholder Settings and click Insert > Placeholder Settings Folder and name it "TravelSite". Right click the newly created folder and click Insert > Placeholder, give the sublayout a name of "Main". 

The placeholder has a setting called Allowed Controls, this allows you to manually define which controls can be added to this placeholder. If left blank, there are no restrictions however if you add selected Sublayouts, only those ones can be added. Click edit and select the MainContent and DestinationContent sublayouts.

Create another placeholder called TopNavigation and set it's allowed controls to allow the Navigation sublayout. Your content tree should look like the following:

Adding sublayouts to a template in Sitecore

Now that we have sublayouts and placeholder settings defined, we could add the required sublayouts to the content items created earlier in this tutorial. However instead of doing it manually multiple times, like anything else the sublayouts can be defined at the template level.

Select the ContentPage template's standard values from the content tree and then select Details (under presentation) off of the top menu. On the Controls tab (after clicking edit under default), click Add, then add the Navigation sublayout to the TopNavigation placeholder.

Do the same for the MainContent sublayout, but add this one to the Main placeholder.

The added controls should now look like the following:

For the Destination template's standard values file, add the DestinationContent control to the Main placeholder and the Navigation control to the TopNavigation placeholder. It should now look like the following:

Publishing the Sitecore site

Now that the items have been created, they have a layout along with multiple sublayouts the Sitecore site can be published (please also ensure the visual studio solution has also been published). From the top menu select Publish > Publish and Publish Site. 

As this is out first publish we will select "Republish everything" to ensure nothing it missed. Normally a smart publish would suffice as Sitecore picks up the changed items well. Click the publish button to publish the site (this may take several minutes).

Once complete your site should load in the browser, for this tutorial the URL for my Sitecore site is "http://Sitecore/" and this URL shows:

Notice that the navigation is showing due to the Navigation sublayout, the content is showing due to the MainContent sublayout and the page title (and browser title) is set due to the MainLayout. The about page (available at "http://Sitecore/About") appears as follows:

Finally a destination page such as Auckland (available at "http://sitecore/Destinations/Auckland") appears as follows:

A zip file containing a Sitecore package of the items, templates, placeholders, layouts and sublayouts, can be downloaded here. To install please see Using the package designer to sync Sitecore content between environments.

Final notes

In this tutorial series we covered the absolute basics for getting a simple Sitecore web site up and running. Once you have achieved a base site like this, you can start diving into the much more advanced features which set Sitecore apart from other content management systems on the market. 

Tutorial: Creating a Sitecore 8 Website Part 4 - Layout and Sublayout File Creation

Introduction

For a Sitecore item to render in the browser it needs to have a layout associated with it. This layout is effectively a master page which includes the HTML/CSS along with the output of Sitecore data (via code). A layout can also have a number of sublayouts included on it, sublayouts are really the building block of the web page. For example the layout would have a number of placeholders which then can host sublayouts (such as a navigation, banner, content, form sublayout).

These layouts and sublayouts need to be created as user controls in Visual Studio, then registered in the CMS and ultimately assigned to the item templates. In part 4 of this tutorial series we are going to create a main layout and a number of sublayouts in Visual Studio.

Creating the main layout

Open up the MySitecoreSite visual studios solution from part 1. For this tutorial I will be using the clean blog design, available from Start Bootstrap (mirror of download available here). To integrate this into the solution, follow these steps:

  1. Delete: the mail folder, about.html, contact.html, LICENSE, post.html, README.md
  2. Create a folder in the root of the project called "Resources" and place the following folders inside it (remember to include these in the project):
    • css
    • fonts
    • img
    • js
    • less
  3. Create a folder named "Layouts" in the root of the project and inside it add a new Web Form called MainLayout.aspx.
  4. On the MainLayout.aspx page use the following code (taken from index.html):

You will notice that there is a registration included for the Sitecore namespace and that 2 Sitecore placeholders have been defined (TopNavigation and Main). These placeholders will allow us to add sublayouts onto the layout in Sitecore. There is also a field output in the title tags, with DisableWebEditing set to true because meta tags can't be edited in the browser by content authors. For on page text fields, this value would not need to be set and the user could edit the fields on page.

Creating the sublayouts

In the root of the project create a folder named "Sublayouts" and add a new Web Forms User Control named "MainContent.aspx". On the control add in the following code:

This is simply outputting the HTML from the Content field on the ContentPage Sitecore items. For more advanced logic you would use C# code to get the fields, perform logic and then output to a repeater or other control.

Create the following Web Forms User Controls in the same Sublayouts folder.

  • DestinationContent.aspx

  • Navigation.aspx

In the navigation code behind we are getting the main Sitecore content item (by GUID - you will need to update to the GUID for your content item). Then we get all of the children of content and add them to the list of menu items. This list of menu items is then bound to the repeater on the user control. For an example of a multi level menu, please see C# nested repeater for a menu with child items.

Now you can publish the solution to your Sitecore web site, this can be done by right clicking on the project and clicking Publish. For instructions on how to set this feature up, see the "Publishing the solution to the Sitecore web site" section on Sitecore setting up a visual studio solution.

A zip file of the visual studio solution, can be downloaded here.

Next step

The layout and sublayout files have been created in visual studio and published to Sitecore. Part 5: Layouts and Sublayouts With Templates now goes into the detail of registering these layouts/sublayouts in Sitecore and assigning them to the relevant templates.

Tutorial: Creating a Sitecore 8 Website Part 3 - Item Creation

Introduction

Now that we have defined templates for both content pages and travel destinations in part 2, we can utilise these templates to create content items. At this step, these items will not actually render in the browser because we first have to design the layouts/sublayouts and then assign them to the item templates.


Creating the items

Log into Sitecore administration and load up the content editor. Select the main Content item and from the top menu select Configure and Assign (Insert Options). Select the ContentPage and Destination templates as the insert options for this item. 

Select the Home item under Content and from the top menu select Configure and then Change (Template). Now select the ContentPage template found in the TravelSite folder, you will get a message indicating that fields will be lost, click Next as these fields were from the default Sitecore template (not required).

Now we are going to create some simple content pages. Right click on the Content item and then Insert > ContentPage and give the item the name "About".  Under the Content field enter some HTML content (click Edit HTML) for the page, the title attribute has pre-populated from the standard values, however you will need to enter a description and keywords.

Do the same step as above for some other general content pages, I added 5 more content pages.

Now right click the destinations item and select Insert > Destination, give the destination the name of "Wellington". Enter some details like the following image (please note that for this tutorial we have used simple content types rather than lookups or selections for country and weather to keep things simple). 

Now enter some other destinations (with multiple countries). I have entered 7 destinations across New Zealand and Australia.

A Sitecore package of the items created, can be downloaded here. To install please see Using the package designer to sync Sitecore content between environments.

Next step

Now that the content has been defined, we can move onto Part 4: Layout and Sublayout File Creation. This will involve creating the layouts/sublayouts in Visual Studio. Part 5 will then cover adding these layouts/sublayouts into Sitecore and assigning them to the ContentPage and Destination templates - which should then make the site render in the browser.

Tutorial: Creating a Sitecore 8 Website Part 2 - Template Creation

Introduction

If you began at part 1, you should now have a clean Sitecore 8 web site and visual studio solution. As we are building a travel web site, there will be two main types of items: content pages and travel destinations. Each of these item types will require a template so that content authors can enter the relevant information for each item instance.

Creating the templates

Log into Sitecore administration and open up the content editor. On the right hand menu expand the Templates item, right click it and create a Template Folder named TravelSite. By creating a folder to hold all custom templates, we make content syncing between environments easy. It also makes it easier for another developer to work with.

Right click the TravelSite folder and click Insert > New Template, do this 3 times and call them the following (they can all inherit from the standard template):
  • Common - This will have fields common across other item templates (such as title, metadata and navigation settings).
  • ContentPage - This is the generic content page
  • Destination - This is the travel destination
Your content tree to the left will now look like the following:

Now the field structure for the templates will be defined, enter the following details into the corresponding template (to keep things simple for right now, only the text and check box types are being used, however list types are ideal for fields like country).
  • Common

  • ContentPage

  • Destination
Click on each template and from the top Sitecore administration menu click Options > Standard values. This creates the standard values configuration for each template where we can set the default field settings, layouts and sublayouts. The folder structure should now look like the following:

On the Common __Standard Values file, set the Title field to "$name", this will default that title field to the name of the Sitecore item. The reason we use this field is because the title may want to be output to the page with special characters (apostrophe for example), and Sitecore does not allow these in item names. On the Common standard values file, tick the TopMenu and SideMenu check boxes.

We also need to assign the Common template as a base template to ContentPage and Destination. Select each item and from the top menu Options and then Base templates (Template). Now add the Common template and click Next to save the changes.


To give a nice user experience, we will also assign some icons to the ContentPage and Destination templates. This is done by selecting the templates, then from the top menu selecting Configure > Icon.
On both the ContentPage and Destination templates standard values we are going to set the insert options. This is what allows content authors to right click an item of this template type and have the templates appear there as insert-able right away. To set the insert options click on the standard values for ContentPage and Destination and from the Sitecore menu select Configure > Insert Options (Assign) and select both ContentPage and Destination Templates.

This will mean that whenever a user right clicks and selects insert on any item of template type ContentPage or Destination they will be able to insert another ContentPage or Destination without having to manually find the template in the tree.

A Sitecore package of the templates created, can be downloaded here. To install please see Using the package designer to sync Sitecore content between environments.

Next step

Now that the templates have been defined, we can move onto Part 3: Item Creation. Which involves creating the items in the content tree based on these template types. 

Tutorial: Creating a Sitecore 8 Website Part 1 - Introduction

Introduction

Sitecore is arguably the most powerful CMS available on the market today. The amount of features available out of the box allow it to be used to create sophisticated web sites that not only deliver simple content but learn about users and deliver the right content at the right time (and so much more). For a new user Sitecore can seem confusing at first (mainly due to the high level of customization available), the aim of this tutorial series is to begin at the basics and get a simple website working in Sitecore 8.

At the end of this series you will have a Sitecore 8 web site with the following features:
  • Custom layout, sublayouts and templates
  • Content pages/custom objects (displayed as pages) with a hierarchical structure
  • Navigation (with opt-out at the item level)

Initial steps

  1. The first step is to install a clean version of Sitecore 8. This will require the Sitecore installation file, a Sitecore license and database (SQL Server or Oracle). 
  2. The second step is to create a visual studio solution to use for this website. You can follow the instruction on my previous post: Sitecore setting up a visual studio solution or download a zip of the solution here.

The website

To keep it simple this tutorial will be creating a web site for a simple travel agency. It will include generic content pages with information about the company and the services they offer (about, contact etc.), along with a custom destination item which uses a custom template/layout in Sitecore to showcase the various destinations which the agency offers travel to.

Tutorial contents