Getting Started with EPiServer 4

Transcription

1 Getting Started with EPiServer 4 Abstract This white paper includes information on how to get started developing EPiServer 4. The document includes, among other things, high-level installation instructions, a brief description of page types and properties, and common troubleshooting problems. Product version: 4.41 Document version: 1.0

2 2 Getting Started with EPiServer 4 Table of Contents SYSTEM REQUIREMENTS 3 Supported Operating Systems 3 Database Requirements 3 Software Requirements 3 Hard Disk Requirements 3 INSTALLATION OF EPISERVER 4 4 GENERATE DEMO LICENCE 7 MAC Address for Installation 7 VISUAL STUDIO.NET 8 Open the Project in Visual Studio.NET 8 Directories and References 8 Compilation 9 DOCUMENTATION (SDK) 9 PAGE TYPES, TEMPLATES AND PROPERTIES 11 A Simple Example 11 TROUBLESHOOTING 12 web.config 12 Fixing HTML 13 IntelliSense 13 Runat= server 13 Aspnet_regiis 13 The Web Site Ceases to Function when a Compiling Error Occurs 13 CTRL+F5 13 The contents of this document are protected by copyright. Changes to the content or partial copying of the content may not be carried out without permission from ElektroPost Stockholm AB. The document may be freely distributed in its entirety, either digitally or in printed format, to all EPiServer users. EPiServer is a registered trademark of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks for their respective owners.

3 System Requirements 3 System Requirements EPiServer 4 has the following system requirements. Supported Operating Systems Any of the following is required: Microsoft Windows 2000 Server with Service Pack 1 or later. This must not be installed as Active Directory root. Microsoft Windows Server This must not be installed as Active Directory root. Microsoft Windows XP Professional can be used for demonstration and development purposes. Database Requirements Any of the following is required: Microsoft SQL Server 2000 Oracle Database Server 9i Oracle Database Server 10g EPiServer 4 also supports Microsoft SQL Server 7.0, although Microsoft SQL Server 2000 is recommended. Software Requirements Internet Information Services (IIS) Server 5.0 must be installed as part of the Windows 2000 Server installation. Internet Information Services (IIS) Server 6.0 must be installed as part of the Windows Server 2003 installation. Microsoft Internet Explorer 6.0 or later is required for editors and administrators. Microsoft Office 2003 or Microsoft Office XP is required to be able to publish to EPiServer from Microsoft Office. Any of the following is also required: Microsoft.NET Framework 1.1 Redistributable Microsoft.NET Framework 1.1 SDK Microsoft Visual Studio.NET This is recommended for development purposes. Note:.NET Framework 1.1 Service Pack 1 is also required to improve security. Hard Disk Requirements At least 50MB free space on an NTFS-formatted partition.

4 4 Getting Started with EPiServer 4 Installation of EPiServer 4 The EPiServer installation program can be found at 1. Open EPiServerInstaller.exe. The installation program starts and the installation dialog box appears. 2. Select the type of installation you want to perform. Select Next. 3. Browse to your licence file, or follow the link if you want to create a time-limited demo licence. 4. Select Next. 5. Click the version you want to install in the Install version list. The latest version appears at the top of the list. Select Next. 6. In the following dialog box, specify how you want to set up your Web site in Internet Information Server (IIS). In the Select IIS instance list, choose whether you want to install EPiServer on an existing Web site in Internet Information Server, or create a new one.

5 Installation of EPiServer If you choose a new Web site, the Create new site dialog box is displayed. Type the name of your Web site in the Site name box. This name will appear later in the name list in the Web browser. The value can be changed later from Admin mode. Type the address you want to use for the Web site in the Url box. Type the directory in which you want to install your Web site in the Directory box. Click Create to create the Web site in Internet Information Server, and you will be returned to the Setup web site dialog box. 8. In the Virtual directory list, click a virtual directory in IIS if you want to link the Web site to a virtual directory. If you want to install the Web site under the root directory, leave this list blank. This is recommended. Select Next. 9. Specify the database that you want to link your Web site to in the Database setup dialog box. The database must be installed and configured before you start installing EPiServer. Make sure that the user specified below has owner rights to the database. Database installation instructions can be found in the Readme file supplied with the installation program.

6 6 Getting Started with EPiServer Type the path to the machine that the database you intend using is installed on in the Server box. If the database is local, i.e. on the same machine you intend installing EPiServer, type (local). Select the name of the database you intend using from the Database list. Select the user name that has owner rights to the database specified above in the Username list. In the Password box, type the password associated with the user specified above. Select Next. 11. In the next dialog box, you create an administration account, which you can later use for logging on to the Web site for the first time. You can simply delete this account later, if you want. 12. Type the user name you want to use to log on to the Web site for the first time in the Username box. Type the password you want to associate with the user specified above in the Password field. Select Next. 13. Start the installation procedure by clicking Install. When the installation procedure is complete, a directory has been created under Program Files\EPiServer4 named Download. This directory contains files that have been downloaded to allow the tool to be installed. It also contains a text file, upgrade.log, which describes the installation procedure. This file can be sent to Support if an error that you require help with has occurred during the installation or upgrade procedure. Important! If there were no problems during the installation procedure, delete the file Program Files\EPiServer4\Upgrade.log from the computer for security reasons. This file will contain sensitive information, such as information for connecting to the database.

7 Generate Demo Licence 7 Tip! Always read the Readme file which comes with the installation files. This provides information about further steps which may need to be taken to ensure installation is complete. Generate Demo Licence If the installation is used for testing and evaluation purposes, a demo licence can be created using the link in the installation program. Complete the Web form that appears. You can choose whether to bind the system to an IP address or to the MAC address of the network adapter. MAC Address for Installation If you are using dynamic allocation of IP addresses (DHCP), you might want to register EPiServer to the MAC address instead of the IP address. The MAC address is a unique identifier for the network adapter and a common standard. To find the MAC address, open a command prompt in Windows and type: ipconfig /all. Ethernet adapter Local Area Connection: Connection-specific DNS Suffix. : Description : Network adapter Physical Address : C-4F-4F-50 Dhcp Enabled : Yes IP Address : Subnet Mask : Default Gateway : The MAC address is found under Physical Address and is entered when generating the licence.

8 8 Getting Started with EPiServer 4 Visual Studio.NET Open the Project in Visual Studio.NET It is possible to build solutions based on EPiServer using any text editor, e.g. Notepad. In this guide, we have chosen to use Visual Studio.NET, as it provides advantages such as IntelliSense and online documentation. If you prefer to work with another tool, refer to the documentation for.net Framework and the tool concerned. The standard distribution of EPiServer 4 contains a sample project for Visual Studio.NET, which in most cases functions as a starting point for further development of Web solutions. To open the project, open the EPiServerSample.csproj.webinfo file. It is located in the C:\Inetpub\EPiServerNET\ directory, unless you specified another location during installation. <VisualStudioUNCWeb> <Web URLPath = " /> </VisualStudioUNCWeb> Change the content to match the configuration on your workstation. Double-click EPiServerSample.csproj in the same directory, and Visual Studio.NET will open the EPiServer project. Directories and References Solution Explorer in Visual Studio contains a representation of the structure of EPiServer. Start by clicking Select All Files in Solution Explorer to show all the files and references in the EPiServer project. The directories that appear transparent contain the files that form the kernel of EPiServer. Altering these files could affect future upgrades of the product.

9 Documentation (SDK) 9 Directory References admin bin edit images lang styles templates upload Description This directory stores references to the functionality desired. It is also possible to add references to Web Services here. References to the basic classes in EPiServer are stored here. ASP.NET files for the administrator interface (Admin mode) in EPiServer. If any files in this directory are altered, the upgrade program will replace these files and any functionality developed in-house in the administrator interface will be lost. The compiled files for EPiServer are stored in this directory, and the entire class library is stored in the episerver.dll file. All new functionality stored in the Web project will automatically be compiled into the EPiServerSample.dll file. ASP.NET files for the editor interface (Edit mode) in EPiServer. If any files in this directory are altered, they will be skipped by the upgrade program and new functionality in the administrator interface will be missed. Contains images for the system. Contains language files which are stored as XML. The files stored here must not be amended. If you want to make changes, you must save new XML files whose contents will apply instead of the original files. Language files are read in alphabetical order, so if you want to save new language data, you need to name the file so that it is placed before those supplied with the installation. Contains style templates (css) for the Web site. All templates for the Web site are saved here. This is the directory where you normally make alterations to build up a Web site based on EPiServer. When files are uploaded as content for EPiServer, they are usually kept under this directory. Compilation As ASP.NET is a compiled environment, it is important to remember to recompile the project following any changes to code-behind files. This is necessary for the system to function and for changes to take effect. Changes to the ASPX pages, however, do not call for a recompile. Documentation (SDK) If you are planning to develop solutions based on EPiServer, an SDK is also distributed along with a help file. This describes the object model, includes a guide to template creation for EPiServer and files to add intellisense to Visual Studio.NET. You can download the documentation files from

10 10 Getting Started with EPiServer 4 File Names ApprovalTask.ascx ApprovalTask.ascx.cs EPiServer4SDK.chm EPiServer.xsd FilterCount.cs FilterEventArgs.cs FormsPostings.ascx FormPostings.ascx.cs PageList.cs PageTree.cs PropertyNumber.cs PropertyWeekday.cs readme.htm Worklog_EPiServerNET.htm Worklog_EPiServerSample.htm Explanation User control for workflow. Code-behind file for ApprovalTask.ascx. Online Help file, in which the whole of the API is specified and which should be used as a reference when developing Web sites. File to implement IntelliSense in Visual Studio.NET. Sample filter in EPiServer limiting the number of pages shown. Source code for the argument class, which is called in a filter event. User control to get a list of form postings. Code-behind file for FormsPostings.ascx. Example of how page listing functions in EPiServer 4. Sample code showing controls for page trees. Sample code showing how a property is saved in EPiServer. Sample code showing how weekdays are displayed in Edit mode. Information about the SDK. Information about changes and bug fixes in EPiServer. Information about changes and bug fixes in the EPiServer sample site.

11 Page Types, Templates and Properties 11 Page Types, Templates and Properties Dynamic properties Page type Page type Page type Properties Page type Properties Properties Properties Template A page on a Web site is represented by two parts in EPiServer. Firstly a page type with associated properties that describe the contents of the page, and secondly by a page size, which presents the contents of the page type in accordance with the graphical profile set up for the Web site. EPiServer also uses the concept of dynamic properties, which are global properties and usually span across several pages, either across the whole Web site or a branch of the hierarchical structure. A Simple Example A simple template would be to add a property that allows the EPiServer editor to save a URL on a page in EPiServer. The page template that forms the base of the page will then be able to show the contents of another URL by using the contents of the property. Follow the steps below: 1. Create a page type. 2. Add a property to the page type.

12 12 Getting Started with EPiServer 4 3. Create a simple template with the following code. <%@ Register TagPrefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %> <%@ Page language="c#" AutoEventWireup="false" Inherits="development.StandardPage" %> <% DataBind(); %> <html> <head> </head> <body> <form runat="server" id="_default"> <%#CurrentPage.Property["ProductURL"].Value%><BR> <IFRAME src="<%#currentpage.property["producturl"].value%>"> </form> </body> </html> 4. Go to Edit mode, create a page, and add a link in the property. Troubleshooting When you begin developing using EPiServer 4, a number of errors may occur, which in many cases are due to.net. The most common errors and solutions to them are listed below. web.config If you make amendments to the web.config file and in any way violate the rules of XML, e.g. forget to properly terminate a tag, your web application will not start. You will usually see a desciptive error message pinpointing the source of the problem. If you work on an EPiServer installed on another physical server, you may also receive an error message, which is not particularly detailed. This makes troubleshooting more difficult.

13 Troubleshooting 13 Fixing HTML If you switch to the Designer tab in Visual Studio.NET, the system may make changes to the HTML code you produced on your ASP.NET page. A tip is to deactivate that functionality in Visual Studio.NET under Tools > Options > Text Editor > HTML/XML > Format. IntelliSense If you want to add EPiServer-specific IntelliSense in the HTML tab, install the EPiServer.xsd file in the directory for Visual Studio.NET (C:\Program Files\Microsoft Visual Studio.NET\Common7\Packages\schemas\xml). In order for it to function in the HTML layer, a reference to an XML namespace in the body marker of the ASP.NET page is required. <body XmlNs:EPiServer=" Runat= server When you add a Web control to an ASP.NET page, you must add runat= server along with the marker for the control that is to be executed by the server before it is distributed to the client. Aspnet_regiis When installing EPiServer, it is often required that the script library for.net is registered. This is done by running the command aspnet_regiis in a command prompt with the flag -c. The Web Site Ceases to Function when a Compiling Error Occurs As ASP.NET is basically a compiling language, the whole Web site ceases to function if there is a compilation error. This is unlike traditional ASP, which is an interpreter, where the error message only arises when the faulty code is executed. CTRL+F5 If changes to the Web site do not appear at once, this might be due to caching in the client. Press CTRL+F5 from the Web browser instead of clicking Update.