How to add the Open In Codepen button to an example page

This page explains how to add an "Open in Codepen" button to an existing example page. If you are creating a new example, you will get this all for free by starting from the example template.

The way the button works:

In all example pages, we import the helper js/examples.js and run the sourceCode.add and sourceCode.make with the appropriate arguments. These functions do the following two things:

1. Pull the html of the example from the example page and prints it prettily under the HTML Source Code header.
2. Fetch the css and js files listed under the Javascript and CSS Source Code header and creates a post request to prefill a CodePen page with the html, css and javascript from the example.

Some example pages have more than one example or specific language, so the information passed to sourceCode.add specifies where in the page to find the example html, the javascript and css file links and where to put the "Open in Codepen" button.

The js/example.js API is documented in the source code.

Steps to add the button to existing examples:

1. To get appropriate styling on the button, wrap the example header in a div with class example-header:

   • If the page has only one example, wrap the h2 header with text "Example" in a div with class example-header
   • If the page has more than one example, wrap the h3 that head the beginning of each separate example widget in a div with class example-header.

2. Add an id to an element that contains a list of links to all the relevant JS and CSS files for each example. This is usually a ul element under the Javascript and CSS Source Code section. If the page has only one example, use id="css_js_files" for consistency.

3. For each example, there should be a script tag with a sourceCode.add function call with two positional arguments. Add a third and fourth positional argument:

   • Third argument: ID of header element under which the "Open in Codepen" button belongs (usually h2 or h3 with the word 'Example').
   • Fourth argument: ID of element you added in step two

How to test your changes locally

In order to test the post request to codepen, you will have to start any local webserver serve the example page. If you have python, you can run pythons simple http server like this:

• In a terminal, run python -m SimpleHTTPServer in the aria-practices directory.
• In your browser, navigate to your example: http://localhost:8000/example/index.html

Make sure that the example works in codepen! You might have to do some slight css editing to make it look good. Make sure whatever changes you make work in both the example page and in codepen.

Does your example not work in CodePen?

The CodePen environment is a little different than the web page environment that contain the CodePen. Sometimes, when you follow the instructions to add the CodePen button, you will see some missing images or the JavaScript might simply not run. Here are some changes you might need to make.

JavaScript should only expect HTML for the example

If your code expects any HTML to exist outside the div that wraps the example (usually a div with id="ex1"), then the JavaScript will error in the CodePen environment. If the code errors, you can see that error in CodePen.

Relative paths from the HTML work, but not from the CSS

When we send the code, CSS, and HTML to CodePen, the directory structure of the example is lost. To keep examples from breaking that use relative paths for images or links in the HTML, we supply a base URL.

However, the base URL does not work for relative paths defined in a url() within the CSS. If you want to use a image URL in CSS, you can use an inline SVG. For example, instead of:

-  content: url("../images/right-arrow-brown.png");

Use:

+  content: url("data:image/svg+xml,%3C%3Fxml version='1.0' encoding='utf-8'%3F%3E%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpolygon points='1 1, 1 11, 8 6' fill=' %23034575' stroke= '%23034575' /%3E%3C/svg%3E%0A");

You can use this website to URL encode SVGs: Url Encoder

Icons from Font Awesome

If you use an Icon from Font Awesome, it will work in CodePen, because we load the Font Awesome stylesheet for all examples we open in CodePen, read about it in Font Awesome's documentation.