ss utils.js JavaScript Client Library

Demis Bellot edited this page Oct 25, 2016 · 11 revisions

This page has moved to

An Embedded Resource inside ServiceStack.dll is ServiceStack's JavaScript utility library that provides a number of convenience utilities in developing javascript web apps. It enables nicer integration with ServiceStack's Server features including Validation, Error Handling and Server Events which can be included in any page with:

<script type="text/javascript" src="/js/ss-utils.js"></script>

DefinitelyTyped and npm

To make it easier to develop with ss-utils in any of the npm-based Single Page Apps templates we're also maintaining a copy of ss-utils in npm and have also added it to JSPM and DefinitelyTyped registry so you can now add it to your project like any other external dependency using JSPM:

C:\> jspm install ss-utils

If you're using TypeScript, you can also download the accompanying TypeScript definition from:

C:\>typings install ss-utils --ambient --save

Or if you're using the older tsd package manager: tsd install ss-utils --save.


To showcase how it simplifies general web development, we'll walkthrough the JavaScript needed to provide all the behavior for the entire UI of Email Contacts that uses just jQuery and bootstrap.js:

Bootstrap Forms

ss-utils.js validation and error handling support works with Bootstrap's standard HTML Form markup, e.g:

<form id="form-addcontact" action="@(new CreateContact().ToPostUrl())" method="POST">
    <div class="col-sm-3 form-group">
        <label for="Name">Name</label>
        <input class="form-control input-sm" type="text" id="Name" name="Name" value="">
        <span class="help-block"></span>

The first thing to notice is the action url is created with a typed API populated using the Reverse Routing ToPostUrl() extension method that looks at CreateContact Request DTO to return the best matching route based on the Route definitions and the fields populated in the Request DTO instance, in this case the empty Request DTO matches [Route("/contacts", "POST")] so returns /contacts.

Other significant parts in this HTML Form is that the INPUT field names match up with the Request DTO it posts to and that it includes Bootstraps class="help-block" placeholders adjacent to each INPUT element which is what ss-utils.js uses to bind the field validation errors.

Binding HTML Forms

You can ajaxify a HTML FORM by using ss-utils bindForm jQuery mixin, e.g:

    success: function (contact) {
        $("#form-addcontact input").val('')

This takes over the handling of this FORM and instead of doing a POST back of the entire page to the server, makes an Ajax request using all the fields in the FORM to POST the data to the CreateContact Service:

public Contact Post(CreateContact request)
    var contact = request.ConvertTo<Contact>();
    return contact;

Fluent Validation

Normally the Service implementation will be called as-is but as we've added the FluentValidation ValidationFeature plugin and there exists a validator for CreateContact below:

public class ContactsValidator : AbstractValidator<CreateContact>
    public ContactsValidator()
        RuleFor(x => x.Name).NotEmpty().WithMessage("A Name is what's needed.");
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleFor(x => x.Age).GreaterThan(0);

The Request DTO is first validated with the above declarative rules and if it fails returns a structured error response which ss-utils uses to bind the validation errors to all the invalid field class=help-block (or help-inline) placeholders:

HTML Validation

Whilst the user goes back and corrects their INPUT, we can provide instant feedback and clear the errors as they update each each field with:


Once all is successful we invoke the success: callback with the response of the Service which in this case is the newly created Contact that we dynamically add to the contacts list by calling the existing addContacts() method. We also clear all form values and put focus back to the first field, ready for a rapid entry of the next Contact:

    success: function (contact) {
        $("#form-addcontact input").val('')

Manual Error Handling

The validate callback can be used to add client side validation logic which can manually set client-side validation errors using setFieldError(), e.g:

    validate: function(){
        var params = $(this).serializeMap();
        if (params.Password != params.Confirm) {
            $(this).setFieldError('Password', 'Passwords to not match');
            return false;

Declarative Events

An interesting difference in the dynamically generated HTML are the presence of data-click=showContact and data-click=deleteContact attributes:

function addContacts(contacts) {
    var html = (c) {
        return "<li data-id='" + c.Id + "' data-click='showContact'>" +
                "<span class='glyphicon glyphicon-user' style='margin: 0 5px 0 0'></span>" +
                c.Name + " " + " (" + c.Age + ")" +
                '<span class="glyphicon glyphicon-remove-circle" data-click="deleteContact"></span>'
             + "</li>";

This showcases some of the declarative event support in ss-utils which allows you to invoke event handlers without needing to maintain bookkeeping of event handlers when adding or removing elements. You can instead define one set of event handlers for the entire page with bindHandlers, e.g:

    showContact: function() {
        var id = $(this).data("id");
        $.getJSON("/contacts/" + id, function (contact) {
            $("#form-emailcontact .alert-success").hide();
    deleteContact: function () {
        var $li = $(this).closest("li");
        $.post("/contacts/" + $"id") + "/delete", function () {
    toggleAction: function() {
        var $form = $(this).closest("form"), action = $form.attr("action");
        $form.attr("action", $"action-alt"))
                .data("action-alt", action);

The matching event handler will be invoked whenever an element with data-{event}={handlerName} is clicked, e.g: data-click='showContact'.

In addition to click, a number of other jQuery events can be declared in this way, as defined in:

$.ss.listenOn = 'click dblclick change focus blur focusin focusout select keydown keypress keyup hover toggle';

Multiple Arguments

Declarative event handlers can also send multiple arguments:

    <li data-click="single">Foo</li>
    <li data-click="multiple:arg1,arg2">Bar</li>
    single: function(){
        var li = this;
    multiple: function(arg1, arg2) {
        var li = this;

Data Binding

Diving into the implementation of showContact we see ss-utils applyValues() jQuery mixin which binds a JS object to the target element, in this case #email-contact:

showContact: function() {
    var id = $(this).data("id");
    $.getJSON("/contacts/" + id, function (contact) {
        $("#form-emailcontact .alert-success").hide();

The data-binding applied by applyValues() include:

  • Set the value of all elements with matching id={field} or name={field}
  • Set the value of all elements marked with data-val={field}
  • Set the innerHTML contents of all elements marked with data-html={field}
  • Set the data-href and data-src attributes

Example Usage


Which binds the returned contact response object to the #email-contact HTML Element, populating all matching elements with data from contact:

<div id="email-contact">
    <a data-href="ProfileUrl"><img data-src="ProfileUrl" /></a>
        Email <span data-html="Name"></span>
    <h4>To: <span data-html="Email"></span></h4>
    <div class="clearfix"></div>
    <form id="form-emailcontact" method="POST">
        <input type="hidden" name="ContactId" data-val="Id"  />

Advanced bindForm usages

Form Loading

Whilst a FORM is being processed all its buttons with [type=submit] (overridable with $.ss.onSubmitDisable) are disabled and a loading class is added whilst a response from the server is pending. This can be used to provide UX feedback to end users with just CSS. E.g. we use .loading CSS rule to show the rotating glyphicon:

#email-contact .loading .rotate {
    visibility: visible;

Server initiated actions

Some useful functionality not demonstrated in this example is your Services ability to invoke client behavior by returning a response decorated with custom HTTP Headers. An example is being able to return "Soft Redirects" to navigate to a different page by adding a X-Location HTTP Header, e.g:

return new HttpResult(response) {
    Headers = {
        { "X-Location", newLocationUri },

When returned to a ajax form, it will instruct the page to automatically redirect to the new url.

You can also trigger an event on the page by returning a X-Trigger header, e.g:

return new HttpResult(response) {
    Headers = {
        { "X-Trigger", "showLoginPopup" },

In this case the page event handler named showLoginPopup will be invoked if it exists.

As we expect these features to be popular when developing ajax apps we've provided shorter typed aliases for the above examples:

return HttpResult.SoftRedirect(new ViewContact { Id = newContact.Id }.ToGetUrl(), newContact);
return HttpResult.TriggerEvent(contact, eventName:"showLoginPopup");


The $.fn.ajaxSubmit is also available for use independently to submit a HTML form via Ajax on demand. This is used in the connections.jsx React Component of Redis React's Connections Page to auto submit the form via ajax to the specified /connection url with the populated Form INPUT values. It also disables the #btnConnect submit button and adds a .loading class to the form whilst it's in transit which is used to temporarily show the loading sprite:

var Connections = React.createClass({
    onSubmit: function (e) {

        var $this = this;
            onSubmitDisable: $("#btnConnect"),
            success: function () {
                $this.setState({ successMessage: "Connection was changed" });
    render: function () {
        var conn = this.state.connection;
        return (
          <div id="connections-page">
            <div className="content">
                <form id="formConnection" className="form-inline" onSubmit={this.onSubmit} action="/connection">
                    <h2>Redis Connection</h2>
                    <div className="form-group">
                        <input name="host" type="text" />
                        <input name="port" type="text" className="form-control" />
                        <input name="db" type="text" className="form-control" />
                    <p className="actions">
                        <img className="loader" src="/img/ajax-loader.gif" />
                        <button id="btnConnect" className="btn btn-default btn-primary">Change Connection</button>
                    <p className="bg-success">{this.state.successMessage}</p>
                    <p className="bg-danger error-summary"></p>


Lets you easily parse the raw text of a Ajax Error Response into a responseStatus JavaScript object, example used in Redis React's Console Component:

.fail(function (jq, jqStatus, statusDesc) {
    var status = $.ss.parseResponseStatus(jq.responseText, statusDesc);
        cmd: cmd,
        result: status.message,
        stackTrace: status.stackTrace,
        type: 'err',


The bindAll API is a simple helper for creating lightweight JavaScript objects by binding this for all functions of an object literal to the object instance, e.g:

var Greeting = $.ss.bindAll({
    name: "World",
    sayHello: function() {
        alert("Hello, " +;

var fn = Greeting.sayHello;
fn(); // Hello, World

TypeScript Definition

The TypeScript definitions for ss-utils.d.ts is an embedded resource inside ServiceStack.dll which is available from /js/ss-utils.d.ts, e.g

API Reference

$.ss.onSubmitDisable = "[type=submit]"  // Disable elements during form submission

$.ss.validation = {                // Customize Validation
    overrideMessages: false,       // Whether to override Server Error Messages
    messages: {                    // List of Server ErrorCodes to override
      NotEmpty: "Required",        // Override `NotEmpty` ErrorCode with `Required`
$.fn.serializeMap()                // Return the FORM's INPUT values as a map
$.fn.setFieldError(name,msg)       // Set the error for field `name` with `msg`
$.fn.applyErrors(status,options)   // Apply errors in ResponseStatus to Element
$.fn.clearErrors()                 // Clear all errors applied to Element
$.ss.clearAdjacentError()          // Clear adjacent errors in help-block/inline
$.ss.parseResponseStatus           // Parse raw JSON Error ResponseStatus

$.fn.bindForm(options)             // Bind and Ajaxify the HTML Form
$.fn.ajaxSubmit()                  // Submit a HTML Form via Ajax
$.fn.applyValues(map)              // Databind values in `map` to HTML Element

$.fn.bindHandlers(handlers)        // Register global declarative JS handlers
$.ss.listenOn = "click ..."        // Specify DOM events for declarative events
$.ss.bindAll                       // Bind all object literal functions to itself

$.fn.setActiveLinks()              // Add `active` class to links with current url

$.ss.todate(string)                // Convert String to Date
$.ss.todfmt(string)                // Convert String to `YYYY-MM-DD` Date Format
$.ss.dfmt(date)                    // Convert Date to `YYYY-MM-DD` Date Format
$.ss.dfmthm(date)                  // Convert Date to `YYYY-MM-DD HH:MM:SS PM`
$.ss.tfmt12(date)                  // Convert Date to `HH:MM:SS PM`

$.ss.splitOnFirst(string,needle)   // Split on first occurrence of needle
$.ss.splitOnLast(string,needle)    // Split on last occurrence of needle

$.ss.getSelection()                // Get currently selected text (if any)

$.ss.queryString(url)              // Return a map of key value pairs

$.fn.handleServerEvents()          // Handle ServiceStack ServerEvents
$.ss.eventReceivers = {}           // Specify global receivers for ServerEvents

combinePaths and createUrl

The combinePaths and createUrl API's help with constructing urls, e.g:

$.ss.combinePaths("path","to","..","join")   //= path/join
$.ss.createPath("path/{foo}", {foo:1,bar:2}) //= path/1

$.ss.createUrl("http://host/path/{foo}",{foo:1,bar:2}) //= http://host/path/1?bar=2

normalize and normalizeKey

normalizeKey and normalize APIs helps with normalizing JSON responses with different naming conventions by converting each property into lowercase with any _ separators removed - normalizeKey() converts a single string whilst normalize() converts an entire object graph, e.g:

$.ss.normalizeKey("THE_KEY") //= thekey

)   //= {"thekey":"key","foo":"foo","bar":{"A":1}}

const deep = true;
    $.ss.normalize({THE_KEY:"key",Foo:"foo",bar:{A:1}}, deep) 
)   //= {"thekey":"key","foo":"foo","bar":{"a":1}}


postJSON is jQuery's missing equivalent to $.getJSON, but for POST's, eg:

$.ss.postJSON(url, {data:1}, response => ..., error => ...);

  1. Getting Started

    1. Creating your first project
    2. Create Service from scratch
    3. Your first webservice explained
    4. Example Projects Overview
    5. Learning Resources
  2. Designing APIs

    1. ServiceStack API Design
    2. Designing a REST-ful service with ServiceStack
    3. Simple Customer REST Example
    4. How to design a Message-Based API
    5. Software complexity and role of DTOs
  3. Reference

    1. Order of Operations
    2. The IoC container
    3. Configuration and AppSettings
    4. Metadata page
    5. Rest, SOAP & default endpoints
    6. SOAP support
    7. Routing
    8. Service return types
    9. Customize HTTP Responses
    10. Customize JSON Responses
    11. Plugins
    12. Validation
    13. Error Handling
    14. Security
    15. Debugging
    16. JavaScript Client Library (ss-utils.js)
  4. Clients

    1. Overview
    2. C#/.NET client
      1. .NET Core Clients
    3. Add ServiceStack Reference
      1. C# Add Reference
      2. F# Add Reference
      3. VB.NET Add Reference
      4. Swift Add Reference
      5. Java Add Reference
    4. Silverlight client
    5. JavaScript client
      1. Add TypeScript Reference
    6. Dart Client
    7. MQ Clients
  5. Formats

    1. Overview
    2. JSON/JSV and XML
    3. HTML5 Report Format
    4. CSV Format
    5. MessagePack Format
    6. ProtoBuf Format
  6. View Engines 4. Razor & Markdown Razor

    1. Markdown Razor
  7. Hosts

    1. IIS
    2. Self-hosting
    3. Messaging
    4. Mono
  8. Security

    1. Authentication
    2. Sessions
    3. Restricting Services
    4. Encrypted Messaging
  9. Advanced

    1. Configuration options
    2. Access HTTP specific features in services
    3. Logging
    4. Serialization/deserialization
    5. Request/response filters
    6. Filter attributes
    7. Concurrency Model
    8. Built-in profiling
    9. Form Hijacking Prevention
    10. Auto-Mapping
    11. HTTP Utils
    12. Dump Utils
    13. Virtual File System
    14. Config API
    15. Physical Project Structure
    16. Modularizing Services
    17. MVC Integration
    18. ServiceStack Integration
    19. Embedded Native Desktop Apps
    20. Auto Batched Requests
    21. Versioning
    22. Multitenancy
  10. Caching

  11. Caching Providers

  12. HTTP Caching

  13. CacheResponse Attribute

  14. Cache Aware Clients

  15. Auto Query

  16. Overview

  17. Why Not OData

  18. AutoQuery RDBMS

  19. AutoQuery Data

  20. AutoQuery Memory

  21. AutoQuery Service

  22. AutoQuery DynamoDB

  23. Server Events

    1. Overview
    2. JavaScript Client
    3. C# Server Events Client
    4. Redis Server Events
  24. Service Gateway

    1. Overview
    2. Service Discovery
  25. Encrypted Messaging

    1. Overview
    2. Encrypted Client
  26. Plugins

    1. Auto Query
    2. Server Sent Events
    3. Swagger API
    4. Postman
    5. Request logger
    6. Sitemaps
    7. Cancellable Requests
    8. CorsFeature
  27. Tests

    1. Testing
    2. HowTo write unit/integration tests
  28. ServiceStackVS

    1. Install ServiceStackVS
    2. Add ServiceStack Reference
    3. TypeScript React Template
    4. React, Redux Chat App
    5. AngularJS App Template
    6. React Desktop Apps
  29. Other Languages

    1. FSharp
      1. Add ServiceStack Reference
    2. VB.NET
      1. Add ServiceStack Reference
    3. Swift
    4. Swift Add Reference
    5. Java
      1. Add ServiceStack Reference
      2. Android Studio & IntelliJ
      3. Eclipse
  30. Amazon Web Services

  31. ServiceStack.Aws

  32. PocoDynamo

  33. AWS Live Demos

  34. Getting Started with AWS

  35. Deployment

    1. Deploy Multiple Sites to single AWS Instance
      1. Simple Deployments to AWS with WebDeploy
    2. Advanced Deployments with OctopusDeploy
  36. Install 3rd Party Products

    1. Redis on Windows
    2. RabbitMQ on Windows
  37. Use Cases

    1. Single Page Apps
    2. HTML, CSS and JS Minifiers
    3. Azure
    4. Connecting to Azure Redis via SSL
    5. Logging
    6. Bundling and Minification
    7. NHibernate
  38. Performance

    1. Real world performance
  39. Other Products

    1. ServiceStack.Redis
    2. ServiceStack.OrmLite
    3. ServiceStack.Text
  40. Future

    1. Roadmap
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.