Documentation

Format Functions

Format functions let you customize how fields are displayed in tabular result pages, e.g:

Where columns are customized using a built-in formatting function referenced by the [Format] attributes:

public class Contact : AuditBase
{
    [Format(FormatMethods.IconRounded)]
    public string ProfileUrl { get; set; }

    [Format(FormatMethods.Currency)]
    public int? SalaryExpectation { get; set; }

    [Format(FormatMethods.LinkEmail, Options = 
        @"{target:'_self',subject:'New Job Opportunity',
           body:'We have an exciting new opportunity...', cls:'text-green-600'}")]
    public string Email { get; set; }
 
    [Format(FormatMethods.LinkPhone)]
    public string Phone { get; set; }
    //....
}

Whilst the [Intl*] attributes provide a typed API to utilize JavaScript's rich Intl object containing the namespace for the ECMAScript Internationalization API, which provides number formatting, and date & time formatting, e.g:

Which was rendered using the [Format] ant [Intl*] attributes below:

public class Tracks
{
    [Format(Method = "stylize", Options = "{cls:'text-rose-500'}")]
    public string Name { get; set; }
    
    [IntlDateTime(Minute = DatePart.Digits2, Second = DatePart.Digits2, FractionalSecondDigits = 3)]
    public long Milliseconds { get; set; }
    
    [Format(FormatMethods.Bytes)]
    public long? Bytes { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD)]
    public decimal UnitPrice { get; set; }
    //....
}

Custom Format Function

The Name column shows an example of calling a custom stylize JavaScript function defined in /modules/locode/custom.js:

/**: Extend locode App with custom JS **/

/** Custom [Format] method to style text with custom class
 * @param {*} val
 * @param {{cls:string}} [options] */
function stylize(val, options) {
    let cls = options && options.cls || 'text-green-600'
    return `<span class="${cls}">${val}</span>`
}

Which makes use of JSDoc and TypeScript's JSDoc support to enable rich static analysis.

Format Attribute

The [Format] attribute lets you call any JavaScript function that exists in your Locode App. These formatting functions take the field value as a first argument and optionally an options object as the 2nd argument, for further customization and can return any HTML fragment to render in-place of the field value.

Where the [Format] attribute's arguments:

[Format(Method,Options)]

Calls the JavaScript function of that name, passing any options if specified:

method(field,options)

For improved discoverability a typed list of all formatting functions are maintained in FormatMethods.cs which map to the built-in JavaScript functions below which are also discoverable in the API Reference Function docs.

Number Formatters

Use number formatters to render numbers in a more human-readable formats:

FormatMethods.Currency

Formats a number into USD currency:

function currency(val: number): string;

This is a shorthand alias for [IntlNumber(Currency = NumberCurrency.USD)].

FormatMethods.Bytes

Formats bytes into human-readable file size:

function bytes(val: number): string;

The link* functions creates HTML Anchor links linking either URLs, emails or phone numbers. In addition to configuring common anchor attributes, the opt Options modifier also lets you configure any of its HTML attributes.

Create formatted HTML A URL links:

function link(href: string, opt?: { cls?: string; target?: string; rel?: string; }) : string;

FormatMethods.LinkEmail

Create formatted HTML A mailto: anchor links:

function linkMailTo(email: string, opt?: { subject?: string; body?: string;
    cls?: string; target?: string; rel?: string; }) : string;

FormatMethods.LinkPhone

Create formatted HTML A tel: anchor links:

function linkTel(tel: string, opt?: { cls?: string; target?: string; rel?: string; }): string;

FormatMethods.Attachment

Creates HTML Link and preview icon for a file. If the file is an image it will render its icon otherwise will use the appropriate icon for its file type.

function attachment(url: string): string;

Rendered with:

public class JobApplicationAttachment
{
    [Format(FormatMethods.Attachment)]
    public string FilePath { get; set; }
    
    [Format(FormatMethods.Bytes)]
    public long ContentLength { get; set; }
}

Format Images

For rendering preview icons of an image instead of its relative or absolute URL.

FormatMethods.Icon

Create HTML IMG Icon from URL

function icon(url: string): string;

FormatMethods.IconRounded

Create rounded HTML IMG Icon from URL

function iconRounded(url: string): string;

FormatMethods.Hidden

For hiding a column from appearing in query results:

function hidden(o: any): string;

TIP

To hide a field from appearing in Create or Edit UI Forms use [Input(Ignore=true)] instead.

Intl Attributes

The [Intl*] attributes provide a typed API to utilize ECMAScript Internationalization Intl API providing flexible number formatting, and date & time formatting functions:

The above referenced docs contain the available formatting options for each formatting function, we recommend using their JavaScript console to find out the formatting options you want, which should map 1:1 with the C# enums and constants in IntlAttribute.cs.

Intl

[Intl] is a generic attribute capable of calling any of the supported APIs although it's more UX-friendly to use the specific [Intl*] attributes instead, e.g:

[IntlNumber(Currency = NumberCurrency.USD)]

Is a shorter alias that's equivalent to:

[Intl(IntlFormat.Number, Number = NumberStyle.Currency, Currency = NumberCurrency.USD)]

IntlNumber

Makes use of Intl.NumberFormat to format numbers, checkout Examples for a quick preview of the common formatting options available.

public class IntlNumberExamples
{
    [IntlNumber]
    public int Example1 { get; set; }
    
    [IntlNumber(NumberStyle.Decimal, Locale = "en-AU", 
                RoundingMode = RoundingMode.HalfCeil, SignDisplay = SignDisplay.ExceptZero)]
    public int Example2 { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD)]
    public int Example3 { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD, CurrencyDisplay = CurrencyDisplay.Code)]
    public int Example4 { get; set; }
    
    [IntlNumber(Unit = NumberUnit.Kilobyte)]
    public int Example5 { get; set; }
}

Which translates to the following JavaScript function invocations:

const number = 123456.789;

// Example 1: 123,456.789
new Intl.NumberFormat().format(number)

// Example 2: +123,456.789
new Intl.NumberFormat('en-AU', { style: 'decimal', roundingMode:'halfCeil', signDisplay:'exceptZero' })

// Example 3: $123,456.79
new Intl.NumberFormat(undefined, { style:'currency', currency:'USD' })

// Example 4: USD 123,456.79
new Intl.NumberFormat(undefined, { style:'currency', currency:'USD', currencyDisplay:'code' })

// Example 5: 123,456.789 kB
new Intl.NumberFormat(undefined, { style:'unit', unit:'kilobyte' })

IntlDateTime

Makes use of Intl.DateTimeFormat to format dates and times, checkout Examples for available date & time styles.

public class IntlDateExamples
{
    [IntlDateTime]
    public DateTime Example1 { get; set; }
    
    [IntlDateTime(DateStyle.Medium, TimeStyle.Short, Locale = "en-AU")]
    public DateTime Example2 { get; set; }
    
    [IntlDateTime(DateStyle.Short)]
    public DateTime Example3 { get; set; }
    
    [IntlDateTime(Year = DatePart.Digits2, Month = DateMonth.Short, Day = DatePart.Numeric)]
    public DateTime Example4 { get; set; }
}

Translates to:

const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));

// Example 1: 12/20/2020
new Intl.DateTimeFormat().format(date)

// Example 2: 20 Dec 2020, 11:23 am
new Intl.DateTimeFormat('en-AU', { dateStyle:'medium', timeStyle:'short' }).format(date)

// Example 3: 12/20/20
new Intl.DateTimeFormat(undefined, { dateStyle:'short' }).format(date)

// Example 4: Dec 20, 20
new Intl.DateTimeFormat(undefined, { year:'2-digit', month:'short', day:'numeric' }).format(date)

IntlRelativeTime

Makes use of Intl.RelativeTimeFormat to format dates and times, checkout Examples for common usages.

Can be applied to DateTime and TimeSpan properties to render a time that's relative to now, e.g:

public class Booking : AuditBase
{    
    [IntlDateTime(DateStyle.Long)]
    public DateTime BookingStartDate { get; set; }
    
    [IntlRelativeTime]
    public DateTime? BookingEndDate { get; set; }

    [IntlRelativeTime]
    public TimeSpan TimeAgo => DateTime.UtcNow - this.BookingStartDate;
    //....
}

Renders the following formatted date & relative times: