Lightning Aura Components Developer Guide
jNewer Version Available
Providing Component Documentation
- Documentation definition (DocDef): Full documentation on a component, including a description, sample code, and a reference to an example. DocDef supports extensive HTML markup and is useful for describing what a component is and what it does.
- Inline descriptions: Text-only descriptions, typically one or two sentences, set via the description attribute in a tag.
To provide a DocDef, click DOCUMENTATION in the component sidebar of the Developer Console. The following example shows the DocDef for c:myComponent.
1<aura:documentation>
2 <aura:description>
3 <p>An <code>c:myComponent</code> component represents an element that executes an action defined by a controller.</p>
4 <!--More markup here, such as <pre> for code samples-->
5 </aura:description>
6 <aura:example name="myComponentExample" ref="c:myComponentExample" label="Using the c:myComponent Component">
7 <p>This example shows a simple setup of <code>myComponent</code>.</p>
8 </aura:example>
9 <aura:example name="mySecondExample" ref="c:mySecondExample" label="Customizing the c:myComponent Component">
10 <p>This example shows how you can customize <code>myComponent</code>.</p>
11 </aura:example>
12</aura:documentation>A documentation definition contains these tags.
| Tag | Description |
|---|---|
| <aura:documentation> | The top-level definition of the DocDef |
| <aura:description> | Describes the component using extensive HTML markup. To include code samples in the description, use the <pre> tag, which renders as a code block. Code entered in the <pre> tag must be escaped. For example, escape <aura:component> by entering <aura:component>. |
| <aura:example> | References an example that demonstrates how the component is used. Supports
extensive HTML markup, which displays as text preceding the visual output and example
component source. The example is displayed as interactive output. Multiple examples
are supported and should be wrapped in individual <aura:example> tags.
|
Providing an Example Component
Recall that the DocDef includes a reference to an example component. The example component is rendered as an interactive demo in the component reference documentation when it’s wired up using aura:example.
1<aura:example name="myComponentExample" ref="c:myComponentExample" label="Using the c:myComponent Component">The following is an example component that demonstrates how c:myComponent can be used.
1<!--The c:myComponentExample example component-->
2<aura:component>
3 <c:myComponent>
4 <aura:set attribute=”myAttribute”>This sets the attribute on the c:myComponent component.</aura:set>
5 <!--More markup that demonstrates the usage of c:myComponent-->
6 </c:myComponent>
7</aura:component>Supported HTML Tags in Document Definitions
Some HTML tags are unsafe or unnecessary. The framework doesn’t support these tags in document definitions.
The SUPPORTED_HTML_TAGS key in this Aura file lists the supported HTML tags. The SUPPORTED_ATTRS key lists the supported HTML tag attributes.
Providing Inline Descriptions
Inline descriptions provide a brief overview of what an element is about. HTML markup is not supported in inline descriptions. These tags support inline descriptions via the description attribute.
| Tag | Example |
|---|---|
| <aura:component> | <aura:component description="Represents a button element"> |
| <aura:attribute> | <aura:attribute name="label" type="String" description="The text to be displayed inside the button."/> |
| <aura:event> | <aura:event type="COMPONENT" description="Indicates that a keyboard key has been pressed and released"/> |
| <aura:interface> | <aura:interface description="A common interface for date components"/> |
| <aura:registerEvent> | <aura:registerEvent name="keydown" type="ui:keydown" description="Indicates that a key is pressed"/> |
Viewing the Documentation
The documentation you create will be available in the Component Library.