ADAM Blog

Extending the classification browser

Ever wanted to display records via a classification browser? The ADAM ClassificationTree control makes this easy for you. All you need is a... ClassificationTree control and a couple lines of code.

This example shows you how to accomplish this.

Example

Create a web page containing an AdamPageManager and a ClassificationTree. The AdamPageManager (required on all ADAM pages) manages all kinds of page events, such as gathering and showing messages when needed.
Obviously, we also need a ClassificationTree control on this page.

<awc:AdamPageManager id="ctrAdamPageManager" runat="server" />
<awc:ClassificationTree ID="ctrTree" 
   OnClassNodeChildAdding="ctrTree_ClassNodeChildAdding"
   OnSelectedNodeChanged="ctrTree_SelectedNodeChanged" 
   AutoPostBack="NodeSelect" runat="server" />

IIn the code-beside, the ClassNodeChildAdding event is used to create new textnodes where we:

load the records, classified in the current classification and containing at least one file.
determine the imageurl based on the resolution of the record's master file. This will give the user a quick view on the resolution of the record's file.
create a new textnode where the label is the record's filename.
add this textnode to the list of childnodes of the current ClassNode.

protected void ctrTree_ClassNodeChildAdding(object sender, ClassNodeCancelEventArgs e)
{
  ClassificationHelper classHelper = new ClassificationHelper(AdamHelper.DefaultApplication);
  if (!classHelper.HasChildren(e.Classification.Id))
  {
    // Search for records with the  following restrictions:
    // 1: The number of files should be at least 0
    // 2: The records should be classified in the current classNode
    string expression = "FileCount > 0 AND DirectClassification.Id = ?";
    RecordCollection records = new RecordCollection(AdamHelper.DefaultApplication);
    RecordLoadOptions options = new RecordLoadOptions();
    options.PreLoadClassifications = false;
    options.PreLoadFields = string.Empty;
    options.PreLoadFileFields = string.Empty;
    options.PreLoadFiles = PreLoadFile.FilesVersions;
    options.LockMode = LockMode.ReadUncommitted;

    records.Load(new SearchExpression(expression, new object[] { e.Classification.Id }), string.Empty, options);
    foreach (Record record in records)
    {
       ImageUri uri = new ImageUri(record, ImageType.Preview);
       TextNode node = new TextNode(record.Files.LatestMaster.FileName, record.Id.ToString(),
       this.GetImageUrl(record.Files.LatestMaster), uri.ToString(), "_blank");
       e.Node.ChildNodes.Add(node);
    }
  }
}

A remark on performance

It's important to know that we need to minimise the number of record loads as much as possible. Recordloadoptions are very useful to do that. In these options we specify:

that the record's fields and classifications should not be loaded because the're not used.
the lockmode is set to readuncommitted, which basically means that the data is gathered with an optimal performance. This makes the impact on the sql server lower than when using the default lockmode.

Running this web page will give you the result shown below. As you can see, this example makes it easy to distinguish high-res from low-res images:

Hacking with Fiddler to make cross-site XmlHttpRequest work in FireFox

Today's web is all about AJAX. Google Mail, Facebook, Twitter, and just about everyone else uses it these days thanks to the helping hand of libraries such as Microsoft AJAX, jQuery and others. At the base of all of this technology is the XMLHttpRequest object that performs background requests to provide asynchronous updates. While being the cornerstone of today's web, it has also spawned interest from the wrong kind of developers, and security became a concern.

In the older days, this problem was 'fixed' by browsers in different ways. But more recently, a new standard was adopted by W3C (the folks that set the web standards) called Cross-Origin Resource Sharing". It has been introduced in Firefox 3.5 and Safari 4.

This is why you'll have a hard time calling web services from JavaScript in these browsers, unless the service specifically implements the access control features described in the standard. And since most services that our outside of your domain are also outside your control, you can't change them to include support for this new standard.

Which is why I was having a hard time implementing my client-side proof of concept for a future version of our product. It took me a while to figure out that the problem came from this new implementation, since FireFox does not let your request fail, it simply strips out the content.

If you look in FireBug and see a response like this, you'll know why:

To your code, the request will have succeeded (unless you specified that the result was of the form 'xml' or 'json'), but there won't be any result to parse. This can be quite a nuisance if you're just trying something out in a local html document, and at least in FireFox 3.6, there is no way to turn this 'restriction' off.

However, I was able to trick it by using Fiddler. Fiddler is a web proxy used to diagnose HTTP requests and responses, but it can do much more than just inspecting. You can do all sorts of nifty things like changing requests and replies in flight.

I added a custom rule to Fiddler, using the following code:

 static function OnBeforeResponse(oSession: Session)
    {
        ...
        
  if (oSession.HostnameIs("services.aonaware.com")) {
   oSession.oResponse.headers["Access-Control-Allow-Origin"] = "*";
  }
  
  ...
    }

This rule adds the required header for FireFox to allow the result to be parsed by your client-side code:

Note that this doesn't work unless you have Fiddler with the custom rule running on the client machine, so you'll have to resort to other options when creating real applications, but to me it's fine for quick tinkering.

Strongly Typed Searching in ADAM, part 2

Remember part 1 of Søren Trudsø Mahon's article of DXP? Who's up for part two? Here goes:

In part 1 we saw how to use the API, in this post we’ll have a look at the implementation behind this.

The interface of the API

To do this, we've created a fluent API for searching ADAM objects: inspired by this series of blog posts:
http://www.lostechies.com/blogs/gabrielschenker/archive/2010/01/03/fluent-silverlight-fluent-api-and-inheritance.aspx
http://www.lostechies.com/blogs/gabrielschenker/archive/2010/01/03/fluent-silverlight-fluent-api-and-inheritance.aspx

To start off with we created an extension method (new feature in c# / .net 3.5) on the Application object like this:

namespace Adam.Core 
{
    public static class ApplicationSearchExtensions 
    {
        public static AdamSearch Search(this Application @this) 
        {
            return new AdamSearch(@this);
        }
    }        
}

We have put this inside of the Adam.Core namespace, this way we don’t have to remember to include our namespace wherever we want to call Search on the Adam.Core.Application object. (We’ll probably end up putting the AdamSearch behind an interface, and having a factory for creating the AdamSearch, enabling us to mock our search). The AdamSearch class is our entry into searching, in here we define the root types you can search on:

public class AdamSearch 
{
    private readonly Application application;

    public AdamSearch(Application application) 
    {
       this.application = application;
    }
        
    public IUserSearchRoot User 
    {
       get { return new UserSearch(this.application); }
    }

    …
}

The class xxxSearch represents the adam object we are searching for, this is hidden behind an interface IxxxSearchRoot. The keywords are defined in interface, IUserSearchKeywords and ISearchKeywords:

public interface IUserSearchKeywords<TSearchParent, TItem, TCollection>
    : ISearchKeywords<TSearchParent, TItem, TCollection> 
{
    TSearchParent Name(string name);
}

public interface ISearchKeywords<TSearchParent, TItem, TCollection> 
{
    IUserSearchKeywords<TSearchParent, TItem, TCollection> CreatedBy 
    { 
      get; 
    }

    TSearchParent Id(Guid id);

    TSearchParent Id(Operator @operator, Guid guid);

    TSearchParent Id(IEnumerable<Guid> ids);

    TSearchParent CreatedOn(Operator @operator, DateTime time);
}

We have methods and properties which correspond to the keywords in the Adam Help. Properties are links to other objects. For example:
CreatedBy.Name("administrator") corresponds to createdby.name = administrator

Methods are actual criteria. For example:
Id(user.Id) correspondents to id = 'C899EFCB-440E-487F-A007-09A9043E678F'

Pretty simple, but showing that our API correspondents to the Adam search.

The TSearchParent generic parameter is used as a placeholder for the kind of search we are performing. That is, if we are performing a RecordSearch this will refer back to an IRecordSearch where the keywords for searching for records are defined. This enabled me to chain the keywords like this:

Application.Search()
  .User.CreatedBy.Name("dxp-stm")
  .CreatedOn(Operator.LessThan, DateTime.Now);

Implementing the API:

We've created a “big” base class where all of the main loading functions and common keywords are implemented:

This class has the responsibility of:

All the search operators that are common to all Adam objects (Id, CreatedBy, CreatedOn...)
Executing queries (delegated to the SearchExecutor).
Collection all search expressions (delegated to SearchExpressionProvider)
Executing queries when we have no search expression yet (Load(Guid Id) and Load(IEnumerable<Guid> ids).

Interesting bits are the implementation of keywords which lead to adding a search criteria to our search expression. But also how we refer to other ADAM objects.

Implementation of keywords in SearchBase.cs:

public TSearchParent Id(Guid id) 
{
    return AddEq("Id", id);
}

protected TSearchParent AddEq(string path, object value) 
{
            return Add(path, Operator.Equal, value);
}

protected TSearchParent Add(string path, Operator @operator, object value) 
{
    ExpressionProvider.Add(ParentPath + path, @operator, value);
    return this.SearchParent;
}

Implementation of keywords in SearchBase.cs -> SearchExpressionProvider:

public void Add(string expression, Operator @operator, object value) 
{
    expression = string.Format("{0} {1} ?", expression, 
        GetOperator(@operator));
    Add(expression, value);
}

public void Add(string expression, params object[] parameters) 
{
    this.expressions.Add(new SearchExpression(expression, parameters));
}

Implementation of “references” to other objects go like this:

public IUserSearchKeywords<TSearchParent, TItem, TCollection> CreatedBy 
{
    get 
    {
        return new UserSearch<TSearchParent, TItem, TCollection>(
            Application, ExpressionProvider, SearchParent, 
            ParentPath, "CreatedBy");
    }
}

And specifically for User we have two classes called UserSearch and UserSearch<TSearchParent,TItem, TCollection>:

The source for these are trivial, and the keywords are like in SearchBase, so it’s mostly constructors, but a couple of things to note about UserSearch is that this closes our chain of parents and inside the constructor it “closes” our chain of parents by setting this to parent. (And this is maybe what I hate most about our current implementation, I would like to put this responsibiliy within my base class, but I just can get my head around that).

public class UserSearch
    : UserSearch<IUserSearch, User, UserCollection>, 
      IUserSearchRoot, IUserSearch 
{
    public UserSearch(Application app)
        : base(app) 
    {
        this.SearchParent = this;
    }
}

public class UserSearch<TSearchParent, TItem, TCollection>
    : SearchBase<TSearchParent, TItem, TCollection>,
      IUserSearchKeywords<TSearchParent, TItem, TCollection>,
      IUserItemLoader<TItem>,
      IUserSearchLoader<TItem, TCollection>
    where TItem : ExtendedItemBase
    where TCollection : ExtendedItemBaseCollection 
{
    public UserSearch(Application app)
        : base(app) 
    {
    }

    public UserSearch(Application app, SearchExpressionProvider expressionProvider, TSearchParent searchParent, string parentPath, string path)
        : base(app, expressionProvider, searchParent, parentPath, path) 
    {
    }

    #region Implementation of IUserSearchKeywords<TSearchParent,TItem,TCollection>

    public TSearchParent Name(string name) 
    {
        return AddEq("Name", name);
    }

    #endregion
}

And then we've got a lot of interfaces:

Basically we have interfaces for doing

Load(Guid id) and Load(IList<Guid> ids):
IUserItemLoader<TItem>: IExtendedItemLoader<TItem>
A Load() using searchexpressions:
IUserItemLoader<TItem>: IExtendedItemLoader<TItem>
Keywords:
IUserSearchKeywords<TSearchParent, TItem, TCollection>: ISearchKeywords<TSearchParent, TItem, TCollection>

These interfaces are all implemented by UserSearch<TSearchParent, TItem, TCollection>, but we never expose that class in our API. That way we can control which operations are available to the consumer at anytime.

Conclusion

That’s where we are now, we got the foundation, but we still need to add keywords, but adding keywords is pretty easy, add it to the IXxxKeywords interface and then implement it in the class that “complaints”, so it’s something we will add along the way and whenever Adam adds new keywords.
And also we’ve created a Resharper template for creating a new Adam object for searching because the object structure and the interfaces needed are very similar, they only differ on the adam object name.

Strongly typed searching in ADAM

This article is soooo cool, and it is so for several reasons.

First, I didn't write it. The idea, the development and writing the article are all done by Søren Trudsø Mahon from our ADAM partner DXP. Second, this isn't going to be a single blog post. This is only part one of three blog posts! This one gets you interested I'm sure, more details (and code!) will follow in the coming days. Stay tuned if you want to learn more about this! Third. It's one of those things that any self respecting developer will see and say "Cooool". But that's just my humble opinion.

Anyway. Enough said. Next is Søren speaking:

Adam’s search is strong, very strong indeed. But as a developer we don’t like to write magic strings in our code:

new SearchExpression("Ancestor.Id = ?", 
  new object[] { classification.Id })

And also we don’t have any type safety with regards to the value we are searching for:

new SearchExpression("Ancestor.Identifier = ?", 
  new object[] { classification.Id })

Which will give us a runtime error. So, what we would like to be able to write is a query like this:

Application.Search()
  .Classification
     .Ancestor.Id(classification.Id)

This combines the power of strongly typed statements and the familiarity of Adam search.

Using the api:

The api is created as an extension method on Adam.Core.Application called Search(), from there you select what you want to search on fx. App.Search().Record or App.Search().Classification.

On “the” first level of the “chain” you can use the Adam Load methods Load(Guid id) or Load(IList<Guid> ids) to just directly load object of that type

IEnumerable<Record> enumerable = app.Search().Record.Load(
  new[] {record1.Id, record2.Id})

Or you can perform an actual search.

IRecordSearch identifier = app.Search().Record
    .Classification.Identifier("First");
RecordCollection records = identifier.Load();

You could also just the SearchExpression without loading any items and use that against a helper:

IRecordSearch identifier = app.Search().Record
    .Classification.Identifier("First");
new RecordHelper(app).Exists(identifier.Expression);

And you can refine your search expression in multiple lines:

IRecordSearch identifier = app.Search().Record
    .Classification.Identifier("First");
identifier = identifier.CreatedBy.Name("administrator");

Search examples:

var rootIdentifier = "First";

// "Searching for a single Classification"
var rootClassification = app.Search().Classification
  .Identifier(rootIdentifier).Single();

// "Searching for underneath classification with identifier 'First'"
var classificationSearch = app.Search().Classification
  .AncestorOrSelf.Identifier(rootIdentifier);
classificationSearch.Print();

// "Refining the expression to include only those created 
// by 'administrator'"
classificationSearch = classificationSearch
  .CreatedBy.Name("administrator");
classificationSearch.Print();

// "Using search expression against helper"
SearchExpression classificationSearchExpression = 
  classificationSearch.Expression;
Console.WriteLine("SearchExpression:{0}", classificationSearchExpression);
var exists = new ClassificationHelper(app)
  .Exists(classificationSearchExpression);
Console.WriteLine(exists);

// Load using just the id (actually uses ExtendedItemBase.Load(Guid id))                
Classification classification = app.Search().Classification
  .Load(rootClassification.Id);

Using it in real life:

Creating some kind of custom UI, where a user inputs for example a date or just a string combined with some other criteria and then we can build a searchexpression for that:

Console.WriteLine("Input ancestor identifer and press 'Enter':");
var ancestorIdentifier = Console.ReadLine();
Console.WriteLine("Input search expression and press 'Enter':");
var searchExpression = Console.ReadLine();
var classifications = app.Search().Classification
    .AncestorOrSelf.Identifier(ancestorIdentifier)
    .Add(new SearchExpression(searchExpression))
    .Load();
classifications.Print();
Console.ReadKey();

That’s where we are now, we got the foundation, but we still need to add keywords, but adding keywords is pretty easy, so it’s something we will add along the way and whenever Adam adds new keywords.

Wanna see the code? Wait a few more days. :-)

Creating your own AdministrationProvider

Introduction

As you might remember from one of our previous webcasts, we provide a set of pages that provide a number of useful administration and monitoring tools for Adam, such as clearing translation or watermark caches, enabling auto-translations or viewing statistics. This set of pages is handled by the Admin Handler.

What few of you will know is that this handler is also designed with the well known Adam Provider Model in mind. Therefore, you can plug-in your own handler in this page and add additional monitoring tools.

In this blog post, I'll create my own handler that checks the state of the different servers participating in my Adam server environment.

Prerequisites

The code presumes that you've created an XML setting called "AdamServerList" that contains a list of all servers you want to monitor. For this example, I've used the following value:

<servers>
  <add name="ADAMS01" type="Database Server" />
  <add name="ADAMS02" type="Fileserver" />
  <add name="ADAMS03" type="Maintenance Server" />
  <add name="ADAMS04" type="Indexing Server" />
  <add name="ADAMS05" type="Web Server" />
  <add name="ADAMS06" type="Workflow Server" />
</servers>

The code

The only thing you'll need to do is create a class that inherits the Adam.Web.Administration.Providers.AdministrationProvider that can be found in the Adam.Web.dll.

To implement this abstract class, you will need to develop the following methods and properties:

CreateControlHierarchy: this is your hook to add controls to the page. In this method you can create a table, panel, ... basically any webcontrol and add it to the control hierarchy by calling this.Controls.Add().
GetMasterResetItems: this method needs to provide the calls that can be invoked when a user clicks the "Master Reset"-link in the Administration page. The calls that are chosen are then passed to the Reset method that can also be overridden.
Title: the title of the page
Description: the description that will be displayed below the title
VendorName: your name. This will also appear at the bottom of the provider page.
VendorUrl: the url to your website. This will appear at the bottom of the provider page.

Once implemented, you can plugin your provider by adding the following configuration section to the web.config file of your Adam site:

<configSections>
  ...
  <section name="Adam.Web" type="Adam.Web.Configuration.AdamWebSection, Adam.Web" />
  ...
</configSections>
...
<Adam.Web>
  <administration>
    <providers>
      <add type="Monitoring.ServerStatusAdministrationHandler, Monitoring"/>
    </providers>
  </administration>
</Adam.Web>

The result

If everything is configured correctly, you should be able to navigate to the AdamAdmin.axd page and view a link to the new provider at the left hand side of the page. Clicking on it, will give you a view of the basic connectivity status of your Adam servers:

The full source code for this sample can be found at the bottom of this post.

Note

Please note that this code is simplified for purposes of example. In a production environment, you should add

additional code for checking input parameters of all methods
additional code for trapping all errors that can be generated by the ping command
an XSD Schema for the XML setting that contains the server list
...

Using the ping command presumes that the network connecting the different servers allows sending the necessary ICMP packets. The ping command also doesn't tell you anything about health parameters of the servers such as disk space, memory consumption,...

That's it! Have fun with this! Looking forward to seeing your work!

The case of the strange filenames.

A recent support call that came in discussed a problem concerning downloading files from an ADAM system with the Internet Explorer family of browsers. The problem occured when downloading files with non-ASCII characters in the filename, using the following code:

    AdamDownloader.DownloadFile(this, path, true);

On the client side, this results in the following dialog shown to the user:

This is a particular hard problem to solve, as there is no single solution that will work for all browsers. Let me explain...

First, I need to explain that this is not a problem with ADAM itself. The same problem can be reproduced in a simple Web Application project. You use the following code to specify the filename in ASP.NET:

    string filename = "test.jpg";
    Response.AppendHeader("Content-Disposition", "attachment; filename=\"" + filename + "\"");
    Response.TransmitFile(MapPath("~/Content/file.jpg"));

This particularly small snippet of code works fine, as long as your filenames do not contain any non-ASCII characters.

By default, all headers are encoded in UTF-8 by the webserver. This is not standard behaviour, as RFC 2047 recommends that headers are encoded in ISO 8859-1. However, it seems that allmost all browsers are broken when it comes to supporting this encoding.

Here you can find a detailed test for various methods to specifying filenames in response headers, and how different browsers respond to it. It seems that Internet Explorer is the more strict, in treating all headers as ISO 8859-1 as per standard, while FireFox 3 is more relaxed in allowing this header to be encoded in UTF-8. That also means that an ISO 8859-1 string that resembles an UTF-8 string is misunderstood by FireFox as being UTF-8. This can lead to interesting effects.

At first one would think changing the default encoding in IIS 7 from UTF-8 to ISO 8859-1. Alas, this doesn't work. I've tried it and the fairly common é is returned as byte sequence 0xBF, 0xEF, 0xBD, which is a disaster to all browsers. Why this happens I haven't found out yet.

Changing the header encoding in code, did work for me, however:

    string filename = "tést.jpg";
    Response.HeaderEncoding = System.Text.Encoding.GetEncoding("iso-8859-1");
    Response.AppendHeader("Content-Disposition", "attachment; filename=\"" + filename + "\"");
    Response.TransmitFile(MapPath("~/Content/file.jpg"));

This worked in IE8, FF3, Chrome and Safari, but not Opera. It will also not work with filenames that contain characters outside of ISO 8859-1, as those characters cannot be represented in any way in this encoding, unlike UTF-8.

Another candidate solution is to use RFC 2231 compliant encoding of URLs in this header. This is easily accomplished:

    string filename = HttpUtility.UrlPathEncode("tést.jpg");
    Response.AppendHeader("Content-Disposition", "attachment; filename=\"" + filename + "\"");
    Response.TransmitFile(MapPath("~/Content/file.jpg"));

And this will work in IE8 and Chrome, but not in FF3, Safari or Opera which will show garbled filenames. These browsers only support the following way:

    string filename = HttpUtility.UrlPathEncode("tést.jpg");
    Response.AppendHeader("Content-Disposition", "attachment; filename*=utf-8''\"" + filename + "\"");
    Response.TransmitFile(MapPath("~/Content/file.jpg"));

This forum post also discusses a third method using path info, but that is also not a general solution as it can only be used in IIS, not the Development Server, and only if you can somehow treat your downloads as a file from a certain server path.

Showing the image of a record when using DataSources

Introduction

Since we have added a data source for ADAM in version 4.4, you got an easy way to consume ADAM objects in standard ASP.NET controls, like e.g. a System.Web.UI.WebControls.GridView.

Next to this, we have added at that time the FieldBinder mechanism to easily show the content of a Field when using the data sources framework.

But did you know that you have also an easy solution for showing images of a record? They are called image binders and out-of-the-box, we provide you six of them:

ClassificationImageBinder
FileTypeImageBinder
LanguageImageBinder
RecordImageBinder
UserImageBinder
WatermarkImageBinder

Usage

Using them is similar to a FieldBinder. In the template of a data bound control, add a control that is capable of showing an image. Next, add e.g. an Adam.Web.UI.WebControls.RecordImageBinder, in the case you are binding to records of cource. On the RecordImageBinder, specify in the TargetControlID the ID of the control that must show the image. Basically, that’s it - as demonstrated in the sample below.

<asp:GridView ID="recordGrid" runat="server" 
              AutoGenerateColumns="false" 
              DataSourceID="recordDataSource" 
              PageSize="5" 
              AllowPaging="true">
  <Columns>
    <asp:TemplateField HeaderText="Image">
      <ItemTemplate>
        <asp:Image ID="recordImage" runat="server" />
        <awc:RecordImageBinder ID="recordImageBinder" runat="server" 
                               TargetControlID="recordImage" />
      </ItemTemplate>
    </asp:TemplateField>
  </Columns>
</asp:GridView>

<awd:AdamDataSource ID="recordDataSource" runat="server"
                    DataProviderType="Adam.Web.UI.DataSources.DataProviders.RecordProvider, Adam.Web"
                    DataOptionsProviderID="recordLoadOptions"
                    SelectExpressionMode="All" />
<awd:RecordOptionsProvider ID="recordLoadOptions" runat="server">
    <LoadOptions PreLoadFiles="FilesVersionsPreviews" />
</awd:RecordOptionsProvider>

These image binders are not limited to Image controls only. If you have another (custom) control with a different property than the Image.ImageUrl property, you can specify the TargetPropertyName on the image binder. This enables you to set for example the NavigationUrl of an HyperLink control, as demonstrated below.

<asp:HyperLink ID="imageLink" runat="server" 
               Text="show preview" />
<awc:RecordImageBinder ID="imageLinkBinder" runat="server" 
                       ImageType="Preview" 
                       TargetControlID="imageLink"
                       TargetPropertyName="NavigateUrl" />

Some of these image binders have even more options that allow you to control what is shown. On a RecordImageBinder, you can e.g. specify whether you want to display the thumbnail or the preview of the record. Or specify whether a watermark must be applied. Have a look at the controls to get a complete view.

As a bonus

Next to these image binder controls in the Adam.Web assembly, you'll find an additional control, the ImageBox control. This control generates an image HTML element, but allows the developer to set more behavior options.

If you set a Width and a Height on the control, you can specify how the image must be resized to fit the specified dimensions. This is controlled by the SizeMode property, which has 4 possible values:

Normal
The ImageBox is sized equal to the size of the image that it contains.
StretchImage
The image within the ImageBox is stretched or shrunk to fit the size of the ImageBox.
Clipped
The image is placed in the ImageBox depending on the ImageLocation property. The image is clipped if it is larger than the ImageBox it is contained in.
Zoom
The size of the image is decreased maintaining the size ratio. When the image is larger than the ImageBox, the ImageLocation property is used to determine the location of the image in the box boundaries.

Achieving the right look for your DataPager with a custom DataPagerField

One of the new controls introduced in ASP.NET 3.5 is the ListView control. It gives you the same flexibility as the Repeater control, but with the features of the GridView and DetailsView, and then some! One of the niceties of this new control is that it uses the new DataPager control, and that it lets you place this anywhere on your page, not just inside your ListView.

This new DataPager gives you a lot more control over its looks than what was available before. This control leaves all the rendering of the output to one of the DataPagerField objects that you add to it, like so:

<asp:DataPager runat="server" ID="pager" PageSize="10" >
  <Fields>
    <asp:NumericPagerField />
    <asp:NextPreviousPagerField />
    <asp:TemplatePagerField>
      <PagerTemplate></PagerTemplate>
    </asp:TemplatePagerField>
  </Fields>
</asp:DataPager>

ASP.NET 3.5 ships with three such pager fields: the NextPreviousPagerField, which displays buttons for the next or previous page, the NumericPagerField, which displays a series of buttons for pages, and last but not least the TemplatePagerField, which gives you fine control over the rendered output using a template. This, however, can lead to pretty complex markup in your ASPX page. You can, however, create your own custom DataPagerField, and it isn’t terribly difficult. In this article, I will explain you how.

For one of our customers, we needed a pager that would show a series of buttons, but that would follow the current page and provide a “window” around it, instead of simply “paging the pager” like the NumericPagerField would. Given a ListView with a content of 97 items and a PageSize of 10, we would want to display the following while on the first page:

When the user moves further in the pages, the list of pages would start to follow, and center the current page:

And when at the end, obviously, it would stop scrolling:

The “next” and “prev” buttons would also not move a whole 10 pages, but work the same as the NextPreviousPagerField and move one page up or down.

The HTML required for this look would look like this (as specified by the designer):

<div class=”pager”>
    <a href=”#”>&lt;&lt; prev</a>
    <a href=”#”>1</a>
    <span>2</span>
    <a href=”#”>3</a>
    <a href=”#”>next &gt;&gt;</a>
</div>

At first I felt a combination of two NextPreviousPagerFields and TemplatePagerField would do the trick, but this resulted in bloated and incomprehensible markup. So I turned to implementing my own custom DataPagerField descendant called FollowingPagerField.

Firstly, we create a class that derives from DataPagerField. The documentation states that three methods must be overridden for this to work: CreateField, CreateDataPagers and HandleEvent.

public class FollowingPagerField : DataPagerField
{
    protected override DataPagerField CreateField()
    {     
        return new FollowingPagerField();
    }

    public override void CreateDataPagers(
        DataPagerFieldItem container, int startRowIndex, 
        int maximumRows, int totalRowCount, int fieldIndex)
    {
    }

    public override void HandleEvent(CommandEventArgs e)
    {
    }
}

CreateField() is required to return a new instance of this class, and is used when cloning the PagerFields collection of the DataPager, so we’re not going to pay further attention to it.

CreateDataPagers() is called by the DataPager, and in this method we must produce all the controls required for rendering. We can use the parameters to calculate the page that we’re on so we can completely render our pager.

HandleEvent() is called when the user clicks on one of the buttons that we render. These buttons contain a CommandName and optionally a CommandArgument that we get here to decide what to do with the DataPager: move a page up or down, or move to a specific page.

I added a couple of properties to allow the user of the component to modify the look a little bit, but these can certainly be expanded upon later:

private string _previousText = "<<";
private string _nextText = ">>";
private int _buttonCount = 5;

public string PreviousText{
    get { return this._previousText; }
    set { this._previousText = value; }
}

public string NextText
{
    get { return this._nextText; }
    set { this._nextText = value; }
}

public int ButtonCount
{
    get { return this._buttonCount; }
    set { this._buttonCount = value; }
}

Implementing CreateDataPagers() was pretty straightforward, using a couple of helper methods:

private void CreatePages(Control container, 
    IEnumerable<int> pages, int current)
{
    foreach (int page in pages)
    {
        if (page == current)
        {
            container.Controls.Add(new HtmlGenericControl 
            { 
                TagName = "span", 
                InnerHtml = page.ToString() 
            });
        }
        else
        {
            container.Controls.Add(new LinkButton
            {
                Text = page.ToString(),
                CommandName = "Page",
                CommandArgument = page.ToString()
            });
        }
    }
}

private void CreateLink(Control container, string caption, 
    string command, bool enabled)
{
    LinkButton button = new LinkButton 
    { 
        Text = caption, 
        CommandName = command, 
        Enabled = enabled 
    };

    if (!enabled)
    {
        button.CssClass = "disabled";
    }

    container.Controls.Add(button);
}

public override void CreateDataPagers(
    DataPagerFieldItem container, int startRowIndex, 
    int maximumRows, int totalRowCount, int fieldIndex)
{
    // The pages here are 0-based. (Page 1 = 0, Page 2 = 1, ...)
    int page = (startRowIndex / maximumRows);
    int totalPages = (totalRowCount / maximumRows);

    // Create a container.
    HtmlGenericControl pagerDiv = new HtmlGenericControl("div");
    pagerDiv.Attributes["class"] = "pager";
    container.Controls.Add(pagerDiv);

    CreateLink(pagerDiv, PreviousText, "Prev", page > 0);

    int firstPage = Math.Max(page - (this._buttonCount / 2), 0);
    int lastPage = Math.Min(firstPage + this._buttonCount, totalPages);
    int count = lastPage - firstPage;

    if (count < this._buttonCount)
    {
        firstPage = Mth.Max(lastPage - this._buttonCount, 0);
        count = lastPage - firstPage;
    }

    CreatePages(pagerDiv, 
        Enumerable.Range(firstPage + 1, count), page + 1);

    CreateLink(pagerDiv, NextText, "Next", (page + 1) < totalPages);
}

A simple container control is created to contain all the elements, which needs to be a div element with a specific CSS class. Again, this can be changed to find the classname in properties, but that’s beside the point here. The heart of the problem is calculating which pages to show.

The HandleEvent() method was even simpler, simply matching the CommandName parameter and parsing the CommandArgument parameter and decide what to do with the current view:

public override void HandleEvent(CommandEventArgs e)
{
    int newStartRowIndex = -1;

    if (e.CommandName.Equals("Prev"))
    {
        if (this.DataPager.StartRowIndex >= this.DataPager.PageSize)
        {
            newStartRowIndex = this.DataPager.StartRowIndex - 
                this.DataPager.PageSize;
        }
    }
    else if (e.CommandName.Equals("Next"))
    {
        if ((this.DataPager.StartRowIndex + this.DataPager.PageSize) < 
            this.DataPager.TotalRowCount)
        {
            newStartRowIndex = this.DataPager.StartRowIndex + 
                this.DataPager.PageSize;
        }
    }
    else if (e.CommandName.Equals("Page"))
    {
        int page;

        if (int.TryParse(e.CommandArgument.ToString(), out page))
        {
            int newIndex = (page - 1) * this.DataPager.PageSize;

            if ((newIndex >= 0) || 
                (newIndex < this.DataPager.TotalRowCount))
            {
                newStartRowIndex = newIndex;
            }
        }
    }

    if (newStartRowIndex >= 0)
    {
        this.DataPager.SetPageProperties(newStartRowIndex, 
            this.DataPager.MaximumRows, true);
    }
}

Since we create the links in the rendered output, we know what to expect when handling this event. I think the code speaks for itself.

Lastly, we need to register our new toy in the page, and instantiate it in the DataPager:

<%@ Register assembly="OurAssembly" Namespace="OurNamespace" TagPrefix="us" %>

<asp:ListView runat="server" ID="lv" DataSourceID="rs" DataKeyNames="Id">
  <LayoutTemplate>
    <asp:DataPager runat="server" ID="pager" PageSize="5" >
      <Fields>
        <us:FollowingPagerField NextText="next >>" 
           PreviousText="<< prev" ButtonCount="10"/>
      </Fields>
    </asp:DataPager>
  </LayoutTemplate>
</asp:ListView>

So there you have it, a working custom pager by implementing two methods!

Using Adam as a SaaS solution

A couple of our partners are using Adam to provide SaaS solutions to their customers and we try to keep that in the back of our mind whenever we’re designing a new module, studio or feature. A couple of examples:

Sites are most often used to specify different setting values depending on the physical server that connects to the Adam database. However, they can also be used to set different setting values depending on the site that a user uses. In that case you need to mutiple sites and setup multiple site registrations (check Admin Guide > System Configuration > Sites > Sites for more info on how to do this) on one physical server. After that, your Adam.Core.Server.exe.config file will look somewhat like this:
```
<databaseregistrations>
  <add name="AdamCustomer1" sqlServer="LOCALHOST" sqlDatabase="AdamSaas"
  workingFolder="D:\Adam\AdamCustomer1" siteName="Customer1"/>
  <add name="AdamCustomer2" sqlServer="LOCALHOST" sqlDatabase="AdamSaas"
  workingFolder="D:\Adam\AdamCustomer2" siteName="Customer2"/>
</databaseregistrations>
```
After this you simply install a separate AssetStudio/ConfigStudio/Custom Studio for each of the sites and make them connect to the corresponding registrations. That way, a user logging in through http://customer1.yoursaasprovider.com will use different setting values compared to one logging in at http://customer2.yoursaasprovider.com.
Another useful concept is Adam Organizations. These help you to shield of the working areas of your different customers. Start by creating an organization for each customer. Next you can create different user groups that belong to a specific organization and assign different permissions to them. Once this is done, you’ll automatically see new roles in the Security > Organization section of a user group profile:
In a similar way you’ll also be able to make certain groups manage or view fieldgroups, languages, filetypes, ... : just click a couple of the other links of the Security-section of a user group profile.
The final piece of the puzzle is where the actual work starts for a SaaS customer: simply create a root classification node for each customer and given the right permissions, the customer will be able to create/edit/delete classifications, fields, field groups, user groups and users that only his users can see.

As you can imagine, putting all of this together can lead up to challenging situations and results that –at first sight- seem to be quite unexpected. When fine-tuning and debugging these things, the Permission Viewers can be very useful tools: try them out; you can find them in the Config Studio in Advanced Features.

Hope someone finds this useful. Looking forward to your feedback!

ADAM Kick Off 2010 Conference, Tuesday January 26th, Ghent - Belgium

IT is DAM business

Why are ADAM customers such as LEGO, Microsoft, Elopak and many more shifting their focus from cost control to proven ROI? ADAM Software has changed the perception on Digital Asset Management from a super file system into a business execution system.

At the 5th ADAM Kick Off conference, we present customer cases, product introductions and analyst's insights.

Take the opportunity, together with more than 120 professionals from leading organizations, to discuss what's happening in your world of DAM.

For complete details and registration, visit http://www.adamsoftware.net/kickoff.

Create a preview player for Flash Video (FLV)

Flash Video (FLV files) became a popular file format for delivering video on the web. These files cannot be embedded on a web page on their own. A FLV player, created in Flash, is required to play those video files.

One solution could be to create your own FLV player in Flash. Or you can search the web for an existing FLV player, there is enough choice out there. For this article, we are going to use the player of http://flv-player.net/, an open source Flash Video player. This should not be considered as 'the way to go'. We just needed one to demonstrate the idea of playing FLV files in ADAM.

About FLV player

Before we create our FLV preview player, we first need to understand how the player is working. Luckily, the flv-player.net website has a wizard that helps us to generate the look-and-feel of the player: FLV Player generator.

If you look at the generated HTML code, you'll see two important parameters for the OBJECT tag: the actual movie and the FlashVars. The actual movie is the SWF file that is capable of playing the actual FLV file The FlashVars instruct the player how it should behave.

The generated HTML code can be used as-is, but we can improve the code by loading the Flash movie through JavaScript, which resolves issues related to different browsers and makes it easy to build the OBJECT tag. To do so, we can rely on a framework called SWFObject. A full explanation on why you should use such a framework can be found in this web page: Flash Embedding Cage Match.

Converting the HTML code to JavaScript using SWFObject is pretty simple and constructing the FlashVars is much easier this way, as you can see in the following code snippet (for more information about the SWFObject features, see SWFObject documentation).

var flashvars = {"flv": "myvideo.flv"};
swfobject.embedSWF(swfUrl, 
                   idOfTargetElement, 
                   width, 
                   height, 
                   requiredFlashVersion, 
                   expressionInstallationSwfUrl, 
                   flashvars);

For this article, you need to download the next two files:

player_flv_maxi.swf
This is the SWF file which is capable of playing the FLV file.
swfobject_2_2.zip
A JavaScript library to dynamically load SWF files.

The Visual Studio project

Embedding resources

Playing an FLV file requires more than some C# code and an FLV file. You'll also need the SWF file (the actual player) and when using the SWFObject approach, the JavaScript file containing the SWFObject code. Since the ADAM preview players are added to a .NET Class Library, there is no actual directory available where you can place the extra SWF and JavaScript files. This is a common problem when developing web solutions and therefore the ASP.NET framework provides us with a solution: embedded resources.

In your Visual Studio class library project, add a new folder 'Files' and drag-and-drop the files player_flv_maxi.swf and swfobject.js into this folder in Visual Studio

Now, select both files in the Visual Studio Solution Explorer, right-click them and choose 'Properties'.

In the properties window, change the Build Action from 'Content' to 'Embedded Resource'. This ensures that those files are embedded in the compiled assembly.

After embedding the files in the assembly, we need to tell the ASP.NET framework that these files must be accessible from an URL request. To do so, add a new C# file to your solution and name it AssemblySetup.cs. Clear the complete contents of the file and add the following code. This code actually instructs ASP.NET to make the embedded resources available from an URL request (how to get an URL to those embedded resources is shown later on).

using System.Web.UI;

[assembly: System.Web.UI.WebResource("FLVPlayer.Files.player_flv_maxi.swf", "application/x-shockwave-flash")]
[assembly: System.Web.UI.WebResource("FLVPlayer.Files.swfobject.js", "text/js")]

The actual preview player

Creating the preview player is pretty much the same as described in the blog article Create a preview player for Flash (SWF) files.

However, there are some differences between both articles:

The preview player requires the inclusion of an additional JavaScript
The SWF file is not the FileVersion, but the player embedded in the assembly
The file that must be previewed is a parameter for the Flash movie

To include an embedded JavaScript file in the generated HTML of a Page, use the GetWebResourceUrl method of the System.Web.UI.ClientScriptManager class, as demonstrated in the following code snippet:

// Include the JavaScript.
ClientScriptManager manager = this.Page.ClientScript;

// Test if the script file is not already included in the HTML output.
if (manager.IsClientScriptIncludeRegistered(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js") == false)
{
  // Get the url to the embedded resource.
  String scriptUrl = manager.GetWebResourceUrl(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js");
  // Add the script to the HTML output.
  manager.RegisterClientScriptInclude(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js", scriptUrl);
}

All the rest is very similar to the previous article, except for the fact that we now need to generate some JavaScript.

protected override void CreateChildControls()
{
    FileVersion version = this.DataItem as FileVersion;
    if (version != null && string.IsNullOrEmpty(version.Path) == false)
    {
        // Include the JavaScript.
        ClientScriptManager manager = this.Page.ClientScript;

        // Test if the script file is not already included in the HTML output.
        if (manager.IsClientScriptIncludeRegistered(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js") == false)
        {
            // Get the url to the embedded resource.
            String scriptUrl = manager.GetWebResourceUrl(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js");
            // Add the script to the HTML output.
            manager.RegisterClientScriptInclude(typeof(FLVPreviewPlayer), "FLVPlayer.Files.swfobject.js", scriptUrl);
        }

        // Get the url to the FLV player (the SWF file).
        string swfUrl = manager.GetWebResourceUrl(typeof(FLVPreviewPlayer), "FLVPlayer.Files.player_flv_maxi.swf");

        // Get the url to the FLV file being previewed.
        ServerFileUri uri = new ServerFileUri(version.Path, "application/x-unknown-content-type");
        string flvUrl = uri.ToString();

        // Create a placeholder for the FLV player on the client.
        HtmlGenericControl placeholder = new HtmlGenericControl("div");
        placeholder.ID = "container";
        placeholder.InnerText = "No Flash player installed";
        this.Controls.Add(placeholder);

        // Prepare variables for the SWFObject framework.
        int width = 470;
        int height = 320;
        String requiredFlashVersion = "9.0.0";

        // Create the script to load the FLV player...
        StringBuilder script = new StringBuilder();
        // Create the flash variables object.
        script.AppendFormat("var flashvars = {{'flv': '{0}', 'autoplay': '1', 'showtime': '1', 'showfullscreen': '1', 'buffermessage': ''}};", HttpUtility.UrlEncode(flvUrl));
        // And embed the SWF file in the HTML document.
        script.AppendFormat("swfobject.embedSWF('{0}', '{1}', '{2}', '{3}', '{4}', null, flashvars, {{'allowfullscreen': 'true'}});", new Object[] { swfUrl, placeholder.ClientID, width, height, requiredFlashVersion });

        // Register the script that loads the FLV player for the FLV file being previewed.
        manager.RegisterStartupScript(typeof(FLVPreviewPlayer), "load", script.ToString(), true);
    }
    else
    {
        this.Controls.Add(new LiteralControl("No FileVersion available or the file could not be found."));
    }
}

The steps to register the preview player in ADAM are identical to the ones described in the Create a preview player for Flash (SWF) files article.

Disabling Search Operators

The search framework in ADAM has a small and little known feature that can improve the search experience of your users. By default, the search framework supports a whole bunch of operators like OR, AND, NOT, CONTAINS, =, >, <> and so on. Next to that, there are also characters that give a keyword in search expression a special meaning like an ampersand (@), a question mark (?), a dot (.) and others.

These operators and special characters give you the developer, or the users using your custom ADAM website, access to some of the advanced search functionality. However, sometimes these features are overkill and hardly used by your users. In this case, you can disable the search keywords that you don't want your users to use. Once a keyword is disabled, it is treated by the search framework as any other ordinary character and it looses its special meaning.

For example:

SearchExpression expr = new SearchExpression("2009 not on the road");
expr.DisabledKeywords = DisabledKeyword.QuestionMark | DisabledKeyword.Dot |
  DisabledKeyword.At | DisabledKeyword.Contains | 
  DisabledKeyword.Or | DisabledKeyword.Not;

The previous code sample creates a search expression that has the specified keywords disabled. This ensures for example that your users don't have to quote the not they specified in not on the road.

FireFox slow when browsing your local ASP.NET apps?

There's an issue with FireFox when used to debug ASP.NET applications together with the ASP.NET Development Server on Windows Vista/Windows 7. Performance seems sluggish, especially compared to Internet Explorer. The solution is pretty simple, once you know what the problem is.

The problem is related to an issue with FireFox on these new operating systems to resolve the IPv6 address of localhost. This results in such slow perceived performance, while Internet Explorer doesn't suffer the same fate. To solve the problem, there's two solutions:

The first solution is to disable IPv6 in FireFox alltogether. If you feel this is a bit drastic (as I do) then you can read on to the next solution. Follow these steps:

Type in about:config in the address bar of your browser. Heed the warning about the dragons, then proceed to the list of settings.
Search or scroll to the setting named network.dns.disableIPv6.
Double-click the value to set it to true.
Restart your browser.

The second solution is very similar, but instead of disabling all of IPv6 you simply add "localhost" as a domain to the list of domains to ignore IPv6 on, like so:

Type in about:config in the address bar of your browser. Skip the warning, then proceed to the list of settings.
Search or scroll to the setting named network.dns.ipv4OnlyDomains.
Double-click the value to edit it, and add localhost.
Restart your browser.

That should make browsing much faster. The original article can be found here.

Scripting ADAM with IronPython

IronPython is an implementation of the Python language for the .NET framework, using the new Dynamic Language Runtime (DLR) as language services layer on top of the Common Language Runtime (CLR). The DLR's reusable hosting model makes it extremely suitable to add scripting capabilities to existing products.

In this post we'll create an ADAM command line utility that will allow us to run IronPython scripts against an ADAM application.

Getting IronPython

IronPython can be downloaded from its CodePlex project page: http://ironpython.codeplex.com/. For this post we're using version 2.6 RC3. After downloading, installation is pretty straight-forward.

Setting up a console application project

Using Visual Studio 2008, create a new console project named Adam.Scripting.CommandLine and add references to the following assemblies (the IronPython assemblies can be found in the IronPython installation directory, which defaults to C:\Program Files\IronPython-2.6):

Adam.Core.dll
Adam.Tools.dll
IronPython.dll
Microsoft.Scripting.dll
Microsoft.Scripting.Core.dll

The Adam.Tools assembly contains a set of classes that make life simpeler for console application developers, and this is a nice occassion to elaborate on some of these helpers. The Arguments class exposes methods for parsing command line parameters and executing commands, much like the standard Adam.Core.CommandLine.exe and Adam.Core.DatabaseManager.exe work.

Our command line tool will expose a single command, RunScript, that will take in ADAM connection information and a path to a Python file to execute:

static readonly Command[] ProgramCommands =
{
  new Command("RunScript", RunScript, RunScriptHelp)
};

As you can see, a Command is defined by a command name (which is used to identify the command passed through the command line), and two delegates: one that handles the execution of the command, and one that displays the help information for the command. These delegates are automatically invoked when calling the Arguments.ExecuteCommand(Command[], DisplayHelpDelegate) method.

Hosting the IronPython engine

In the RunScript command, we allow the user to specify the location of a Python script file, which will then be executed by the IronPython engine. For this to work, we need to initialize an IronPython hosting environment within our command line tool:

// Initialize the IronPython engine.
ScriptEngine engine = Python.CreateEngine();

// Preparing the scope for the script.
ScriptScope scope = engine.CreateScope();
scope.Engine.Runtime.LoadAssembly(typeof(Application).Assembly);
scope.SetVariable("adamApp", app);

// Loading the script file.
ScriptSource source = engine.CreateScriptSourceFromFile(path);
source.Execute(scope);

First of all, we're creating an instance of the IronPython engine, which is a factory for all IronPython-related work. As a side-note, the ScriptEngine class is really a part of the DLR, and can be used to host other dynamic languages as well (such as IronScheme, IronRuby, ...).

Next, we're creating and initializing a ScriptScope for the file we're going to execute. This involves preparing the assembly references and global variables that should be available to the script. In this case, we're adding a reference to the Adam.Core assembly, and pass the logged on Application object as the adamApp variable.

Your very first ADAM IronPython Script

At this point we have a command line utility that can be run like this:

 Adam.Scripting.CommandLine.exe -path=C:\Temp\ListUsers.py
  -registration=AdamTest -userName=Administrator
  -password=password

And now to test this, let's create a Python script that lists all users known to ADAM. Open your favorite Python editor, and enter the following:

import Adam.Core

users = Adam.Core.Management.UserCollection(adamApp)
users.Load(Adam.Core.Search.SearchExpression('*'))

for user in users:
  print user.Name

Now, if we save the file to ListUsers.py, and run the script using our command line tool, the output should list all ADAM users. Please note that the adamApp variable is available in the script (as passed through the scope), and the import Adam.Core statement is required to make the Adam.Core namespaces available.

Wrapping it up

And now it is up to you to experiment. Go nuts. You could use this little application to create import scripts (yes, you can add records, users and other ADAM objects using script), create maintenance jobs, or even, given some modifications, execute workflows using script. Feel free to share your experiences in the comments. Happy coding!

The impact of User Account Control (UAC) on the Adam command line tools

By default applications run without any administrative permissions and therefore they cannot make any changes to the system. For some Adam commands, administrator privileges are required though. In Windows XP / Windows Server 2003 you could open your command prompt with "Run this program with restricted access" unchecked. In that case and if you do have administrator privileges, you are running the command with administrator privileges, but still as the logged on user. So these commands have access to your profile information like user folder, etc.

Windows Vista / Windows Server 2008 / Windows 7 on the other hand uses User Account Control forcing you to select "Run As Administrator" to be able to run a command with administrator privileges. In that case you are not executing this command with the logged on user, but with the administrator account, thus these commands don't have access to your profile information and have access the administrator's profile information instead. This can lead to unexpected results regarding Adam tools

Adam Commandline Tool

When starting the Adam Commandline Tool, runned as Administrator, you no longer end up in the Adam installation folder, but in the C:\Windows\system32 folder instead. So before proceeding you should navigate to the installation folder yourself.

Install Visual Studio Templates

When running as administrator, the same problem occurs as above: instead of running from the adam installation folder, the C:\Windows\system32 folder is used. Since this batch command needs the adam installation folder to continue properly, this results in an error. To bypass this you should execute the following steps:

Fire up the command prompt with administrator rights.
Move to the VSTemplates folder within the Adam installation folder.
Start InstallTemplates.bat

Webinar about the StatefulFormView control

This webinar walks you through the new ADAM StatefullFormView web control. Forget the standard ASP.NET FormView control who don’t always match with the highly dynamic nature of ADAM objects. The new StatefullFormView caches data object on the server so that e.g. default values will be calculated on a correct way.

Defensive programming with ADAM

Defensive programming is a set of techniques for writing more comprehensible, less error-prone code, and gracefully handling unexpected input or rare runtime conditions. Using these techniques along with unit testing will improve code quality as well as reduce bug count considerably.

The ADAM API consistently exposes methods that lend themselves quite well for defensive programming. In this article, I'm going to delve deeper into the realms of the ADAM API and use code examples that explain how to defensively program against ADAM.

User input validation

First of all, all user input should be validated and checked. Never leave it to the user to enter a valid number in a text field where you can enter any alphanumeric character. Make sure all public methods check their parameters and make sure all casting/parsing is done safely.

In the Adam.Tools assembly, the ADAM API provides a few helper converter classes to help with input validation. These classes consistently expose TryParse(...) methods that can be used to safely convert string values to their respective value types. These methods also have a Parse(...) counterpart, which will throw a FormatException when the parsing fails.

decimal number;

// Non-defensively parsing a decimal from a string.
number = DecimalConverter.Parse("3.14159", CultureInfo.InvariantCulture);

// Defensively parsing a decimal from a string.
if (!DecimalConverter.TryParse("3.14159", CultureInfo.InvariantCulture, out number))
{
  // Gracefully handle invalid values, or revert to default value...
}

Defensively logging on to ADAM

The first example I'm giving is the Application.LogOn(...) method (and its overloads). As you should know, this is the method that connects the Application object to an ADAM registration. The return type of this method is LogOnStatus, and the method will not throw an exception if the registration name, user name or password is incorrect.

One of the main reasons for this is to prevent the method from exposing information that might be used by malevolent users to launch an attack on the system.

You can use the LogOnStatus enumeration returned by the method defensively to ensure connecting to ADAM succeeded:

if (app.LogOn(null, userName, password) != LogOnStatus.LoggedOn)
{
  // Handle connection failure gracefully...
}

Defensively loading ADAM objects

As an ADAM developer, you're probably familiar with the Record.Load(...) method (and its overloads). Suppose we are using this method to load a record from ADAM, you might write a piece of code like this:

Record record = new Record(app);
record.Load(id);
// Do some work...

However, the Record.Load(Guid) might throw an ItemNotFoundException when no record is found with the specified id. Other overloads of the Record.Load(...) method might also throw an InvalidNumberOfMatchesException when more than one matches are found. Therefore, you might change the code above to this:

Record record = new Record(app);

try
{
  record.Load(id);
  // Do some work...
}
catch (ItemNotFoundException ex)
{
  // Log the exception, show some output to the user, or throw
  // a different exception, ...
}

In the above code, the ItemNotFoundException can be anticipated, and even avoided. Exceptions are expensive in terms of resources and additional overhead they incur, and whenever you can, you should prevent them from being thrown in the first place.

In order to fix this situation, let's take a look at the Record.TryLoad(...) method (again with its overloads), which can be used to defensively load a record.

The return type of the TryLoad(...) method is the TryLoadResult enumeration, which you can use to check wether loading was successful, the item was not found or multiple items were found matching your query.

With this knowledge, we can now rewrite the example above in a defensive way, making it more robust and maintainable:

Record record = new Record(app);

if (record.TryLoad(id) != TryLoadResult.Success)
{
  // You could create the record you're expecting here, or query the
  // user for input, or throw a meaningful exception, or ...
}

// Do some work...

As a side note, when you only need to assert the existence of a specific record/classification, without necessarily loading it; using the RecordHelper.Exists(SearchExpression)/ ClassificationHelper.Exists(SearchExpression) method is a more performant way to go.

Exception handling

As already briefly mentioned above, exceptions are to be avoided whenever possible. However, sometimes unexpected things are bound to happen. In that case, good exception handling comes to the rescue. General guidelines for exception handling can be found here: http://msdn.microsoft.com/en-us/library/ms229005.aspx.

The ExceptionManager class, which can be found in the Adam.Tools assembly, adds some additional functionality to exceptions, and provides factory methods for creating common exception types.

When developing custom ADAM studios, you can use the ExceptionManager.SetExceptionData(Exception, boolean) to set the IsSensitive custom property, which is used by the web interface to determine whether or not to hide the exception message from normal users.

Putting it all together

In this post we've shared a few techniques to program defensively in general, and with the ADAM API specifically. We've shown that user input should not be trusted until proven trustworthy, that every exception that can be avoided should be avoided and, when really unexpected circumstances occur, your code must be ready to handle them gracefully.

As much as I hate automobile industry comparisons, I cannot resist adding this one: exception handling is much like car insurance. Even when you've got good insurance, having an accident is never a happy experience. Defensive driving significantly lowers the probability of having an accident, so it is the smart thing to do. Happy coding!

UpdateSchema fails

Recently, a support ticket came in with the following problem: Executing "Adam.Core.DatabaseManager.exe UpdateSchema" failed with the error message 'You can only specify the READPAST lock in the READ COMMITTED or REPEATABLE READ isolation levels' (see screenshot).

Cause from this problem? Replication was on enabled on the specific database. Because ADAM does NOT support replication on databases, you should temporary disable replication when executing UpdateSchema.

Setting up an adam development environment quickly

What's the absolutely quickest way to set up a new adam environment? The way that is described in the installation manual is the one that gives you the must control over your setup, but it takes a bit too long to do if you simply want to set up a new dev environment on your laptop.

Here comes the Adam.Core.DatabaseManager SetupLocalDemo command to the rescue! It creates and activates the database for you, installs the StudioSelector, Config Studio and Asset Studio. All you need to do after running this command, is to install your license manually.

There are a few limitations built into this tool to ensure that you only need to do a minimum amount of configuration.

For example, it will always create a directory under C:\ with the name of the registration. This directory will contain the databases, documents and studios. Everything will be installed locally.

Simply run Adam.Core.DatabaseManager SetupLocalDemo -? to see a description of all the arguments possible. You'll recognize many of the arguments as the ones that the "normal" installation commands use.

The simplest way to run this command is to use the -ask argument like this Adam.Core.DatabaseManager SetupLocalDemo -ask. When it asks for sql accounts, specify the necessary accounts or press enter to use Windows Authentication.

Create a preview player for Flash (SWF) files

Adobe Flash movies are a popular file format. The ADAM engine has no issues in storing those file formats, but there is no out-of-the-box preview player. However, creating such a preview player is pretty straight forward.

The basics

To create a custom preview player, you should subclass the abstract class FileVersionView..This class is the base class for all preview players in ADAM.

To create the HTML that provides a preview of the Flash file, you can add HtmlGenericControl controls as a child controls and set the necessary properties to it in order to output standard HTML for embedding a Flash file:

To determine the URL of the Flash file, you need access to the FileVersion being previewed. This object is available in the DataItem property of the FileVersionView control. The FileVersion object has a property Path which contains the local (or network) path of the actual file. To convert this path into an URL, you can use a ServerFileUri object to create a secure URL from it.

protected override void CreateChildControls()
{
  FileVersion version = this.DataItem as FileVersion;
  if(version != null && string.IsNullOrEmpty(version.Path) == false)
  {
    string path = version.Path;
    
    ServerFileUri uri = new ServerFileUri(path, "application/x-shockwave-flash");
    string url = uri.ToString();
  
    HtmlGenericControl control = new HtmlGenericControl("object");
  
    HtmlGenericControl param = new HtmlGenericControl("param");
    param.Attributes.Add("name", "movie");
    param.Attributes.Add("value", url);
    control.Controls.Add(param);
  
    HtmlGenericControl embed = new HtmlGenericControl("embed");
    embed.Attributes.Add("src", url);
    embed.Attributes.Add("type", "application/x-shockwave-flash");
    control.Controls.Add(embed);
  
    this.Controls.Add(control);
  }
  else
  {
    this.Controls.Add(new LiteralControl("No FileVersion available or the file could not be found."));
  }
}

Note: the code above is a stripped down version and only contains the minimal required HTML properties to embeds a Flash file into an HTML page. When using the code in a production environment, you should complete the code to provide all properties. To get more information about which properties are available, there are dozens of articles on the web. We suggest following articles:

Macromedia Flash OBJECT and EMBED tag syntax
Flash OBJECT and EMBED tag attributes.

Using the preview player in ADAM

A preview player is a provider. Therefore, once the code of the preview player is completed, you must register the containing assembly in ADAM and add the preview player in the 'Preview Render Web Control Providers' setting. More information on registering and configuring a provider in ADAM can be found in the topic 'Creating a custom provider' of the ADAM development guide,

Once this is done, open up the Config Studio, go to 'File Type Management', search for the SWF file type and add the Flash preview player to the list of preview players.

Configuring the preview player

The abstract class FileVersionView has an additional virtual method: ApplyProviderSettings. This method has one parameter (settings) which contains the additional XML attributes set on the <add /> tag of the corresponding preview player configured in the 'Preview Render Web Control Providers' setting. You can use this method to configure your preview player.

By example, you could add configuration options to the preview player to control its width and height. To achieve this, add these properties in the setting. E.g.:

<add name="FlashPreviewPlayer" type="Sample.FlashPreviewPlayer, Sample" width="600px" height="400px" />

You can now read these options in the ApplyProviderSettings method:

private Unit _width = Unit.Empty;
private Unit _height = Unit.Empty;

public override void ApplyProviderSettings(IDictionary<string, string> settings)
{
  if (settings != null)
  {
    if (settings.ContainsKey("width") == true)
    {
      string width = settings["width"];
      if (string.IsNullOrEmpty(width) == false)
      {
        try
        {
          _width = Unit.Parse(width);
        }
        catch
        {
          _width = Unit.Empty;
        }
      }
    }

    if (settings.ContainsKey("height") == true)
    {
      string height = settings["height"];
      if (string.IsNullOrEmpty(height) == false)
      {
        try
        {
          _height = Unit.Parse(height);
        }
        catch
        {
          _height = Unit.Empty;
        }
      }
    }
  }
  base.ApplyProviderSettings(settings);
}