Technical Blog


Posted on

WidgetData is the new settings system that makes FreshTags-Singpolyma2 tick. It is a standard way of storing data for JavaScript widgets, so that they can share data and be less likely to have namespace conflicts with each other. It is by no means set in stone, however this post will be a brief description of the system, and how it is used in FreshTags.

The basic WidgetData system is a JSON object stored in var WidgetData in the global JavaScript scope of a page with the following basic structure:

//widget data

Where Widget-System is the name of the system that should render this widget (ie, ‘freshtags’) and XHTML-block-ID is the DOM ID of an XHTML block the widget will be rendered into (ie, ‘freshtags_tags’).

As Used in FreshTags
In the FreshTags WidgetData setup, there are certain standard fields on each block (all the fields here discussed are assumed to be on the JSON object at WidgetData[‘freshtags’][‘XHTML-block-id’]).

  • type – Tells FreshTags what kind of widget this is. Currently three types are supported: tags (a tag list), posts (a list of posts, either associated with a particular tag list or not), and external (a reserved type that simply tells FreshTags not to render this widget automatically).
  • tag_list – posts/external widgets only, tells FreshTags that this widget is linked to the tags widget whose id is tag_list.
  • source – Tells FreshTags what service to pull the data from. On tags widgets the only currently legal value (and the default value) is ‘’. On posts (and external which are to act like posts) widgets this may be ‘’ (default), ‘wordpress’ (pull data from a FreshTags for WordPress enabled blog), or ‘feed’. Posts/external widgets which are linked to a tags widget will default to the same source as the tags widget.
  • username – the username to give the service when extracting data (currently only valid on source). Posts/external widgets which are linked to a tags widget will default to the same username as the tags widget.
  • anchor – The anchor tag to use when drawing in posts.
  • format – The format to render widget in (such as ‘drop’ or ‘drop-add’, may also be an @-separated cust_html string, an array of the type produced by the FreshTags switch, or a function that takes the widget ID and renders it to a string which it returns).
  • rows – Maximum number of posts/tags to display.
  • feedurl – The URL to the feed for post data (to use if there is no other post data, or if source==feed)
  • url – posts/external widgets with source==wordpress only. The URL to the WordPress blog’s main page.
  • prompt – Default entry in a drop-down list. Default ‘- Tags -‘ for tags, default blank for all else.
  • tag_url – tags widgets only, the URL to send browser to on tag selection. Blank for current page. ?tags=TAGS tacked on automatically, %tags% also replaced with tags
  • join_char – tags widgets only, the character to use between the tags in an intersection when replacing into %tags% for tag_url.
  • defs – default tags if no tags detected.
  • no_autocapture – default false, set to true to stop the attempt to autocapture rel=tag data on failure to detect tag from URL/refer URL.
  • curr_tags – the tags currently detected/selected by this widget.
  • all_tag_data – where the list of all tags in an account is stored in the JSON format {‘TAG’:’COUNT’}
  • tag_data – where the list of all tags in an account matching curr_tags is stored in the JSON format {‘TAG’:’COUNT’}
  • posts_data – posts/external widgets only, stores the JSON data for all posts in the widget.

Leave a Response