help.axcms.netAxinom Logo
Save Save Chapter Send Feedback

Developer guide for Silverlight template project

 

Introduction

SilverlightSample project is an example project for implementation of the idea how to provide dynamic content for Silverlight application. The project is using AxCMS functionality for providing alternative user experience for website visitors who have Silverlight installed in their browser.
Site editors can create content that is used for both standard HTML (Silverlight not installed clients, search engines ) and Silverlight application.


Understanding the relations and content between projects in the solution

The solution contains following projects:

1. AxCMSTemplates_SilverlightSample
2. Create_SilverlightSample
3. Extras
4. ExtraServices
5. Resources_SilverlightSample
6. SilverlightDemo
7. SilverlightSample.BL

8. UnitTests_SilverlightSample

Bold marked projects contain important logic for the solution.

The structure of the solution is generally same as other Axinom Sample projects (Sample, Premium Sample). There is additional project for Silverlight 2.0 application: SilvelightDemo. Having this project located in the same solution, lets us configure the location of compiled application. In this solution, compiled application location is under folder AxCMSTemplates_SilverlightSample\Silverlight.
It is important to understand that this is the root folder for Silverlight application. Application cannot access the resources from server, that are located in upper folder(s). For this reason, there is one workaround used in this solution. During installation, you have created 'upload'  virtual directory, pointing to AxDocuments upload folder.  By this workaround, silverlight application can access AxCMS server side files (images, ... ).


General concept behind the solution is following:

There is additional Channel defined in template project CmsSite.xml. The channel has specific rendering engine implementation (AxCMSTemplates_SilverlightSample\RenderEngines\SilverlightRenderEngine.cs). AxCMS generates content for both Standard and Silverlight channels.
SilverlightTemplate.aspx under template project is implementing the check of Silverlight installation and switch to Silverlight version.

Silverlight application is running as client in browser after it has been downloaded. It contains general functionality of the application and also implementation of dynamic controls' Silverlight version.  Silverlight application is using Webservice for getting information from webserver. For example: information about navigation points, information that is required for the controls on pages etc. is exchanged over webservice.

SilverlightSample.BL project contains the implementation of webservice and its webmethods.


Rendering the content of the pages

Special rendering is important part of SilverlihtSample solution. Silverlight is using XAML content for representation of controls and content. Special rengering engine is creating information in required markup so that Silverlight application is able to present the information.
Rendering engine contains implementation of 4 kind of AxCMS objects: AxLabel, AxImage, dynamic control, structure element.


Rendering AxLabel


In AxCMS, AxLabel usually contains fragments of html.  Since AxCMS 8.5, there is tinyMCE version that is following xhtml standards.
The rendering technique for AxLabels is using simple xHTML - >  XAML  conversion with help of XSLT transformation. The transformation rules are described in template project, file RenderEngines\HtmlToXaml.xslt .

Please note that xslt transformation is expexting correct XML as input. Therefore, some characters are replaced before performing the transformation. The current replacements can be found from transformer class located in RenderEngine  folder.


Rendering AxImage


AxImage rendering has no deep logic behind. There is only one issue that should be taken into account: the format of the images. As Silverlight supports only PNG & JPEG image formats, there may be need to avoid rendering of other formats at all. This is an easy customization and can be added quickly.  Although, please consider using only supported formats  for your content, as same image files can then be used for different channels.


Rendering Dynamic control


Dynamic controls use special approach in SilvelightSample solution. At first, you have to have special control for Silverlight created with desired dynamic functionality. There are also special  SilverlightSample specific configuration fragments in CmsSite.xml  config file.

For every dynamic control, add following additional TAGs :

1. SilverlightControlName
2. SilverlightNamespace
3. SilverlightTagPrefix

An example config of DocumentRotator control in CmsSite.xml

      <ElementTemplateDefinition axid="dyn_2001" description="DocumentRotator">
...
          <SilverlightControlName>DocumentRotatorControl</SilverlightControlName>
          <SilverlightNamespace>
              <![CDATA[xmlns="http://schemas.microsoft.com/client/2007"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:custom="clr-namespace:SilverlightDemo.AxCMSControls;assembly=SilverlightDemo"]]>
          </SilverlightNamespace>
          <SilverlightTagPrefix>custom</SilverlightTagPrefix>
         ...
      </ElementTemplateDefinition>

Those 3 tags are taken into account during rendering. Example of result in XAML is something like this:

<custom:DocumentRotatorControl 
xmlns="http://schemas.microsoft.com/client/2007"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:custom="clr-namespace:SilverlightDemo.AxCMSControls;assembly=SilverlightDemo"
Parameters = "CategoryID=1022" />

As you notice, render engine can also parse control Parameters that are defined for dynamic controls. This way, you can easily implement the behaviour of your Silvelight version of dynamic control to use all the parameters. The parameters are serialized during rendering, and they are deserialized in Silverlight application. Check some existing dynamic controls and see how easy it is to use them on Silverlight side.


Rendering Structure element

For rendering structure elements, general AxCMS rendering approach is used.  There are only 2 main points that must be defined for the control:

1. Control's Silverlight channel file location

For example:
      <ElementTemplateDefinition axid="ImageText" description="Image(left) - Text">
          <Files>
              <File channel="Normal">CustomElements/ImageText.htm</File>
              <File channel="Silverlight">CustomElements/Silverlight/ImageText.xaml</File>
          </Files>
          <Placeholders>
              <Placeholder axid="imagePlaceholder" />
              <Placeholder axid="textPlaceholder" />
          </Placeholders>
      </ElementTemplateDefinition>

2. Indicated file must have the placeholders defined.

Silverlight specific issues

There are some issues that have to be taken into account when we are loading external XAML (so-called: loose XAML):

1. Namespaces for the controls are very important and they have to be correct.
Please check the existing controls and their namespaces for example.

2. Loose XAML files are not compiled with an application, which creates the following limitations:
    * They do not allow external assemblies
    * No use of classes, code-behind (or any C#)
    * No two-way databinding

Customizing, developing the webservice

The solution contains an important webservice and 2 references to the same webservice.
SilvelightSample.BL project contains the webservice in SLWebAPI.AxCMSSilverlightServiceProxy.cs . The same service is referenced from Template project and ExtraServices.  And finally, SilverlightDemo is using the same service, has the information about service definition and description for implementing the data queries over webservice.

It is obvious, that we are using the webservice from template project. Silverlight application will know the location of runtime webservice this way. Having the reference from ExtraServices, has different purpose. AxCMS is authenticating by default all requests that are sent for Management System. This means that also requests to webservice are authenticated. Unfortunately, Service Reference for Silverlight project does not support authentication.
The workaround for this is to have service reference under ExtraServices. Then you can add the reference for SilverlightDemo to point to
http://localhost/AxCMSPublishService_SilverlightSample/ExtraServices/AxCMSSilverlightWebService.asmx


You may need to change/add/remove some methods from the webservice and update the reference after that. Please note that there maybe problems with "Update Service Reference"  in Visual Studio 2009 SilverlightDemo project. The easiest workaround is to delete the existing "AxCMS" reference and add it again with same name.

Troubleshooting Silverlight content loading

Here is initial checklist if you have problems with customizing the solution:

Check the content that is rendered

Check, which is the rendered content of the pages. Note that Managament System and Live System are acting differently about the source of pages. Management System is using channel's direct URL and Live System is using published resource.


Debugging the rendering process


Sometimes there may be problems with rendering content. Interactive debugging can be attached for Management System requests. Rendering process is running on server side. Debug your server process and check if that is still a problem.


Debugging Silverlight application


It is prossible to debug Silverlight application. The correct process for this is browser process. Please be sure that you are using Silverlight type  process when attaching the debugger.

It is important to understand for debugging that Silverlight application is loading content from Server with asynchronous webClient methods.


Checking which requests are sent from client to webserver

Since Silverlight application is running as client in browser, you can track, which requests are sent to the server and which responses do they get.  Very useful tool for tracking the requests is Fiddler HTTP debugging Proxy. Newer Fiddler2 has also quick support for Firefox debugging.