Components

Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.

Notifier

A frontend only component. It shows the user messages in the bottom right.

The notifier can be used on a page by instantiating the javascript class on the notification element available on most pages in the app.
Example:

const notificationsElement = $('#notifications')
const notifier = notificationsElement.length ? new Notifier(notificationsElement) : null

Notifier Methods

notify (message, level, isDismissable)
message - The message to be displayed to the user
level - info for a green notification, warn for an orange notification, error for a red notification
isDismissable(optional) - true(default) provides a button for the user to delete the notification. false to not provide the button.
Returns a Notification object

totalNotificationCount ()
Returns the total number of notifications shown. Only notifications created by notify are counted.

waitForAsyncOperation () Adds one to the notifier's count of async operations waiting to be resolved. While the count is greater than 0, the below saving notification is shown

resolveAsyncOperation (errorMsg)
errorMsg(optional) - The error message explaining why an awaited async operation failed.
If no arguments are passed the saved success notification is shown instead.

Notification

A frontend only component. A child component of the notifier. It represents a single notification generated by the notifier.

Notification Methods

dismiss ()
Removes the notification from the page.
Throws ReferenceError if the notification has already been removed from the page.

getText ()
Returns the text of the notification shown to the user.

isUserDismissable ()
Returns true if a button to dismiss the notification is accessible to the user, false otherwise.

isDismissed ()
Returns true if the notification has been removed from the page, false otherwise.

setUserDismissable (dismissable)
Controls whether the user has access to a button to dismiss the notification.
dismissable - true to show the dismiss button, false to hide it.
Throws ReferenceError if the notification has already been removed from the page.

setText (newText)
Sets the text of the notification shown to the user.
newText - The message to be shown to the user. Throws TypeError if newText is not a string
Throws ReferenceError if the notification has already been removed from the page.

toggleUserDismissable ()
If the user has access to a dismiss button, the dismiss button will be made unavailable. If the dismiss button is not accessible from the user, it will be made accessible to the user. Throws ReferenceError if the notification has already been removed from the page.

Local Time

A backend only component. Displays a localized time.

Parameters

format - A string to be passed to strftime
unix_timestamp - an integer representing the unix timestamp to be displayed
time_zone - The time zone to display the time in.

Example usage:

  <%= render (LocalTimeComponent.new(format: "A date: %b %d, %Y", unix_timestamp: 1694349775, time_zone: current_user&.decorate&.local_time_zone)) %>

Form Validation Components

These are components that initialize when their parent form is given a class of component-validated-form

Ranged Date Picker

A minimum and maximum date can be set for this date picker. If the date is found to be out of range, the form the date picker is a part of will not allow submitting and an error will be shown to the user.

HTML parameters

component_name - A word or phrase to complete this sentence: "Date for component_name is before minimum allowed date of 1/1/1111"
form - The form the datepicker is part of. Usually from a line that looks like form_with(...) do |form|
initial_value - The default value of the datepicker. Can be any string.
max_date - The latest valid date. Either today or a date format the javascript Date object can parse
min_date - The earliest valid date. Either today or a date format the javascript Date object can parse

Example Usage

<%= render "layouts/components/ranged_date_picker",
    form: form, model_field: :occurred_at, initial_value: occurred_at.to_date,
    max_date: "today", component_name: "occurred on" %>