Repository files navigation

A suite of pre-built Dojo widgets, ready to use in your web application.These widgets are built using Dojo's widget authoring system(@dojo/framework/core).

• Usage
• Features
• Conventions
  • Icons
  • Coding conventions
• How Do I Contribute?
  • Installation
  • Testing
• Licensing Information

To use@dojo/widgets in your project, you will need to install the package:

npm install @dojo/widgets

This package containsall of the widgets in this repo.

All of the widgets are on the same release schedule, that is to say, that we release all widgets at the same time.Minor releases may include new widgets and/or features, whereas patch releases may contain fixes to more than 1 widget.

To use a widget in your application, you will need to import each widget individually:

importButtonfrom'@dojo/widgets/button';

Each widget module has a default export of the widget itself, as well as named exports for things such as properties specific to the widget:

importButton,{ButtonProperties}from'@dojo/widgets/button';

Because each widget is a separate module, when you create a release build of your application, you will only include the widgets that you have explicitly imported.This allows ourdojo cli build tooling to make sure that the production build of your application only includes the widgets you use and is as small as possible.

• All widgets are supported in all evergreen browsers (Chrome, Edge, Firefox, IE11+, and Safari) as well as popular mobile browsers (Mobile Safari, Chrome on Android).

• All widgets are designed to be accessible. If custom ARIA semantics are required, widgets have anaria property that may be passed an object with customaria-* attributes.

• All widgets are fully themeable. Example themes are available in the@dojo/themes repository.

• All widgets support internationalization (i18n)

Live examples of current widgets are available in thewidget showcase.

Button

Calendar

Checkbox

CheckboxGroup

ComboBox

DateInput

EmailInput

FloatingActionButton

Form

Label

List

Listbox

NativeSelect

NumberInput

OutlinedButton

PasswordInput

Progress

Radio

RadioGroup

RaisedButton

RangeSlider

Select

Slider

Switch

TextArea

TextInput

TimePicker

Typeahead

Accordion

Card

Header

HeaderCard

SlidePane

SplitPane

TabContainer

ThreeColumnLayout

TitlePane

TwoColumnLayout

Avatar

BreadcrumbGroup

Chip

ChipTypeahead

ConstrainedInput

ContextMenu

ContextPopup

Grid

Dialog

GlobalEvent

Icon

LoadingIndicator

Pagination

Progress

Result

Snackbar

SpeedDial

TriggerPopup

Toolbar

Tooltip

You can register event handlers that get called when the corresponding events occur by passing the handlers into a widget'sproperties.The naming convention for event handlers is as follows:

• if the parent of the widget has the power to decideif an event is successful, i.e. can cancel the event, then the child widget will call an event handler in the following format:

onRequest[X], e.g. for aclose event, the event handler called by the child widget must be calledonRequestClose

Here the child widget is requesting that theclose event take place.

• for events that will occur regardless of child/parent interaction, then theRequest naming convention is dropped:

on[X], e.g. for adismiss event, the event handler called by the child widget must be calledonDismiss

We usefont awesome for icons.Where a theme requires specific icons that are not part of the Font Awesome set, then those themes will ship their own icons.

Icon fonts are generated usingIcoMoon. If a new icon is required, it is possible to upload the currentdojoSelect.json fromsrc/theme/fonts and then add new icons by selecting from the Font Awesome library. After selecting the new icons from the library, merge them down into the current icon set, then delete the rest of the Font Awesome icons that were added by IcoMoon. After this you can export and download them as a zip. Once downloaded you will also need to unzip them and replace the font files (svg, woff, ttf) insrc/theme/fonts. Now download the new selection JSON file from theprojects page of IcoMoon and replace the currentdojoSelection.json file.

To make use of the new icons it is necessary to update theicon.m.css file in the theme folder with the new unicode icon like so:

.newIcon:before {content: "\f123";}

Where\f123 is the unicode character for the new icon. To check the new icon works you can render it in thesrc/widgets/examples/icon/Basic.tsx to make sure everything renders correctly.

There is anicon widget that aids in creating in proper semantics and provides type-checking for the type of icon.

px vs. em - we specify font sizes inpx.When creating a widget, spacing (margin, padding) should be specified usingpx unless the design calls for proportional spacing, in which caseem can be used.

Widgets adhere to a basic convention for using specific ranges of z-index values based on function and visual context. This convention is followed in both individual widget CSS and in the Dojo theme styles. These values can be overridden in a custom theme if necessary since noz-index values are set in fixed styles.

The range definitions are as follows:

• 0 - 100: Any specific component layering, e.g. a caption over an image.
• 100 - 200: Fixed position elements. Fixed headers and footers are clear examples of fixed page elements, but it could also include a drag-and-drop element in a drag state.
• 200 - 300: Partial-page overlays such as Slide panes.
• 300 - 400: Full-page overlays such as Dialogs.
• 400 - 500: Body level popups, tooltips and alerts.

There are many ways in which you can customize the behavior and appearance of Dojo widgets.See thecore README for examples of how to customize the theme or a specific CSS class of a widget.

Or can you write your own widget that extends an official widget.

Because all Dojo widgets are Classes, you can simply extend the Class to add or change its behavior.

exportclassMyWidgetextendsButton{...}

Dojo widgets provide standard extension points to allow you to customize their behavior. For more details, please refer to thewidget authoring system.

Individual widgets also provide certain types of extension points where applicable:

• render*: Large render functions are split up into multiple smaller pieces that can be more easily overridden to create custom vdom.
• getModifierClasses: Modify the array of conditionally applied classes likecss.selected orcss.disabled.Not all widgets include these extension points, and some have additional overridable methods.

When writing a widget variant, ie.RaisedButton, you should ensure that you usetheme.compose from the widgettheme middleware. This allows your variant to interit css from it's base widget whilst allowing it to be themed separately.

We appreciate your interest! Please see theDojo Meta Repository for theContributing Guidelines and Style Guide.

Note that all changes to widgets should work with thedojo theme. To test this start the example page (instructions atInstallation section) and select the dojo option at the top of the page.

To start working with this package, clone the repository and runnpm install.

In order to build the project runnpm run build.

Test cases MUST be written usingIntern using the Object test interface and Assert assertion interface.

90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.

To test locally in node run:

npm run test

The Dojo widget examples application is located insrc/examples.

To add a new example, create a directory that matches the directory name of the widget e.g.src/examples/src/widgets/text-input. Each widgetmust have an example calledBasic.tsx and an entry in thesrc/examples/src/config.ts keyed by the name of the widget directory. The widget example should import widgets from@dojo/widgets and not via a relative import. It is very important that the config entry name (ie.text-input) matches the folder name / css file name of the widget otherwise the doc build will fail.

{    'text-input: {filename:'index',overview:{example:{module:BasicCheckbox,filename:'Basic'}},examples:[{title:'The example title',description:'Optional example description',module:OtherCheckbox,filename:'Other'}]}}

• filename: The name of the widget module, defaults toindex
• overview: The configuration for the basic example including the imported Basic module and the example filename (has to be'Basic')
• examples: Additional examples for the widget, an array of configuration that specifies the title, description, module and example filename.

To view the examples locally runnpm run dev in the root directory and navigate tohttp://localhost:9999, this starts the examples in watch mode and should update widget module are changed. Note that you do not have to install dependencies in thesrc/examples project, this will result in an error.

The widget examples and documentation is automatically generated by theexamples application when built with thedocs feature flag set totrue. The site relies on a few conventions in order to be able do this:

1. A widgets properties interface must be the name of the widget with a suffix ofProperties, e.g. fortext-input the properties interface would beTextInputProperties
2. The widget properties must be exported to ensure they are visible in the generated widget documentation.
3. All themeable styles must be added to the corresponding theme css module insrc/theme and match the name of the widget directory e.g.text-input.m.css
4. For properties description docs must be included inline above each property, e.g.
5. All widgets must have aREADME.md file in their root directory.

interfaceExampleProperties{/** This is the description for foo */foo:string;/** This is the description for bar */bar:string;}

To build the documentation runnpm run build:docs and to build and serve the documentation in watch mode runnpm run build:docs:dev

The examples also run on Codesanbox, to run the examples on the master branch go tohttps://codesandbox.io/s/github/dojo/widgets/tree/master/src/examples. To run the examples for a specific user/branch/tag adjust the url as required.

© 2018JS Foundation.New BSD license.