So you’ve finished your first installation of Umbraco, perhaps to your local PC to try it out. Now you're wondering, “What Next?".
This guide will help you get started with setting up a website in Umbraco. This document is based on my experience with learning and using the free version of Umbraco 4.0.3.
What is Umbraco?
5-minute Video Introduction: http://umbraco.org/documentation/videos/getting-started/what-is-umbraco
There are plenty of documents about installing Umbraco, so I won’t cover the details here.
If you are trying out Umbraco for the first time, you may want to install it to your local PC.
To find more documents on installing Umbraco, see the home page of this wiki. There are also PDF files covering installation on the Umbraco download page itself http://umbraco.codeplex.com/releases/
As of this writing, I haven't seen one install guide that contains everything I would want in such a document. I recommend you look at several to get all the information you can.
You may find my own install notes helpful - see the last section in this document.
Setting up an Umbraco Web Site
The Admin Page
After you have successfully installed Umbraco, you will probably be looking at the default admin page. (I don’t know the official name for this page, so I will call it the “admin page.”)
If you are not on the admin page, point your browser to http://<YourSite>/umbraco/umbraco.aspx. On my local installation, I use http://localhost:81/umbraco/umbraco.aspx (I set up Umbraco to use port 81). If you are not logged in, this URL will first redirect you to the login page.
The Umbraco admin page has three main panes: Content (top left), Sections (bottom left), and the main panel (large panel on the right).
The Content panel on a default empty install will show a only Content folder with the Recycle Bin folder under it.
The Runway Demo Site
If you did not choose install Runway as part of your Umbraco install, I recommend you install it when learning Umbraco. Runway is a bare bones demo website that will show you an example of how to set things up using best practices.
If you want an even more fleshed out site, you can install the Creative Website Starter (CWS) at http://our.umbraco.org/projects/creative-website-starter-(cws). The CWS package contains a detailed document on how to install and set up CWS.
To install Runway, go here: Umbraco admin page > Sections panel > Developer > Packages > Install Runway link > Install Runway button > click Yes > check Accept License > Install Package button. Do not close the page until the install is complete.
The Install Runway link under the projects folder appears to be hard-coded into Umbraco, so it is always available to install if you want.
It is also easy to uninstall Runway if you ever want to:
To uninstall Runway: Admin page > Sections panel > Developer > Packages > Installed Packages > Runway link > Uninstall Package button > Confirm Uninstall button.
The core concepts about an Umbraco website are Document Types, Templates, and macros.
Before you can create a web page in Umbraco, you must first create a Document Type. Then when you do create the web page, you will specify which Document Type it is based on.
The Document Type defines the data that a web page will use. It also defines the interface you will see when creating the web page. A Document Type specifies which kind of data, fields (web controls), and content can go on the web page. Document Type does not have anything to do with web page presentation or layout - that is handled in Templates, which are described in a different section below.
To go to your Document Types:
Go to Umbraco admin page > Sections panel > Settings > Document Types folder > expand the folder. If you installed Runway, you will see two document types already created, Runway Homepage and Runway Textpage.
To create a Document Type:
- Go to Umbraco admin page > Sections panel > Settings.
- Right-click on the Document Types folder and enter a name such as “test.”
To set up a Document Type:
Access the Document Type by clicking on it in the Settings panel (go to admin page > Sections panel > Settings). In the main panel (on the right in your browser) you will see the tabs where you define that type.
- The Info tab sets such things as the Document Type name and which templates it can use.
- The Structure tab sets which child Document Types can be created under this one.
- The Generic Properties tab is where you specify what kind of content can go on web pages that are based on this Document Type. These Properties determine which fields and controls can appear on your web page. If you do not set any Properties, web pages using this Document Type will be blank. For example, if you want even just simple text on a web page, you must first add a new Property for it. To do this, in the Type drop down list on the Property page, set either Textbox Multiple (multi-line textbox) or Rich Text Box.
- The Tabs tab is where you specify the tabs that will show up when you create a web page based on this Document Type. After you create a tab, you can assign Properties to it in the Properties tab.
To learn more, watch the free video about Document Types: http://umbraco.tv/documentation/videos/for-site-builders/foundation/document-types
As described above, web pages in Umbraco are based on Document Types. Before you can create a web page, you must have a Document Type for the type of page you want.
To see to your web pages: Admin page > Sections panel > Content. Web pages will appear as nodes in the Content panel.
To create a web page:
- If you do not yet have any web pages, create one by right-clicking on Content and choosing Create.
- Enter a name for the page and click Create. The page will show up under the Content folder (refresh your browser page if you need to).
- Click on your new page. In the right panel, you will see the tabs that allow you to set the content that will appear on the page.
- Enter the content for the page, by entering content in the tabs in the main panel. If you want your page to contain more types of content than are allowed here, you must edit the Document Template which is used by the page. To see which Document Type the page uses, go to the Properties tab for the web page.
- When you’re done, click the “save and publish” button in the tool bar.
- To see how your page looks in Umbraco, go to the Properties tab for that page, then click the "Link to Document" URL at the bottom of the tab.
Templates define the layout and presentation of a web page. Templates are where you define the design and layout, which CSS to use for the page, etc.
When you create a Document Type, by default a Template is also created for that Document Type.
Templates are actually .NET Master Pages. If you don’t know how Master Pages are used in a .NET website, you should learn about them. See http://www.asp.net/(S(sf10gzjodvrpce55el2p5cnk))/learn/master-pages/
Templates can be based on other templates.
To go to your Templates: Admin page > Sections panel > Settings > Templates folder.
To learn more, watch the free video about Templates: http://umbraco.tv/documentation/videos/for-site-builders/foundation/templates
Macros are used to get data from Umbraco and display it. For example, site maps, navigation, and news lists. This can be done using XSLT. Umbraco includes several pre-built XSLT macros, and you can also create your own.
Macros can also be used to wrap .NET user controls or custom controls, to include those in your web page.
For more information see the video http://umbraco.org/documentation/videos/for-site-builders/foundation/what-are-macros
How -To Videos
There are free videos at http://umbraco.tv/
To get started watch the following videos, which are part of the free "Foundation" series:
- Document Types: http://umbraco.tv/documentation/videos/for-site-builders/foundation/document-types
- Templates: http://umbraco.tv/documentation/videos/for-site-builders/foundation/templates
Outside the Foundation series, it appears most of the other Umbraco TV videos are not free. But a one-month subscription is very reasonable (about US $25). You will pay using PayPal.
I have found the forum very helpful. I usually get a response within an hour or two.
Other Useful Guides
A Complete Newbie's Guide To Umbraco
Wikipedia article for Umbraco
Notes about my first installation
My first local install
I did my first ever Umbraco install as a local installation on Windows Vista PC. I installed using the Microsoft Web App Gallery, http://www.microsoft.com/web/gallery/Umbraco%20CMS.aspx
The install process completed successfully, but Umbraco did not work until I went through the following document, http://umbraco.codeplex.com/releases/view/33743#DownloadId=95707
I went through the steps in this document, skipped steps I thought I could, and got it working. My main problem seemed to be setting the correct permissions on the Umbraco folders.
My first real website install, on a shared-hosted site
My company has several small shared-hosted websites. I am installing Umbraco to use for one of them.
I found the following document helpful: http://our.umbraco.org/wiki/install-and-setup/installing-umbraco-4-on-reliablesitenet-(or-similar-hosts)
I FTP'ed the Umbraco install archive (Umbraco 4.0.3) to my site's root directory. The Umbraco install files are found at http://umbraco.codeplex.com/releases/
I had to ask my hosting company to unzip the file for me.
I ran the Umbraco install by going to <mysiteURL>/default.aspx. I got to page 2 of the install, where you enter in your database connection information. Upon submit I got an error that Umbraco could not write to my web.config. So I asked my hosting company to fix the permissions.
Then I got through the rest of the install pages. However, at the very end I got the following ASP.NET error:
Validation of viewstate MAC failed. If this application is hosted by a Web Farm or cluster, ensure that <machineKey> configuration specifies the same validationKey and validation algorithm. AutoGenerate cannot be used in a cluster.
My host told me to fix this by doing the following, which worked:
Intermittent ASP.NET sessions: The cause of this intermittency is the recycling of the application pool where your site lives.
The best way of handling this issue is configuring your application to use "Out of Process" sessions, which is very easily accomplished by configuring the web.config in the following way:
<sessionState mode="StateServer" cookieless="false" timeout="20" stateConnectionString="tcpip=127.0.0.1:42424" />
This didn't work with my own website. It solved the problem by adding <mahcineKey/> within <system.web/>:
<machineKey validationKey="a-generated-key" decryptionKey="a-generated-key" validation="SHA1" decryption="AES" />
The key can be generated for you at the following url: