1.5 Embedding stori.es Content on a Website

Embedding stori.es Content on a Website

You can embed questionnaires and collections directly on a website, at the end of a blog post, or on a web page!

We've developed a small JavaScript code package that can be deployed using any content management system to present stori.es content within your organization's domains. You simply need to install the code package and reference it from the target page. The requested content will load and display.

To embed a stori.es questionnaire or collection directly on a website, follow these two steps:

1. Reference the stories JavaScript library
2. Embed a questionnaire or a collection

Also read our suggested best practices and troubleshooting tips for optimal results.

• Best Practices
• Troubleshooting

1. Reference the stori.es JavaScript library

Add a reference to the stori.es JavaScript library on the pages or posts where you want to display a stori.es questionnaire or collection. Note that this reference must appear after the embedded questionnaire or collection itself. We explain how to embed the questionnaire or collection in the next step.

You can use either http or https protocol. Tip: The only difference between the two code snippets below is the use of the https protocol.

http Protocol

To use the http protocol, include this code:

<script>
var storiesConfig = { corsDomain: "z.stori.es", corsPort: "" };
</script>
<script type="text/javascript" src="http://z.stori.es/surveymvp/surveymvp.nocache.js"></script>

https Protocol

If you’re hosting content securely, pull the stori.es JavaScript library from our secure server. To do so, include this code:

<script>
var storiesConfig = { corsDomain: "z.stori.es", corsPort: "" };
</script>
<script type="text/javascript" src="https://z.stori.es/surveymvp/surveymvp.nocache.js"></script>

2. Embed a Questionnaire or a Collection

You’re now ready to embed stori.es content. This simply requires you edit the HTML of the page or post where you want the questionnaire or collection to appear.

When the JavaScript file you included (in step 1 above) is downloaded and executes, it scans the current web page for an HTML element you designate and renders the questionnaire or collection there.

In this step, you just need to designate an existing HTML element as the target location or add a new HTML element for this purpose.

---

If you haven’t created and published your questionnaire or collection, you must do so in order to complete this step. This is because you'll need to include the URL for the published questionnaire or collection you are embedding.

Here's an example published questionnaire URL.: https://stori.es/share/contact-regarding-stories-platform

(Click the link to see an example questionnaire. It's the the general contact form for the stori.es website.)

---

First, make a note of the unique portion of your questionnaire or collection's URL. In the above example, the questionnaire’s unique URL fragment is:

contact-regarding-stories-platform

Tip: Remember the leading slash (/) is not part of the unique portion of the URL.

Next, designate the target HTML element:

1. Set the target HTML element’s ID attribute to “survey”

2. For questionnaires, prefix your questionnaire’s unique URL fragment with stories-questionnaire- and add that value as a class on the target HTML element

For collections, prefix your collection's unique URL fragment with stories-collection- and add that value as a class on the target HTML element

For example, here’s how the target HTML element looks on the WordPress page where we embedded the stori.es general contact form:

<div id="survey" class="stories-questionnaire-contact-regarding-stories-platform"></div>

Once you have designated the location in the page where you want the questionnaire or collection to render and referenced the stori.es JavaScript library, stori.es will take care of the rest. You should be able to save and preview your page, and stori.es will render the content for you!

Best Practices

You can reference the stori.es JavaScript library in any number of ways. Some are easier to manage while others optimize site performance.

1. The easiest route is to simply add the JavaScript reference to the footer of your website. However, if you use this approach your website's performance will be affected, because the JavaScript file will be downloaded and executed for every request to every page of your site (though it will be cached after the first download). Referencing the library in this way makes it easy to embed content anywhere on your site, but results in a performance cost.

2. You can reference the target JavaScript file on a per-page or per-post basis. Tip: Although it’s generally recommended that you include JavaScript references in the footer or header of an HTML page, you can really inject them anywhere in the page. Sometimes this may be the best approach.

3. We recommend selectively including the JavaScript reference in the footer of those pages or posts where you are most likely to embed a questionnaire or collection. For example, in WordPress you can create a custom page template which includes the JavaScript in the footer. This requires a little custom coding, but provides a nice balance between usability and performance.

Troubleshooting

Since this is a manual process, it can be tough to debug. Here’s some things to watch out for.

• Make sure you get the right questionnaire or collection URL fragment. Don’t include a leading slash (/).
• Use the appropriate prefix: “stories-questionnaire-” for questionnaires; “stories-collection-” for collections.
• You’re currently limited to embedding one questionnaire or collection per HTML page. We’re going to lift that restriction later.

Still not working? Contact us! That’s why we’re here.