Getting started - developing applications

From Sense/Net Wiki
Jump to: navigation, search
The following guide shows you how to extend your Sense/Net portal with custom programmed logic. If you need to embed a simple web application to manage portal content or you want to add custom behaviour to your content you can start off by reading the following articles and tutorials and you will be ready to develop fancy features into your portal! You will come accross simple APIs and open source code making everything easy while developing. C# skills are required and basic javascript knowledge is also necessary for a couple of articles.

The following diagram displays an overview of the application tiers of Sense/Net ECMS and the main concepts of the foundation of this platform: the Content and its fields.

Content and field in the Sense/Net Content Repository

This guide assumes you already have a basic knowledge of managing content and building portals in Sense/Net. If you are new to Sense/Net please read Getting started - using Sense/Net and Getting started - building portals before advancing. Also, you will find some relevant information on installing Sense/Net in the Getting started - installation and maintenance guide.

Developing against Sense/Net Content Repository

ASP.NET Webform portlets

How to create and install a Portlet - An itroduction about how to write your first Sense/Net portlet.

Remote API

OData REST API - Accessing the Sense/Net Content Repository with a standardized RESTful API, namely OData. Sense/Net content and functionality is exposed via HTTP, so you can create any applications on a robust and performant content repository.

We also offer a client SDK (Client library) for .Net developers to be able to manage content in the repository without having to write http requests.

.NET API

Most common API calls - You can check out the most common .Net API here for server-side development.

Setting up your development environment

Development environment
If you plan to use Sense/Net in production it is advised to create a convenient development environment that will enable you to install your repository with just a single click and also to bind your solution to source control. This article will guide you step-by-step to show you how we at Sense/Net manage our custom Sense/Net based customer solutions:

Most common API calls

The following article shows some common scenarios for which common API calls are used. The following scenarios are explained:

  1. Authentication
  2. User creation
  3. Adding users/groups into another group
  4. Creating a Workspace
  5. Adding a Folder
  6. Uploading a File
  7. Setting ACLs
  8. Checking permissions
  9. Searching workspaces

Developing portlets

Portlets
Let's start with creating portlets! Sense/Net portlets are based on ASP.Net Webparts. The base class for a Sense/Net portlet is PortletBase but you can use a couple of pre-defined portlet types like the following:
  • CacheablePortlet: when using this class as the base class portlet output cacheing functionality will be included in your portlet and a Cache tab will appear on the portlet properties dialog.
  • ContextBoundPortlet: inheriting from this class will allow you to reach context binding functionality from code using the ContextNode property and a Context binding tab will appear on the portlet properties dialog. Note that a ContextBoundPortlet is also a CacheablePortlet.
  • ContentCollectionPortlet: this is a common portlet used to handle collections. Derive your portlet from this class to get some collection related functionality like the GetModel() function returning an object containing the current child collection. A Collection tab will appear on the portlet properties dialog where builders can define the current collection.

It is highly recommended to develop cacheable portlets all the time. Cacheing can be switched off on cacheable portlets any time, but the only way to make non-cacheable portlets cacheable is to rewrite them.

Implementing custom logic can be done just like implementing a custom ASP.Net Webpart. The following how-to shows how a simple portlet can be created from scratch:


Content and Node API

Content API
Now that you know how to execute your custom code on the portal using your own portlets it's time to jump into the content API of Sense/Net! Content in Sense/Net is presented in two layers:
  • Node: this is the storage layer for a Content. It is the parent type of all ContentHandlers, that define properties that are persisted to the database and implement custom storage-related logic. Use this class whenever you need to perform low-level operations on Content, like creating, moving, copying, deleting, etc.
  • Content: this class is the presentational layer of Content and it is built above the Node layer. You can always initialize a Content from a Node. The main difference between the Node and the Content is that while the Node contains properties that are the low-level representation of data persisted to the database, the Content contains Fields that are built above the property data with extended logic. The upper presentational layers (ContentView) also rely on field logic so you should use the Content class whenever it has anything to do with presenting Content on a UI or accessing custom logic of Fields.

To understand more of the above concepts read the corresponding reference documentation:

Note, that the Node is an abstract class and the Content Type hierarchy is represented by derived types. The most basic Node is the GenericContent which is the ContentHandler of the GenericContent Content Type. There is some custom logic implemented on GenericContent so it is useful to get acquainted with this type when developing applications over the Content Repository:

Creating new Content can be done via either the Content or the Node API. You can create new Content by instantiating derived classes of Node (ie. User, Folder, File etc.) or using the Content.CreateNew static method. Also, you can create Content from templates. For the latter, the following documentation will be helpful:

Using ContentViews from code

Content View
Creating a ContentView and presenting it in a portlet is no big deal. You can use the static Create methods on the ContentView class and add the created control to the control collection of your portlet. You will need a Content instance to provide since the ContentView is the presentation of a Content and it relies on its Fields. You can either use the CommandButtons control on a ContentView to handle Content operations like saving the content, or you can use functions of the ContentView for validating and updating Content Field values from user input. Read more about using ContentViews from code here:

You can read more about using the CommandButtons control and how to attach to CommandButtons' events here:

Creating custom Field Controls

FieldControl
A Content View displays Field values of a Content via Field Controls. A Field Control is an ASP.Net UserControl that defined some methods for using within Content Views (ie. GetData(), SetData() methods for data transfer between the control and the content's Field). A Field Control can be used in templated mode meaning that the ASP.Net layout is defined either in a separate file under the folder /Root/Global/fieldcontroltemplates or in the Content View as an inline template. The following how-to shows you how to develop a FieldControl to present the value of a Content's Field in a custom way:

You can find examples for built-in FieldControls in the source under the folder Portal/UI/Controls/FieldControls. Read more about Field Controls here:

Creating custom Fields

Field
To create a custom Field you have to define your own class derived from the Field baseclass. You will have to override methods like ConvertFrom() and ConverTo() for exchanging data between the Node property holding the Field value's stored data (storage layer) and the FieldControl presenting the Field's value. There are methods available for controlling importing and exporting of the Field's value and also for presenting the Field in an XML to be used with XSLT rendering. You can find examples for built-in Fields in the source under the path ContentRepository/Fields. Read more about Fields here:

The field's configuration and validation is handled by a FieldSetting object. In many cases it is desired to define custom field validation logic, for which implementing a new FieldSetting class can be a useful extensibility point:

Creating custom ContentHandlers

ContentHandler
You are already familiar with the different presentational layers of Content (Content and Node - or Content and ContentHandler). It's time to see how you can extend the default behavior of your custom Content Types! Read the following article to get acquainted with the various possibilities a custom ContentHandler allows you to exploit:

Also, the following tutorial might be helpful:

The above articles showed you how to implement logic to customize content operations on your type or create special properties. It is also possible to create a ContentHandler that handles url requests to the Content and generates custom response. For example you could create a Content Type for sitemap configurations, and when the sitemap configuration Content is requested in a browser, the ContentHandler for the type returns the sitemap with the given configuration in XML format - simply using the common IHttpHandler interface. This next tutorial shows you how it's done:

NodeObserver

NodeObserver
Implementing custom logic for content operations can be easily done by writing custom ContentHandlers - as you have seen above. You also have the possibility to achieve this from a class being independent of ContentHandlers - only observing content operations - by creating a NodeObserver. This is useful when you want to attach the exact same behavior to multiple types or when your logic is not related to Content Types but for example to paths in the Content Repository. You could for example log whenever a new content is created under the folder /Root/Myfolder. Read the following documentation to learn more about NodeObservers:

UI Tools: Css and Javascript

Javascript control
When a FieldControl, a user control, or an XSLT renderer uses a Css file for custom appearance or uses a javascript file for providing client-side functionality referencing these files is easily done using static functions of the UITools class. Read the following article to see how you can reference Css or JS files from code:

This following how-to shows you how to integrate client-side scripts into Sense/Net server controls (this one shows you how a FieldControl with javascript logic is created but the same technique can be applied to Portlets and user controls):

It is sometimes useful to implement the complete UI layer using HTML and javascript instead of ASP.Net. The easiest way to do this is to use Mvc controller services to provide server-side functionality. This next how-to shows you how it's done step-by-step:

Creating and using custom user controls

Advanced control
You already know how to implement an ASP.Net application in the form of a portlet. To enable builders to modify the layout of your applications it is wise to prefer using ASCX files to define controls and layout instead of hard-coded controls created from code. Go through this next simple how-to in order to learn the basics:

As you've noticed in the above tutorial the created portlet became very simple since most of the application logic was implemented in the code-behind of the used ASCX file. This means that a single thin portlet could host your various applications. For this reason the system comes with a special portlet designed to host custom ASCX controls:

Using an ASCX also has the advantage that you can write inline code between the markup. This allows you to create simple applications containing only a couple of codelines and the markup within one single file. It is also possible to take advantage of some built-in Content-presentation features like paging and sorting within a single ASCX. The next tutorial shows you a good example for this:

Developing custom Actions

Custom Actions
Creating a Smart Page for Content Types and creating action links to allow the user reach the functionality can be done in Sense/Net just by clicking around. This section shows you how to do some more advanced stuff when it comes to Action links and Applications like a Smart Page. First of all, you should develop a custom Action when you need to achieve any of the following:
  • to create an action link for redirecting the page to a custom location
  • to control the visibility of the action link from C# code
  • to run custom javascript when clicking the action link instead of redirecting to a page

The following tutorial shows the tricks for implementing a custom Action:

For developers who want to create actions that are accessible through the OData API:

You can also create Applications like a simple Smart Page with advanced functionality controlling the response for the request. The next how-to shows an example for doing this:

Another aspect of extending the functionality of the Smart Application Model with programmed logic is creating custom Scenarios. You could already come accross the concept of Scenarios when displaying an action link on a content for a Smart Page. A scenario is basically a defined list of actions. There are some custom built-in scenarios that build up their lists using special logic: the New scenario for example collects the available Content Types in a given context and provides action links to create content of the available types. To build a custom action link list you can create your own scenario, just read the next tutorial to get into picture:

Tracing, logging, debugging

Logging
Sense/Net provides you simple APIs to help you in the process of developing custom applications. Tracing your application is no big deal: just launch DebugView and read the following article:

You can easily create applications that log events and errors using the portal's logging framework. This next article let's you know everything about using the logging API and configuring logs:

Debugging your applications is done the same way you would do it with any ASP.Net application. Just run the portal on your localhost and attach your Visual Studio to the process of your web server! The following how-to helps you in debugging the portal's code if you need to understand underlying portal mechanisms:

Developing console applications

Console application
You can easily develop console applications that access the portal by creating a new Console Application project and referencing portal dll-s (referencing SenseNet.Portal.dll, SenseNet.Storage.dll and SenseNet.ContentRepository.dll will let you access most of the API functionality). Creating a correct application configuration is of crucial importance as the App.config will hold all the necessary information to access the portal and to use API functions (configuration settings like ConnectionStrings, loggingConfiguration, etc.). To set up proper communication between your console application and the portal you will need to have MSMQ installed on your system and you have to make sure that the portal's web.config and your application's configuration is set up properly to use the same MSMQ channel. This next how-to summarizes everything you need to do in order to create your custom console application:

Custom settings

Custom settings
When developing applications you will probably run into the problem of making your applications configurable to enable users to fine-adjust the logic of your apps. When the configuration affects the behavior of a single portlet only then the most straightforward way of making your application configurable is to use portlet properties.

When you need configuration values that are essential during system startup, you can store them in the Web.config file. In all other cases the best practice is to use the Settings infrastructure that is available from Sense/Net 6.3. It handles caching and you can retrieve strongly typed values through a simple API.


Congratulations! You have finished the Getting started guide on developing applications under Sense/Net! You are now able to create portals fully customized to your needs. You can check out the How-tos page to see more tutorials or you can return to the Main Page and check out other Getting started guides to get acquainted with other areas of Sense/Net!

Localization and globalization

Localization
Sense/Net ECMS is a perfect choice for enterprises or companies providing portals for a huge audience, where accessing a site in different languages is crucial. We provide an easy way for clients to localize the core Sense/Net system, and an API for developers and portal builders for creating globalized features in Sense/Net.