Reference Source

Function

Static Public Summary
public

The abbreviateNumber utility converts a number to a shorter localized form.

public

alertEmailConfirmation(app: ForumApplication): {...vdom: Object, "children": *}

Shows an alert if the user has not yet confirmed their email address.

public

anchorScroll(element: DOMElement, callback: Function)

The anchorScroll utility saves the scroll position relative to an element, and then restores it after a callback has been run.

public

avatar(user: *, attrs: *): *

The avatar helper displays a user's avatar.

public

bidi(node: *, prop: *): *

public

computed(dependentKeys: ...String, compute: function): Function

The computed utility creates a function that will cache its output until any of the dependent values are dirty.

public

escapeRegExp(input: undefined): *

Escapes the RegExp special characters in input.

public

extend(object: object, methods: string | string[], callback: function)

Extend an object's method by running its output through a mutating callback every time it is called.

The callback accepts the method's return value and should perform any mutations directly on this value.

public

extract(object: undefined, property: undefined): *

The extract utility deletes a property from an object and returns its value.

public

extractText(vdom: VirtualElement): String

Extract the text nodes from a virtual element.

public

Calls console.warn with the provided arguments, but only if the forum is in debug mode.

public

formatNumber(number: undefined): *

The formatNumber utility localizes a number into a string with the appropriate punctuation.

public

fullTime(time: *): *

The fullTime helper displays a formatted time string wrapped in a <time> tag.

public
public

Strip HTML tags and quotes out of the given string, replacing them with meaningful punctuation.

public

highlight(string: *, phrase: *, length: *): *

The highlight helper searches for a word phrase in a string, and wraps matches with the <mark> tag.

public

humanTime(time: undefined): *

The humanTime utility converts a date to a localized, human-readable time- ago string.

public

humanTime(time: *): *

The humanTime helper displays a time in a human-friendly time-ago format (e.g.

public

icon(fontClass: *, attrs: *): *

The icon helper displays an icon.

public

insertText(textarea: undefined, undefined: undefined)

public

isExtensionEnabled(name: *): *

public
public

listItems(items: *): *

The listItems helper wraps a collection of components in

  • tags, stripping out any unnecessary Separator components.
  • public

    The liveHumanTimes initializer sets up a loop every 1 second to update timestamps rendered with the humanTime helper.

    public

    mapRoutes(routes: Object, basePath: String): Object

    The mapRoutes utility converts a map of named application routes into a format that can be understood by Mithril, and wraps them in route resolvers to provide each route with the current route name.

    public

    mixin(Parent: Class, mixins: ...Object): Class

    The mixin utility assigns the properties of a set of 'mixin' objects to the prototype of a parent object.

    public

    override(object: object, method: string | string[], newMethod: function)

    Override an object's method by replacing it with a new function, so that the new function will be run every time the object's method is called.

    public

    patchMithril(global: *)

    public

    proxifyCompat(compat: *, namespace: *): *

    public

    punctuateSeries(items: Array): VirtualElement

    The punctuateSeries helper formats a list of strings (e.g.

    public

    routes(app: App)

    The routes initializer defines the forum app's routes.

    public

    routes(app: App)

    The routes initializer defines the forum app's routes.

    public

    saveSettings(settings: *): *

    public

    Mithril 2 does not completely rerender the page if a route change leads to the same route (or the same component handling a different route).

    public

    slidable(element: DOMElement): Object

    The slidable utility adds touch gestures to an element so that it can be slid away to reveal controls underneath, and then released to activate those controls.

    public

    slug(string: undefined): *

    Create a slug out of the given string.

    public

    stringToColor(string: undefined): *

    Convert the given string to a unique color.

    public

    styleSelectedText(textarea: undefined, styleArgs: undefined)

    public

    subclassOf(A: *, B: *): *

    Check if class A is the same as or a subclass of class B.

    public

    truncate(string: undefined, length: undefined, start: undefined): *

    Truncate a string to the given length, appending ellipses if necessary.

    public

    ucfirst(string: undefined): *

    Make a string's first character uppercase.

    public

    userOnline(user: *): *

    The useronline helper displays a green circle if the user is online

    public

    username(user: *): *

    The username helper displays a user's username in a tag. If the user doesn't exist, the username will be displayed as [deleted].

    public

    withAttr(key: *, cb: *)

    An event handler factory that makes it simpler to implement data binding for component event listeners.

    Static Public

    public abbreviateNumber(number: undefined): * source

    import abbreviateNumber from 'flarum/common/utils/abbreviateNumber'

    The abbreviateNumber utility converts a number to a shorter localized form.

    Params:

    NameTypeAttributeDescription
    number undefined

    Return:

    *

    public alertEmailConfirmation(app: ForumApplication): {...vdom: Object, "children": *} source

    import alertEmailConfirmation from 'flarum/forum/utils/alertEmailConfirmation'

    Shows an alert if the user has not yet confirmed their email address.

    Params:

    NameTypeAttributeDescription
    app ForumApplication

    Return:

    {...vdom: Object, "children": *}

    public anchorScroll(element: DOMElement, callback: Function) source

    import anchorScroll from 'flarum/common/utils/anchorScroll'

    The anchorScroll utility saves the scroll position relative to an element, and then restores it after a callback has been run.

    This is useful if a redraw will change the page's content above the viewport. Normally doing this will result in the content in the viewport being pushed down or pulled up. By wrapping the redraw with this utility, the scroll position can be anchor to an element that is in or below the viewport, so the content in the viewport will stay the same.

    Params:

    NameTypeAttributeDescription
    element DOMElement

    The element to anchor the scroll position to.

    callback Function

    The callback to run that will change page content.

    public avatar(user: *, attrs: *): * source

    import avatar from 'flarum/common/helpers/avatar'

    The avatar helper displays a user's avatar.

    Params:

    NameTypeAttributeDescription
    user *
    attrs *

    Attributes to apply to the avatar element

    Return:

    *

    public bidi(node: *, prop: *): * source

    import bidi from 'flarum/common/utils/bidi'

    Params:

    NameTypeAttributeDescription
    node *
    prop *

    Return:

    *

    public computed(dependentKeys: ...String, compute: function): Function source

    import computed from 'flarum/common/utils/computed'

    The computed utility creates a function that will cache its output until any of the dependent values are dirty.

    Params:

    NameTypeAttributeDescription
    dependentKeys ...String

    The keys of the dependent values.

    compute function

    The function which computes the value using the dependent values.

    Return:

    Function

    public escapeRegExp(input: undefined): * source

    import escapeRegExp from 'flarum/common/utils/escapeRegExp'

    Escapes the RegExp special characters in input.

    Params:

    NameTypeAttributeDescription
    input undefined

    Return:

    *

    public extend(object: object, methods: string | string[], callback: function) source

    import {extend} from 'flarum/common/extend'

    Extend an object's method by running its output through a mutating callback every time it is called.

    The callback accepts the method's return value and should perform any mutations directly on this value. For this reason, this function will not be effective on methods which return scalar values (numbers, strings, booleans).

    Care should be taken to extend the correct object – in most cases, a class' prototype will be the desired target of extension, not the class itself.

    Params:

    NameTypeAttributeDescription
    object object

    The object that owns the method

    methods string | string[]

    The name or names of the method(s) to extend

    callback function

    A callback which mutates the method's output

    Example:

    Example usage of extending one method.
    extend(Discussion.prototype, 'badges', function(badges) {
      // do something with `badges`
    });
    Example usage of extending multiple methods.
    extend(IndexPage.prototype, ['oncreate', 'onupdate'], function(vnode) {
      // something that needs to be run on creation and update
    });

    public extract(object: undefined, property: undefined): * source

    import extract from 'flarum/common/utils/extract'

    The extract utility deletes a property from an object and returns its value.

    Params:

    NameTypeAttributeDescription
    object undefined
    property undefined

    Return:

    *

    public extractText(vdom: VirtualElement): String source

    import extractText from 'flarum/common/utils/extractText'

    Extract the text nodes from a virtual element.

    Params:

    NameTypeAttributeDescription
    vdom VirtualElement

    Return:

    String

    public fireDebugWarning(args: undefined) source

    import fireDebugWarning from 'flarum/common/helpers/fireDebugWarning'

    Calls console.warn with the provided arguments, but only if the forum is in debug mode.

    This function is intended to provide warnings to extension developers about issues with their extensions that may not be easily noticed when testing, such as accessibility issues.

    These warnings should be hidden on production forums to ensure webmasters are not inundated with do-gooders telling them they have an issue when it isn't something they can fix.

    Params:

    NameTypeAttributeDescription
    args undefined

    public formatNumber(number: undefined): * source

    import formatNumber from 'flarum/common/utils/formatNumber'

    The formatNumber utility localizes a number into a string with the appropriate punctuation.

    Params:

    NameTypeAttributeDescription
    number undefined

    Return:

    *

    public fullTime(time: *): * source

    import fullTime from 'flarum/common/helpers/fullTime'

    The fullTime helper displays a formatted time string wrapped in a <time> tag.

    Params:

    NameTypeAttributeDescription
    time *

    Return:

    *

    public getCategorizedExtensions(): * source

    import getCategorizedExtensions from 'flarum/admin/utils/getCategorizedExtensions'

    Return:

    *

    public getPlainContent(string: undefined): * source

    import {getPlainContent} from 'flarum/common/utils/string'

    Strip HTML tags and quotes out of the given string, replacing them with meaningful punctuation.

    Params:

    NameTypeAttributeDescription
    string undefined

    Return:

    *

    public highlight(string: *, phrase: *, length: *): * source

    import highlight from 'flarum/common/helpers/highlight'

    The highlight helper searches for a word phrase in a string, and wraps matches with the <mark> tag.

    Params:

    NameTypeAttributeDescription
    string *

    The string to highlight.

    phrase *

    The word or words to highlight.

    length *
    • optional

    The number of characters to truncate the string to. The string will be truncated surrounding the first match.

    Return:

    *

    public humanTime(time: undefined): * source

    import humanTime from 'flarum/common/utils/humanTime'

    The humanTime utility converts a date to a localized, human-readable time- ago string.

    Params:

    NameTypeAttributeDescription
    time undefined

    Return:

    *

    public humanTime(time: *): * source

    import humanTime from 'flarum/common/helpers/humanTime'

    The humanTime helper displays a time in a human-friendly time-ago format (e.g. '12 days ago'), wrapped in a <time> tag with other information about the time.

    Params:

    NameTypeAttributeDescription
    time *

    Return:

    *

    public icon(fontClass: *, attrs: *): * source

    import icon from 'flarum/common/helpers/icon'

    The icon helper displays an icon.

    Params:

    NameTypeAttributeDescription
    fontClass *

    The full icon class, prefix and the icon’s name.

    attrs *

    Any other attributes to apply.

    Return:

    *

    public insertText(textarea: undefined, undefined: undefined) source

    import insertText from 'flarum/common/utils/insertText'

    Params:

    NameTypeAttributeDescription
    textarea undefined
    undefined undefined

    public isExtensionEnabled(name: *): * source

    import isExtensionEnabled from 'flarum/admin/utils/isExtensionEnabled'

    Params:

    NameTypeAttributeDescription
    name *

    Return:

    *

    public isSafariMobile(): * source

    import isSafariMobile from 'flarum/forum/utils/isSafariMobile'

    Return:

    *

    See:

    public listItems(items: *): * source

    import listItems from 'flarum/common/helpers/listItems'

    The listItems helper wraps a collection of components in

  • tags, stripping out any unnecessary Separator components.
  • Params:

    NameTypeAttributeDescription
    items *

    Return:

    *

    public liveHumanTimes() source

    import liveHumanTimes from 'flarum/common/utils/liveHumanTimes'

    The liveHumanTimes initializer sets up a loop every 1 second to update timestamps rendered with the humanTime helper.

    public mapRoutes(routes: Object, basePath: String): Object source

    import mapRoutes from 'flarum/common/utils/mapRoutes'

    The mapRoutes utility converts a map of named application routes into a format that can be understood by Mithril, and wraps them in route resolvers to provide each route with the current route name.

    Params:

    NameTypeAttributeDescription
    routes Object
    basePath String
    • optional

    Return:

    Object

    See:

    public mixin(Parent: Class, mixins: ...Object): Class source

    import mixin from 'flarum/common/utils/mixin'

    The mixin utility assigns the properties of a set of 'mixin' objects to the prototype of a parent object.

    Params:

    NameTypeAttributeDescription
    Parent Class

    The class to extend the new class from.

    mixins ...Object

    The objects to mix in.

    Return:

    Class

    A new class that extends Parent and contains the mixins.

    Example:

    class MyClass extends mixin(ExistingClass, evented, etc) {}

    public override(object: object, method: string | string[], newMethod: function) source

    import {override} from 'flarum/common/extend'

    Override an object's method by replacing it with a new function, so that the new function will be run every time the object's method is called.

    The replacement function accepts the original method as its first argument, which is like a call to super. Any arguments passed to the original method are also passed to the replacement.

    Care should be taken to extend the correct object – in most cases, a class' prototype will be the desired target of extension, not the class itself.

    Params:

    NameTypeAttributeDescription
    object object

    The object that owns the method

    method string | string[]

    The name or names of the method(s) to override

    newMethod function

    The method to replace it with

    Example:

    Example usage of overriding one method.
    override(Discussion.prototype, 'badges', function(original) {
      const badges = original();
      // do something with badges
      return badges;
    });
    Example usage of overriding multiple methods.
    extend(Discussion.prototype, ['oncreate', 'onupdate'], function(original, vnode) {
      // something that needs to be run on creation and update
    });

    public patchMithril(global: *) source

    import patchMithril from 'flarum/common/utils/patchMithril'

    Params:

    NameTypeAttributeDescription
    global *

    public proxifyCompat(compat: *, namespace: *): * source

    import proxifyCompat from 'flarum/common/utils/proxifyCompat'

    Params:

    NameTypeAttributeDescription
    compat *
    namespace *

    Return:

    *

    public punctuateSeries(items: Array): VirtualElement source

    import punctuateSeries from 'flarum/common/helpers/punctuateSeries'

    The punctuateSeries helper formats a list of strings (e.g. names) to read fluently in the application's locale.

    punctuateSeries(['Toby', 'Franz', 'Dominion']) // Toby, Franz, and Dominion
    

    Params:

    NameTypeAttributeDescription
    items Array

    Return:

    VirtualElement

    public routes(app: App) source

    import routes from 'flarum/admin/routes'

    The routes initializer defines the forum app's routes.

    Params:

    NameTypeAttributeDescription
    app App

    public routes(app: App) source

    import routes from 'flarum/forum/routes'

    The routes initializer defines the forum app's routes.

    Params:

    NameTypeAttributeDescription
    app App

    public saveSettings(settings: *): * source

    import saveSettings from 'flarum/admin/utils/saveSettings'

    Params:

    NameTypeAttributeDescription
    settings *

    Return:

    *

    public setRouteWithForcedRefresh(route: undefined, params: undefined, options: undefined) source

    import setRouteWithForcedRefresh from 'flarum/common/utils/setRouteWithForcedRefresh'

    Mithril 2 does not completely rerender the page if a route change leads to the same route (or the same component handling a different route). This util calls m.route.set, forcing a reonit.

    Params:

    NameTypeAttributeDescription
    route undefined
    params undefined
    options undefined

    public slidable(element: DOMElement): Object source

    import slidable from 'flarum/forum/utils/slidable'

    The slidable utility adds touch gestures to an element so that it can be slid away to reveal controls underneath, and then released to activate those controls.

    It relies on the element having children with particular CSS classes. TODO: document

    Params:

    NameTypeAttributeDescription
    element DOMElement

    Return:

    Object

    Return Properties:

    NameTypeAttributeDescription
    reset function

    Revert the slider to its original position. This should be called, for example, when a controls dropdown is closed.

    public slug(string: undefined): * source

    import {slug} from 'flarum/common/utils/string'

    Create a slug out of the given string. Non-alphanumeric characters are converted to hyphens.

    NOTE: This method does not use the comparably sophisticated transliteration mechanism that is employed in the backend. Therefore, it should only be used to suggest slugs that can be overridden by the user.

    Params:

    NameTypeAttributeDescription
    string undefined

    Return:

    *

    public stringToColor(string: undefined): * source

    import stringToColor from 'flarum/common/utils/stringToColor'

    Convert the given string to a unique color.

    Params:

    NameTypeAttributeDescription
    string undefined

    Return:

    *

    public styleSelectedText(textarea: undefined, styleArgs: undefined) source

    import styleSelectedText from 'flarum/common/utils/styleSelectedText'

    Params:

    NameTypeAttributeDescription
    textarea undefined
    styleArgs undefined

    public subclassOf(A: *, B: *): * source

    import subclassOf from 'flarum/common/utils/subclassOf'

    Check if class A is the same as or a subclass of class B.

    Params:

    NameTypeAttributeDescription
    A *
    B *

    Return:

    *

    public truncate(string: undefined, length: undefined, start: undefined): * source

    import {truncate} from 'flarum/common/utils/string'

    Truncate a string to the given length, appending ellipses if necessary.

    Params:

    NameTypeAttributeDescription
    string undefined
    length undefined
    start undefined

    Return:

    *

    public ucfirst(string: undefined): * source

    import {ucfirst} from 'flarum/common/utils/string'

    Make a string's first character uppercase.

    Params:

    NameTypeAttributeDescription
    string undefined

    Return:

    *

    public userOnline(user: *): * source

    import userOnline from 'flarum/common/helpers/userOnline'

    The useronline helper displays a green circle if the user is online

    Params:

    NameTypeAttributeDescription
    user *

    Return:

    *

    public username(user: *): * source

    import username from 'flarum/common/helpers/username'

    The username helper displays a user's username in a tag. If the user doesn't exist, the username will be displayed as [deleted].

    Params:

    NameTypeAttributeDescription
    user *

    Return:

    *

    public withAttr(key: *, cb: *) source

    import withAttr from 'flarum/common/utils/withAttr'

    An event handler factory that makes it simpler to implement data binding for component event listeners.

    The handler created by this factory passes the DOM element's attribute identified by the first argument to the callback (usually a bidirectional Mithril stream: https://mithril.js.org/stream.html#bidirectional-bindings).

    Replaces m.withAttr for Mithril 2.0.

    Params:

    NameTypeAttributeDescription
    key *
    cb *

    See: