Webnodes Developers Manual

Transcription

1 Webnodes Webnodes Developers Manual Framework programming manual Administrator 1/1/2010

2 Webnodes Developers manual Webnodes Overview... 5 Definitions and meanings of words... 5 Introduction... 5 Key components... 6 The Application Storage Layer... 6 Data Objects... 7 The Application Engine Layer... 7 Adaptive Objects... 7 Application Interface... 7 AQL... 8 Installing WAF... 8 The website folder structure Steps to create your first website Setting up the semantic data model Creating a template The WAF semantic data model Content Base Inner Contents Built-in content types Hierarchal Contents Site SystemUser UserGroup ContentFile InnerContentFile Property Types CheckBoxPropertyClass IntegerPropertyClass FloatPropertyClass ShortStringPropertyClass LongStringPropertyClass HTMLPropertyClass P a g e

3 DateTimePropertyClass InnerContentsPropertyClass FilePropertyClass FileFolderPropertyClass NodeParentPropertyClass ParentNodeRelationPropertyClass / ChildNodeRelationPropertyClass ParentsNodeRelationsPropertyClass / ChildrenNodeRelationsPropertyClass AccessPropertyClass LinkPropertyClass EnumerationPropertyClass EnumerationsPropertyClass PasswordPropertyClass PropertyPropertyClass ContentClassPropertyClass ContentClassesPropertyClass CulturePropertyClass CommandPropertyClass HeadingPropertyClass ObjectPropertyClass SettingsPropertyClass Relations Node relations Inner content relations Node parent relations Database structure Working with content WAF.Data WAF.Engine WAF.Presentation Creating, changing and deleting content Retrieving contents Retrieving contents content directly from the WAF Session object Retrieving contents from other contents Retrieving contents from through AQL queries P a g e

4 Working with revisions and culture versions The revision property Derived revisions Changing revisions in code Release and Retain dates AQL queries The AQL Caches The AQL objects The Query Object AqlQuery AqlContentsQuery AQL Expressions Content Aliases Aql Expressions for enumeration property types Query Result Select queries Join queries Aggregate queries Group By queries Miscellaneous Aql functions Index queries Working with files Images and videos Setting up a Site Languages DNS and redirects Error pages Google Analytics integration Templates P a g e

5 Webnodes Overview Definitions and meanings of words When using the term WAF in this document, it is the short expression for Webnodes Adaptive Framework Introduction Our motivation for developing WAF is that we feel traditional CMS solutions does not meet the real world requirements of many of today s websites. The functionality and purpose of websites are broadening and it is no longer just about publishing content. Conventional CMS solutions are good at publishing content but not so good at being frameworks for web applications. Sure, today most CMS systems come with a lot of added modules for functionality like Blog, E-shop etc, and so do WAF, but this is not enough. Websites are becoming tightly integrated with the business processes of a company, and every company has different needs and it becomes difficult to use standardized modules. The alternative in many situations is to custom build things from scratch. This is time consuming and these systems often become disconnected from the rest of the website and need a separate UI. With the semantic data modelling capabilities of WAF you do not need to create separate customized databases or systems. Everything can be stored in WAF and everything can be edited through the same UI. You also save a lot of time as WAF will generate the code and database fields for you automatically. In fact, the key aim with WAF is: Combine the freedom and flexibility found in custom built software with the cost and user-friendliness found in standardized software As an example: Let s say you wanted to expand your website with an online CV database where your already registered users could expand their profile with CV data. In WAF you would simply expand the user object using object inheritance. You would define new classes for entities like: companies, colleges, education types etc. and set up one-to-many and many-to-many relations between them. Once the semantic data model is defined WAF would generate all the C# classes, database fields and edit interface for you. The CV database becomes an integral part of you website and CMS system. Since it becomes part of WAF you also get access to functionality for: free text searching, user access control, template system for rendering, user friendly URLs, version handling, images scaling, video conversions, Google analytics integration and much more. In essence WAF is a fully fledged ORM system with an integrated UI and functionality related to web. 5 P a g e

6 Key components WAF follows a basic three layer architecture: Application Interface Application Interface (HTML, Winform, IIS etc), Template engine etc. Adaptive Objects WAF Session Object SMS Application Engine Runtime Code Generator Runtime Code Compiler AQL Query Engine + Entity broker Cache Workflow Engine Dialogue engine MMS WAP Web Post Data Objects Telephone Application Storage Data layer, ADO.NET Index Lucene Search Engine Database SQL / My Sql / Lite Files NTSF The Application Storage Layer The storage or data layer consists of three parts: the database, the text index and the file system. The database has one table for each class defined in the system with a field for each property. The database is the master storage for all content except files. The database is also the key engine behind the WAF query language AQL. The text index system is build on top Lucene and contains text extracts for both database fields and files. The text index is fast and efficient at doing free text searches across all properties and files. It supports concepts such as relevance based result lists and fuzzy searches. WAF uses the NTSF file system to store files uploaded to the system. The files are organized in folders located within the websites root folder. The data layer contains abstractions of the SQL language to provide a query system independent of the database provider. 6 P a g e

7 Data Objects The DataObject is the main data flowing between the storage layer and the application engine layer. The data-object is a generic object that can house all the properties that belongs to a WAF object. The property values are stored in a dictionary so the same data-object can be used for any class data and support lazy loading of individual properties not loaded in the first request. The Application Engine Layer The application engine layer is more complicated. The key purpose is to receive data queries from the interface and return the data in the form of objects based on compiled classes. Typical examples are: users, documents, forum messages, etc. To be able to do this fast it has a built in cache mechanism so that calls to the storage layer and resulting SQL statements can be avoided as much as possible. The caching mechanism is automatic and very effective. In a normal website most pages will not require a single SQL and execute within 5-10 ms. It reloads only relevant parts on content changes. This cache must not be confused with the built in page cache mechanism in ASP.Net. The ASP.Net page cache can be used in addition to the WAF cache, but as WAF is very fast most websites will not need this. This simplifies the development of templates. The key API against the engine layer is the WAF Session object. A WAF session object is created for every web session. The WAF Session object contains information about the user s access rights and validates all queries and operations against this. The WAF Session object is the key object you work against to retrieve or change data in WAF. The engine layer is also responsible for generating the class files according to data definition and compile changes to the content classes in runtime. The engine layer has built in support for communicating to users via the UI, , SMS and MMS. A last important part of the engine is the system for hosting workflows which is based on the Windows Workflow Foundation. Workflows are used in several areas of the system. All dialogues in the edit interface are controlled by a workflow. The workflow system is also used for long running processes that are not suitable to run in the context of a page rendering. Typical examples are the sending of large number of newsletters or SMS. Adaptive Objects The base class of all adaptive objects is called ContentBase. This class is the base class of all entities in WAF, which means all: users, templates, files, forums, blogs, sites, domains, user groups, etc. If you have defined your own classes the code files for these classes are located in the App_Code folder. These classes are partial classes and you can override methods to add custom functionality. Since each entity you define in WAF is represented by an actual class you get full intellisense when you work with these objects in Visual Studio. Application Interface The presentation layer of WAF is mainly split in two. The visit and edit part. The visit part is the part all site visitors go to. The rendering of this is done in normal.aspx files that you create from scratch using normal ASP.Net components such as: Controls, UserControls, Masterpages etc. The WAF HttpModule rewrites the requested URL to the correct template file. (WAF supports friendly URL s). 7 P a g e

8 Making the templates is normally the most time-consuming job of setting up a site in WAF but there is complete freedom in the template design. At the moment WAF does not have many visit side controls for rendering content and relies on the build in controls of ASP.Net. You may find it useful to acquire third party controls to build rich user interfaces. The edit part is the admin interface. It is accessed by typing /edit after the websites address. This interface is the same for every WAF website but is adapted to your semantic data model. It is split into modules that group functionality. The key purpose is to edit and preview content changes. There are about 10 built in modules, but you can also easily create your own modules. AQL AQL is short for Adaptive Query Language. AQL is the primary query API to get content out of WAF. Installing WAF Installing WAF is easy. Download the setup program here: The setup utility has a series of functions related to installing, moving, copying and editing Webnodes installations. To install a new website press the Create button: You can choose to install for development and use the build in web server in Visual Studio or install to an local or remote IIS (v 6 or v 7). If you choose to install to an IIS installation you will need to setup a IIS website the files can be copied to. The recommended settings for an IIS website are: 8 P a g e

9 Full access to the file system within the website root folder. This means giving the ASP.Net user and the App_Pool Process identity user (normally NetworkService) full access in the NTFS file system. On some systems the Network Service system user must be given full access to the.net temp folder as well: Run in full thrust mode, (only applicable to IIS7) Pipeline mode: Classic, (only applicable to IIS7): 9 P a g e

10 Turn off App Pool recycling as much as possible: Allow the IIS App Pool at least 400 mb of private memory limit before recycling. Be sure to check that your hosting partner meet this last requirement. Many shared hosting environments do not support this. Almost all dedicated server or virtual server hosting support it. See our website for recommended hosting partners. Please feel free to contact us should you experience any problems during the setup. We offer free and fast support if you have any problems with this. 10 P a g e

11 The website folder structure This section gives an overview of the website folder structure. The WAF applications stores most of its files in the WAF folder. You should never really need to access this folder unless you are creating your own edit modules. The content types you define will have its C# class files generated in the App_Code folder. WAF Template files or your own.aspx files can be created anywhere but we normally put them in the Templates folder. There is not fixed location for style sheets, script files or images. Use whatever structure you find most suitable. We normally put all these files under the Templates folder. Here is a quick glance: ASP.Net folder. WAF uses folder to overrides certain web control methods ASP.Net folder. WAF saves class files for content types here ASP.Net folder. WAF stores the search index here ASP.Net folder. WAF stores the default skin for edit mode here ASP.Net folder. WAF stores the WAF.dll and other components here WAF folder. Directs all request to /edit to WAF/edit/main/default.apx Optional. Typical folder name for storing templates WAF system folder. Contains all files needed to run WAF. Optional. Not really in use as most requests are directed to a template. ASP.Net file. Here you configure WAF db connection and the master user. 11 P a g e

12 Here is a more detailed view: ASP.Net folder. WAF uses folder to overrides certain web control methods ASP.Net folder. WAF saves class files for content types here This folder contains auto generated code by WAF. Do not edit files here. Each namespace gets its own folder. Do not edit files here. Each content class gets its own class file. Do not edit files here. This folder contains files you can modify to change or extend content classes Each namespace gets its own folder One file is created for each content class. Add your custom class code here. ASP.Net folder. ASP.Net folder. WAF uses a HTML editor from Telerik. Here are the editor dictionaries. This folder is used to store the WAF Text Search index. (The engine is based on Lucene) If you are using the SQL Express in Visual Studio then this is normally the database file. ASP.Net folder. WAF stores the default skin for edit mode here. ASP.Net folder. WAF stores the WAF.dll and other components here WAF folder. Directs all request to /edit to WAF/edit/main/default.apx WAF folder. Optional. Typical folder name for storing templates. You may use any other folder. Optional. Typical folder name for stylesheets. You may use any folder name you like. Optional. Typical folder for storing images referred to by style sheets. Typical filename for css file used in HTML editor. Typical location of css file used by visit templates. Templates files can put anywhere but are normally located here. This is a template file for the login page You may use the ASP.Net master page system for templates. WAF system folder. Contains all files needed to run WAF. WAF client script files. Mostly used by the Edit interface. Folder for workflow dialogues files. Folder containing a subfolder for each edit module. Folder for storing WAF files with data specific this installation Icons for all defined content classes The files for each content file field Definition XML files Log files WAF Temporary files. Can be deleted. Temporary location for files during upload in WAF Folder for storing miscellaneous WAF handler files Folder for storing miscellaneous WAF service files WAF setup folder. Can be opened directly using localhost or via the System Menu Internal WAF skin folder for edit controls WAF folder used for storing miscellaneous files for visit side functions Optional file. Could be a template file, but can also be empty and not in use. ASP.Net Configuration file. Contain WAF db connection and other settings. 12 P a g e

13 Steps to create your first website In this simple walk-through example we will create a very basic website in WAF. The design of the website looks like this: You can install the source code for this example from the setup program. The site has a basic hierarchal menu structure and a free HTML field for the content area. After installing WAF the first natural step is to think about the semantic data model and the template files. 13 P a g e

14 Setting up the semantic data model The model for this website is very simple. All we need is a content type with a free HTML field and a content type with relation properties so we can organize the contents into hierarchy for the menu structure. For the hierarchal properties there is a built in content type called HierarchalContent. If we inherit from this class we get two relation properties called Parent and Children. All contents that appear in the tree structure found in the content module inherit from this base class. To define the class you open the Semantics module: Type the namespace MySite, the classname Article and inherit from Native.HierarchalContent and click OK, this will create a new content class. Next add the following properties using the New property... button. Codename Type Ingress Long string Image File BodyContent HTML Files File folder 14 P a g e

15 Once done, select Full rebuild under New Definitions in the menu. This will start the build process. The necessary fields will be created in the database and new code files are also created under App_Code : Two partial class files are created for the new class Article. The one under WAF/MySite folder contains all the new properties and is overwritten on every WAF recompile. The one in WAF_Custom/MySite is created once by the system and never overwritten by WAF. If you want to add custom properties and override default behaviour of the class you can do that here. 15 P a g e

16 Creating a template In WAF templates are just normal.aspx files. To create new templates you simply create a new.aspx file in Visual Studio and associate them with the content types. In this example want to use a simple ASP.Net Master Page setup, so we start with creating the master page Main.master under /Templates Our master page contains the following code: <%@ Master Language="C#" AutoEventWireup="true" CodeFile="Main.master.cs" Inherits="Templates_MasterPage" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " transitional.dtd"> <html xmlns=" <head runat="server"> <link href="~/templates/stylesheets/stylesheet.css" rel="stylesheet" type="text/css" /> <title></title> <meta http-equiv="content-type" content="text/html;charset=utf-8" /> <asp:contentplaceholder ID="head" runat="server"> </asp:contentplaceholder> </head> <body> <form id="form1" runat="server"> <div id="layoutouter"> <div id="layoutheader"> <div id="layoutheaderlogo"> </div> <div id="layoutheadermenubar"> <div id="layoutheadermenulinks"> <asp:literal ID="litMenu" runat="server" EnableViewState="false" /> </div> </div> </div> <div id="layoutbody"> <div id="layoutbodymenu"> <div id="layoutbodymenutitle"> <asp:literal ID="litSubMenuTitle" runat="server" EnableViewState="false" /> </div> <asp:literal ID="litSubMenu" runat="server" EnableViewState="false" /> </div> <div id="layoutbodycontent"> <div id="layoutbodycontentframe"> <asp:contentplaceholder ID="cphBodyText" runat="server"> </asp:contentplaceholder> </div> </div> </div> <div id="layoutfooter"> </div> </div> </form> </body> </html> 16 P a g e

17 The master page uses two literals for the menu and has one placeholder for the body content. In Page_Load method the literals are initialized: protected void Page_Load(object sender, EventArgs e) { litmenu.text = gettopmenuhtml(); litsubmenutitle.text = getsubmenutitle(); litsubmenu.text = getsubmenuhtml(); } The literals have deactivated their viewstate as the content is set on each request. The method gettopmenuhtml() renders the top menu: string gettopmenuhtml() { StringBuilder html = new StringBuilder(); Site site = WAFContext.Session.GetContent<Site>(WAFContext.Session.SiteId); var children = site.children.query().where(aqlhierarchicalcontent.showinmenu == true).execute(); foreach (HierarchicalContent child in children) { bool onselectedbranch = child.isparentorsame(wafcontext.request.nodeid); html.append("<a"); html.append(" href=\"" + HttpUtility.HtmlAttributeEncode(WAFContext.GetUrl(child.NodeId)) + "\""); html.append(">"); if (onselectedbranch) html.append("<span class=\"headermenuselected\">"); html.append(httputility.htmlencode(child.name)); if (onselectedbranch) html.append("</span>"); html.append("</a>"); } return html.tostring(); } This method uses a StringBuilder to build the HTML for the menu. We could have used an ASP.Net Repeater control, and had better separation of HTML formatting and C# code. Examples later will show how this can accomplished. But, the approach used here is perhaps simpler to implement and provides the best performance. We will come back to the details of retrieving content from WAF later, but a short description follows here. The key object to notice is the WAFSession object. It can be accessed via the static object WAFContext: WAFContext.Session. WAFContext is a utiliy object in WAF that contains a lot of method and properties relevant to the current web request, like Session, urls, filepaths, current content, current culture, etc. The WAFSession is an object created for every ASP.Net session and contains information about the users autentication. This object has the key methods for retrieving and changing content. All actions are filtered and denied according to the users access rights. That means that a content query using the session object will be filtered according to the content the user has read access to. Further, a property change on an object the user does not have write access to will cause an AccessViolationException to be thrown. The purpose of this is to simplify and centralize the site s access control to content. For example, if you have set that only system administrators should be able to read certain content, you can be sure all template code done throught the session object will never be able to read out the data you want to protect unless the user is logged in with an account with administrative account. This architecture also save you the hassel of adding access control code to every template. The first statement: Site site = WAFContext.Session.GetContent<Site>(WAFContext.Session.SiteId); 17 P a g e

18 Retrieves the content object representing the site. The WAFSession.GetContent<> method is a general purpose method for retrieving one content and has many overloads. In this case the paramater is the node id of the current site. The WAF Session object always holds the id of the node id of the current site. The next line retrieves all the children of the site object: var children = site.children.query().where(aqlhierarchicalcontent.showinmenu == true).execute(); The site object inherits from the object type HierarchicalContent that define the.parent and.children property. The.Children property is a relation property and has a method called.query(). The.Query() method returns a query object that can be used to perform sub queries on the related contents. The HierarchicalContent class also define the property ShowInMenu which indicate if the content should be shown in the menue or not. The query expression is an example of the WAF AQL query language. Further information on the AQL query language can be found in a separate section. Worth mentioning is that the site object was retrieved with the WAFSession object and that the session object therefore follows into the site object so that the query will filter out any contents the user migth not have read access to. This applies to all methods of relation properties. The call results in calls to the WAF engine and datalayer and will end up in SQL to the database if the query is not cached. For most page request this query will be cached and the call will execute very fast and can safely be done for every page request without affecting performance. A query like the one above typically executes in less than 0.05 ms, so that 100 of these calls will take less than 5 ms. This is important as it means you mostly do not need to worry about making to many queries in the rendering of a page. The ASP.Net page cacheing is normally not necessary to setup for WAF based websites. Further on in the method there is a loop going through each menu item. The first statement in the loop determines if the current item should be renered as selected in the HTML. To determine this the method IsParentOrSame() is used. This method is one of several utility methods on the HierarchicalContent class to help with common functions you need when building menues. foreach (HierarchicalContent child in children) { bool onselectedbranch = child.isparentorsame(wafcontext.request.nodeid); WAFContext.Request gives retrieves WAFRequest that is an object that contains key information about the current request like the content associated with the request, the language etc. The final piece of code in the master page to commment is the use of ASP.Net HttpUtility Class. This object has several static methods that are usefull to encoding the HTML correctly. It is important you use this object all the places where you render strings into HTML code, other wise characters like < in the title of a content will mess up you HTML. The rest of the methods in the template follows a similar pattern and should be fairly self explanetory: string getsubmenuhtml() { 18 P a g e

19 } var c = WAFContext.Request.GetContent(); if (!(c is HierarchicalContent)) return ""; var root = ((HierarchicalContent)c).GetParentAtLevel(1); StringBuilder html = new StringBuilder(); buildsubmenu(root, 1, html); return html.tostring(); } void buildsubmenu(hierarchicalcontent parent, int level, StringBuilder html) { var children = parent.children.query().where(aqlhierarchicalcontent.showinmenu == true).execute(); if (children.count == 0) return; html.appendline(); html.appendline("<ul class=\"layoutmenu\">"); foreach (var child in children) { bool onselectedbranch = child.isparentorsame(wafcontext.request.nodeid); bool isselected = child.nodeid == WAFContext.Request.NodeId; html.append("<li"); if (isselected) html.append(" class=\"menuselected\""); html.append("><a href=\""); html.append(httputility.htmlattributeencode(wafcontext.geturl(child.nodeid))); html.append("\">"); html.append(httputility.htmlencode(child.name)); html.append("</a>"); if (onselectedbranch) buildsubmenu(child, level + 1, html); html.appendline("</li>"); } html.appendline("</ul>"); } The next step is to create the.aspx temlate file. Add an.aspx file under /Templates called Article.aspx and select Main.Master as the master page. The code for this temlate is: <%@ Page Title="" Language="C#" MasterPageFile="~/Templates/Main.master" AutoEventWireup="true" CodeFile="Article.aspx.cs" Inherits="Templates_Article" %> <asp:content ID="Content1" ContentPlaceHolderID="head" runat="server"> </asp:content> <asp:content ID="Content2" ContentPlaceHolderID="cphBodyText" runat="server"> <h1> <asp:literal ID="litTitle" runat="server" EnableViewState="false" /></h1> <div class="ingresstext"> <asp:literal ID="litIngressImage" runat="server" EnableViewState="false" /> <asp:literal ID="litIngress" runat="server" EnableViewState="false" /> </div> <div style="clear: both;"> </div> <div class="bodytext"> <asp:literal ID="litBodyText" runat="server" EnableViewState="false" /> </div> </asp:content> and the codebehind file contains: using System; using System.Collections.Generic; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using WAF.Presentation.Web; using WAF.Engine.Content.MySite; public partial class Templates_Article : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { var article = WAFContext.Request.GetContent<Article>(); littitle.text = HttpUtility.HtmlEncode(article.Name); litingress.text = HttpUtility.HtmlEncode(article.Ingress).Replace(Environment.NewLine, "<br />"); if (article.image.containsfile()) litingressimage.text = article.image.getimagehtml(100); litbodytext.text = article.bodycontent; } } The code should be fairly self explanetory. On thing worth mentioning is the Image property. The Image property is a file property and has several useful methods usefull for rendering html. In the 19 P a g e

20 example above article.image.getimagehtml(100) will return the HTML for an image tag. The actual image will be generated on the fly and cached in WAF when the clients browser requests the image. Once the.aspx file is created you must create a reference to the file via a template content in WAF. To do this open the Template module. In this module you see a filtered treeview of the.aspx files and folders in the installation. Locate the article.aspx file and click on the Create template for this file... button. This will create template content with a reference to this file. Next you must select the content type that can use this template. Select the Article content type. The template is now ready: Next step is to reference the stylesheet you want to use in the HTML editor field. Click the Stylesheets tab and locate the stylesheet in the tree structure. In this example there is a stylesheet called editor.css. Double click on the file and click on the Create stylesheet for this file... button. Then, relate the stylesheet with the template we create earlier clicking on the Select under Templates. This relation will make the HTML editor base its styles on the file editor.css during editing of articles using the template Artcles.aspx. The relation does not affect the rendering of articles in the visit mode. To reference and include stylesheets for the visit rendering use the normal html references in the header just as you would for any other.aspx file. WAF is now setup and you can start to add content in the content module. 20 P a g e

21 The WAF semantic data model This section will describe the details of the semantic data modelling possibilities in WAF. Document types you define in WAF become C# class files and to some extent WAF is an ORM framework for web applications complete with an edit interface. ORM is short for Object-relational mapping and is a technology for converting data and data models found in rational databases with object oriented language systems. Typically you define your data model in a XML document and the system generates the database fields and code files for you. In WAF there is a XML file that defines the semantic data model, but there is also a built in content type editor that is much easier to work with. Content Base Almost everything in WAF inherits from the base object ContentBase. This includes objects like system users, sites, usergroups, domains, documents, files etc. The main id of each object is called the NodeId. The NodeId is shared across all versions of the object. Depending on you setup there can be multiple versions of each object and some versions can have content that is derived from another culture or preliminary revision. The unique key to each of these versions is the combination of NodeId, CultureId and Revision. There is a property called Key that stores these three ids. Most of the time you only use the NodeId and a request based on NodeId will use the culture of the current session. By default the published revision will be retrieved. If the content does not have content in the specified culture a special derived version will be returned. The derived version contains content copied from another culture with published content. Some of the key properties of ContentBase are: NodeId LCID Revision SiteId Name Address TemplateId The NodeId of the content. The culture ID of the content. The revision of the content. The NodeId of the site the content belongs to. The name of the object Unique friendly URL The node id of the template used to render a page request to the content To make changes to a content you simply set the relevant property values and call the method UpdateChanges(). Inner Contents Inner contents are special contents that only exist as part of a normal content inheriting from ContentBase. The inner contents are related to a content via a inner content relation property. You can define several inner content relation properties in one content class and an inner content class can also contain its sub inner contents through a inner content relation property. In this way you can create a tree structure of inner contents within one content. The process of defining inner contents is the same as for defining normal contents. You can use inheritance and most of the property types that you can define for a normal content can be used for an inner content. The exceptions are the node relation properties. 21 P a g e

22 Inner contents are particularly useful if you need a document template where the content is formatted and displayed in series of optional paragraphs or modules. A typical example could be if you wanted to give the user the possibility to build up a document from a range of 3 paragraphs types. One for just a heading and a free HTML field, a second for a series of pictures and a third as table with a graph. Sometimes the user might need just three graphs, and other times just text and a series of pictures. With inner contents you could define one inner content class for each paragraph type and with one inner content relation property the user would be free to add whatever paragraphs he wanted. Another important aspect of inner contents is that all inner contents appear as editable as part of the same document within the edit interface. You could have achieved the same functionality using normal contents and a node relation field, but each paragraph would then have to be edited separately. Since all inner contents appear simultaneously in the edit interface it is not suitable for larger collections of objects. If you expect more than or more items you should consider using normal content and a node relation where there is no practical limit. The base object of inner contents is InnerContentBase. The base class is much simpler than ContentBase and the only important property is the ContentId. Every inner content has unique ContentId, but to retrieve a inner content you must start by retrieving the ContentBase object it belongs to. 22 P a g e

23 Built-in content types WAF comes with a series of built-in content types for key functionality. You may modify and inherit from to build your own functionality. The most important content types are described below. Hierarchal Contents HierarchalContent is a content class that inherits from ContentBase. It has key properties needed to make the content part of the common navigation hierarchy. About half of the built in classes inherits from this class and any document type you define that you want to make part of a menu should inherit from this class. The key properties are: Parent Children ShowInMenu ShowInTree Default... A relation to the parent content Relations to all child contents Flag to indicate if content should be visible in the menu Flag to indicate if content is visible in the tree in edit mode A series of default values of new child contents that are added to the content Site Site is the content class that represents each site in the system. Every content in a installation belongs to a site and has a SiteId property. The site is the root object in the navigation hierarchy of each site. Each site is associated with one or more domains. The domain of the first request in a user session will determine what site in an installation the user will be directed to. Once the site is established the StartNode of the site will be the first page the visitor sees. SystemUser SystemUser is the content type used to hold user data. It contains the expected properties like username, password, group memberships etc. UserGroup UserGroup is the content type used to group users. Setting access rights in the system is done by referring to user groups. A user is granted access if the user is a member of the group. ContentFile ContentFile is a built-in content class that inherits from HierarchalContent and is a designed to part of the hierarchy of the File Library. This hierarchy is based on a relation between FileFolder and ContentFile. The key property of ContentFile is the File property that contains the file. ContentFile have three descendants. InnerContentFile InnerContentFile is a built-in inner content class that inherits from InnerContentBase. In combination with a property type call FileFolder which inherits from the normal inner content relation property, it is useful if you want to give the user the possibility to upload a collection of files as part of a content. The key property of InnerContentFile is called File and contains the uploaded file. You may inherit from the InnerContentFile class to expand with you own properties on each uploaded file. 23 P a g e

24 Property Types There are a series of built-in property types you can add the content classes you define in the semantics module. With each property type it follows a set of rules and characteristics. These are defined in the PropertyClass that belongs to each property. To define your own property classes you need to define a class that inherits from one of the existing PropertyClasses. The PropertyClass defines things like: the code to be generated in the content classes that use it. What DataValues are relevant? How the search index should index it. What web controls should be used in edit. What the relevant settings are. Etc. All database values in WAF are abstracted into a set of 6 universal data value classes: BooleanDataValue IntegerDataValue FloatDataValue ShortStringDataValue LongStringDataValue DateTimeDataValue db True/False, can be indexed in db 32 bit signed integer, can be indexed in db 32 bit floating point, can be indexed in db up to 255 unicode characters, no null, can be indexed in db unlimited unicode characters, no null, cannot be indexed in db Date and time value, :00:00 is null, can be indexed in There are two data value types for holding node relational data: NodeRelationDataValue revision. NodeRelationsDataValue A relation to one content node. Can be specific to culture and Relations to content nodes. Can be specific to culture and revision. And last, one to hold the values of related inner contents InnerContentsDataValue A container for related inner contents. Although you normally do not relate directly to these value classes and most property classes use a combination of the data values, the values form the bases for the query system and build in cache mechanisms. One the next pages you will find a description of all the built-in property classes: CheckBoxPropertyClass This property class is of type bool and a checkbox is displayed in the edit interface. The underlying datavalue is BooleanDataValue. IntegerPropertyClass This property class is of type 32 bit integer and a text box is displayed the edit interface. The underlying datavalue is IntegerDataValue. FloatPropertyClass This property class if of type 32 bit double and a text box is displayed in the edit interface. The underlying datavalue is FloatDataValue. 24 P a g e

25 ShortStringPropertyClass This property is of type string and a one line textbox field is displayed in the edit interface. The underlying datavalue is ShortStringDataValue. The length is limited to 255 characters. An exception will be thrown if you set a value longer than 255. The property is never null and if you set it to a null value the saved value is an empty string. The content of the text is not HTML encoded so remember to use HttpUtility.HtmlEncode if you write the value of the property out as HTML. LongStringPropertyClass This property class is of type string and a multiline textbox field is displayed in the edit interface. The underlying datavalue is LongStringDataValue. The length has no limit, but if you enter text longer than a million characters the system will slow down and load time in the client browser will be very long. The content of the text is not HTML encoded so remember to use HttpUtility.HtmlEncode if you write the value of the property out as HTML. HTMLPropertyClass This property class is of type string and a WYSIWYG HTML editor is used in the edit interface. The underlying datavalue is LongStringDataValue. The length has no limit, but if you enter text longer than a million characters the system will slow down and load time in the client browser will be very long. The content of the text is HTML and the value can be written directly to the response stream. All URL references in the HTML are parsed and changed to use ID numbers each time a new value is set. Each time a value is read the HTML is parsed to friendly addresses with the correct relative reference to the current page. The WYSIWIG editor loads the CSS stylesheets that belongs to the template the content is using. DateTimePropertyClass This property class is of type DateTime and a basic date time picker is used in the edit interface. The underlying datavalue is DateTimeDataValue. A value of :00 is considered a null value. The null can be references Utils.DateTimeNull. InnerContentsPropertyClass This property class is of type InnerContentsDataValueand the field is rendered as a set of expandable panels that contain the fields for each of the related inner contents. There is not specific limit to the number of inner contents there can be in one relation field, but for performance reasons we recommend you limit the number to about 100. If you need to relate more items we recommend you use a node relation field where each item is not rendered with edit controls and is shown in a list with buttons for paging. InnerContents supports nested relations and you can have relations fields inside related inner contents. The property type is well suited to paragraphs, optional document elements, smaller image galleries etc. FilePropertyClass This property class is of type FilePropertyValueClass and holds the content of a file. The actual file is stored in the file system under WAF/Files/Content/*content_id+/*property_id+/*guid+. The [content_id] is the ContentId of the content or inner content. (Not NodeId). [property_id] is the numeric id assigned to each property. The [guid] is a folder generated for each file to protect the file from direct download by guessing file ids. The property has several methods to retrieve information related to the file like, the type of file, the size, the dimensions, the duration (if relevant) etc. Some of the key properties such as name, size, extension and type are store in the database so that you make 25 P a g e

26 queries on file properties. The Property also has a number of useful functions for generating URL s to scaled versions of images, converted video, generating HTML for flash players etc. FileFolderPropertyClass This property class inherits from inner content property and is a property specifically designed to hold a collection of inner content files. The property has an upload button where you can create multiple inner content files with by uploading multiple files in one click. An inner content of type InnerContentFile is created for each file. This property is particularly useful if you want to give the user the possibility to upload a collection of files as part of a document with no references to the file library. NodeParentPropertyClass This property can be used to relate of another content node. The relation is done through a NodeId stored in the content class table. Internally this property class is of type Integer and uses a IntegerDataValue to store a NodeId. The relation is one-to-many but there is no matching property type for the opposite side of the relation. There are no query expressions to perform query joins over this relation type either. The advantage with this relation is that it is easy to set up and that it can be used by inner contents. A typical usage is the start node of a site. ParentNodeRelationPropertyClass / ChildNodeRelationPropertyClass This property is used to relate one node to another node. The relation is stored in a relation table that is defined separately in the semantics module. This relation type cannot be used on inner contents. The relation is two way. That means that you can define another property on the content you are relating to that will show the opposite side of the relation. If you delete the relation from one of the contents, the relation will also be removed from property on the other content. This property supports a single relation and can be use in relations of type: one to one, one to many. You can perform join queries with this relation property. The relation can be set up to be specific to both culture and revision. ParentsNodeRelationsPropertyClass / ChildrenNodeRelationsPropertyClass This property is used to relate one node to multiple other nodes. The relation is stored in a relation table that is defined separately in the semantics module. This relation type cannot be used on inner contents. The relation is two way and can be used on relations of type: one to many and many to many. You can perform join queries with this relation property. The relation can be set up to be specific to both culture and revision. AccessPropertyClass This property stores a reference to a user group. You can relate to both built in groups such as Anonymous and Administrator and any other userdefined usergroup. LinkPropertyClass This property is useful for storing a link. The field can link to internal pages, external pages and s. EnumerationPropertyClass This property is using a C# enumeration as the property value. Internally it is using an integer. The user is presented with a drop down control or a set of radio buttons. The enumeration type must be defined in the semantics module. Here you can use a different text for the interface control and the 26 P a g e

27 underlying codevalue. You can also define different text values for each culture. You can perform queries on enumeration properties. The property is ideal for values such as: country, county, fixed colours, layout style, fixed categories etc. Since the actual value is an enumeration it is not very easy for non technical users to add new values and it is therefore not suited for properties where the possible values are frequently changed. The advantage is efficient database storage and fast query performance. Working with enumeration values is also easier for a programmer. EnumerationsPropertyClass This property can contain a list of C# enumeration values. Internally it is using a series of integers and a BitArray to store the values. In the interface it is displayed as a set of checkboxes. The storage is very efficient and it supports AQL queries. You can use a different text for the interface control and the underlying codevalue. You can also define different text values for each culture. The property type is ideal for countries, counties, fixed categories etc. Since the actual value is an enumeration it is not very easy for non technical users to add new values and it is therefore not suited for properties where the possible values are frequently changed. The advantage is efficient database storage and fast query performance. Working with enumeration values is also easier for a programmer. PasswordPropertyClass This is a property type for storing passwords. Internally it uses a ShortStringDataValue. The property can store the password in three modes: 1. Unencrypted: The password is stored as plain text. This mode will expose the password if the database is compromised. 2. Encrypted: In this mode the full password is stored in the database, but it is encrypted with a installation specific key that is stored separately from the database. In this mode it is still possible to retrieve the password if the database is compromised, but it is considerably more difficult. It requires access to the database, the WAF code files and in depth knowledge of the encryption routine in WAF. The passwords stored in this mode can be retrieved at any point if you are an administrator. If you want to preserve to possibility of sending a user a password he has forgotten and do not want to generate a new one, then this is the best mode. 3. Hashed. In this mode the password is hashed (and salted) so that the underlying password is never stored in full in the database. It is not possible to retrieve the password, in a compromised system as the full password is not stored. The disadvantage with this mode is that the original password can never be retrieved, you can only check if a given password generates the same hash code. PropertyPropertyClass This is a property class used to relate to the definition of a property of a WAF content class. ContentClassPropertyClass This is a property class used to relate to the definition of a WAF content class. ContentClassesPropertyClass This is a property class used to relate to the definition of one or more WAF content classes. CulturePropertyClass This is a property class used to relate to a specific system culture (LCID). 27 P a g e

28 CommandPropertyClass This is a property class used to relate to the definition of a WAF property class (or type). HeadingPropertyClass This is a property class with no resulting property on the actual c# class. It is used to add headers and information text in the edit module. It can also be used to insert HTML with client javascript. ObjectPropertyClass This is a property class for storing objects. Objects must be serializable and not too big. There is no specific limit on the size, but as the object is serialized as a 64 base encoded string and stored in the database an object larger than about 1 MB will start to have noticeable effects on the performance. SettingsPropertyClass This is an internal property class used for settings objects. Relations Relations form an important part of any semantic data model and it is important you understand the pros and cons of the three base types that exists in WAF. Node relations This is a two way relation between two content classes. It supports one to one, one to many and many to many. The actual relation is stored in a table separately from the content class table. This makes it possible to constrain the relation to any combination of content classes. The relation can be both dependent of both content culture and revision. You can relate an unlimited amount of contents. The actual property is shown as a paged list in the edit interface. The relation stores the order in which each item is related. A node relation supports join queries. To define a node relation you start by defining the actual relation independent of the content properties. This is done in the definitions module under Relations. A special class is created for the relation, this class has methods you can override to add custom validation rules etc. The definition of a relation consists of the following: OneToMany / ManyToMany: Select the appropriate type. Select OneToMany if you want to define a OneToOne relation. The key difference here is that an OneToMany relation automatically updates the parent properties on all siblings. Parents: This is a list of the content classes that are legal as parents. Each listed class will include inherited classes as well. Children: This is a list of the content classes that are legal as children. Each listed class will include inherited classes as well. Once the relation is defined you must add relation properties to the relevant content classes. The relevant property classes are: ParentNodeRelationPropertyClass ParentsNodeRelationPropertyClass ChildNodeRelationPropertyClass ChildrenNodeRelationPropertyClass 28 P a g e

29 The disadvantages with this relation type are: It is slightly more complicated to set up and that the edit interface only shows a list of related items. To edit related items you must click on each item individually and open a new window. You can only relate from one content class to another. You cannot add a relation property to an inner content. A sample of the edit interface: Inner content relations This relation type is designed to handle data such as content paragraphs in a page. Typically you want to be able to edit all paragraphs within one edit page in the edit interface. You may also want to give the user a few paragraphs type to choose between. One for images, one for mainly text, quotes etc. This could of course be achieved by adding a series of fixed properties to a normal content class, but it would be very limiting. The user would not be able to determine the order of the paragraphs or the number of paragraphs of each type. An inner content relation is a relation to a set of classes called inner contents. Inner contents are very similar the content base class, but they can only exist as part of a normal content. They do not have properties for things like template, access control etc. These properties are derived from the base content they belong to. An example of the edit interface of inner contents: Collapsed: 29 P a g e

30 Expanded: An important feature of inner contents is the ability to add inner content relation fields to inner contents. This enables you to create a tree structure of inner contents within one content. A variety of inner content relations is the file folder property. This uses inner content relations to relate to a series of upload files. For each upload file an inner content of type InnerContentFile is created. You may expand the built in type InnerContentFile by creating your own inner content class that inherits from InnerContentFile. Node parent relations This relation type uses an IntegerDataValue to store the NodeId of the node you are relating to. The advantage with this relation type is that it is very simple to set up and that it can be used from within inner contents. The disadvantage is that is its one way. There is no opposite property for the child nodes. You relation does not support join queries either. In the interface the property looks like this: 30 P a g e