3.5.0Components for building user interfaces
A virtical navigation accordion component
Extends sp-tab-container
<sp-accordion />
An accordion page
Extends sp-tab-page
<sp-accordion-page />
A confirm dialog box with options for accepting or rejecting
<sp-confirm />
A <sp-confirm /> component's ViewModel
Extends sp-modal.ViewModel
The text to display in the accept confirmation button. The default is 'Ok'
Type: String
The text to display in the reject confirmation button. The default is 'Cancel'
Type: String
Called when the accept button is clicked. Resolves the actionPromise.
In addition, the accept event is dispatched on the component element.
Called when the reject button is clicked. Rejects the actionPromise.
In addition, the reject event is dispatched on the component element.
Inserts a dropdown toggle button into the page. Consider using spectre.css css-only dropdowns instead
<sp-dropdown />
Dropdown View Model
The icon class to display next to the dropdown.
The default is a font-awesome caret fa fa-fw fa-caret-down
Type: string
iconClass:from="'fa fa-fw fa-table'"
The button class to apply to the button dropdown. The default is btn btn-link.
See the spectre.css styles for details on more button classes available
Type: String
An array of buttons to display next to the dropdown button. This creates a split dropdown menu button group
Type: Array<sp-dropdown.ButtonObject>
Whether or not to align this dropdown menu on the right hand side of the button.
Type: HTMLBoolean
toggles the display of a sp-dropdown component
(Event)
(event) the click event to cancel
(Boolean)
optional - whether or not to display the menu,
if undefined the dropdown will toggle the current visibility
Boolean:
always returns false to prevent page navigation from occuring
Queries the dom for other sp-dropdown components and hides them. This is used when a dropdown component is visible and another one is clicked, any others will be made invisible
When a primary button is clicked, this function dispatches the primaryclick
event with the button that was clicked as its argument.
(ButtonObject)
the button that was clicked
(MouseEvent)
The mouse click event on the button that we should prevent default
Boolean:
returns false to prevent event from changing page route
A formatted list of files with slots for actions. Images are displayed if available.
<sp-file-list />
A type used throughout the sp-file-list component to represent array of file maps
Type: DefineList
`import {FileList} from 'spectre-canjs/sp-file-list/ViewModel';
A <sp-file-list /> component's ViewModel
A list of file objects
Type: FileList
Removes an individual file from the list
(FileMap)
The file to remove from the list
Sets the isDragOver value to something else
(DomEvent)
Event to prevent default on
(any)
Whether or not drag over is currently happening
Triggers a click event on the hidden input element
(DomEvent)
Event to prevent default on
Called when viewmodel is connected to the dom
(DomElement)
This components root element
A modal dialog
<sp-modal />
A <sp-modal /> component's ViewModel
Whether or not this modal is currently active. The default is false
Type: HTMLBoolean
Whether or not to use a custom body content for the modal. The default is false.
This overrides the title property and modal-body divs displayed by displaying
only the content passed to the <sp-modal></sp-modal> component
Type: HTMLBoolean
Flag to make this modal a small (modal-sm) modal. The default is false
Type: HTMLBoolean
Whether or not to display this modals backdrop. The default is true.
Type: Boolean
Shows this modal
Hides this modal
A paginate ui component
<sp-paginate />
A <sp-paginate /> component's ViewModel
The number of pages to show on either side of the currently selected page. The default is 3. For example, if the selected page is 5, the visible pages should be 2,3,4,5,6,7,8.
Type: Number
A virtual property used by the template to indicate whether or not there is a next page
Type: Boolean
A virtual property used by the template to indicate whether or not there is a previous page
Type: Boolean
Hides the first button
Type: HTMLBoolean
Hides the last button
Type: HTMLBoolean
Hides the previous button
Type: HTMLBoolean
Hides the next button
Type: HTMLBoolean
Hides the list of pages
Type: HTMLBoolean
Tab page component used in the sp-tab-container for navigation
<sp-tab-page />
A <sp-tab-page /> component's ViewModel
A navigation container for navigating between tabbed pages
<sp-tab-container />
A <sp-tab-container /> component's ViewModel
An array of pages currently displayed in this sp-tab-container
Type: Array<sp-tab-page.ViewModel>
The currently active page
Type: sp-tab-page.ViewModel
The id of the page that is currently active. This value should be set to change the activePage
Type: String
When a <sp-tab-page> element is inserted into the document, it calls this
method to add the page's scope to thepages array.
(sp-tab-page.ViewModel)
the page view model that was added
When a <page> element is removed from the document, it calls this
method to remove the page's scope from the pages array.
(sp-tab-page.ViewModel)
the page view model to remove
Sets a page to the currently selected/active page
(sp-tab-page.ViewModel)
The page to set as the active page
Used by nav containers that might need to toggle pages, rather than just activate them (accordion)
(sp-tab-page.ViewModel)
the page to toggle
A hideable notification component
A <sp-toast /> component's ViewModel
Whether or not to use the content tag, that will display whatever
is inside the <sp-toast></sp-toast> tags. This overrides the
body property of this sp-toast
Type: Boolean
The class that gives the sp-toast context. Must be either info, success, warning, or danger.
Type: string
Marks the sp-toast as dismissable, which adds a "close" icon to the sp-toast. The default is true
Type: boolean
Displays a helpful icon next to the toast text
Set to null or empty string to exclude icon completely. The default is
icon icon-error_outline
Type: boolean
Hide this sp-toast
A controller that adds and removes toasts from the dom
<sp-toast-container />
A <sp-toast-container /> component's ViewModel
adds a new toast
(sp-toast.ViewModel)
the toast options or toast object to add
Removes a toast
(sp-toast.ViewModel)
the toast object to remove
Components for managing and viewing data
A filter component for creating complex filters
<sp-filter />
A component for allowing users to create complex filters
<sp-filter-builder />
A <sp-filter-builder /> component's ViewModel.
A string referencing a field type that will exclude that field from this classes fields. The default is 'list'.
Type: String
A list of filterObjects currently used in this widget
Type: Array<sp-filter-builder.Filter>
An array of field options to display for the field selection dropdown.
Type: Array<sp-form/fields/sp-select-field.SelectOption>
Adds a new filter or set of filters to the list of filters in this widget.
TODO: A filterFactory may be defined on the field which may return one filter or an array of
filters.
(string)
the array of arguments from the fieldchange event
Boolean:
returns false to prevent event propagation from links
Creates a new filter
A value to filter on. Can be any primitive type. If the
[sp-filter-builder.Filter.props.field field] property
is set, the field.type property will be used to coerce the value.
Type: any
A field object that defines the available operator options and properties.
This is used to create the dropdown choice for each filter in the sp-filter-builder.
This field is generated automatically. If the
[sp-filter-builder.Filter.props.field field] property is set,
the field.type property will be used to filter the operator options.
Type: Object
A property to show or hide this filter in the picker. The default is true
Type: Boolean
A property to disable this filter's remove button. This filter will not
be removable. In addition, the operator field will be fixed. The default
is false.
Type: Boolean
A virtual property to provide the field alias. If the
[sp-filter-builder.Filter.props.field field] property is set, this alias
will match the field.alias
Type: String
A field object that defines the value field properties.
This is used to create the value field for each filter in the sp-filter-builder.
If the [sp-filter-builder.Filter.props.field field] property is set, the
valueField will be a customized field based off of the set field.
Type: util/field/Field
The field object used to initialize this filter. When this value is provided, the custom field will be used in place of the regular text field. This allows the user to interract with a different type of field, like a checkbox when setting filters.
Type: util/field/Field
A virtual property that creates a dummmy form object for use with the field template
Type: Object
a setter for the value field for use with the field template
(util/field/Field)
the field object
(domElement)
the input element
(Object)
the view model scope
(any)
the object with the value set on the form
Creates a new filter list
A table to hold an array of objects - one object per row
<sp-list-table fields:from="fields" objects:from="objects" />
{
fields: ['field_name', {
name: 'other_name',
displayComponent: '<strong>{{object[field.name]}}</strong>
}]
}
A <sp-list-table /> component's ViewModel.
A string referencing a field type that will exclude that field from this classes fields. The default is 'list'.
Type: String
Optional promise or deferred object that will resolve to an object. Once the promise resolves, the objects list will be replaced with the promise result
Type: Promise
Id type name for the rows of objects. The default is id. This value
is used to determine whether objects are selected or not. For a built in
unique ID, _cid may be used. _cid is automatically generatted by can-define
and should be guaranteed to be unique accross all DefineMaps
Type: String
A virtual type that helps the template determine whether all objects are selected
Type: Boolean
The current sort field
Type: can.List
Selects or unselects all of the objects in the table
A two column table for displaying Field:value object pairs
<sp-property-table />
A <sp-property-table /> component's ViewModel. This viewmodel
extends the [util/field/ ]'s properties
A string referencing a field property that will exclude that field from this classes fields. The default is 'detail'.
Type: String
A flag to allow deleting (Not yet implemented) TODO: implement deleting
Type: Boolean
The ID value of the object that should be retrieved. This value along with the connection object will be used to retrieve an object from a RESTful service
Type: Number
The connection object that should be used to retrieve an object. This value along with the objectId value will be used to retrieve an object from a RESTful service
Type: can-connect
A generic object to display in a tabular format. This can be used instead of providing a connection and objectId property
Type: Object
A promise that resolves to the object. Used to determine state of current fetching operations
Type: Promise
Asynchronously fetches an object using a can-connect model and an id
(can-connect)
The connection object to an api resource. The model must have a
get(id)
method.
(Number)
The id number of the object to retrieve
Promise:
A promise that is resolved once the object is retreived
Field components for modifying and creating data. Use with sp-form.
A form component useful for validation, data updating, and dirty checking
<sp-form />
Form View Model
A string referencing a field type that will exclude that field
from this classes fields. The default is 'edit'.
Type: String
Whether or not to show the saving icon when the submit button is clickered.
Type: HTMLBoolean
The connection info for this form's data. If this is provided, the object will be fetched using the objectId type
Type: can-connect
The object id of the item to retrieve. If this and [sp-form.ViewModel.connection] is provided, a request will be made to the connection object with the specified id.
Type: Number
An object representing the current state of the values passed to the form. If the fields have changed, this object will be updated when the submit button is pressed and the validations have passed. To capture current state of the form, use [sp-form.ViewModel.dirtyObject].
Type: DefineMap
An object consisting of validation error strings
{
field: 'error message',
otherfield: 'another error message'
}
Type: Object
A boolean field that can be used as a switch or a checkbox
<sp-check-field />
A file upload field using dropzone. See http://www.dropzonejs.com/
<sp-dropzone-field />
The <sp-dropzone-field /> component viewmodel
Extends Field
The timout to automatically remove files from the dropzone container after successful uploads. Set to 0 to never remove
Type: Number
When the upload succeeds, the 'fieldchange' event is dispached
(FileMap)
The uploaded file
(any)
The result json from the rest service
Removes the uploaded file after a set time
(FileMap)
the file to remove
A field for handling multiple checkboxes
<sp-multi-check-field />
The <sp-multi-check-field /> component viewmodel
Extends Field
The current value of this field. Can be string or a list.
Type: Any
The current array values selected. When this changes, it updates the value
Type: Array<Any>
A select dropdown
<sp-select-field />
A fieldset to display a set of fields in a nested pattern
<sp-subform-field />
A
Extends Field
The type of object to use for this form object. If you'd like
to use a different type, than the Type defined in define map,
you can provide a subType instead. This will override the Type.
Type: Constructor
An alternative property to using Type. Since Type is a DefineMap keyword, subType is provided to allow for customizability between the field and the map
Type: Constructor
A basic text field configureable to be formatted as different HTML5 input types or HTML textarea elements
<sp-text-field />
A <sp-text-field /> component's ViewModel
Extends Field
The type of input to create. The default is 'text'
Type: String
textType="number"
Show or hide the clear input addon button
Type: Boolean
showClear="true"
Checks for the enter keypress and triggers a change event on the input The enter key press triggers a submit event on the form, but before the submit event, we need to trigger a change on the field value
(domElement)
The form input element
(KeyDownEvent)
The form submit event
Boolean:
Utility functions and classes
Constructs a new field. Used throughout spectre-canjs to define displays of properties, aka fields.
A friendly name for the field used to display to the user The default is to capitalize the name and remove underscores
Type: String
A virtual property that is used as a shorthand for setting all properties on this field. This value doesn't actually get set and will never return anything.
Type: Object
The form object. Passed to fields so they can use it in cascading dropdowns...etc
Type: Object
A boolean flag to display form field inline with others and hide labels
Type: Boolean
Text to display when the field is empty (like a textbox). Doesn't apply to some fields, like select or date fields.
Type: String
Adds css classes to the table cells and headings. Selectors should use
th.classname and td.classname
Type: String
If field component implements this method, it will be called when the component is inserted, with the input element It can be used to customize the input, like adding a date picker
Validates a type and returns a string if the field is invalid
(ValidationObject)
A special object consisting of information about the current value and dirty state of the form object
(String | falsey):
a string error message if the value is not valid or undefined if there is no error message
A base class for widgets that need to iterate through a set or subset
of fields.
ViewModels inheriting this map should define a excludeFieldKey which
is a field property that will exclude those fields from this class. For
instance, if we are designing an edit widget, an appropriate way to exclude
fields from the widget would be to use the key edit: false and set
excludeFieldKey: 'edit' in this class.
Converts a DefineMap to an array of Field objects using the property definitions property or the keys
((Constructor | DefineMap))
The extended map/constructor to parse
Array<util/field/Field>:
The array of fields
Converts an array of strings or field json objects into Field objects
(Constructor
= Field)
Type of field to create and return
Array<Field>:
The array of fields
Formats the field by replacing underscores with spaces and capitalizing the first letter
(String)
The name of the field
String:
The formatted field string. Example:
my_field_name
will become
My field name
.
Internal and CanJS Object types
By providing the required attribute to a component, this value will evaluate to true. See https://canjs.com/doc/can-define.types.html
Type: Boolean
<element active />
The dropzone library object See http://www.dropzonejs.com/
Type: Object
An observable maplike constructor object See https://canjs.com/doc/can-define/map/map.html
Type: Object
An observable array like list See https://canjs.com/doc/can-define/list/list.html
Type: Object