Beginning Sitecore Development, Part 3 - Adding support for Twitter Bootstrap, Sublayouts and User Controls

Overview

This is part 3 of a series of posts on Beginning Sitecore Development in Sitecore 8. Knowledge of previous posts is assumed, so if you have trouble with any of the material here, you can refer back to the previous post at Beginning Sitecore Development, Part 2 - Building a Visual Studio Project.

Goals

In this post, we're going to extend our existing solution to add styling with Twitter Bootstrap 3.32. In addition, we'll add a sublayout so our editors will have flexibility in how they layout content. Finally, we'll add some custom controls to present content in a specific format to our users.

Adding support for Bootstrap

Our existing Visual Studio project has some structure already, but it could use a little more organization to support the new additions we plan to make. 

Here's the current layout of the solution.

Let's add a vendor subfolder to assets/MySitecore so we don't have to split up any 3rd party frameworks that might have their own asset folders.

Now download Bootstrap and unzip it to the assets/Mysitecore/vendor folder. Then add the Bootstrap files to your solution by setting your project to show all files and then including the folder. Your solution should now look like this:

When you are done, your solution should look like this:

With the Bootstrap files now available, let's update our HomeLayout to reference the appropriate styles and scripts, using relative paths. Let's also make a quick update to the content of our page to verify if Bootstrap is working correctly.

With all the proper hooks in place, it's time to test it out. Build and Publish in Visual Studio. Then go into Sitecore and preview your page again. You should see it is now leveraging Bootstrap.

Creating Sublayouts for Different Page Configurations

Now that we've got Bootstrap support, it'd be really great if we could offer several different configurations of the page. Let's create some sublayouts that support different column configurations.

Let's start by updating our layout page. We'll remove all of the Bootstrap test content we created and instead add Placeholders that represent the areas of the layout where a content editor can add sublayouts, controls, or renderings. We'll also add a hook for a new style sheet.

Here's our updated HomeLayout.aspx.

Let's go ahead and create our new stylesheet we just referenced. Create mysitecore.css under the assets/MySitecore/styles folder. Here we've set it up to contain some base styles we'll use with our sublayouts.

We'll now create a sublayout that provides for a two column configuration. Add a new control to the layouts/MySitecore/Sublayouts folder in Visual Studio named TwoColumn.ascx.

Our Visual Studio project should now look like this:

Open TwoColumn.ascx and add the Bootstrap styles to divide the page into two columns. Make sure to add Sitecore Placeholder controls so the content editors can organize content they add.

Go ahead and publish your solution.

Now we need to tell Sitecore about our new Sublayout. Find the /Layout/Sublayouts node in the content tree and then create a new Sublayout Folder named MySitecore. Create another Sublayout Folder inside of that one named Sublayouts.

Right click that folder and add a new Sublayout named TwoColumn and click Next

Place it in the appropriate location.

Select the file location that corresponds to our Visual Studio project. 

Note that we have the usual chicken-and-egg problem where Sitecore wants to provision a file that we want to publish with Visual Studio. If you did the step in Sitecore first, you'd be missing the new folder structure. However, if you did the step in Visual Studio first, the file will already be there and Sitecore will be unhappy. 

Just delete the file you already published at C:\inetpub\wwwroot\[Sitecore Instance]\Website\layouts\MySitecore\Sublayouts\TwoColumn.ascx, and click Create on the Sitecore wizard. This will create the Sitecore default version of the file. Then go back into Visual Studio and republish to get our customized version.

Creating a Custom Control

In order to test our Sublayout, we need something to put in it. We'll go ahead and create a very basic user control for this purpose.

Start by adding a new Web Forms User Control to the layouts/MySitecore/Controls folder in Visual Studio named CurrentTime.ascx.

Add a label to the user control that we can store the time in. Here's our file with the markup added.

Now add the code to store the current time in the label. Here's our code behind.

Go ahead and publish your solution.

Now we need to tell Sitecore about our new control. Find the /Layout/Sublayouts/MySitecore node in the content tree and then create a new Sublayout Folder named Controls. It should look like this now.

Right click that folder and add a new Sublayout named CurrentTime and click Next.

Place it in the appropriate location.

Select the file location that corresponds to our Visual Studio project. 

Yet again, we get our chicken and egg problem. Delete the C:\inetpub\wwwroot\[Sitecore Instance]\Website\layouts\MySitecore\Controls\CurrentTime.ascx file and click Create.

Your content tree should now look like this, with a CurrentTime control and a TwoColumn sublayout.

Republish your Visual Studio solution.

Testing the SubLayout and Control

Go to the content/My Home node that corresponds to our custom page. Click on the Presentation tab in the top menu, then the Details button.

Click edit under the Default device and then click on the Controls tab to the left.

Click the Add button. Navigate to the Sublayouts/MySitecore/Sublayouts folder and select the TwoColumn sublayout. For the Placeholder text box, enter "content", which corresponds to the key value of the Placeholder we added on HomeLayout.aspx. Click Select once your screen looks like this.

Now we will add the custom control we created.

Click the Add button. Navigate to the Sublayouts/MySitecore/Controls folder and select the CurrentTime control. For the Placeholder text box, enter "/content/leftcolumn", which corresponds to the key value of the Placeholder in the TwoColumn.ascx sublayout when it exists within the "content" Placeholder of the HomeLayout.aspx layout. Click Select when your screen looks like this.

Now click OK to close the Device Editor and OK to close the Layout Details.

Save your page, then click on Publish in the top menu, then Preview. If everything went well, your page should look like this.

Since this is a two column layout, let's add a control to the other column to make sure our sublayout is behaving as we'd expect. 

Go back to the Device Editor and add another CurrentTime control, but this time, add it to "/content/rightcolumn".

Save your page, then refresh the preview. Your page should now look like this.

Extending our Solution

Now that we have a working sublayout and a basic control, we can try something a little more advanced.

Although the sample page that comes with Sitecore includes an XSL rendering, it would be more beneficial to us if that were a user control. This would allow us to leverage the rich .NET libraries rather than working only with XSL.

To start, we're going to need some new fields on our page template. Browse to the Page Template at Templates/MySitecore/Page Templates/Home Page, which we created in Part 1 of this series.

On the Builder tab, add a new Section, Page Details. Now add a Banner field that is of type Image, and a Title field that is of type Single-Line Text.

Your Page Template should now look like this. Save your changes.

Browse to the My Home item in the content tree and set the Title field. You can leave the Banner field empty for now.

Next we'll tell Sitecore about our new control. We'll follow the same process we did for adding the CurrentTime control to the content tree. Remember to add your new control to the /Layout/Sublayouts/MySitecore/Controls node in the content tree.

Name the new control "Header", then set your location to Sublayouts/MySitecore/Controls and your file location to Website/layouts/MySitecore/Controls. Click Create.

Your content tree should look like this now:

Remember to delete the file that was created by Sitecore from the file system. It should be located at C:\inetpub\wwwroot\[Sitecore Instance]\Website\layouts\MySitecore\Controls\Header.ascx

Now we'll create a new control in Visual Studio in the /layouts/MySitecore/Controls folder and name it Header.ascx. Edit the file to look like this:

If you try to compile now, you'll get an error because you are using some Sitecore controls in your new ascx. Add a reference to Sitecore.Kernel.dll, which is located in the C:\inetpub\wwwroot\[Sitecore Instance]\Website\bin folder.

Build the solution and then Publish it.

Testing the Header Control

Now we have a header control, but we need to add it to our page so we can see the results.

Go to the content/My Home node that corresponds to our custom page. Click on the Presentation tab in the top menu, then the Details button.

Click edit under the Default device and then click on the Controls tab to the left.

Click the Add button. Navigate to the Sublayouts/MySitecore/Sublayouts folder and select the TwoColumn sublayout. For the Placeholder text box, enter "pageheader", which corresponds to the key value of the Placeholder we added on HomeLayout.aspx. Click Select once your screen looks like this.

Now click OK to close the Device Editor and OK to close the Layout Details.

Save your page, then click on Publish in the top menu, then Preview. If everything went well, your page should look like this.

As a final exercise for the reader, edit the My Home page and set the Banner property. You can select the banner that is included with the sample page or upload one of your own in the Media Library. After you publish you should see that the sc:Image control you put in Header.ascx will read the Banner property on My Home and display the corresponding image on the page.

Summary

In this post, we added support for Twitter Bootstrap as our UI framework. We then added a sublayout to allow flexibility in how content is presented to users. Finally, we added two new user controls that provide custom functionality.

Beginning Sitecore Development, Part 2 - Building a Visual Studio Project

Overview

This is part 2 of a series of posts on Beginning Sitecore Development in Sitecore 8. If you want a little background on how all of the moving parts work together to display a web page to a user, check out the the first post in the series, Beginning Sitecore Development, Part 1 - Dissecting the out of the box Sitecore Home page.

Please note that since this is begginners' series, it is a built in an incremental fashion. As such, while later posts may cover MVC or TDS, this post will be based on using ASP.NET Web Forms and uses Visual Studio publishing.

Goals

In this post, we're going to create a new layout. We will create all of the items needed in the Sitecore content tree, as well as the corresponding files that will be manged by Visual Studio and deployed to the file system.

Setting up the Visual Studio solution

The first step is to set up a base solution in Visual Studio that we will use to hold all of our Sitecore related files that are custom to us.

Open Visual Studio 2013 and select File > New Project. In the dialog box, set the target framework to 4.51, and select the ASP.NET Web Application template. Note that we are using 4.51 because we are building a solution for Sitecore 8. If you are using an earlier version of Sitecore, make sure you pick the appropriate target framework.

On the next screen, select the Empty template, but make sure to check the box to include references for Web Forms.

Once your project is created, you'll want to clean up the extra items we don't need. Remove the App_Data, Models and Global.asax items from the solution. In addition, copy the Web.config from your Sitecore instance over the one that Visual Studio created. The web.config should be located at C:\inetpub\wwwroot\[SitecoreInstance]\Website\web.config.

Now we need to create a folder structure to manage our files. Let's create an assets folder first. We'll use this to store any static files like styles sheets or images that aren't stored in Sitecore. 

As a rule of thumb, it's always a good idea to create a folder that matches the name of your site or solution under the root Sitecore folders. This helps organize files if you have multiple sites or projects you'd like to manage. In addition to the assets folder, create a layouts folder as well. 

Once you are done, your solution should look like this.

Now let's create a layout. Right click on the layouts\MySitecore\Layouts folder and add a new item. Select the Web Form template, give it an appropriate name, and click Add.

Here you can see what the file looks like after Visual Studio creates it. This would be fine in a standalone web forms application, but for Sitecore, we need to add just a little more to it.

Let's copy some of the entries we found in the Sample Layout that comes with Sitecore. If you recall, that file is located at C:\inetpub\wwwroot\[SitecoreInstance]\Website\layouts\Sample layout.aspx. The content we want to add is highlighted below.

We'll start by adding some page directives. We'll use a Register directive so we can leverage Sitecore controls. In addition, the OutputCache directive will instruct Sitecore how we want to cache our page.

We'll add a Sitecore control for tracking our user and then we can add the content we want to display. In this first pass, we won't add any placeholders. We want to focus on getting all of the plumbing in place between Sitecore and Visual Studio first. We can add functionality afterwards.

Here is the current state of our Visual Studio project. You can see that we have some basic organization, but just one file to deploy - HomeLayout.aspx.

In order to deploy our solution, we need to set up a Publishing Profile. Before you go through this, make sure you have copied the web.config from your Sitecore instance into Visual Studio. If you miss this step, you will wipe out your web.config!

Start by right-clicking your project and selecting Publish. You'll be shown a dialog prompting you to select a publishing target. Click on Custom.

A dialog box will prompt you to name your profile. As a general rule, you'll want your Profile name to match your solution and/or your Sitecore instance name. But use whatever you feel is appropriate. Click OK.

On the Connection screen, change the Publish method to File System and then set the Target location to your Sitecore instance. Make sure you are pointing at the Website folder. Click Next.

On the settings tab, set your Configuration to Debug for now. This will help you during development so you can attach a debugger to your website. Make sure all of the File Publish Options are unchecked and then click Next.

Your Publishing profile is now configured. Click Publish to push out the HomeLayout.aspx file, your web.config, and your project assembly.

Verify that your HomeLayout.aspx file has been deployed to the file system. It will be located at C:\inetpub\wwwroot\[SitecoreInstance]\Website\layouts\MySitecore\HomeLayout.aspx. Go ahead and delete the file for now. Don't worry, it will get updated the next time we publish.

Create the Layout in Sitecore

Now you have a layout that IIS can see, but you need to tell Sitecore about it. Open up the Content Editor and browse to the Layout\Layouts node. Click on the Layout Folder button or right-click on the Layouts node to insert a new Layout Folder.

Just like in Visual Studio, we want to create a folder to group all of our files together within each Sitecore node. Name the new Layout Folder the same as you did in Visual Studio. Click OK.

Now that we have a folder, click on it and then the Layout button or right-click on your folder and insert a new Layout. We want the name for the Layout to be the same in Sitecore and in Visual Studio, so let's name the new layout HomeLayout. Click Next.

Place the layout under our custom Layout Folder by selecting it and then clicking Next.

Now you need to set where the layout will be deployed to the file system. Expand the layouts folder and you should see the folders you created in Visual Studio earlier, assuming you have published. 

If you skipped the publishing step, when you expand the layouts folder, your custom folders will not be displayed. You can also create these folders manually on the file system if you skipped publishing, but you'll have to restart the layout wizard.

Now click Create.

If you ran a Visual Studio publish earlier, but did NOT delete the HomeLayout.aspx, you'll get a warning here. Go ahead and delete the file from the file system and click Create again. The wizard will complete and you'll see that Sitecore places a HomeLayout.aspx file there for you.

Here's the state of the content tree after adding our layout:

Now Sitecore knows about our HomeLayout, and so does Visual Studio, but we lost our version of HomeLayout.aspx when we were forced to delete it. Let's remedy that by running a Publish from Visual Studio again to make sure the correct files are known to IIS.

Creating the Page Template

Now that we have a layout, we need to create a page that uses that layout. We'll start by defining the page template.

In Content Editor, select the Templates node. Now right-click on the Templates node and select Template Folder.

We'll keep our convention of defining folders for our project and name the new Template Folder accordingly. Click OK.

Since we will be adding more data templates later, it's a good idea to organize this area of the content tree based on how the data templates are used. This keeps your folder from being filled with lots of unrelated types of templates.

With the MySitecore template folder selected, click the Template Folder button or right-click and insert a Template Folder. Name this one Page Templates. 

With the Page Templates folder selected, click the New Template button or right-click and insert a New Template. Select a friendly name that corresponds to your layout, but leave the base template at the default setting. Click Next.

Confirm the location for the template and then click Next.

The wizard should complete. Click Close.

Just to clean things up a bit, we'll also set an icon for our new Home Page template. Select the item in the content tree, then click on the Configure menu at the top. You'll see an Icon button in the ribbon. Click that.

Pick whatever Icon you'd like, then click the Save button in the ribbon.

Creating the Page

Now that we have a Page Template, we need to create a content item that uses that template. Right client the Content node and select Insert, Insert from template.

Select your new Page Template and give an appropriate Item Name, then click Insert.

Next we need to configure how this content item so it'll show on the website correctly. With your new page selected, click the Presentation tab in the top menu and then click Details.

Here you can see that no layout has been specified. Under the Default device, click Edit.

On the Layout tab, click the drop down and select our custom Page Layout. Click OK to close the Device Editor dialog.

Click OK to close the Layout Details dialog. Now click Save in the ribbon bar to save the changes we've made to the content item.

Now all of the pieces are wired up and it's time to see our page come to life. On the Publish tab, click the Preview button. 

A new window will open up and show our page.

Not very exciting so far, but now we have all of the pieces in place to start adding more feature-rich components to our site. 

Just to prove that our Visual Studio project ties into our Sitecore instance, go back to Visual Studio and make a small edit to the HomeLayout.aspx.

Publish those changes with Visual Studio and then refresh your Sitecore preview. You should see the changes have carried over.

Summary

In this post, we created a Visual Studio project that will serve as the framework for building a custom Sitecore project. We then created the corresponding items in the Sitecore content tree. Finally, we demonstrated that our Visual Studio project could be used to control the presentation of Sitecore items.