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:

Edit this page on GitHub