Getting Started with EPiServer 4

Transcription

1 White Paper Getting Started with EPiServer 4 System requirements This is a guide for getting started with development using EPiServer 4 and it is assumed that you as a developer have access to the following: a Microsoft 32-bit operating system (if a local copy of EPiServer is to be installed on the workstation, Windows 2000 or Windows XP Professional is required).net Framework Visual Studio.NET If EPiServer is also to be installed, the following is required as a minimum: Internet Information Server 5.0 SQL Server 7.0 If the EPiServer security system is to be integrated with ActiveDirectory or NDS, the Windows 2000 or Windows XP Professional operating system is required. ElektroPost Stockholm AB Finlandsgatan 38 SE KISTA SWEDEN Phone Fax info@ep.se

2 Installation of EPiServer 4.0 The installation program can be obtained from Below you can find a description of the installation step by step. Start the file EPiServerInstaller.exe. The installation program starts running and the installation dialogue box appears. You should now enter the settings you want for your installation under the various slides in a wizard. Begin with the start slide and choose Next to begin the installation. First you should enter the licence information for the EPiServer version you intend installing. All licences are available for partners to order via 1. In the Licensed to company field, enter the company name which is specified when ordering the licence. 2. In the Licensed to person field, enter the person s name which is specified when ordering the licence. 3. In the License key field, enter the licence code which has been sent via after the licence has been ordered. 4. Select Next. Rev (16

3 5. In the Install version field select the version you intend installing. The latest version appears at the top of the list. 6. Select Next. Under the next slide you can specify how you want to set up your website in Internet Information Server. 7. In the Select IIS instance field choose whether you want to install the website on an existing website in Internet Information Server or create a new one. If you choose a new website, the dialogue box for Create new site is shown. 8. In the Site name field enter the name of your website. This is the name which will appear later in the name list in the web browser. The value can be changed later from Admin mode. 9. In the URL field, specify the address you want to use for the website. 10. In the Directory field select the directory you intend installing your website in. 11. Click on Create to create the website in Internet Information Server. 12. In the Virtual directory field choose whether you want to link the website to a virtual directory in IIS. If you intend installing the website under the website root directory, leave this field blank, which is recommended. Rev (16

4 13. Select Next. On next slide you should specify the database you want to link your website to. 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. You can read the Readme file supplied with the installation program to find out how to install your database. 14. In the Server field, specify the path to the machine where the database you intend using is installed. If the database is local, i.e. on the same machine you intend installing EPiServer on, enter (local). 15. In the Database field, enter the name of the database you intend using. 16. In the Username field, enter the username which has owner rights to the database specified above. 17. In the Password field, enter the password associated with the user specified above. 18. Select Next. Rev (16

5 On the next slide, enter an administrator account, which you can use later for logging onto the website for the first time. You can simply delete this account later, if you want. 19. In the Username field, enter the username you want to use to be able to log onto the website for the first time. 20. In the Password field, enter the password you want to associate with the user specified above. 21. Select Next. Start the installation procedure by clicking on Install. Rev (16

6 When the installation procedure is complete a directory has been created in the installation directory. This contains files which have been downloaded to allow the tool to be installed. It also contains a text file, which describes the actual installation procedure. This file can be sent to support if any error has occurred during the installation procedure, which you need help with. If there were no problems during the installation procedure you should delete the file from the computer as it contains information which may be too sensitive to leave lying around for unauthorised persons to look at. 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. Rev (16

7 Generate demo licence If the installation is used for testing and evaluation purposes, a demo license 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 2000 and write: 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 : Fig 7, The result of an ipconfig /all The Mac address is found under Physical Address and is entered when generating the license. Rev (16

8 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 on-line 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 file named EPiServerSample.csproj.webinfo.It is located in the directory C:\Inetpub\EPiServerNET\ unless you specified another location during installation. <VisualStudioUNCWeb> <Web URLPath = " /> </VisualStudioUNCWeb> Fig 8, EPiServerSample.csproj.webinfo on installation Change the content to match it to the configuration on your workstation. Then double-click on the file EPiServerSample.cspro 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. Fig 9, Show All Files in Visual Studio.NET Rev (16

9 The directories that appears as transparent contain the files which form the kernel of EPiServer. Altering these files could affect future upgrades of the product. Directory References 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. Admin Bin Edit Images Lang Styles Templates Upload ASP.NET files for the administrator interface in EPiServer. If any files in this directory are altered, the upgrade program will over-write 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 file episerver.dll. All new functionality stored in the web project will automatically be compiled into the EPiServerSample.dll file ASP.NET files for the editor interface in EPiServer. If any files in this directory are altered, the upgrade program will skip these files 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 website. All templates for the website are saved here. This is the directory where you normally make alterations to build up a website based on EPiServer. When files are uploaded as content for EPiServer, they are usually kept under this directory. Table 1, Directories in EPiServer 4 Rev (16

10 Compilation As ASP.NET is a compiler, 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. Rev (16

11 Documentation (SDK) If you are planning to develop solutions based on EPiServer, an SDK is also distributed along with a help file which describes the object model, a guide to template creation for EPiServer and files to add intellisense to Visual Studio.NET. You can download the documentation files from File names PropertyNumber.cs FilterCount.cs FilterEventArgs.cs PageList.cs Creating templates in EPiServer_410.pdf ChangesXToX.htm EPiServer.xsd EPiServer4.chm Readme.htm Worklog.txt Editor s manual Administrator s manual Explanation Sample code showing how a property is saved in EPiServer. Sample filter in EpiServer limiting the number of pages shown. The source code for the argument class which is called in a filter event. Example of how a page listing functions in EPiServer 4. A document showing how to build templates in accordance with the recommendations issued by ElektroPost. Lists of amendments between different versions of EPiServer 4. File to implement intellisense in Visual Studio.NET. Help file in which the whole of the API is specified and which should be used as a reference when developing websites. Information about the SDK. Amendments between different versions of EPiServer. The manual that describes all the standard functions in edit mode The manual that descirbes all the standard functions in admin mode. Rev (16

12 Page Types, Templates and Properties Dynamiska egenskaper Sidtyp Sidtyp Sidtyp Egenskaper Sidtyp Egenskaper Egenskaper Egenskaper Sidmall A page on a website is represented by two parts in EPiServer: firstly a page type with associated properties which describes 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 website. EPiServer also uses the concept of dynamic properties, which are global properties and usually span across several pages, either across the whole website or a branch of the hierarchical structure. A Simple Example A simple template would be to add a property which allows the EPiServer editor to save a URL on a page in EPiServer. The page template which 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. Rev (16

13 2. Add a property to the page type. 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> Rev (16

14 Then enter the editor mode and do the following: 1. Create a page and add a link in the property. The completed page is shown in the image further down. Rev (16

15 Tips and Tricks When you begin developing using EPiServer 4, a number of errors can arise, which in many cases are due to.net. The most common errors and solutions to them are listed below. machine.config If you make amendments to the file web.config and in any way violate the rules of XML, e.g. forgetting to compete a marker,.net automatically uses the standard file machine.config, which is saved in the.net directory under the Windows directory. If you work on an EPiServer installed on another physical server, you may also get an error message which is not particularly detailed, which makes trouble-shooting harder. Fixing HTML If you switch to the design 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, you have to install the file EPiServer.xsd in the directory for Visual Studio.NET ( C:\Program Files\Microsoft Visual Studio.NET\Common7\Packages\schemas\xml). In order to make it 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=" Rev (16

16 Runat= server When you add a web control to an ASP.NET page, you have to add runat= server along with the marker for the control which 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 Website Ceases to Function when a Compiling Error Occurs As ASP.NET is basically a compiling language, the whole website ceases to function if there is a compiling error, unlike traditional ASP which is an interpreter and the error message only arises when the faulty code is executed. Ctrl+F5 If changes to the website do not appear at once, this might be due to caching in the client. Press Ctrl+F5 when in the web browser instead of pressing the Update button. Rev (16