Twingly Blog Box

Introduction

This page contains the documentation for Twingly Blog Box. There are two types of Blog Boxes, Blog Box Product and Blog Box Site, both of which are documented here.

This chapter describes information common to both types of Blog Boxes. More information about each specific type of Blog Box can be found in their respective chapter.

For information about the pricing of Twingly Blog Box, you can contact us at https://www.twingly.com/contact.

What is a Blog Box?

A Blog Box consists of a piece of HTML code which, when inserted in a website, expands into a more complex entity. All logic takes place on the client side (the web browser), saving server resources. Behind the scenes, a client script and a stylesheet are downloaded to the browser. The client script provides the logic and generates all the necessary HTML code to let the user interact with the Blog Box.

Why use a Blog Box?

A Blog Box is very easy to integrate - just a short HTML snippet needs to be inserted into the existing code. Also, it is very easy to maintain: all changes, bug fixes and updates can be done transparently by the company providing the Blog Box.

Reliability

Blog Boxes are very easy to integrate into any website with almost no work for the customer. Blog data and the Blog Box scripts themselves are hosted on an extremely reliable and distributed server farm provided by Amazon Inc. This ensures full scalability and stability.

Moderation

A blog or blog post that for some reason is deemed as inappropriate can be removed very easily. If a blog is removed, none of its posts will ever show up again. All of the above is done through an easy to use interface, Twingly Administration Center (the documentation for Twingly Administration Center can be found here). User moderation has proven to be a very efficient and powerful tool for detecting and removing inappropriate content. With the moderation button a user can easily specify and submit the nature of a complaint for a specific post. The reports will be displayed in the Abuse report view in Twingly Administration Center.

Basic setup for all Blog Boxes

To run any of the Blog Boxes, you’ll need to include a javascript file. To include this file, copy and paste the following html code into your page:

<script type="text/javascript"
        src="https://eu.widgetdata.twingly.com/scripts/widget/twingly.widget.3.1.0.min.js">
</script>

This code snippet should be included at the end of the html file just before the closing </body> tag.

<html>
  <head>
    <script type="text/javascript">
      //The configuration for the Blog Boxes should be put here
    </script>
    <!--Head section of your html file-->
  </head>
  <body>
    <!--Body section of your html file-->
    <!--Include the Blog Box javascript file at the end of the body-->
    <script type="text/javascript"
          src="https://eu.widgetdata.twingly.com/scripts/widget/twingly.widget.3.1.0.min.js">
    </script>
  </body>
</html>

Also note that there is a section in the head part of the html file that we will use for configuring the Blog Box. Configuring the Blog Boxes is done by assigning values to different java script variables. Different variables apply to different Blog Boxes and they will be explained in detail in the Blog Box specific sections. There are some variable that apply to all Blog Boxes. They are explained below.

Common configuration

Styling the Blog Boxes

It is possible to change the look and feel of the Blog Boxes to make them fit right into the design of the rest of the website. Please note that we require that the logo and link to Twingly remains visible as stated in the user agreement.

The CSS file used by the Blog Boxes is located at https://eu.widgetdata.twingly.com/scripts/widget/css/widget3.0.css

Pick the attributes you want to modify and put them into a file on your local servers. Use the following settings to be sure that your modified styles are used instead of the defaults:

//Note that tw_skipDefaultCss should only be set if you don’t want
//any of the default styles applied. This option should be used with
//care since the default settings are well tested.
var tw_skipDefaultCss = true;

var tw_localCss = "http://your.domain.com/styles/mywidget.css";

And now you are almost done! After you followed the few steps in the product specific documentation below you should see the Blog Box appear at the position in the page where you put the HTML snippet mentioned above.

Blog Box Product

Blog Box Product is used to display information about which blog posts that link to a specific product.

Twingly Blog Box Product

If a limited number of blog posts are listed a “Show all”- link leads to a search result page on Twingly.com where all results are displayed. For each blog post the following information is displayed:

The blog posts are displayed by default according to their date. Alternatively results can be displayed by the Twingly Rank which might give even more relevant results but which are not necessarily the most recent ones.

Integration

To integrate the Blog Box Product into a page, the basic setup explained earlier must be performed.

The following html snippet should be placed in your html page where you would like the Blog Box to appear:

<div id="tw_link_widget">
  <a href="https://www.twingly.com/">Twingly Blogsearch</a>
</div>

The Blog Box will fill up the width it is given, so a common way to control the width is to put the Blog Box inside a <div> that has a specific width:

<div style="width:300px;">
  <div id="tw_link_widget">
    <a href="https://www.twingly.com/">Twingly Blogsearch</a>
  </div>
</div>

Configuration

Below we walk through all of the available options or the Blog Box Product and explain each one of them.

Example

For reference, the HTML for a complete page is included below:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Twingly Blog Box Example</title>
    <script type="text/javascript">
      //Observe that tw_url is used only for testing.
      var tw_url = "https://www.twingly.com/";
    </script>
  </head>
  <body>
    <!-- Put a div with id set to tw_link_widget where you
    want the Blog Box to appear. The Blog Box will fill out
    the space given to it. Here, the outer div will make the
    Blog Box become 300px wide. -->
    <div style="width:300px;">
      <div id="tw_link_widget">
        <a href="https://www.twingly.com/">
          Twingly Blogsearch
        </a>
      </div>
    </div>
    <!-- Include the javascript file needed for the widget
    in the lower part of your BODY tag -->
      <script type="text/javascript"
              src="https://eu.widgetdata.twingly.com/scripts/widget/twingly.widget.3.1.0.min.js">
      </script>
   </body>
</html>

Example Result

Blog Box Site

Blog Box Site displays a list of the newest blog posts that have linked to a site or a part of a site. For the Blog Box to display links that links to a specific part of a site, the URL pattern must be consistent so that the particular subpart of the site is recognizable from the URL alone.

Twingly Blog Box Site flavours

In the blog mode the Blog Box comes in two flavours; it can be centred around the product as in the left picture, or it can be centered around the blog posts as in the right picture.

Integration

The following html snippet should be placed in your html page where you would like the Blog Box to appear:

<div id="tw_latestblogged_widget">
  <a href="https://www.twingly.com/">
    Twingly Blogsearch
  </a>
</div>

The Blog Box will fill up the width it is given in the page. A common way to limit its width is to put the Blog Box into a div that has a specified width:

<div style="width:300px;">
  <div id="tw_latestblogged_widget">
    <a href="https://www.twingly.com/">
      Twingly Blogsearch
    </a>
  </div>
</div>

Configuration

The configuration of Blog Box Site is easy and typically one or two variables need to be set.

Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      <title>Blog Box Site Example</title>
      <script type="text/javascript">
        //Tell the Blog Box for which site the latest blogged list is.
        var tw_latestbloggedUrl = "https://www.twingly.com/";
    </script>
  </head>
  <body>
    <!-- Put a div with id set to tw_latestblogged_widget where
    you want the Blog Box to appear. The Blog Box will fill out
    the space given to it. Here, the outer div will make the
    Blog Box become 300px wide. -->
    <div style="width:300px;">
      <div id="tw_latestblogged_widget">
        <a href="https://www.twingly.com/">
          Twingly Blogsearch
        </a>
      </div>
    </div>
    <!-- Include the javascript file needed for the Blog Box
    in the lower part of your BODY tag -->
    <script type="text/javascript"
            src="https://eu.widgetdata.twingly.com/scripts/widget/twingly.widget.3.1.0.min.js">
    </script>
  </body>
</html>

Example Result

Blog Box Search displays a list of blog posts matching a search. Each item in the list displays the title of the blog post and a short excerpt from the post, with the match highlighted. The number of blog posts shown in the Blog Box can be changed. Contact us for this.

Integration

The following html snippet should be placed in your html page where you would like the Blog Box to appear:

<div id="tw_searchresult_widget">
  <a href="https://www.twingly.com/">
    Twingly Blogsearch
  </a>
</div>

The widget will fill up the width it is given in the page. A common way to limit its width is to put the widget into a div that has a specified width:

<div style="width:300px;">
  <div id="tw_searchresult_widget">
    <a href="https://www.twingly.com/">
      Twingly Blogsearch
    </a>
  </div>
</div>

Configuration

The configuration of Blog Box Search is easy. There is only one configuration option that is specific for this widget.

Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Blog Box Site Example</title>
    <script type="text/javascript">
      // Tell the widget which Blog Box Search result that should
      // be shown.
      var tw_searchresultName = "1010_twingly_demo";
    </script>
  </head>
  <body>
  <!-- Put a div with id set to tw_searchresult_widget where you want the widget to appear. The widget will fill out the space given to it. Here, the outer div will make the widget become 300px wide. -->
    <div style="width:300px;">
      <div id="tw_searchresult_widget">
        <a href="https://www.twingly.com/">
          Twingly Blogsearch
        </a>
      </div>
    </div>
    <!-- Include the javascript file needed for the widget
    in the lower part of your BODY tag -->
    <script type="text/javascript"
            src="https://eu.widgetdata.twingly.com/scripts/widget/twingly.widget.3.1.0.min.js">
    </script>
  </body>
</html>

Example Result

FAQ

Why does the blog box widget return 404?

After implementing the Twingly Blog Box, you may have noticed that it will return a HTTP 404 status code for pages that don’t have blog links to it.

HTTP 404 from Twingly Blog Box

Short anwser:

Nothing is broken. If there are no links to URL, there is no data for the widget to fetch. It’s just the data file that is missing, not the widget script.

Longer answer:

The Blog Box widget is comprised of a Javascript and JSON data. Javascript is included by the site implementing the widget, which will in turn load JSON data to populate the widget.

When Twingly’s system detects a link to a customer site, we compile a JSON data file and uploads it to our data storage. We can only create this file for URLs that have a link from a blog, otherwise we wouldn’t know what the URL would be since we don’t crawl your website.

The HTTP 404 is a response to an asynchronous JavaScript and JSON request and should not be marked as a “broken link” by search engines.

Nothing is broken, we just don’t have data for that particular URL.

By the way, the reason why it’s trying multiple times is to work around potential cache issues.

Known incompabilities

Changelog

Below is a brief description of new features and changes between versions, with most recent version first.