Modules and components are the fundamental building blocks of an MWF web page. So, it is important to understand what these controls are and how they are used.
Always start building your page with modules. You can think of modules as cross sections of a page stacked one on top of another composed from components and other elements. Many modules are designed to cover the full width of the page or the grid, although some are not. When using modules, their position, including all margins and padding, are programmatically determined based on their relationships to one another. Each module may also include a grid when appropriate.
Modules are designed around more complex task-oriented use cases involving multiple components, and unique user interactions.
One area where modules do have built-in behaviors is their reactivity. All modules are reactive. That is a basic requirement so that this behavioral UX is consistent across all MS websites. You do not have to implement it; you can just use it.
Components differ from modules by being limited in functional scope. Components are the most granular objects of MWF. They can be a simple as a wrapper around an HTML element to control its look-and-feel or as complex as multiple elements working in coordination to provide a tightly focused functionality.
Most of what has been mentioned about using modules applies to components. Except, of course, those components are the primary building blocks of modules. Details on how to use each component can be found in its datasheet on getmwf.com. Just look up the component by name and you will discover everything there is to know about using it.
Using components and modules
There are several patterns of usage that are common to all components and modules. These are the most important.
Children of the grid
In a very real sense, every component and module is the child of a grid container. Its positioning on the page and relative to other neighboring elements, components and modules is relative to its siblings in the grid container. Likewise, the children of a specific grid container are relatively located to neighboring grid containers. It is always a mistake to try and force the positioning of an page element outside of its parent grid container. The results will never be quite what you expect. And it goes against MWF principles.
All MWF components and modules have specific properties that must be applied. Components have an associated class whose name uses a "
c-" prefix. Modules have an associated class whose name uses an "
m-" prefix. They both may have functional options available using additional classes whose name uses an "
f-" prefix. You will also encounter several attributes, some common and some unique to each control. The individual component or module will describe each of these attributes and how to use them. In many cases, there are attribute values that are used to link functionality. For example, a button element might have an attribute data-f-describedby. It is assigned the same id value of an associated span element containing tooltip text for the button. This allows the button to display the proper tooltip text when the user hovers oveer the button. This is illustrated in the following example code taken from the Action toggle component's (where you can find a working example of this code).
<button class="c-action-toggle c-glyph glyph-play f-toggle" data-toggled-label="Pause" data-toggled-glyph="glyph-pause" aria-label="Play" data-f-describedby="glyphOnlyPause"></button> <span id="glyphOnlyPause" class="c-tooltip" role="tooltip" aria-hidden="true">Pause</span>
There is another common pattern to notice in the above example. This component uses a button element that can display a text label and / or a glyph. In this case, the button only shows a glyph. Adding the "
c-glyph" class to the button alerts the MWF framework to look for a glyph identifier for the glyph to use as a label. Here, it is specified by the "
glyph-play" class. And in the case of this component (that has two toggled states) the framework knows to actually use two glyphs to display, one for each state (play and pause). In fact, there are two attributes (
data-toggled-glyph) included for this purpose. This pattern is common in many MWF controls.
You might have noticed the
aria-label attribute assigned a value of "Play." If you don't recognize it, this attribute is present for usability purposes. Its value is detected by a screen reader for visually impaired users and "spoken" out loud, so the user knows the purpose and use of that control. Screen readers can pick up much information from components, but those features that depend on visual recognition must be identified by "aria-" attributes when semantic HTML is not enough. To learn more about Accessibility.
Some modules and components require more than the MWF libraries to function correctly. Additional libraries are required to add functionality or to guarantee consistent functionality across all browsers. You can learn more about this on the Exploring CDN page and the Scripting page.