Script and Razor Server UI Controls

Deprecated. Moved to #Script Pages UI Controls and Razor UI Controls dedicated docs.

Both #Script Pages and ServiceStack.Razor Share the same implementations for their Server Controls which are utilized in ASP.NET Core Project Templates and World Validation Application.

UI Component List​

Currently the component libraries include common Bootstrap UI Form Controls and Navigation Components, here's a side-by-side comparison displaying the names for the different Control for each Server Control:

Control #Script Pages ServiceStack.Razor
ErrorSummary validationSummary @Html.ValidationSummary
ValidationSuccess validationSuccess @Html.ValidationSuccess
Input formInput @Html.FormInput
TextArea formTextarea @Html.FormTextarea
Select formSelect @Html.FormSelect
CheckBox formInput({type:'checkbox'}) @Html.FormInput(new )
HiddenInputs htmlHiddenInputs @Html.HiddenInputs
SvgImage svgImage @Html.SvgImage
Nav nav @Html.Nav
Navbar navbar @Html.Navbar
NavLink navLink @Html.NavLink
NavButtonGroup navButtonGroup @Html.NavButtonGroup

Bootstrap UI Form Controls​

The Bootstrap UI form controls include built-in support for validation where they can render validation errors from ServiceStack's ResponseStatus object, e.g the Login Page in World Validation:

#Script Pages​

<form action="/auth/credentials" method="post" class="col-lg-4">
    <div class="form-group">
        {‎{ ['userName','password'] | validationSummary({class:'alert alert-warning'}) }‎}
        {‎{ { continue: qs.continue ?? '/server/', errorView:'/server/login' } | htmlHiddenInputs }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'userName'} 
           | formInput({label:'Email',help:'Email you signed up with',size:'lg'}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'password',type:'password'} 
           | formInput({label:'Password',help:'6 characters or more',size:'lg',preserveValue:false}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'rememberMe',type:'checkbox',checked:true} | formInput({label:'Remember Me'}) }‎}
    </div>
    <div class="form-group">
        <button type="submit" class="btn btn-lg btn-primary">Login</button>
    </div>
    <div class="form-group">
        <a class="lnk" href="/server/register">Register New User</a>
    </div>
</form>

ServiceStack.Razor​

The equivalent implementation in Razor:

<form action="/auth/credentials" method="post" class="col-lg-4">
    <div class="form-group">
        @Html.ValidationSummary(new[]{ "userName","password" }, 
            new { @class = "alert alert-warning" })
        
        @Html.HiddenInputs(new { 
            @continue = Html.Query("continue") ?? "/server-razor/",
            errorView = "/server-razor/login"
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { id = "userName" }, new InputOptions {
            Label = "Email",
            Help  = "Email you signed up with",
            Size  = "lg",
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { id = "password", type = "password" }, new InputOptions {
            Label = "Password",
            Help  = "6 characters or more",
            Size  = "lg",
            PreserveValue = false,
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id   = "rememberMe", 
            type = "checkbox",
            @checked = true,
        },
        new InputOptions { Label = "Remember Me" })
    </div>
    <div class="form-group">
        <button type="submit" class="btn btn-lg btn-primary">Login</button>
    </div>
    <div class="form-group">
        <a class="lnk" href="/server-razor/register">Register New User</a>
    </div>
</form>

Login Page UI​

The Login Page contains a standard Bootstrap Username/Password form with labels, placeholders and help text, which initially looks like:

What it looks like after submitting an empty form with Server Exception Errors rendered against their respective fields:

Form Control Properties​

Essentially both #Script and Razor have identical properties but implemented idiomatically for each control where #Script uses camelCase names and JS Object literals. The first (aka target) argument is for attributes you want to add to the HTML <input/> Element whilst the 2nd Argument is used to customize any of its other high-level features:

/// High-level Input options for rendering HTML Input controls
public class InputOptions
{
    /// Display the Control inline 
    public bool Inline { get; set; }
    
    /// Label for the control
    public string Label { get; set; }
    
    /// Class for Label
    public string LabelClass { get; set; }
    
    /// Override the class on the error message (default: invalid-feedback)
    public string ErrorClass { get; set; }

    /// Small Help Text displayed with the control
    public string Help { get; set; }
    
    /// Bootstrap Size of the Control: sm, lg
    public string Size { get; set; }
    
    /// Multiple Value Data Source for Checkboxes, Radio boxes and Select Controls 
    public object Values { get; set; }

    /// Typed setter of Multi Input Values
    public IEnumerable<KeyValuePair<string, string>> InputValues
    {
        set => Values = value;
    }

    /// Whether to preserve value state after post back
    public bool PreserveValue { get; set; } = true;

    /// Whether to show Error Message associated with this control
    public bool ShowErrors { get; set; } = true;
}

Contacts Page​

The Contacts Page shows a more complete example with a number of different UI Controls.

#Script Pages​

<form action="/contacts" method="post" class="col-lg-4">
    <div class="form-group">
        {‎{ 'title,name,color,age,filmGenres,agree' | validationSummary }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'title',type:'radio'} | formInput({values:contactTitles,inline:true}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'name',placeholder:'Name'} | formInput({label:'Full Name',help:'Your first and last name'}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'color',class:'col-4'}
           | formSelect({label:'Favorite color',values:{'', ...contactColors}‎}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'filmGenres',type:'checkbox'} 
          | formInput({label:'Favorite Film Genres',values:contactGenres,help:"choose one or more"}) }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'age',type:'number',min:13,placeholder:'Age',class:'col-3'} | formInput }‎}
    </div>
    <div class="form-group">
        {‎{ {id:'agree',type:'checkbox'} | formInput({label:'Agree to terms and conditions'}) }‎}
    </div>
    <div class="form-group">
        <button class="btn btn-primary" type="submit">Add Contact</button>
        <a href="/server/contacts/">reset</a>
    </div>
</form>

Whereas Razor uses anonymous objects for properties that can be unbounded like a HTML Element Attribute List and a Typed Class like InputOptions to specify the controls other high-level features, e.g:

ServiceStack.Razor​

<form action="/contacts" method="post" class="col-lg-4">
    <div class="form-group">
        @Html.ValidationSummary(new[]{ "title","name","color","age","filmGenres","agree" })
        @Html.HiddenInputs(new { @continue = Continue, errorView = Continue })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "title", 
            type = "radio",
        }, new InputOptions { 
            Values = Html.ContactTitles(),
            Inline = true,
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "name", 
            placeholder = "Name", 
        }, new InputOptions {
            Label = "Full Name",
            Help  = "Your first and last name",
        })
    </div>
    <div class="form-group">
        @Html.FormSelect(new { 
            id = "color", 
            @class = "col-4", 
        }, new InputOptions {
            Label  = "Favorite color",
            Values = new StringDictionary { {"",""} }.Merge(Html.ContactColors()),
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "filmGenres", 
            type = "checkbox",
        }, new InputOptions { 
            Label  = "Favorite Film Genres",
            Help   = "choose one or more",
            Values = Html.ContactGenres()
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "age", 
            type = "number",
            min = 13,
            placeholder = "Age",
            @class = "col-3",
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new {
            id   = "agree",
            type = "checkbox",
        },
        new InputOptions { Label = "Agree to terms and conditions" })
    </div>
    <div class="form-group">
        <button class="btn btn-primary" type="submit">Add Contact</button>
        <a href="/server-razor/contacts/">reset</a>
    </div>
</form>

Both Server UI Controls provide auto Validation Form Binding for any validation rules specified on the CreateContact Validator:

public class CreateContactValidator : AbstractValidator<CreateContact>
{
    public CreateContactValidator()
    {
        RuleFor(r => r.Title).NotEqual(Title.Unspecified).WithMessage("Please choose a title");
        RuleFor(r => r.Name).NotEmpty();
        RuleFor(r => r.Color).Must(x => x.IsValidColor()).WithMessage("Must be a valid color");
        RuleFor(r => r.FilmGenres).NotEmpty().WithMessage("Please select at least 1 genre");
        RuleFor(r => r.Age).GreaterThan(13).WithMessage("Contacts must be older than 13");
        RuleFor(x => x.Agree).Equal(true).WithMessage("You must agree before submitting");
    }
}

As well as any ArgumentException thrown within the Service Implementation:

public object Any(CreateContact request) 
{
    var newContact = request.ConvertTo<Data.Contact>();
    newContact.Id = Interlocked.Increment(ref Counter);
    newContact.UserAuthId = this.GetUserId();
    newContact.CreatedDate = newContact.ModifiedDate = DateTime.UtcNow;

    var contacts = Contacts.Values.ToList();
    var alreadyExists = contacts.Any(x => x.UserAuthId == newContact.UserAuthId && x.Name == request.Name);
    if (alreadyExists)
        throw new ArgumentException($"You already have contact named '{request.Name}'",nameof(request.Name));
    
    Contacts[newContact.Id] = newContact;
    return new CreateContactResponse { Result = newContact.ConvertTo<Contact>() };
}

Contacts Page UI​

The Contacts Page is representative of a more complex page that utilizes a variety of different form controls where the same page is also responsible for rendering the list of existing contacts:

Here's an example of what a partially submitted invalid form looks like:

To view the complete implementation in context checkout World Validation Server Implementation.

The Server Navigation Controls are used to render your Apps Unified Navigation

#Script Pages​

In #Script Pages you can use render the navbar and navButtonGroup methods to render NavItems:

You can render the main menu navigation using the navbar script method:

{‎{ navbar }‎}

Which by default renders the View.NavItems main navigation, using the default NavOptions and User Attributes (if authenticated):

You can also render a different Navigation List with:

{‎{ navItems('submenu').navbar() }‎}

Which can be customized using the different NavOptions properties above, in camelCase:

{‎{ navItems('submenu').navbar({ navClass: 'navbar-nav navbar-light bg-light' }) }‎}

Button group​

The navButtonGroup script can render NavItems in a button group, e.g. the OAuth buttons are rendered with:

{‎{ 'auth'.navItems().navButtonGroup({ navClass: '', navItemClass: 'btn btn-block btn-lg' }) }‎}

Which renders a vertical, spaced list of buttons which look like:

Razor Pages​

The same server controls are available in ServiceStack.Razor Apps as HTML Helper extension methods:

@Html.Navbar()

@Html.Navbar(Html.GetNavItems("submenu"))

@Html.Navbar(Html.GetNavItems("submenu"), new NavOptions {
    NavClass = "navbar-nav navbar-light bg-light"
})

@Html.NavButtonGroup(Html.GetNavItems("auth"), new NavOptions {
    NavClass = "",
    NavItemClass = "btn btn-block btn-lg",
})

The NavItem classes capture the Navigation information which is used together with the NavOptions class below:

public class NavOptions
{
    /// User Attributes for conditional rendering, e.g:
    ///  - auth - User is Authenticated
    ///  - role:name - User Role
    ///  - perm:name - User Permission 
    public HashSet<string> Attributes { get; set; }
    
    /// Path Info that should set as active 
    public string ActivePath { get; set; }
    
    /// Prefix to include before NavItem.Path (if any)
    public string BaseHref { get; set; }

    // Custom classes applied to different navigation elements (defaults to Bootstrap classes)
    public string NavClass { get; set; }
    public string NavItemClass { get; set; }
    public string NavLinkClass { get; set; }
    
    public string ChildNavItemClass { get; set; }
    public string ChildNavLinkClass { get; set; }
    public string ChildNavMenuClass { get; set; }
    public string ChildNavMenuItemClass { get; set; }
}

Use camelCase when specifying nav options in #Script controls.

Edit this page on GitHub