developer’s manual...• component art, componentart.web.ui.dll • javascript library prototype...

Developer’s Manual

2

Table of contentsIntroduction.............................................................3 Extension.......................................................................................3

Getting started........................................................3 System requirements.......................................................................3 Install manually with Extension installer......................................3 Components...............................................................3 Third party components.................................................3

Developer’s guide..................................................4 EPiServer vs. Extension................................................................4 Main API..........................................................................................5 The page - area - function relation.....................................4 Create an Extension template........................................................5 Create the base class........................................................5 DefinetheExtensionareas................................................6 RegisterthetemplateasanEtensionpagetype.............6 CreateanExtensionfunction........................................................6 Createasimplecontentfunction...................................6 Create a combination function.......................................7 Register content function................................................7 Create an Extension template page..............................................8 Working with global functions.......................................................8 Managing existing global functions...............................8 Working with dynamic content functions........................................8 Using dynamic content functions....................................8 Administrate Extension.................................................................9 Plug-in settings....................................................................9 Settings......................................................................9 Set rules................................................................................9 Extension specialized properties.................................................10 Extension web controls................................................................10 The sample project LoremIpsum...............................................10

Namespaces...........................................................11

Vocabulary..............................................................12

More information.................................................13 Wiki.................................................................................................13 Blog... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Support....................................................................................13

Developer’s Manual Extension 3.1 | © Dropit AB

3

System requirements• Extensionfiles• PuttheExtensionlicenseunder“/Dropit/License”• Updatetheweb.configwiththeconfigurationintheupdate.config.

Install manually with Extension Installer• Extensionfiles• PuttheExtensionlicenseunder“/Dropit/License”• Updatetheweb.configwiththeconfigurationintheupdate.config.

Components• Dropit.Extension.dll:Corecomponent,containstheAPIclasses.• Dropit.Extension.UI.dll:GUIcomponentcontainsallclassesforrendering and edit mode.• Dropit.Extension.Providers.dll:TheExtensionproviderforstoringthedata.Third party components• ComponentArt,ComponentArt.Web.UI.dll• JavaScriptlibraryPrototype• JavaScriptlibraryRico

Getting Started

IntroductionExtension 3 is a module developed for EPiServer CMS 5. This manual is intended for system and template developers with knowledge in ASP.NET 2.0 and EPiServer developmentandwillonlycoverfunctionalityspecificforExtension.Forinstructionson EPiServer standard functionality we recommend you to read EPiServers Tech Notes available at www.episerver.com.

ExtensionExtensionallowspeoplewithoutprogrammingskillstocreateandchangepagetypes,introducinganewwayof workingwithEPiServer.Untilnow,editorshadtoturntotheirsystemdevelopertoadd,removeochchangethefunctionsatthewebsite.Extensionwillinsteadlisttheminafunctionlibrary,allowingyoutodraganddropthem directly at the website. An intelligent permission system controls where you are allowed to drop them to maintain the structure and layout of the page. Everything is done in EPiServers user interface already familiar to you.


4

Developer´s GuideEPiServer vs. ExtensionExtension 3 does not replace EPiServer. It gives the user the opportunity to create thecontentwithmoreflexibilitythantraditionalEPiServer.Letusmakeasimplecomparison.InEPiServer,youworkwiththetraditionalasp.netwaytocreateawebpagebyusingatemplatepage(.aspx)andunits(usercontrol,.ascx).Programmati-cally,younormallyworkwithoneobjectonly,bothfromthepageanditsunits.TheCurrentPageobjectisaPageDataandcontainsallpageproperties,suchasHeading,MainIntro,MainBody.ButwithExtension,theCurrentPageobjectstillremainsforthe page but each content function on the page has its own equivalent CurrentPage object,ContentFunctionDataobjectandcontainsthecontentfunctionsownproper-ties.

Main APIThe Page – Area – Function relationTherearethreemainclassesintheExtensionsAPI:ExtensionPageData(equivalenttoPageData),ContentAreaDatafortheExetensionContentAreaandContentFunc-tionData for the Extension content function. Below UML diagram describes the relation between these classes.


5

It is important to add the code to your code behind for the template class.

using Dropit.Extension.Core;

namespace EPiServer.Templates{ public class MyExtensionTemplate : EPiServer.TemplatePage { // ExtensionPageHandler for Extension Functionality protected ExtensionPageHandler _extPageHandler; public MyExtensionTemplate(): base(0, 0)//extended by default { // create an instance of ExtensionPageHandler _extPageHandler = new ExtensionPageHandler(); } protected override void OnInit(System.EventArgs e) { base.OnInit(e); // initialize ExtensionPageHandler instance // must always be placed at this position _extPageHandler.Initialize(this); } }

}

Create an Extension template

1. Create the base classa) MyExtensionClass is either created as default or customized. The default one in-herits the Dropit.Extension.Core.ExtensionBaseTemplate.

b)BychoosingcustomizedyourExtensiontemplatescaninheritanybaseclass,butneedtoimplementanExtensionPgaeHandler.Itisrecommendedtocreateabaseclass when you choose this option for all Extension templates.


6

3. Register the template as an Extension page type There are two ways of doing this.a) Register the template as an EPiServer page type exactly the same way you dowiththestandardEPiServertemplates(AdminPageTypeCreatenew page type). You can also add new properties to the page type if it’s required.b) GotoExtensionadmin->PageTypesandfollowthewizardtoregisterthe Extension template as an Extension page type.

Create an Extension functionCreate simple content functionAn Extension content function control is a user control and inherits BaseContent-Function(Dropit.Extension.Core).

<asp:Content ID=”MainContent” ContentPlaceHolderID=”MainBodyRegion” runat=”server”> <div id=”MainBody”> <Extension:ExtensionContentArea runat=”server” id=”MainArea” description=”The main content area,400px” /> </div></asp:Content><asp:Content ID=”RightContent” ContentPlaceHolderID=”SecondaryBodyRegion” runat=”server”> <div id=”SecondaryBody”> <Extension:ExtensionContentArea runat=”server” id=”RightArea” description=”The right area for banners, 100px” /> </div>

</asp:Content>

2. DefinetheExtensionAreasUse the Extension web control ExtensionContentArea (Dropit.Extension.Core) to defineyourtemplateareas.BelowexampledefinestwoExtensioncontentareas,aMainArea and a RightArea.


7

Register a content function Aftercreatingacontentfunctiontemplate,gotoExtensionAdminforregistration:ExtensionAdmin->ContentFunctions.1. Register the user control.

Create a layout functionAdd one or more content areas to a content function using the web control Content Areafordefininglayoutcontentfunction(divider).Exampleonhowtocreatealay-out function with two equal columns.

<table style=”width:100%;”> <tr> <td style=”width:50%;padding-right:10px;” valign=”top”> <Extension:ExtensionContentArea runat=”server” id=”LeftArea” /> </td> <td style=”width:50%;padding-left:10px;” valign=”top”> <Extension:ExtensionContentArea runat=”server” id=”RightArea” /> </td> </tr></table>


<div> <h1> <Extension:Property ID=”propHeading” PropertyName=”Heading” runat=”server” /> </h1></div><div style=”padding-top:10px;”> <Extension:Property ID=”propBody” PropertyName=”MainBody” runat=”server” /></div>

Example on how to create a standard Extension content function with two proper-ties-HeadingandMainbody.

8


2. AddcontentfunctionpropertiesexactlyasyoudowhendefininganEPiServ er page type.3. Setdefaultaccessrightsfornewlycreatedcontentfunctiondefinitionscan be changed in the settings.4. Select the content areas that the content function are allowed to be dropped in.

Creating an Extension template pageAnExtensiontemplateisapagewithpredefinedstructureandcontent.Byselectingatemplate when creating a new page the user can maintain the layout and start editing with the content functions already in place. This reduces the risk of creating incorrect content in the wrong place and saves a lot of time for the editor who needs to create lots of pages with the same structure and layout. Administratorscansimplycreatethembyclicking“Saveastemplate”andgiveitaname,shortdescriptionandanicon.Thetemplatewillthenbeavailabletotheeditoras an option in the list of page types.

Working with global functionsA global function is an Extension content function with only one instance in the whole site but it still appears on several pages. If the global function instance is changed,itwillaffectallinstancesof thisfunctionandinallpageswhereitisused.To create or edit a global function you need to be an Extension administrator. Create new global function from any content function instance on any Extension page by selectingthe“Saveasglobalfunction”option.Allavailableglobalfunctionsarelistedunder“Globalfunction”sectionintheToolbox.Managing existing global functionsExtension administrators can edit the existing global function from the Administra-tion tab in the Toolbox.

Working with dynamic content functionsA dynamic content function is a global function limited within a part of the page structure as a dynamic property. This dynamic property is applied only for the pages with the same page type as the root (the page where the dynamic property is set). Using dynamic content functionsa. Createadynamicpropertytypeof ExtensionDynamicContentFunction.b. A dynamic content function is using a global function so you need to create a global function before setting the dynamic content function.c. Settingthevaluetothecontentfunction:• Selectthecontentfunction• Selectthecontentareathatthedynamiccontentwillbeappliedto.• Selectthepositionforrenderingthedynamiccontent(firstorlast).

9


Administrate ExtensionPlug-in settings1. ExtensionDataContainerID:SettheIDfortheExtensionDatacontainerin the page tree.2. HideExtensionDataContainer:ShoworhidetheExtensionDataContainer from the page tree in edit mode.Settings 1. “Extensionadministrators”:Choosetheusergroupsthatshouldhaveadmin istratoraccessrights:a) Create Extension templates.b) Create global functions.c) Manage global functions and Extension templates from the Administration tab in the Toolbox.

2. “RootforExtensioncategory”:SelectarootfortheExtensioncategories from standard Category.

3. “Errorhandlelevel”:DecidehowExtensionwillhandleerrors.Exceptwrit ingthemessagestothelog,thelevelshandleerrorsasfollowing:a) Defaulterrorhandle(0):Extensionforwardseverythingtothesender.Rec ommended during development phase.b) Showfriendlyerrormessage(1):Extensionshowsamorefriendlyerrormes sage. Recommended during test phase.c) Donothing(2):Extensionignoresallerrorsandtriestorenderanyway.Rec ommended during production.

4. Defaultaccessrightsfornewpagetypes:Setthedefaultaccessrightsfor newly created page types.

5. Defaultaccessrightsfornewcontentfunctions:Setthedefaultaccessrights for new created content functions.Create rules for content areas and content functionsThe Extension administrator can set rules for what type of content is allowed in each content area and on each Extension page type. These rules can be set either in the rulemanagementinthecontentfunctiondefinitionorinthepagetypedefinition.Bydefault a content function can exist in all available content areas.

10

The sample project LoremIpsumThe sample project LoremIpsum contains examples on how to work with Extension forbothbeginnersandadvanceddevelopers.Furtherexampleswillcontinuouslybeadded to this project.


Extension web controlsThe Extension web controls are located under the Dropit.Extension.UI.WebControls namespace.

Extension specialized propertiesThe Extensions specialized properties are located under Dropit.Extension.Special-izedProperties namespace

11

Namespaces


12

VocabularyContent functionThe Extension web controls are located under the Dropit.Extension.UI.WebControls namespace.Layout functionFunctionusedtosplitthecontentareaintwoormorecolumns.Combined functionCombination of a content function and a layout function.Global functionContentfunctiondefinedonagloballevel.Extension templateTemplatecreatedinExtension,containingoneormorefunctions.Extension page typePage type in Extension separate from EPiServer pages.ToolboxDragable element to the right on the screen containing the different functions.ToolbarElement at the top of the screen containing a number of action buttons.ClipboardArea in the toolbox used for copying functions.My favouritesArea in the toolbox used to store favourite functions.CategoryA function can belong to one or more categories.PropertyProperty of a content function or combined function.Edit On PageEdit the Extension content directly from View mode using the Edit On Page modeFunction typeFunctionsbelongtosomeof thefollowingtypes:content/layout/combined/globalAccess rightsTellswhichpersonorgroupisabletocreate,changeordeleteacertainfunctionAccess rulesRules that set the access rights for users. Content areaArea on an Extension template where you can create (drop) content functions.Nested content areaLayout function inside another layout function.


13

More informationMore information about Extension and other modules developed by Dropit AB is availableathttp://www.cmsapps.net.

Wikihttp://wiki.cmsapps.netiscontinuouslyfilledwithuserinformationrelatedtotheCMSapps products. It is available to those of you who have purchased a license or received a demo account. Questions not covered in the wiki are directed to [email protected].

BlogGetinformationaboutnewreleasesandfollowthedevelopmentprogressonupcom-ingproductsathttp://cmsapps.wordpress.com/

SupportThemodulesupportteamisavailableSwedishofficehoursbetween9amand5pm(GMT+01:00).Pleasenotethatthesupportserviceisintendedforexistingcustom-ers.

Phone:+46105226480E-mail:[email protected]


developer’s manual...• component art, componentart.web.ui.dll • javascript library prototype...

Documents