Tagul » Docs - Gorgeous tag clouds

Docs

Sorry, the documentaion is incomplete.

How it works
Create
Core Options
Black list
Style options
Finalize
Embedding in a Web Page

How it works^

There are several simple steps to get your cloud working.

Sign up to the service
Create a cloud and choose its core options, including:
– data source (rss feed, html web page, etc.)
– tags url pattern (e.g. http://google.com/search?q=$tag)
– cloud shape
– fonts to render tags
– tags’ rotation angles
Click “Build it” button and wait until the cloud is done
Customize its appearance by choosing:
– tags and background colours
– rollover colors and effects
Save it, choose rebuild interval and embed the cloud into your web page using html code provided

That’s it! Your cloud is ready. Since then Tagul will automatically rebuild (refresh) your cloud based on the chosen rebuild interval.

Create^

Create your cloud using “My clouds” pane on the right. Every user can have up to 10 active clouds, you can track the remaining amount on the “create” link.

Core Options^

The first thing you should do in order to get your cloud working is to fill the “Core Options”. Choose your cloud name (from 1 to 50 characters) and proceed with providing the source URL.

Source URL^

Specify an URL that will be the source of your tag cloud. It can be any html or rss link started with “http://” (e.g. http://news.google.com). You can also use API mode by providing a specific XML file as the source, read more about it in the “API mode” section. If you are not going to use API mode leave the corresponding checkbox empty.

Links pattern^

Links pattern is an URL that contains “$tag” pseudo text that will be replaced with the concrete tag’s text in your cloud. E.g. default “http://www.google.com/search?&q=$tag” will be transformed to “http://www.google.com/search?&q=myTag” for a tag called “myTag”. For example if you have a wordpress blog with URL “http://www.example.com” you can use “http://www.example.com/search/$tag” pattern in order to perform a search on this tag. If you need more links customization please consider using API mode.

Tags case^

Choose the case of your tags. All the tags text will be converted according to the chosen case.

Stemming algorithm^

In short Stemming is a way of grouping words based on their root, e.g. words “cat” and “cats” should be stemmed to single “cat”. You can read more about Stemming here. If you wish you tags to be stemmed you can choose the appropriate language to be used while stemming.

API mode^

In the API mode you provide specific XML file as your cloud’s source. In order to use the API mode please enable the corresponding checkbox. Here is an example of API xml:

<tags>
    <tag angle="0"
         color="3488BF"
         font="Linux Libertine Regular"
         url="http://tagul.com"
         weight="130">Tagul</tag>
    <tag url="http://google.com/search?q=money" weight="18">money</tag>
    <tag url="http://google.com/search?q=tag" weight="12">tag</tag>
    <tag url="http://google.com/search?q=cloud" weight="7">cloud</tag>
    <tag url="http://google.com/search?q=html" weight="23">html</tag>
    <tag url="http://google.com/search?q=web" weight="21">web</tag>
</tags>

This is an excerpt from tagul.xml that is used as the front page cloud source.
The following attributes can be used for each tag:

Name	Type
weight	positive integer
url	url
font	from the list*
angle	float (min:-360, max: 360)
color	hex

The API xml is checked against tagul xsd schema, so it contains the complete specifications and can be used for the reference.

Shape^

Fonts^

Rotation angles^

Black list^

Style options^

Finalize^

Embedding in a Web Page^

Here are several ways of embedding your cloud in a web page. All of them has their pros and cons, but we recommend the third (swfobject) approach as it provides the best user experience (mostly because of “click to activate” problem being solved). If you faced with troubles while implementing the third solution it is OK to stick with the first one.

The quick and dirty way^

This method is implemented on the “Finalize” tab of your cloud options. So you can grab the code from there and don’t be bothered by copy-pasting and changing the code below.

Pros:^

- Simple to embed
- Best browser compatibility, including some mobile devices.
(- Youtube utilizes this approach, so it is robust and mature.)
- No javascript used

Cons:^

- “Click to activate” mechanism in IE and Opera 9/10
- not valid XHTML
- no alternative content displayed if flash player plugin is not installed

How to embed^

In order to embed your cloud just copy the text into any DIV element on your web page

Don’t forget to replace [your cloud id], [width], [height] with your cloud credentials

<object
    width="[width]"
    height="[height]"
    type="application/x-shockwave-flash"
    data="http://cdn.tagul.com/cloud.swf">
       <param name="movie" value="http://cdn.tagul.com/cloud.swf"></param>
       <param name="flashvars" value="id=[your cloud id]"></param>
       <param name="allowscriptaccess" value="always"></param>
       <param name="swfversion" value="10"/>
       <param name="expressinstall" value="http://cdn.tagul.com/expressInstall.swf"/>
       <embed
           src="http://cdn.tagul.com/cloud.swf"
           type="application/x-shockwave-flash"
           allowscriptaccess="always"
           width="[width]"
           height="[height]"
           flashvars="id=[your cloudid]">
       </embed>
</object>

The quick and dirty way 2 – valid XHTML^

If the above way suites your needs except for xHTML suport, you can just remove “embed” tag in order to get valid xHTML code.

<object
    width="[width]"
    height="[height]"
    type="application/x-shockwave-flash"
    data="http://cdn.tagul.com/cloud.swf">
       <param name="movie" value="http://cdn.tagul.com/cloud.swf"></param>
       <param name="flashvars" value="id=[your cloud id]"></param>
       <param name="allowscriptaccess" value="always"></param>
       <param name="swfversion" value="10"/>
       <param name="expressinstall" value="http://cdn.tagul.com/expressInstall.swf"/>
</object>

The only drawback you get (compared to the above solution) is less browser compatibility (moslty ancient browsers are dropped)

SWfObject method^

The more advanced way of embeding flash is using SWFObject javascript library.

Pros:^

- no “click to activate” problems, so best end user experience
- valild XHTML
- alternative content if no flash player plugin installed
- express install if old (<10) flash player installed
- wide browser support

Cons:^

- Won’t work if javascript disabled. (Who disables javascript and leaves flash enabled? )
- At first it seems hard to implement

How to embed^

We are going to use dynamic embedding method described here

Don’t use swfobject 2.2 version. It has known glitches with incorrect displaying in Firefox 3. Use 2.1 version instead of.

Don’t forget to replace [your cloud id], [width], [height] with your cloud credentials

a) Your HTML mark up must be valid XHTML. If your mark up is not valid XHTML the solution can either work or not, but anyway it is worth trying.
b) Add to your head section the following code

<head>
    ...
    <script type="text/javascript"
      src="http://ajax.googleapis.com/ajax/libs/swfobject/2.1/swfobject.js">
    </script>

    <script type="text/javascript">
        swfobject.embedSWF("http://cdn.tagul.com/cloud.swf", "myCloud",
          "[width]", "[height]", "10.0.0", "http://cdn.tagul.com/expressInstall.swf",
          {id: "[your cloud id]"}, {allowscriptaccess: "always"});
    </script>
    ...
</head>

c) Add to your body section the following code

<body>
    ...
    <!--A div your cloud will be placed into-->
    <div id="myCloud">
        <p><a href="http://www.adobe.com/go/getflashplayer">
            <img
              src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif"
              alt="Get Adobe Flash player"/>
       </a></p>
    </div>
    ...
</body>

That’s it! Here is the complete example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <title>My cloud</title>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />

        <script type="text/javascript"
          src="http://ajax.googleapis.com/ajax/libs/swfobject/2.1/swfobject.js">
        </script>

        <script type="text/javascript">
            swfobject.embedSWF("http://cdn.tagul.com/cloud.swf", "myCloud",
              "400px", "400px", "10.0.0", "http://cdn.tagul.com/expressInstall.swf",
              {id: "test@test"}, {allowscriptaccess: "always"});
        </script>

    </head>
    <body>
        <div id="myCloud">
            <p><a href="http://www.adobe.com/go/getflashplayer">
                <img
                  src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif"
                  alt="Get Adobe Flash player" />
            </a></p>
        </div>
    </body>
</html>

Docs

How it works^

Create^

Core Options^

Source URL^

Links pattern^

Tags case^

Stemming algorithm^

API mode^

Shape^

Fonts^

Rotation angles^

Black list^

Style options^

Finalize^

Embedding in a Web Page^

The quick and dirty way^

Pros:^

Cons:^

How to embed^

The quick and dirty way 2 – valid XHTML^

SWfObject method^

Pros:^

Cons:^

How to embed^

Latest news