Owin Framework

The [GenerateClientScript] Attribute

Optionally attach this attribute to a web service to create a component that will render Javascript that makes it very easy to call the endpoints of the service.

Other page elements that will call this service can have the [NeedsComponent] attribute attached to them to indicate that they have a dependency on this Javascript and ensure that it is included on all pages where it is needed.

Example Usage

[IsService("order", "/order/", new[] { Method.Get })]
[GenerateClientScript("order-service-client")]
public class OrderService
{
    [Endpoint(UrlPath = "id/{id}")]
    [EndpointParameter("id", typeof(AnyValue), EndpointParameterType.PathSegment)]
    public void GetOrderById(IEndpointRequest request)
    {
        var id = request.Parameter<long>("id");
        // Use data access layer to retrieve the order details
    }
}
[IsRegion("order-region")]
[NeedsComponent("order-service-client")]
[NeedsComponent("libraries:ajax")]
public class OrderRegion { }

In this example:

• Any page that includes the order-region region knows that it must render the order-service-client component because of the [NeedsComponent] attribute on the region.
• The order-service-client component will write Javascript where it is accesible to the page. Where exactly it gets written depends on the asset deployment mechanism that you configured.
• The Javascript that is produced depends on the ajax library, so this region also specifies that the ajax library is required wherever this region is used.
• The GetOrderById method of the order service can now be called using one line of Javascript similar to ns.myApp.orderService.getOrderById({id: 123},function(order){})

Note that:

• I called the service order but the Javascript function is called orderService. This is by convention. The [GenerateClientScript] attribute appends "Service" to the service name to avoid naming conflicts in the generated Javascript.
• The generated Javascript is in a namespace. The Pages Framework uses a convention where all namespaces are contained in the ns property of the window object, so the fully qualified name of the function call begins with ns.
• In this example I used myApp as the namespace name. The actual namespace that is required here is defined by your Package. You can have multiple application packages, but many websites will have only one. You should substitute myApp in the example above with the namespace name of your application package.
• In the C# code the method is called GetOrderById but the Javascript calls getOrderById. This is another convention. When generating the Javascript the first letter is converted to lower case to make the Javascript more conventional.
• The Javascript getOrderById takes up to 4 parameters. In this example I only passed the first two. The first parameter is the parameters that are expected by the service endpoint (in this example just the "id"). The second parameter is a function that will be called if the request succeeds. The function will be passed a Javascript object that will be a Javascript representation of whatever C# object you serialized as the response from your service endpoint.