INTRANET. EXTRANET. PORTAL.

Transcription

1 Intranet DASHBOARD API Getting Started Guide Version 6

2 Contents 1. INTRODUCTION TO THE API... 3 Overview... 3 Further Information... 4 Disclaimer GETTING STARTED... 5 Creating an Application within your Intranet... 5 Viewing the Application... 7 Understanding Installation, Paths and IIS... 8 Creating Pages... 9 Utilizing id Themes Obtaining User Details Using Existing id Content Creating id CMS Components Creating Custom Workflow Actions Namespaces and Assemblies Database Usage APPLICATION MANAGEMENT Deploying an Application Removing an Application CONCLUSION Page 2 of 45

3 1. Introduction to the API Overview The Intranet DASHBOARD (id) Application Programming Interface (API) has been created to enable users to interact programmatically with id. Using the API, developers have the ability to create and manage their own custom id applications and integrate them seamlessly within the existing id framework. Customized components can also be created using the id API, allowing new functionality to be integrated into id CMS pages. This Getting Started guide is designed to explain the basics of how to use the id API, including installation information, system requirements, and the creation of basic applications and id CMS components. The id API is available on any id installation running version 4.0 or higher. A sound knowledge of both the id user interface and object orientated programming using Microsoft.NET Framework languages such as VB.NET or C# is required. Thank you for using the Intranet DASHBOARD API. If you have any questions, comments, or suggestions, please contact us at support@intranetdashboard.com. Page 3 of 45

4 Further Information Comprehensive documentation of all classes included in the id API is available from the API Documentation application in your id installation. This can be accessed via the View Documentation link on the following page within your id intranet Disclaimer The information and materials contained herein are provided "as is" without warranty of any kind, either expressed or implied. Page 4 of 45

5 2. Getting Started Creating an Application within your Intranet The first step in developing an application within Intranet DASHBOARD is to specify the details of the application in the id administration system. This initial step will create the structure of the application including the required application folders, IIS virtual directories and starting files, as well as a new Visual Studio solution that can be used to develop your application. To specify the application s details within the administration system simply log into the id Administration using a superuser account and navigate to the Administration > Utilities > API > Develop Application menu option. Figure 1: Develop Application wizard Page 5 of 45

6 The Develop Application wizard will prompt you for the details of the application you wish to create. These details include: Vendor Name The name of the vendor the application will be attributed to. Usually this will be the name of your company. Application Name The name of the application (id will use this value when creating the start-up solution files) Application Path The path used by the application. This value will determine both the URL path used to access the application by end users as well as the file system path used to store application assets. Starting Template A basic Microsoft Visual Studio solution template that can be used as a starting point for your application. There are several options to choose from depending which.net programming language and version of Visual Studio you wish to use. That s it! Once you have entered and confirmed the application s details id will automatically create a new API application, including all of the required files and folders. In order to view your new application for the first time you must first open the new application solution in Visual Studio and then build the solution. The location of the new solution file on the server file system is displayed on the final step of the Develop Application wizard. Once the solution has been built for the first time you can load the application in your web browser. To view it within id, use the path provided at the end of the Develop Application wizard. The location of the application solution file and path to access the application in the browser may also be found on the App Details tab when editing your application in the id administration system. Using Your Own Visual Studio Solution In addition to the default Visual Studio template solutions provided by id, API applications may also be created from an existing solution. To use your own solution to create an API application, simply create a zip file from the folder containing your solution file, ensuring that the application files are contained in a subfolder named /www. This zip file may then be imported as an API application using the Add Application wizard, as detailed in the Deploying a New Application in id section of this document (page 42). Page 6 of 45

7 Viewing the Application Once an application has been created in Intranet DASHBOARD and built in Visual Studio, viewing the application via the Intranet is simply a matter of entering the application s URL. The initial application created by the API template is very simple and is only provided as a guide on how to go about accessing some basic functionality of the API. Please read the Creating Pages section in this document for more information on getting started with application development. Application Display Within the id Layout By default API applications accessed using the standard path above are displayed inside the id layout in order for them to appear as a seamless part of the id intranet. When an application is displayed within the id layout it will be contained within an iframe control surrounded by the id header, footer and left and right panes. The surrounding layout components can be customized on a per-subsite basis using the Layout Manager tool in the id administration system. To view API applications outside of the id layout (i.e. without the id header and navigation, etc.) simply pass the following additional query string to the application page URL: idlayout=0. A value of 1 may also be used with this query string (i.e. idlayout=1) to display the application within the id layout (this will look exactly the same as if the query string is omitted). Figure 2: API application within id layout Figure 3 API application outside id layout Page 7 of 45

8 Understanding Installation, Paths and IIS In order to proceed with application development it is useful to understand exactly what Intranet DASHBOARD does when you create an application via the id administration interface. The following information describes the folder, file and Internet Information Services (IIS) structure that all API applications use. For the purposes of this guide we will assume that Intranet DASHBOARD has been installed in the default installation path found at: C:\Program Files\IntranetDASHBOARD\<InstanceName> If your id installation is located in a different folder, please substitute that in place of the above path in these examples. Under your id installation folder there is an API subfolder located at: C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps This folder holds your id API applications, with each API application having its own subfolder. The API Documentation application is included here by default when id is installed. After you have created an API application within id its application folder will be located at the following path, where <ApplicationPath> is the value specified when the application was created: C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps\<ApplicationPath> This is the root folder of your API application, containing the project and solution files. In addition to these files the API will also create another subfolder: C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps\<ApplicationPath>\www This folder acts as the web root for your application and is where IIS points to as the root of your application. As mentioned earlier, the entire configuration process, including creation of IIS virtual Folders, is handled automatically by Intranet DASHBOARD. This means that all you are required to do is create a new API application in the id administration system and all of the required folders and IIS settings will be created and set up for you automatically. Page 8 of 45

9 Creating Pages A simple way to get started with a new id API application is to create a new ASPX page within the application solution id created for you. This page should include a using (C#) or Imports (VB) directive to import the IntranetDASHBOARD.API namespace, and should inherit from the class IntranetPage. Class IntranetPage Description Abstract class inheriting from System.Web.UI.Page that encapsulates functionality for implementing pages within Intranet DASHBOARD. Pages inheriting from IntranetPage gain access to the Intranet property, which provides access to a number of important and useful methods and properties for accessing id data and returning information such as the current logged in user and the current subsite. More information about these properties is detailed in the sections below. Pages within your application may also inherit from the default System.Web.UI.Page class; however in this case they will not have access to the Intranet property by default. Instead the same functionality can be accessed using the static Get method of the Intranet class to return an Intranet object. (Note that for the purposes of this guide we will assume that properties of the Intranet class are being accessed using the IntranetPage.Intranet property.) Listing 1 Page1.aspx: Sample mark-up code of a page inheriting from the IntranetPage class Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.Page1" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>welcome</title> <link href="styles.css" type="text/css" rel="stylesheet" /> </head> <body> <form id="form1" runat="server"> <p>welcome to your id API application.</p> <p><asp:literal ID="LayoutMsg" runat="server" /></p> </form> </body> </html> Page 9 of 45

10 Listing 2 - default.aspx.vb: Sample code of a page inheriting from the IntranetPage class VB.NET Imports IntranetDASHBOARD.API Partial Public Class Page1 Inherits IntranetPage Protected Overrides Sub OnLoad(ByVal e As EventArgs) End Sub LayoutMsg.Text = "This application will sit within the layout of your intranet." End Class Listing 3 - default.aspx.cs: Sample code of a page inheriting from the IntranetPage class C# using IntranetDASHBOARD.API; public partial class Page1 : IntranetPage protected override void OnLoad(EventArgs e) LayoutMsg.Text = "This application will sit within the layout of your intranet."; Once you have created your new page you can begin customizing it by adding your own code, content and images, or whatever else is appropriate for the application you are developing. You may also add additional pages, classes, files and subfolders under your API application folder. Page 10 of 45

11 Utilizing id Themes Whether or not your API application interacts directly with id data, your users experience of using your application will be more intuitive if your application makes use of a consistent look and feel that fits with the rest of the id site. When your application blends seamlessly in appearance with the rest of your intranet site it provides an interface that is already familiar to the user. Intranet DASHBOARD allows visual themes to be applied to each subsite. These themes control the appearance of all applications and content under each subsite so that they share a consistent appearance. Your id API application can make use of the same themes as the rest of the id site by importing the correct style sheet and applying the required CSS classes. Pages that inherit from the IntranetPage class have access to the Intranet.CurrentSubsiteThemePath property, which returns the correct style sheet path for the subsite that the page is being viewed under. This property can be used to create a <link> tag in your page s header to load the style sheet for the current subsite theme. Listing 4 Page2.aspx: Sample mark-up code of a page header including the style sheet for the current subsite Markup <head> <title>subsite Theme Demo</title> <link href="styles.css" type="text/css" rel="stylesheet" /> <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> </head> Some styles will be applied automatically by the imported style sheet, however to fully integrate the look and feel of your application with the rest of id some additional CSS classes need to be applied to your HTML code. Full details on using id styles are available in the id Theme Guide, which is available on request by ing support@intranetdashboard.com. Page 11 of 45

12 Obtaining User Details Information about id website users, including the current user accessing the page, is available within API applications. This information can be accessed using the Intranet.CurrentIntranetUser property, which returns an instance of the IntranetUser class representing the user who is currently accessing the API application page. IntranetUser objects representing users other than the current user may be created using the Intranet.LoadUser method. Intranet.LoadUser accepts as an argument either a unique ID belonging to an IntranetUser or login credentials consisting of a username and password hash. When used with login credentials, this method can be used to validate a user s login. To calculate the SHA1 hash of the user s password use the IntranetDASHBOARD.API.Hashing.CalculateSHA1 method. Name LoadUser(Int32) LoadUser(String, String) Description Loads an IntranetUser from Intranet DASHBOARD with the specified intranetactorid. Loads an IntranetUser using the specified login credentials, returning null (Nothing in Visual Basic) if the login fails. Once loaded, the IntranetUser class exposes the following properties: Name Address GivenName Description The user's address. The user's given name. IntranetActorID The ID corresponding to the IntranetActor. PasswordHash The SHA1 hash of the user's password. Surname The user's last name. Username The user's username. These properties can be used to display basic information about the user, for example to show a personalized welcome message. IntranetUser objects are also used for security verification purposes when retrieving id data (see the Using Existing id Content section below) or to display information about which user created or last modified certain id data. Page 12 of 45

13 Listing 5 Page3.aspx: Sample mark-up code of a page utilizing the CurrentIntranetUser class to access the details of the logged in user Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.Page3" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>current User Details</title> <link href="styles.css" type="text/css" rel="stylesheet" /> <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> </head> <body> <form id="form2" runat="server"> <h3>current User Details</h3> <br /> Given Name: <asp:literal ID="GivenName" runat="server" /> <br /> Surname: <asp:literal ID="Surname" runat="server" /> <br /> Address: <asp:literal ID=" Address" runat="server" /> </form> </body> </html> Page 13 of 45

14 Listing 6 - Page3.aspx.vb: Sample code of a page utilizing the CurrentIntranetUser class to access the details of the logged in user VB.NET Imports IntranetDASHBOARD.API Partial Public Class Page3 Inherits IntranetPage Protected Overrides Sub OnLoad(ByVal e As EventArgs) ' Retrieve the current intranet user details Dim currentuser As IntranetUser = Intranet.CurrentIntranetUser ' Display the user's first name GivenName.Text = currentuser.givenname ' Display the user's surname Surname.Text = currentuser.surname ' Display the user's address Address.Text = currentuser. address End Sub End Class Listing 7 - Page3.aspx.cs: Sample code of a page utilizing the CurrentIntranetUser class to access the details of the logged in user C# using IntranetDASHBOARD.API; public partial class Page3 : IntranetPage protected override void OnLoad(EventArgs e) // Retrieve the current intranet user details IntranetUser currentuser = Intranet.CurrentIntranetUser; // Display the user's first name GivenName.Text = currentuser.givenname; // Display the user's surname Surname.Text = currentuser.surname; // Display the user's address Address.Text = currentuser. address; Page 14 of 45

15 Using Existing id Content In many id API applications there will be, at some stage, a requirement to access existing content from within Intranet DASHBOARD. The majority of user generated content within Intranet DASHBOARD can be described as an IntranetEntity. This includes content such as Subsites, Document Manager Folders, Forms Manager Forms and News Articles just to highlight just a few. IntranetEntity provides a simple way to access the shared properties of these different object types, as well as providing methods to navigate to other IntranetEntity objects. Before we get into the details of this important object, it will be useful to briefly examine the internal structure of Intranet DASHBOARD. Data within id is stored hierarchically as a structure of objects called entities. At the top of the hierarchy is the root entity, under which is stored a collection of entities representing each of the subsites in id. Under each subsite is a collection of subsite/application entities which represent the root of each application within that subsite. Each subsite/application contains a further hierarchy of entities structured according to the functionality of the application. In a typical application these entities would be a collection of categories or folders, each of which may contain files, documents, subfolders or other data items. The entity hierarchy used by Intranet DASHBOARD allows each entity to have a unique path (although not all entities are directly accessible through the id site using their path). This structure also forms the basis for inheritance of security settings within id. For example, security applied to a folder will automatically be inherited by all items within that folder unless specifically overridden on those items. Below is an example entity structure in id: URL Entity Type Description / Root entity Website root. This URL is normally redirected to the "Home" subsite. /MySite/ Subsite "MySite" subsite /MySite/News/ Subsite/Application News application under the "MySite" subsite /MySite/News/MyCategory/ Application folder News category /MySite/News/MyCategory/MyArticle/ Application entity News article /MySite/News/MyCategory/MyArticle/AnImage.png Application file Image in a news article The table above shows an example of the hierarchy of entities used to store an article in the News application. Each of these entities is represented in code by the IntranetEntity class, with the exception of the application file in the last row which is represented by the IntranetFile class. Page 15 of 45

16 Retrieving id Entities There are several methods available within the id API to retrieve id entities as IntranetEntity objects. The simplest way is to use the Intranet.LoadEntity method to directly load the entity you wish to use. The LoadEntity method requires you to know either the unique ID or path to the entity you wish to load. This is passed to the method along with an IntranetUser object, which is used to verify security access to the entity. If the requested entity does not exist or is not accessible to the specified IntranetUser then a value of null (Nothing in Visual Basic) will be returned. Name LoadEntity(Int32, IntranetUser) LoadEntity(String, IntranetUser) Description Loads an IntranetEntity from the intranet. This Entity is loaded based on the ID (IntranetEntity.ID) and user provided. If the user does not have access to this entity null (Nothing in Visual Basic) will be returned. If the entity does not exist null (Nothing in Visual Basic) will be returned. Loads an IntranetEntity from the intranet. This Entity is loaded based on the URL and user provided. If the user does not have access to this entity, null (Nothing in Visual Basic) will be returned. If the entity does not exist, null (Nothing in Visual Basic) will be returned. A second method of loading IntranetEntity objects is to traverse the hierarchy of entities until you find the entity or entities you require. Using this method you will begin with a known entity (such as a subsite or application folder) and load the collection of child entities under that object in the hierarchy. You may then locate the required child entity and repeat the process as necessary until you have located the target entity. An entity s child objects are retrieved using the IntranetEntity.GetChildren method. This method returns a collection of IntranetEntity objects representing the children of the entity it was called on. IntranetEntity.GetChildren takes as an argument a list of zero or more EntityTypes that are used to filter the returned list of entities. Name GetChildren Description Returns a List of all the entities that sit below this IntranetEntity within the Intranet DASHBOARD hierarchy/folder structure. For example, by calling GetChildren on an IntranetEntity representing a News category and filtering by type EntityTypes.NewsArticle, only child objects representing News articles will be returned. Page 16 of 45

17 Listing 8 Page4.aspx: Sample mark-up code of a page displaying entities from the id entity hierarchy Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.Page4" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>news Categories</title> <link href="styles.css" type="text/css" rel="stylesheet" /> <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> </head> <body> <form id="form1" runat="server"> <h3>list of News Categories and their News Articles</h3> <asp:literal ID="Categories" runat="server"/> </form> </body> </html> Listing 9 Page4.aspx.vb: Sample code of a page displaying entities from the id entity hierarchy VB.NET Imports IntranetDASHBOARD.API Partial Public Class Page4 Inherits IntranetPage Protected Overrides Sub OnLoad(ByVal e As EventArgs) ' Display content from News DisplayNewsContent() End Sub Private Sub DisplayNewsContent() ' Retrieve the news application object for the current subsite Dim newssubsiteapplication As IntranetEntity = _ Intranet.LoadEntity(Intranet.CurrentIntranetSubsite.URL & "news/", Intranet.CurrentIntranetUser) ' Retrieves a list of news categories in the current subsite Dim types1 As New List(Of EntityTypes) types1.add(entitytypes.newscategory) Dim newscategories As List(Of IntranetEntity) = newssubsiteapplication.getchildren(types1) Page 17 of 45

18 ' Iterate through the news categories For Each newscategory As IntranetEntity In newscategories If newscategory IsNot Nothing Then ' Print the title of the category Categories.Text &= "<br /><b> " & newscategory.title & "</b> - " & newscategory.url Categories.Text &= "<br /> News Articles" ' Retrieve a list of news articles that belong to this category Dim types2 As New List(Of EntityTypes) types2.add(entitytypes.newsarticle) Dim newsarticles As List(Of IntranetEntity) = newscategory.getchildren(types2) If newsarticles IsNot Nothing Then ' Iterate through the news articles for this category For Each newsarticle As IntranetEntity In newsarticles ' Print out the title of the article If newsarticle IsNot Nothing Then Categories.Text &="<br />" & newsarticle.title End If Next Categories.Text &= "<br />" End If End If Next End Sub End Class Listing 10 Page4.aspx.cs: Sample code of a page displaying entities from the id entity hierarchy C# using IntranetDASHBOARD.API; public partial class Page4 : IntranetPage protected override void OnLoad(EventArgs e) // Display content from News DisplayNewsContent(); private void DisplayNewsContent() Page 18 of 45

19 // Retrieve the news application object for the current subsite IntranetEntity newssubsiteapplication = Intranet.LoadEntity(Intranet.CurrentIntranetSubsite.URL + "news/", Intranet.CurrentIntranetUser); // Retrieves a list of news categories in the current subsite List<EntityTypes> types1 = new List<EntityTypes>(); types1.add(entitytypes.newscategory); List<IntranetEntity> newscategories = newssubsiteapplication.getchildren(types1); // Iterate through the news categories foreach (IntranetEntity newscategory in newscategories) if (newscategory!= null) // Print the title of the category Categories.Text += "<br /><b> " + newscategory.title + "</b> - " + newscategory.url; Categories.Text += "<br /> News Articles"; // Retrieve a list of news articles that belong to this category List<EntityTypes> types2 = new List<EntityTypes>(); types2.add(entitytypes.newsarticle); List<IntranetEntity> newsarticles = newscategory.getchildren(types2); if (newsarticles!= null) // Iterate through the news articles for this category foreach (IntranetEntity newsarticle in newsarticles) // Print out the title of the article if (newsarticle!= null) Categories.Text += "<br />" + newsarticle.title; Categories.Text += "<br />"; Page 19 of 45

20 In addition to GetChildren, the IntranetEntity class also supports the GetFiles and GetParent methods. Name GetFiles GetParent Description A Dictionary of IntranetFile objects associated with this IntranetEntity, each IntranetFile in the Dictionary has a key value of the IntranetFile Title. The parent IntranetEntity of the current IntranetEntity. IntranetEntity.GetFiles returns a collection of IntranetFile objects located under the current IntranetEntity in the hierarchy. IntranetFiles represent static files (e.g. images, uploaded documents, etc.) and have different properties available from IntranetEntities. IntranetEntity.GetParent will return the parent IntranetEntity object of the current IntranetEntity. Page 20 of 45

21 Creating id CMS Components In addition to creating pages, the id API can also be used to create id CMS components. Components created using the API may be added and edited on id CMS pages and templates in the same way as the default id CMS components included with id. If you have created a new API application using one of the provided templates from the Develop Application wizard in the administration system it will already contain an example id CMS component in the /cms folder, located under the application folder. API applications may contain multiple id CMS components. In order to add a new id CMS component to your API application the steps are as follows: Step 1 Open your application solution in Visual Studio and add a new web form (ASPX page). This page may be added to the default location in the /cms folder of your application or to any other path within your application. Step 2 Open the code behind file for your new web form and make the following changes: i. Add a using (C#) or Imports (VB) directive pointing to the IntranetDASHBOARD.API namespace. ii. Change your page to inherit from the idcmscomponent class instead of the System.Web.UI.Page class. iii. Delete the default Page_Load method and add in the following methods (OnLoad, OnLoadOfEditMode, OnLoadOfDisplayMode) as shown in the code example below: Listing 11 idcmscomponent1.aspx.vb VB.NET Imports IntranetDASHBOARD.API Partial Public Class idcmscomponent1 Inherits idcmscomponent Protected Overrides Sub OnLoad(ByVal e As EventArgs) ' Insert code that should run each time the id CMS Component loads. End Sub ' Call the underlying OnLoad, which will call OnLoadOfDisplayMode and OnLoadOfEditMode as required. MyBase.OnLoad(e) Protected Overrides Sub OnLoadOfEditMode() End Sub ' Insert code that will be run when the id CMS Component is changed to edit mode. Page 21 of 45

22 Protected Overrides Sub OnLoadOfDisplayMode() End Sub ' Insert code that will be run when the id CMS Component is changed to display mode. End Class Listing 12 idcmscomponent1.aspx.cs C# using IntranetDASHBOARD.API; public partial class idcmscomponent1 : idcmscomponent protected override void OnLoad(EventArgs e) // Insert code that should run each time the id CMS Component loads. // Call the underlying OnLoad, which will call OnLoadOfDisplayMode and OnLoadOfEditMode as required. base.onload(e); protected override void OnLoadOfEditMode() // Insert code that will be run when the id CMS Component is changed to edit mode. protected override void OnLoadOfDisplayMode() // Insert code that will be run when the id CMS Component is changed to display mode. Page 22 of 45

23 Step 3 Open the Markup view of your new web form and make the following changes: i. Add two <PlaceHolder> tags inside the <form> tags with the IDs DisplayMode and EditMode. These placeholders will contain the content to be displayed within your component when it is in display or edit modes respectively. Listing 13 idcmscomponent1.aspx Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.iDCMSComponent1" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> <link href="/includes/css/api_stylereset.aspx" type="text/css" rel="stylesheet" /> </head> <body> <form id="form1" runat="server"> <!-- Display View --> <asp:placeholder ID="DisplayMode" runat="server"> Display mode content goes here </asp:placeholder> <!-- Edit View --> <asp:placeholder ID="EditMode" runat="server"> Edit mode content goes here </asp:placeholder> </form> </body> </html> ii. Add the tags shown below inside the <head> tags of the page to import the necessary id CMS component style sheets. It is important to make sure that these style sheets are imported in the correct order (as shown in Listing 14 below) to ensure that where required, subsite theme styles are overwritten by API styles. Listing 14 idcmscomponent1.aspx Markup <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> <link href="/includes/css/api_stylereset.aspx" type="text/css" rel="stylesheet" /> Page 23 of 45

24 Step 4 Register your new component in your API application s web.config file by adding a new <add> tag inside the <CmsComponents> tags. The <add> tag should contain the following attributes: Name uniquekey title virtualpath iconpath Description A unique key used to identify each component The title of the component, which is displayed when editing id CMS templates and pages The path of the component ASPX file, relative to the www folder within the application folder The path to the image that appears before the component title on the External tab in id CMS Listing 15 web.config XML <CmsComponents> <add uniquekey="idcmscomponent1" title="my Component" virtualpath="/cms/idcmscomponent1.aspx" iconpath="/cms/idcmscomponent1icon.gif" /> </CmsComponents> Step 5 Build your API application in Visual Studio. In order to make your registered id CMS component available for use on id CMS pages it is first necessary to add it to the template(s) your pages inherit from. This may be done as follows: i. Edit the id CMS template that your page(s) will inherit from. ii. Select the Component tab, then select External and click the Set Allowed Components button. iii. Scroll through the list of components until you find your new API id CMS component and check the box next to it, and then click OK. iv. Save and exit your template. v. Repeat steps 1-4 for any other templates that you wish to make your component available on. At this point your new component will be available to include on any id CMS pages within id that use the template(s) you have added your component to. To insert your component onto an id CMS page find it on the External tab and drag it onto the page as you would with any other id CMS component. If your component is not listed on the External tab, click the Manage Components button, scroll through the list of components until you find your API application component and check the box next to it, and then click OK. Page 24 of 45

25 id CMS Component Properties In some cases your id CMS component may require further settings to be available to users in addition to those available through the edit mode interface. For example, in a component that shows an RSS feed your main edit mode interface may be used to choose the feed to display, while you also require an extra property to set how many items to display in the component. id provides a mechanism for handling these additional settings through component properties. These properties are available on the Component tab after selecting Component Properties from the component options menu while editing an id CMS page or template. Figure 4: Component properties Component properties take the form of string or Boolean values that can be set by users when your component is added to an id CMS page, and retrieved in code. When specifying a component property you can select which of the following control types will be used to edit it: Textbox used for entering string values Drop down list used to select a string value from a predetermined list of values, the value returned will be the same as the selected text displayed in the control (available only in id 4.2 and above) Checkbox used to specify Boolean values, returns a string value of either True or False when the property is accessed Page 25 of 45

26 Properties for your id CMS component are specified in your API application web.config file. Multiple properties can be defined for each component. To add a property, first locate the <add> tag for your component inside the <CmsComponents> tag in your web.config file. Each property should be added as a new <property> tag inside your component s <add> tag, and must contain the following attributes: Name uniquekey title description defaultvalue controltype defaultlockedvalue AdditionalSettings Description A unique key used to identify each property within the id CMS component The title of the property, displayed when editing component properties A brief description of the property, displayed when editing the property The default value assigned to the property the first time it is edited The type of control used to edit the property value - allowed values are textbox, dropdown or checkbox Boolean value indicating whether the property is locked so that it can be set on templates only (and not in id CMS pages). Set to False if you want users to be able to edit the property on id CMS pages. Used to set additional settings relevant to the selected control type. When controltype is textbox set this value to Password if you wish to use the textbox as a password type in order to hide its contents in the interface. When controltype is dropdown use this value to specify the list items, using as a separator. In all other instances this attribute should be left blank. Listing 16 web.config XML <CmsComponents> <add uniquekey="idcmscomponent2" title="my Component" virtualpath="/cms/idcmscomponent2.aspx" </add> iconpath="/cms/idcmscomponent1icon.gif"> <property uniquekey="txtproperty" title="textbox Property" description="this is a textbox property" controltype="textbox" defaultvalue="some text" defaultlockedvalue="false" AdditionalSettings="" /> <property uniquekey="pwdproperty" title="password Property" description="this is a password property" controltype="textbox" defaultvalue="secret" defaultlockedvalue="false" AdditionalSettings="Password" /> <property uniquekey="ddlproperty" title="dropdown Property" description="this is a dropdown list property" controltype="dropdown" defaultvalue="option 1" defaultlockedvalue ="false" addtionalsettings="option 1 Option 2 Option 3" /> <property uniquekey="cbxproperty" title="checkbox Property" description="this is a checkbox property" controltype="checkbox" defaultvalue="true" defaultlockedvalue="false" AdditionalSettings="" /> </CmsComponents> To retrieve and use the value of a component property in your code pass its unique key to the idcmscomponent.getexternalcomponentpropertyvalue method. This method is accessible when your component inherits from the idcmscomponent class, as described earlier in this document. Page 26 of 45

27 Name GetExternalComponentPropertyValue Description Retrieves the value of the current id CMS Component's property based on the uniquekey supplied. This method will return the property value as a string, or an empty string if the property has no value specified. If an invalid unique key is used the method will return an empty string. Note that property values cannot be modified in code they can only be set using the Component Properties interface in id CMS. Listing 17 idcmscomponent2.aspx.vb: Sample code of a CMS component displaying component property values VB.NET Imports IntranetDASHBOARD.API Partial Public Class idcmscomponent2 Inherits idcmscomponent Protected Overrides Sub OnLoad(ByVal e As EventArgs) ' Call the underlying OnLoad, which will call OnLoadOfDisplayMode and OnLoadOfEditMode as required. MyBase.OnLoad(e) End Sub Protected Overrides Sub OnLoadOfEditMode() End Sub ' Insert code that will be run when the id CMS Component is changed to edit mode. Protected Overrides Sub OnLoadOfDisplayMode() Dim textvalue As String = GetExternalComponentPropertyValue("txtProperty") Dim passwordvalue As String = GetExternalComponentPropertyValue("pwdProperty") Dim dropdownvalue As String = GetExternalComponentPropertyValue("ddlProperty") Dim checkboxvalue As Boolean = False Boolean.TryParse(GetExternalComponentPropertyValue("cbxProperty"), checkboxvalue) propertyvalues.text = "Text property value = " & textvalue & "<br>" & _ "Password property value = " & passwordvalue & "<br>" & _ "Dropdown list property value = " & dropdownvalue & "<br>" & _ "Checkbox property value = " & checkboxvalue.tostring() End Sub End Class Page 27 of 45

28 Listing 18 idcmscomponent2.aspx.cs: Sample code of a CMS component displaying component property values C# using IntranetDASHBOARD.API; public partial class idcmscomponent2 : idcmscomponent protected override void OnLoad(EventArgs e) // Call the underlying OnLoad, which will call OnLoadOfDisplayMode and OnLoadOfEditMode as required base.onload(e); protected override void OnLoadOfEditMode() // Insert code that will be run when the id CMS Component is changed to edit mode. protected override void OnLoadOfDisplayMode() string textvalue = GetExternalComponentPropertyValue("txtProperty"); string passwordvalue = GetExternalComponentPropertyValue("pwdProperty"); string dropdownvalue = GetExternalComponentPropertyValue("ddlProperty"); bool checkboxvalue = false; bool.tryparse(getexternalcomponentpropertyvalue("cbxproperty"), out checkboxvalue); propertyvalues.text = "Text property value = " + textvalue + "<br>" + "Password property value = " + passwordvalue + "<br>" + "Dropdown list property value = " + dropdownvalue + "<br>" + "Checkbox property value = " + checkboxvalue.tostring(); Page 28 of 45

29 Preserving Data between Edit and Display Modes If your id CMS component makes use of data that needs to be preserved between the edit and display modes of your component (e.g. a textbox in edit mode used to set text that is displayed on your component) you will need to make use of the idcmscomponentfield class. This class allows data to be passed between the two separate sets of web controls used by edit mode and display mode. To use idcmscomponentfield in your component complete the following steps for each web control whose value needs to be preserved. In this section we will use as an example a basic component that displays a welcome message to the user. Step 1 Declare a new public idcmscomponentfield object and pass the default value of the field as an argument to the constructor. Listing 19 VB.NET Public welcomemsg As idcmscomponentfield = New idcmscomponentfield("welcome") Listing 20 C# public idcmscomponentfield welcomemsg = new idcmscomponentfield("welcome"); Step 2 In the OnLoad method of your component, bind the idcmscomponetfield object to an edit mode web control using the idcmscomponent.bindcmscomponentfieldtocontrol method. The specified web control is the control whose value will be preserved. Page 29 of 45

30 Listing 21 VB.NET Protected Overrides Sub OnLoad(ByVal e As EventArgs) MyBase.BindCMSComponentFieldToControl(welcomeTextBox, welcomemsg.forminputname) End Sub MyBase.OnLoad(e) Listing 22 C# protected override void OnLoad(EventArgs e) base.bindcmscomponentfieldtocontrol(welcometextbox, welcomemsg.forminputname); base.onload(e); Step 3 Use the Value property of the idcmscomponetfield object to retrieve the preserved value. Listing 23 VB.NET Protected Overrides Sub OnLoadOfEditMode() welcometextbox.text = welcomemsg.value End Sub Protected Overrides Sub OnLoadOfDisplayMode() End Sub welcomelabel.text = welcomemsg.value Listing 24 C# protected override void OnLoadOfEditMode() welcometextbox.text = welcomemsg.value; protected override void OnLoadOfDisplayMode() welcomelabel.text = welcomemsg.value; Page 30 of 45

31 id CMS Component Help Files If your id CMS component includes a help file, this can be automatically integrated with your component by placing it in the /www/help folder under your API application folder. A link to the help file will be available from the Component Help link in the component options menu while in edit mode. In order for your component help file to be automatically linked to from the edit view of your component the file must be an HTML file, and the filename must be the same as the value registered as the title of your component in your API application web.config file, with all spaces and invalid filename characters (any of the following: \ / : *? " < > ) removed. For example, if your component title was My CMS Component, the help file must be named MyCMSComponent.html (note that the filename is not case-sensitive). Your help file may also include links to other files if required. Page 31 of 45

32 Example id CMS Component Listing 25 idcmscomponent3.aspx: Sample mark-up code of a basic id CMS component Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.iDCMSComponent3" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <link href="<%=intranet.currentsubsitethemepath%>" type="text/css" rel="stylesheet" /> <link href="/includes/css/api_stylereset.aspx" type="text/css" rel="stylesheet" /> </head> <body> <form id="form1" runat="server"> <div> <!-- Display View --> <asp:placeholder ID="DisplayMode" runat="server"> <div id="content"> <br /> <br /> <asp:label ID="Hello" runat="server" /> <br /> <br /> </div> </asp:placeholder> <!-- Edit View --> <asp:placeholder ID="EditMode" runat="server"> <br /> <br /> Name of person to say hello to: <asp:textbox ID="NameInput" runat="server" /> <br /> <br /> </asp:placeholder> </div> </form> </body> </html> Page 32 of 45

33 Listing 26 idcmscomponent3.aspx.vb: Sample code of a basic id CMS component VB.NET Imports IntranetDASHBOARD.API Partial Public Class idcmscomponent3 Inherits idcmscomponent Public WhoToGreet As idcmscomponentfield = New idcmscomponentfield("api Developer") Protected Overrides Sub OnLoad(ByVal e As EventArgs) ' Insert code that should run each time the id CMS Component loads. MyBase.BindCMSComponentFieldToControl(NameInput, WhoToGreet.FormInputName) End Sub ' Call the underlying OnLoad, which will call OnLoadOfDisplayMode and OnLoadOfEditMode as required. MyBase.OnLoad(e) Protected Overrides Sub OnLoadOfEditMode() ' Insert code that will be run when the id CMS Component is changed to edit mode. NameInput.Text = WhoToGreet.Value End Sub Protected Overrides Sub OnLoadOfDisplayMode() ' Insert code that will be run when the id CMS Component is changed to display mode. Hello.Text = "Hello " & WhoToGreet.Value End Sub End Class Page 33 of 45

34 Listing 27 idcmscomponent3.aspx.cs: Sample code of a basic id CMS component C# using IntranetDASHBOARD.API; public partial class idcmscomponent3 : idcmscomponent public idcmscomponentfield WhoToGreet = new idcmscomponentfield("api Developer"); protected override void OnLoad(EventArgs e) // Insert code that should run each time the id CMS Component loads. base.bindcmscomponentfieldtocontrol(nameinput, WhoToGreet.FormInputName); // Call the underlying OnLoad, which will call OnLoadOfDisplayMode and // OnLoadOfEditMode as required. base.onload(e); protected override void OnLoadOfEditMode() // Insert code that will be run when the id CMS Component is changed to edit mode. NameInput.Text = WhoToGreet.Value; protected override void OnLoadOfDisplayMode() // Insert code that will be run when the id CMS Component is changed to display mode. Hello.Text = "Hello " + WhoToGreet.Value; Page 34 of 45

35 Creating Custom Workflow Actions In addition to creating pages and id CMS components the id API can also be used to create custom workflow actions that can be performed on entry or exit of certain steps in a workflow process. If you have created a new API application using one of the provided templates from the Develop Application wizard in the administration system it will already contain an example custom workflow action in CustomAction.vb or CustomAction.cs in the application folder. Only one custom workflow action may be created per application. If you wish to create multiple custom workflow actions you will need to create multiple API applications. How to create a custom workflow action Step 1 Create a new API application using the Develop Application wizard and select either the VB.NET VS2010 Custom Action Example or the C# VS2010 Custom Action Example. Step 2 Open the file CustomAction.vb or CustomAction.cs which is contained in the application folder. Step 3 Update the contents of the FireAction method to handle the workflow action you wish to perform. Please note that you must not delete or alter the signature of this method, otherwise the custom workflow action will not be fired. There are certain parameters which will be supplied to this method which may be of use to you when creating your custom workflow actions. These are as follows: Name intranetentityid currentstateid intranetactorid workflowname statename Description The unique ID of the item which is being processed through the workflow The unique ID of the current state the item is at in the workflow The unique ID of the user who processed the item through the workflow The name of the workflow that the item is being processed through The name of the current state the item is at in the workflow eventtypeid An ID representing whether the event occurs on Entry (1), on Exit (2) or on a Timer (3) Page 35 of 45

36 Namespaces and Assemblies Each id API application must contain a reference to the idapi assembly, which can be found at the following path by default: C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps\lib\iDAPI.dll idapi.dll contains all of the necessary classes and functionality to interact with Intranet DASHBOARD. Types and classes in this assembly are contained in the IntranetDASHBOARD.API namespace. Name IntranetDASHBOARD.API Description The API namespace provides you with the ability to interact programmatically with Intranet DASHBOARD. The API allows developers to create and manage their own Intranet DASHBOARD Applications and id CMS Components that can work in conjunction with Intranet DASHBOARD in a manner that is seamless to end users. The API namespace also provides you with access to information that is stored within Intranet DASHBOARD. This includes details about the current intranet user, the current subsite and many of the entities that are stored within the Intranet DASHBOARD hierarchy. Page 36 of 45

37 Database Usage Persistent Data Persistent data provides a mechanism for storing simple data items in the id database, without the need to create any custom database tables or SQL. These data items are stored in the form of key-value pairs, where the key is a unique string (max. 255 chars) and the value is either a string or a byte array (useful for storing serialized objects). The Persistent Data functionality is most useful for storing limited quantities of basic information such as configuration settings for your application. Each API application uses its own persistent data store, and this information is not accessible to other API applications. Persistent Data is manipulated using the Intranet.ApplicationDataStore property, which returns an instance of the PersistentData class. This class provides the following methods: Name ContainsKey Delete KeyCollection Retrieve Store Description Determines whether the API Application's Persistent Data contains the specified key. Deletes data that was stored for your application that corresponds to the specified key. Returns a list of Keys that exist for this application. Overloaded. Retrieves the data that was stored for your application that corresponds to the specified key. Overloaded. Stores and updates basic data for your application. If the specified key already exists in your application the value for this key will be updated. Data can be stored and updated using the Store method. This method will overwrite any existing data stored under the same key name. Data is retrieved from the Persistent Data store using the Retrieve method. This method will return null (Nothing in Visual Basic) if the specified key cannot be found. The ContainsKey method returns a Boolean value indicating whether any data has been stored for the specified key within the API application. The KeyCollection method returns a list of Keys that have been stored for within the API application. Page 37 of 45

38 Listing 28 Page5.aspx: Sample mark-up code of a page demonstrating the use of persistent data Markup <%@ Page Language="VB" AutoEventWireup="false" Inherits="HelloWorld.Page5" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>persistent Data Storage</title> <link href="styles.css" type="text/css" rel="stylesheet" /> <link href="<%= Intranet.CurrentSubsiteThemePath%>" type="text/css" rel="stylesheet" /> </head> <body> <form id="form1" runat="server"> <h3>persistent Data Storage</h3> <br /> Enter your favorite color: <asp:textbox ID="FavoriteColor" runat="server" /> <asp:button ID="SubmitPersistentData" runat="server" Text="Store" /> <br /> Your favorite color is: <asp:literal ID="FavoriteColorDisplay" runat="server" /> <asp:button ID="ClearPersistentData" runat="server" Text="Clear" /> </form> </body> </html> Page 38 of 45

39 Listing 29 Page5.aspx.vb: Sample code of a page demonstrating the use of persistent data VB.NET Imports IntranetDASHBOARD.API Partial Public Class Page5 Inherits IntranetPage Protected Overrides Sub OnLoad(ByVal e As EventArgs) If Not IsPostBack Then ' Display favorite color saved in persistent data on first page load DisplayFavoriteColorFromPersistentData() End If End Sub Private Sub DisplayFavoriteColorFromPersistentData() ' Retrieve the current user's favorite color using their IntranetActorID as the key Dim favoritecolor As String = "<i>[unknown]</i>" If (Intranet.ApplicationDataStore.ContainsKey(Intranet.CurrentIntranetUser.IntranetActorID)) Then End If Intranet.ApplicationDataStore.Retrieve(Intranet.CurrentIntranetUser.IntranetActorID, favoritecolor) End Sub FavoriteColorDisplay.Text = favoritecolor Private Sub SubmitPersistentDataClick(ByVal sender As Object, ByVal e As System.EventArgs) _ Handles SubmitPersistentData.Click ' Store persistent data value of the current user's favorite color using their IntranetActorID as the key Intranet.ApplicationDataStore.Store(Intranet.CurrentIntranetUser.IntranetActorID, FavoriteColor.Text) End Sub ' Refresh the display DisplayFavoriteColorFromPersistentData() Private Sub ClearPersistentDataClick(ByVal sender As Object, ByVal e As System.EventArgs) _ Handles ClearPersistentData.Click ' Check whether the key exists in the current application's persistent data If Intranet.ApplicationDataStore.ContainsKey(Intranet.CurrentIntranetUser.IntranetActorID) Then ' If the key exists, delete the data associated with it Intranet.ApplicationDataStore.Delete(Intranet.CurrentIntranetUser.IntranetActorID) ' Refresh the display DisplayFavoriteColorFromPersistentData() End If End Sub End Class Page 39 of 45

40 Listing 30 Page5.aspx.cs: Sample code of a page demonstrating the use of persistent data C# using IntranetDASHBOARD.API; public partial class Page5 : IntranetPage protected override void OnLoad(EventArgs e) if (!IsPostBack) // Display favorite color saved in persistent data on first page load DisplayFavoriteColorFromPersistentData(); private void DisplayFavoriteColorFromPersistentData() // Retrieve the current user's favorite color using their IntranetActorID as the key string favoritecolor = "<i>[unknown]</i>"; if ((Intranet.ApplicationDataStore.ContainsKey(Intranet.CurrentIntranetUser.IntranetActorID))) Intranet.ApplicationDataStore.Retrieve(Intranet.CurrentIntranetUser.IntranetActorID, favoritecolor); FavoriteColorDisplay.Text = favoritecolor; private void SubmitPersistentDataClick(object sender, System.EventArgs e) // Store persistent data value of the current user's favorite color using their IntranetActorID as the key Intranet.ApplicationDataStore.Store(Intranet.CurrentIntranetUser.IntranetActorID, FavoriteColor.Text); // Refresh the display DisplayFavoriteColorFromPersistentData(); private void ClearPersistentDataClick(object sender, System.EventArgs e) // Check whether the key exists in the current application's persistent data if (Intranet.ApplicationDataStore.ContainsKey(Intranet.CurrentIntranetUser.IntranetActorID)) // If the key exists, delete the data associated with it Intranet.ApplicationDataStore.Delete(Intranet.CurrentIntranetUser.IntranetActorID); // Refresh the display DisplayFavoriteColorFromPersistentData(); Page 40 of 45

41 Custom Database Objects If your application requires you to store more complex data or large quantities of data it may be necessary to create custom database tables, views, stored procedures or other database objects. Each API application has access to its own database schema in the id database within which these objects may be created. API applications do not have access to database objects stored within the schemas of other API applications or the main id database schema. The Intranet.SQLDatabaseConnectionString property provides a connection string that can be used to access to your application schema within the Intranet DASHBOARD database. This connection string is unique to your application and provides you with complete access to your own database schema. This means you are free to execute any SQL or DDL commands you wish on your application. Name SQLDatabaseConnectionString Description The connection string that your application can use to store and retrieve data from the database. This connection string provides you with a private schema within the Intranet DASHBOARD database. During development of your API application the details from the provided database connection string can also be used to create and edit database objects through an external database interface such as SQL Server Management Studio. Page 41 of 45

42 3. Application Management Deploying an Application id provides a simple mechanism to share and distribute API applications that allows API applications to be easily deployed to another server. Deploying a New Application in id Packaged API applications are provided as a single zip file and can be deployed into id through the administration interface as follows: i. Log into the id administration interface using a superuser account. ii. Open the Administration > Utilities > API > Add Application page. iii. Browse to the location of the zip file containing the application to be deployed and set the folder name to be used in id by the application. iv. Click Next, confirm the entered details and click Finish to install the application. Figure 5: Add Application wizard The application will be automatically installed and set up in id and IIS. Page 42 of 45

43 An alternative method to install an API application is to extract the contents of the zip file into a folder in the following location in the file system: C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps id automatically scans all of the folders in the \<InstanceName>\API\apps folder and creates id API application URLs for them with the web address Note that when using this method the application folder name used by id will be automatically set to be the same as the name of the application folder in the zip file. If an invalid or conflicting folder name is used by the application the user will not receive a warning and the application will be unable to function. If this occurs, please use the steps above to install the application through the id administration interface instead. Packaging an Application for Deployment If you wish to distribute your API application to another server it is first necessary to package it ready for installation on other servers. Steps to package an API application ready for deployment are as follows: i. Locate the API application folder in the file system. Your application can be found in the following location (assuming id was installed in the default location): ii. C:\Program Files\IntranetDASHBOARD\<InstanceName>\API\apps\<ApplicationFolder> Create a zip file of your application folder. This zip file forms a deployment package that can then be distributed and deployed by others on their id installations. At present there is no automated mechanism in the id API to run an SQL initialization script for your application when it is deployed. If you require this functionality (eg. to create the necessary database tables for your application) you will need to add your own functionality to check whether the database is initialized and run the necessary SQL commands when required. Page 43 of 45

44 Removing an Application API applications can be removed from id using the administration interface. Note that removing an API application will cause the application and all its files to be completely removed from id, IIS, the id database and the server file system. We strongly recommend creating a backup of the application files and database objects before removing them if there is any likelihood that the application may be required again in future. Steps to remove an API application are as follows: i. Log into the id administration interface using a superuser account. ii. Open the Administration > Utilities > API > Edit Application page. iii. Click the Delete button next to the application you wish to remove, and when prompted click OK to confirm you wish to proceed. Figure 6: Removing an application Page 44 of 45