Overview

Any table on Factual can be incorporated into a site through the Factual Visualizations, which can be completely customized to the design of your site.  These can be found on the Visualization tab on each table. 

 

If you would like to get access to our JSAPI to submit your own Visualization, please let us know through the Factual Developer Group.  We're excited for some talent out there to build cool visualizations that we have not thought of.

 

Basics

Factual visualizations use standard HTML with some additional attributes to inject Factual data into your webpage when they are rendered.   Primarily the markup goes into the Factual attribute in one of the following manners: markers and widgets.

 

Widgets 

Widgets enable behaviors to be injected into HTML controls, that enable manipulation of the data as you see it.  For example, the following enables a text input to filter the data in a list:

     <form>
<input factual="widget:filter; operator:is; on:$fieldIdx12" name="season" type="radio" value="Y"/>Spring 
<input factual="widget:filter; operator:is; on:$fieldIdx13" name="season" type="radio" value="Y"/>Summer 
<input factual="widget:filter; operator:is; on:$fieldIdx14" name="season" type="radio" value="Y"/>Fall 
</form>

 

Markers

Markers describe how content will be mapped to a block of HTML.  For example, the following would enable a list of data to be injected into an HTML list:

 

     <ul factual="marker:list">
.
.
.
</ul>

Rows

The content portion of your code will require iterating through rows of data from your table.  In order to do so, you use the row marker, nested within your content marker.  Multiple row markers can be used, in order to create formatting such as having every other or every third row of data use a different background.  Simply declare successive blocks of HTML using the row marker within the same content in the order you want them to loop.  For example, if you wanted every other row to be gray, you might mark your template like this:

 

     <ul factual="marker:list">
          <li class="oddRows" factual="marker:row">...</li>
          <li class="evenRows" factual="marker:row">...</li>
     </ul>

 

 

Data

In order to place data from Factual tables in your HTML, you must first make sure you've declared content and row markers.  Within HTML blocks that you have marked as Factual rows, you use the following syntax to let Factual know where to insert a value for any field in a row of data:

 

     $fieldIdx1 (put the current consensus value of the 2nd field in your table from the left into the html here.  The index is 0 based.)

     $fieldId1 (put the current consensus value of the field with field ID # 1 into your html here.)

 

Note: If you want to make it easy to port a visualization from one table to another table, the field index is the easier path to use.  However, it can be brittle if the table has a publicly editable schema that might result in the order of the fields changing.  In those cases, the field Ids are clearly more robust.

 

These inline values can be inserted anywhere in your tags with the exception of the Factual attribute.  So, for example, the following are valid:

 

     <span class="data">Name: $fieldIdx1</span> (for example, if the consensus value of fieldIdx1 was "John Smith" for row 1, show "Name: John Smith" in a span.

     <img src="$fieldIdx2"/> (use the value of the third field from the left in your table as the URI for an image, as appropriate per row)

     <input type="button" id="$fieldId4256"/> (set the id of this input as the value from field 4256

 

Null Handling 

When Factual doesn't have a consensus value for a field, you may want to branch the behavior.  In particular, this can be helpful in making presentations that don't contain blank spaces with no clickable area to enable adding the data, as well as making sure you don't end up with things like broken image icons or dead links when using Factual fields for HREF or SRC attributes.  The following sample shows the value when present, and a solicitation to populate the value otherwise:

 

     <span class="value" factual="if:$fieldIdx5 notNull; explorer:fact $fieldIdx5">$fieldIdx5</span> 
<a class="value" factual="if:$fieldIdx5 isNull; explorer:fact $fieldIdx5">know this?</a>

The <a..> block will be rendered in the case that the value in the 6th field from the left is null.  The span will be rendered otherwise.

 

Explorers

In the sample above, it is worth noting the explorer property.  The explorer property stipulates that clicking on the block will open either a subject or fact explorer. 

 

Factual Properties

The following is a complete list of current Factual properties.

 

 

• marker:list | content
• contains:
• marker:row  
• marker:item
• marker:map
• properties:
• zoom: <int>
• lat: <fieldDef>
• lng: <fieldDef>
• center: <lat float> <lng float>
• widget:filter  ( this needs to be added for "center" to work, otherwise it will autocenter to provided locations )
  example:
  <div factual = "marker:map;center:34.017 -118.262; zoom:9; type:roadmap; lat:$fieldId1; lng:$fieldId2; widget:filter"></div>
  
• marker:gchart
• properties:
• data: <fieldDef>  ( used only for pie and bar charts )
• label <fieldDef>  ( used only for pie and bar charts )
• 3D: <boolean>  ( used only for pie and bar charts )
• type: <chart type>  ( possible chart types include: bar, pie, table and custom )
• fields: <fieldDef> ( used only for table and custom charts )
• gpackage: <google package> ( used only for custom charts.  refer to http://code.google.com/apis/visualization/documentation/gallery.html to check out options )
  
• gclass: <google class> ( used only for custom charts.  refer to http://code.google.com/apis/visualization/documentation/gallery.html to check out options )
  example:
  <img factual = "marker:gchart; type:bar; 3D:true; data:$fieldIdx1; label:$fieldIdx0">
• marker:row  ( must be a child of marker:content or marker:list )
• contains
• marker:field
• attributes: ( same as marker:field )
• properties: ( same as marker:field )
• subjectKey:<constant> | $get[<key>] ( used to display only one row of data, same as filtering on:subjectKey )
  
• marker:field  ( must be a child of marker:item or marker:row )
• attributes: 
• onEachRow = "<javascript>"  ( executed while the item is being displayed ) 
• beforeEachRow = "<javascript>" ( executed before the item is displayed )
• href = <fieldDef>
  
• src = <fieldDef>
  
• customstyle = "<css property> <constant attribute value> <fieldDef> <constant attribute value>  ( <constant attribute value> not necessary )
  example:
  <div factual = "marker:field;" customstyle = "border: 1px solid $fieldIdx"></div>
  <div factual = "marker:field;" customstyle = "background-color: $fieldIdx0px"></div>
• properties:
• fieldIdx: <int>  ( uses column order as index starting at 0 )
• fieldId: <int>  ( uses column ID )
  example:
  <span factual = "marker:field; fieldId:1></span>
• if: <fieldDef> <isNull | notNull>
  example:
  <a href = "$fieldIdx21" factual = "marker:fields; if: $fieldIdx21 notNull"> Here's the field </a>
  <a href = "/default" factual = "marker:fields; if: $fieldIdx21 isNull"> No data </a>
• explorer:subject
• explorer:fact <fieldDef>
• marker:fields ( must be a child of marker:list or marker:row ) | any element ( must be a child of marker:row )
  
• attributes: ( same as marker:field )
• properties: ( same as marker:field )
• value:
• <fieldDef>
• variables:
• strength
• user_vote
• unique_votes
• user_action 
  example:
  <span></span> $fieldIdx0.strength
• marker:preload | class = "factual-preload" ( visible only before data is loaded )
• marker:onload | class = "factual-onload" ( visible only after data is loaded ) 
• widget:rowForm  ( used for add row and edit row )
• contains:
• widget:input
• properties: ( properties included become text fields which, once submitted become fact inputs of the new row ) 
• for:<fieldDef> | $source | $comments ( $source and $comments used together with "noMetadata" to allow source and comment to be inputed from text fields )
• widget:rowFormSubmitter ( Add "disabled" class to disable it )
• properties:
• noMetadata:<boolean> ( used to turn off comment/source soliciting dialog )
  example:
  <form factual = "widget:rowForm" >
    <input factual = "widget:input; for:fieldIdx:0">
    <input factual = "widget:rowFormSubmitter" type = "button" value = "add"></form>
• properties:
• subjectKey:<constant> | $get[<key>] ( if added, becomes edit row ) 
  
• widget:filter
• properties
• operator:<operator>  ( possible <operator> values: contains, is, isnot, starts, ends )
• on:<fieldDef> | subjectKey 
  example:
  <input factual = "widget:filter; operator:is; on:$fieldIdx0" name = "difficulty" type = "radio" value = "easy">
• autoSubmit:<boolean>
• onLoad:<boolean> ( requires "value" attribute of the input tag to be set to either a constant or $get[<key>].  ONLY works when fieldDef is an actual field ID.)
• default:<constant> ( used to set a default "value", useful when value is set to $get[<key>] )
  
• widget:resetFilters
• properties
• autoSubmit:<boolean> ( automatically submits the resetted filters )
• widget:submitter | applyFilters
• widget:search
• properties  ( not specifying "on" property results in a search on all fields )
• on:<fieldDef> | <type> ( can be multiple <fieldDef> , comma or space delimited.  Possible <type> values include: visibleFields and referencedFields. <type> and <fieldDef> can be used together )  
  example:<input factual="widget:search; on:referencedFields $fieldIdx1, $fieldIdx2">
• widget:sorter | sort
• properties
• on:<fieldDef>
• dir:<direction>  ( possible <direction> values: asc, desc )
  example:
  <select factual = "widget:sort">
     <option factual = "on:$fieldIdx0; dir:asc"> A-Z </option></select>
  
• widget:pagination
• properties
• per:<int> ( number of items per page )
• widget:starRating
•  properties
• on:<fieldDef>
• min ( minimum rating )
• max ( maximum rating )
• widget:incrementalRating ( thumbs up/down rating )
• properties
• on:<fieldDef>
• widget:messenger ( used to display messages to user ie: "Retrieving data." )
• widget:history ( used together with marker:list to display the primary key vote history of the clicked subject )