Widgets

By Pete LePage

Pete is a Developer Advocate

WebFundamental provides a wide variety of widgets to use in documentation.

Common Links

Maintaining links can be a pain, to simplify this, you can add common links to the _common-links.md file, add it as in include to your markdown document then use the reference link syntax to reference it in your document.

First, define the link, in _common-links.md, using the standard reference link markdown syntax:

[id]: http://example.com/  "Optional Title Here"

Be sure to add links sorted alphabetically by id, check to ensure the link you're adding doesn't already exist yet.

Next, include the _common-links.md file in your document.

<<../_common-links.md>>

Finally, use the reference link in your document:

This is [an example][id] reference-style link.

Includes

The include tag includes another file or template at the location of the tag. If the file contains Django template directives, those directives will be interpolated.

Oh, hello! I'm a child file that's been included in a parent file.

{% include "web/_shared/sample.html" %}

Article translation is out of date

If you update an article that has a localized version, please add the translation-out-of-date widget. The widget has been translated into all languages we support and recommends that developers check the English version as the localized version may be out of date.

The widget looks like:

To include it, use:

{% include "web/_shared/translation-out-of-date.html" %}

Including live JavaScript in pages (framebox)

The framebox tag lets you embed a live demo of JavaScript functionality in a page, running the demo in a domain-sandboxed environment. The contents of the framebox tag are moved to a separate file served from a non-google.com domain, and automatically included in the documentation page using an iframe. Frameboxes can contain HTML, CSS, and JavaScript. Text in frameboxes is automatically submitted for translation with the rest of the document, and served in the same locale as the page.

The code for this example:

{% framebox height="80px" %}
<style>
.borderdemo { border: 1px solid red; }
</style>
<p id="demopara">Click the button to toggle the border.
  <button id="demobutton">Click Me</button>
</p>
<script src="https://www.gstatic.com/external_hosted/jquery2.min.js"></script>
<script>
$(function() {
  $('#demobutton').click(function(event) {
    if ($('#demopara').hasClass('borderdemo')) {
      $('#demopara').removeClass('borderdemo');
    } else {
      $('#demopara').addClass('borderdemo');
    }
  });
});
</script>
{% endframebox %}

Supported parameters for framebox:

• height: Sets the height of the framebox
• class: Adds a class to the framebox’ iframe

Including code from the local project (includecode)

Use includecode with a content_path argument to refer to a path to a file in the content area, typically in a hidden subdirectory. The path is relative to the locale root. If the file is not found in the page's locale, it also checks for the file in the en locale before failing.

<pre class="prettyprint">
{% includecode content_path="web/fundamentals/resources/_code/file.js" %}
</pre>

Includes can be limited by using region_tag="region" and including a [START region] and [END region] within the code file.

By default includecode returns the specified section of the source code, including whitespace, without modification. This may be undesired if the specified region is deeply indented in the source file as it may appear out of line with the rest of the documentation. You can adjust the indentation of the included code with the adjust_indentation="auto" option.

<pre class="prettyprint">
{% includecode content_path="path/file.js" adjust_indentation="auto" %}
</pre>

Reusable related guides includes

WebFundamentals made it easy to include related guides, unfortunately DevSite doesn't have an equivalent. To make life easier and allow for simple reuse, you can use a set of pre-created related guides.

{% include "_shared/related-guides/heading.html" %}
{% include "_shared/related-guides/service-workers.html" %}

Will render as:

Related Guides

Videos

Wrap all YouTube videos in <div class="video-wrapper"> or <div class="video-wrapper-full-width">. class="video-wrapper" automatically floats the video right on larger screens, keeping it at 50% of the column width but forcing the video into vertical layout on smaller screens, with the video at 100% of the column width. As the video's size changes, it automatically maintains a 16:9 ratio. class="video-wrapper-full-width" keeps the video at 100% of the column width at all sizes, and still scales it to automatically maintain a 16:9 ratio.

<div class="video-wrapper">
  <iframe class="devsite-embedded-youtube-video" data-video-id="yQhFmPExcbs"
          data-autohide="1" data-showinfo="0" frameborder="0" allowfullscreen>
  </iframe>
</div>

Add the "was this page helpful?" widget to your docs

Want to find out if readers actually find your docs useful? Add the "was this page helpful?" widget to your docs.

Step 1: Add the widget to your page

1. Open your doc in a code editor.

2. Put the following code at the bottom of your page.

   ## Feedback {: #feedback .hide-from-toc }
   
   
   {% include "web/_shared/helpful.html" %}

The widget reports your data to Google Analytics as an event. The category of the event is Helpful. The label is the page's absolute path. The value is 0 if the user clicks No (the doc was not helpful) or 1 if the user clicks Yes (the doc was helpful).

Step 2: Wait

Once the widget is live on your page, you'll probably need to wait a while before you can derive any meaning from the data. The more responses you get, the more confident you can be that the data actually represents the sentiment of your users.

Step 3: Access the data

1. Request access to the Web Fundamentals site data on Google Analytics.
2. Open Google Analytics.
3. Go to Behavior > Events > Overview.
4. Under Events Category select Helpful. If you can't see Helpful, click view full report and find it there.
5. For Primary Dimension select Label.

The Total Events column represents the total number of times that someone clicked Yes or No. The Avg. Value column represents the average sentiment. For example, if 100 people responded, and the average value is 0.75, that means that 75 out of 100 people clicked Yes (the page is helpful).

Step 4: Interpret and act on the data

• If your page is getting low ratings, take a look at it and think about how you can improve it. Make that change, and then check back after a while to see if your rating improved.
• If your page is getting high ratings and you think you know why, share this knowledge with the rest of the team. We can conduct experiments to see if this change reproducibly improves page ratings.

Feedback