Some of the least documented features of the Lightning Component framework are the documentation features themselves.
When utilised properly, these can bring huge efficiencies in how quickly you can pull together a technical reference guide for your Lightning Components.
The coolest part is that the documentation is a lightning application itself. We can incorporate real life examples of how a component can be implemented, right there in the documentation.
This quick guide will take you through some of these features in more detail, starting with how plug into the auto-generated documentation app (which you already have, but might not know it), through to a simple example of how to use a live example to bring your documentation to life.
The Documentation Segment?
I’m talking about this:
By now you’ll be comfortable with most of the segments above.
I’m going to guess that you’ve built a thing (COMPONENT), you’ve made it “do stuff” (CONTROLLER + HELPER), you’ve made it “look nice” (STYLE). For the real eager beavers out there you may have even used the Renderer, Design and SVG components.
But besides from a rogue click, or a burning interest in documentation, I’d bet a number of you are yet to explore the DOCUMENTATION segment of the lightning bundle yet.
Alas, neither had I. Until now.
What’s it all about?
In a nutshell, the documentation tab enables you to add structured documentation elements at a component level, which is then automatically exposed via a bundled app within your Salesforce Org.
In fact, you could try it now.
Try the following:
https://yourdomain.lightning.force.com/auradocs/reference.app#
.. and you’ll find something like this:
As the Lightning Component framework is an extension of the Aura Framework, along with some pre-built components which Salesforce have already provided, what you will see straight off the bat is:
- A reference guide for all other components on the framework (e.g.: everything which exists under the aura, force, ui, forceChatter and ltng namespaces.
- and… an undocumented reference of all your components, applications, events, interfaces etc…
What’s Aura?
Aura began life as an internal project at Salesforce aimed at building a component-based user interface framework.
This was later open sourced and moved to the Salesforce1 platform (and rebranded under the lightning component framework)
So, to make the most of this you’ll want to plug your own components into the documentation application.
Here’s how…
Viewing a component in the app.
Let’s start with the easy stuff.
I’m going to assume you’ve done the very first Lightning Components Trailhead. If you haven’t go and do it now.
Now that that’s been completed, look into your Aura Documentation App again, you’ll notice an entry under Components > yournamespace > MyContactList.
Here’s what it’ll look like.
A lot of nice stuff has already been created for you.
Across the top tabs you can see a number of things already, such as the client side controller (JavaScript), css styles, dependencies and source code.
However, it’s up to you, the developer, the build this out. In this quick tutorial I’ll demonstrate how to do the following:
- Create a Description for the Component
- Provide inline Descriptions for the Component Attributes
- Provide an interactive Example so other developers can see how your component can be implemented.
1. Creating a Component Description
In the developer console, click the Documentation tab.
This will initialise with the following.
We’ll be approaching this step by step, so delete the <aura:example> tag and replace the description content with something more meaningful.
Remember, you can use embedded HTML to make the documentation more readable.
Here’s what I’ve used.
Which produces a rather snazzy component description on the documentation app.
2. Creating Attribute Descriptions
On the overview page you’ll notice the “contacts” attribute is currently without a description.
Getting into the habit of adding the description tag to your Component markup will enable the documentation to pick this up automatically.
Add a description to your <aura:attribute name=”contacts” type=”Contact[]”/>. Refreshing the documentation app will add the component description.
3. Providing an Interactive Example
The final step is to add an example implementation of your component to the documentation. In doing this, your fellow developers can see how the component is integrated. There may also be various examples of how this can be done and the documentation allows for this also.
3.1 Create an Example Component
The first step is to create an example implementation of your component in a brand new component.
In the developer console: Create a new Lightning Component, called: MyContactList_Doc_Example1.
In the component markup, add any implementation of MyContactList you like. As it’s a really straightforward component, with no attributes, we’ll just use this:
In real life, you may want to cover various scenarios or initialisation attributes to demonstrate the full capabilities of the component.
3.2 Assign the example to your main Component Documentation
Now we have a nice example sitting there, the next step is to add an <aura:example> tag to the documentation markup of our lightning component.
The example tag itself must contain the following:
- Ref: Link to the Example Component you just created
- Name: This is just an API name
- Label: Used for descriptive purposes.
You can then also add any HTML markup between the <aura:example> tags to provide further information if required.
3.3 Viewing the example!
Finally, head over to your documentation and go to the Examples Tab and you’ll find a live example and the component source, along with your description!
In Conclusion…
I sincerely hope you enjoyed this tour through the world of Aura documentation. Remember, documentation is your friend, and it can be a doddle when you leverage these techniques.
Happy documenting.
charles oneill 