Tweetports


Tweetports Documentation


ImageTweetports derives its name from the combination of Tweets (as in Twitter) and Reports. This Joomla! 1.5 component allows registered users to add "reports" to a Joomla! site primarily using Twitter.

If users are tweeting using a geo-enabled twitter client their reports will be placed directly where their longitude and latitude location is. Tweetports however allows for alternative methods of reporting primarily using # (hashtags) which can be including in a tweet or using the Tweetports Manual Report interface.

Tweetports uses interactive Google Maps for displaying geo-targeted reports and deriving geo-positioning for user submitted locations. Site admins can also create their own hashtag locations, and for those locations that Google can't locate the administrative interface allows for manual input of longitude and latitude coordinates.

Enough of the fluff - Let's get Started!

Getting Started

Download com_tweetports from EO MediaLabs Download(external link) and install using the Joomla! 1.5 Extension installer. If you need more detailed instruction for installing components see the page below or visit Joomla Documentation(external link) or Joomla Community Forums(external link).

Install Component

Setup Cron Job

The first step is to edit the cronjob.php file, it can be found at /joomla_root/components/com_tweetports/cronjob.php. Nothing to extravagant here just simply need to set the hostname to your sites URL. On or about Line 11 of the cronjob.php file fill in the $hostname field with your sites URL.

Note: There is a subfolder field which can be set to your sites path if it resides within a subfolder of the specified URL. Be careful not to add opening or closing slashes on the subfolder path.

//
// Package: Tweetports
// License: GNU GPL v2
// Copyright: (C) 2009 - 2011 EO MediaLabs. All rights reserved.
//
// Support: Visit EO MediaLabs
//

// Change the $hostname to your site's URL

$hostname = 'www.yourdomain.com';

// If you have subfolder on your main site, specify it here. Should not end or begin with any trailing slash.
$subfolder = '';


Once you have saved your changes to cronjob.php on your hosting server it is time to setup a Cron Job within your server. Simply, Cron Jobs are scripts that run automatically at a preset interval, see your hosting providers documentation for what is necessary to setup in your particular situation. You'll be asked to provide the path the the cronjob.php script, generally it will look something like below, things will change based on your particular URL and path setup.

http://www.yourdomain.com/components/com_tweetports/cronjob.php

Note: You can test your URL be simply entering in your browser, if your path is correct you will get a Tweetports Cronjob processed text message in the browser.

The interval is important as the cronjob.php script will make searches against Twitter for those users who's tweets you're following. These searches will be handled and added to the Tweetports Cache. The searches are made asynchronously using CURL but with a large population of users being followed or a time interval that is too frequent you may run in to processing limits imposed by your hosting provider.

The reason for the implementation of a cache within Tweetports is to mitigate the amount of hits against the Twitter search API especially when a user is interacting with the Tweetports front end display. If there was no cache the Twitter API would have to be hit each and every time a user refreshed the frontend, this would result in excessive processing load as well as a significant lag between requesting information and receiving it back from Twitter, as the twitter search API is not very high performance in reality.
Cron Job - Administrative Interface
Setup the Cron Job menu which will allow you to manually run the cron job and process all of the registered Twitter users.

To create this interface open the Joomla! administrator and add a new menu, from the internal links selection choose the Tweetports entry, and then select Tweetports Cron Job.

User Agent: This is an identifying string that allows Twitter to track hits against the Search API. Twitter's suggestion is to make User Agent strings use your domain name or even an email address so that if Twitter identifies problems they can communicate with the site administrator.

NOTE from Twitter: Applications must have a meaningful and unique User Agent when using this method. A HTTP Referrer is expected but not required. Search traffic that does not include a User Agent will be rate limited to fewer API calls per hour than applications including a User Agent string.

Google Map API: You will need to obtain a Google Maps API key; these are free, immediately obtainable, and tied to your domain. Follow the link below and get you key.

Google Maps API Key Signup(external link)

# of tweets per: This is the number of tweets the component will pull from each Twitter account Tweetports is following. If these messages already exist in the Tweetports cache they will be discarded, and they represent the latest X number of tweets by each user.

Tweetports is able to use the sequence message ID (since parameter) but it is disbaled because the Twitter API is incredibly unstable at returning the tweets. This may change as Twitter stabilizes the API but for now it isn't so we are pulling a number of recent tweets from each user.

Show Report Info: If you choose to show the Report Info a dump will be created that shows all of the Twitter API search requests and their returned data in raw form.

Setup Tweetports

The main interface for the Tweetports component is the Tweetports Frontpage Layout which includes the Google Maps interface, search dialog, and the twitter reports listing.

To create this interface open the Joomla! administrator and add a new menu, from the internal links selection choose the Tweetports entry, and then select Tweetports Frontpage Layout.
Setting the Parameters

ImageGoogle Map API: This is the same key obtained for the cron job setup. See above.

max # tweets for frontend: This limits the number of reports that are including in the right accordion display for each user that meets the search parameters. There is a link provided in that display that will allow site users to get at more of the users reports.

# of records per query: When Tweetports begins to build the data set to draw on the Google Map it queries against the cache to build a list of reports that meets the search criteria. Instead of querying the entire cache Tweetports takes bites of data and builds the result set and stop processing when it has gotten enough data to satisfy the max # tweets for frontend.

Twitter Avatar: Do you want the twitter avatar to be included in the report display.

Add follow link: Do you want a Twitter follow link to be included the report display. This will allow your site users to add them to their private twitter account.

Follow Link Text: If you allow the follow link what do you want the text of the link to be.

Loading Text: When a site user processes a search this is the text that will appear as Tweetports gathers the data from the cache.

Allow Statistics: Do you want to show a statistics display on the Tweetports frontend.

Number of Tweets: If you allow statistics the text associated to the number of tweets returned.

Number of Followers: If you allow statistics the text associated to the number of user follows returned.

Width of Map: The width of the Google Map in either px or %, default is 650px.

Height of Map: The height of the Google Map in either px or %, default is 700px.

Map Type: The mode in which Google maps display in by default: hybrid, satellite only, map only.


Show Set Default: Show the Set Default button to non-registered (guest) users.

Setup Twitter User

Now that you have setup up the main Tweetports display it's time to setup the interface where site users can associate their twitter account to the Joomla! user account.

To create this interface open the Joomla! administrator and add a new menu, from the internal links selection choose the Tweetports entry, and then select Tweetports Register Layout.

Auto Approve Registration: When a site users registers their twitter account should it be auto-approved within Tweetports. Site administrators can manage approvals using the Joomla! Administrator->Components->Tweetports->Follows interface.

Allow Location Display: Allows for a multiple select list that users can select the locations they will be reporting for. THIS IS FUTURE USE. In a future version of Tweetports we will use this selected list of locations to determine which site users are reporting for a set of locations (determined by search criteria) in an effort to reduce processing requirements. The multiple select list functions currently but nothing is using it within the main Tweetports component.

When users enter the registration dialog they will be allowed to enter their twitter name ( the twitter account name) and an optional alias that will be displayed instead of their twitter name within most of the Tweetports component.

If Auto Approve Registration = Yes their tweets will immediately begin to be added to the cache each time the cron job runs.

If Auto Approve Registration = No a site administrator will have to approve the registration prior to it being picked up by the cron job. Typically prior to approval it is worthwhile to check their twitter account to see what the site user has been tweeting and insure it's not just some spam account.
Twitter User - Pro Level Users

ImageThe site administrator can also set a registrant to Pro level status using the administrative interface. Pro users are whatever you make them out to be, but in the original implementation of Tweetports it is used for those people who were adding professional level reporting. For example, if Tweetports is being used for fishing reports; Pro Level might be considered for those users who are charter captains or professional fisherman, and in exchange for their expert level reporting the are offered options in return.

When the site administrator sets a user to Pro status a number of additional options are presented.
  • The site administrator, from within the administrative interface, can set a URL for the Pro user. This URL is presented under the name and date of the report. This URL will be displayed on every report this user submits and can only be changed by a site administrator. (do not add http://)
  • When the site user enters the registration interface after being promoted to Pro status two additional fields will be presented to them.
    • Small Text Ad insert: This is a small text based ad that the user can control and is displayed on each report by this user. Each time the user edits the ad text it is changed dynamically so the next time a report is viewed the changes will be displayed. The text ad is restricted to 255 characters.
    • Small Text Ad insert URL: This is a URL added to the text ad. (do not add http://)
The Small Text Ads are included at the bottom of the report as seen in the image surrounded by the dotted box. This ad and separate URL can be used by the Pro Users to promote a particular product or offering and can be changed as these offers change over time.

Setup Locations

Locations is a powerful part of the Tweetports component and covers a number of functions within the total system. Locations allow non geo-capable twitter users to submit reports for specific locations by using #hashtagging to specify a location.

See this for a description of #hashtags(external link)

Locations are also core to the search functionality of the main Tweetports interface and are a REQUIRED aspect of a functional Tweetports implementation. This is because the main interface is using Google maps and functions based upon a longitude/latitude pair (a location) and the search function is required for Tweetports to generate a map.


ImageIf you are doing a global Tweetport implementation then locations might be major metropolitan areas, for example, New York, London, Sydney, and Mumbai. If you are doing a local implementation then locations may be individual businesses, restaurants, or hotels etc...

As a site administrator you have a couple of options for creating locations.

Go to the Administrator-> Components-> Tweetports-> Hash Tags interface to manage all of your locations. Site administrators can add a location providing at a minimum three pieces of information
  • Location Name: The location name that will be displayed, for example, Sydney or London
  • Location Address: The address of the location, for example, Sydney NSW Australia or London, UK. If you do a search on Google and can find the location Tweetports will be able to determine the longitude and latitude.
  • Location Hashtag: The corresponding #hashtag, for example, #sydney or #london, but these can be anything you desire.

You are not required to enter the longitude and latitude for a given location. Each time the main Tweetports interface is accessed the component will query against Google to attain the longitude and latitude for those locations that have empty coordinates. In some cases the default location coordinates acquired from Google may not be desirable, you can override them by simply adding a longitude and latitude (using typical numeric notation).

Setup Locations - Frontend Interface
You may want to get your user community involved by allowing them to create locations and #hashtags.

To create this interface open the Joomla! administrator and add a new menu, from the internal links selection choose the Tweetports entry, and then select Tweetports Location Input Layout.

This interface includes a list of existing locations and #hashtags so that a user can check to see if the location they would add already exists. It allows them to add the location name, location address, and the #hashtag, the interface DOES NOT allow them to add longitude and latitude directly.

If a user tries to add a location that exists already either by name, address, or #hashtag the entry will be rejected.
Setup Locations - Location Addresses
There were simple examples of locations and addresses previously but Tweetports uses the power of Google Maps so the addresses can be very specific.

If your requirements are more local in nature you can add locations by specific street address for example, if the desired location is the Empire State Building you can use the direct address 350 Fifth Avenue, New York, NY 10118 and Tweetports will get the specific coordinates.

If your requirements don't have corresponding Google locations then you can always use manual input through the administrative interface.

Manual Report Information

If your users just cant tweet, don't want to tweet, or just flat out hate Twitter; Tweetports supports submission of reports directly through Joomla!.

To create this interface open the Joomla! administrator and add a new menu, from the internal links selection choose the Tweetports entry, and then select Tweetports Report Layout.

This interface provides a simple text dialog that allows for direct text reports, these direct must include a #hashtag. If a manually submitted report does not include a #hashtag it will be rejected.

Using Tweetports

Once you have setup all your menus and the main Tweetports interface it takes a bit of work to get it going. Without reports, with twitter users, and without locations their is no data to show and therefor a dysfunctional system.

1. Create locations, these are REQUIRED, that represent your implementation goals for Tweetports whether they be local or global or something in between. It is not necessary to create every location but the Tweetports search capability does require at the very least one location, an anchor location, to function.

2. Setup your twitter user account and configure as described above. You need to have one Twitter user configured for a number of reasons but mainly so you can test your cron job to make sure reports are coming in as desired.

3. Create some reports, once you have confirmed your twitter account is working it's easy to seed the reports using the manual interface if you don't want to clutter your twitter account.

Once you have done these steps and confirmed that the inbound flow is working from twitter you now have a fully functioning Tweetports component.

Site Users

When a registered user, who is logged in, first enters the main Tweetports display they will be presented with only the search dialog and a Joomla! notice with the default text to follow.

''This is most likely your first visit.

Please set the search parameters for your area and click SET DEFAULT button.
Try to be reasonable, the bigger you set you search the longer it will take with Twitter to fill your map.

This will become your default search whenever you first enter, you can change it anytime by clicking SET DEFAULT. You can do other searches without affecting your default by clicking SEARCH.''


NOTE: If you are making Tweetports open the non-registered (public) users you should log out and then enter the Tweetports component so that you can set the Default search for the zero ( 0 ) user. Once you've set the default search for non-registered users you can go back into the parameters of the Tweetports component and change the value for Show Set Default to Hide, this will hide the Set Default button so guests don't continuously reconfigure the default view for other guests.
The Tweetports search dialog gives the user four parameters to select to control which reports are displayed to them.

Location: The user will be presented with a drop down select list comprised of all of the locations that have been added to Tweetports. The user will select a city that will be the anchor of their search.

Include Reports: The user can filter reports by age selecting No Restriction or choosing from 1 to 7 days of age.

Report Type: The user can choose to view all reports, reports made only by Pro Users ( See Pro Users ), or those made only by non Pro Users.

Radius in Miles: The user can select the radius from the Location that reports should be returned. NOTE: Currently Tweetports only works in miles, kilometer support will be brought in a subsequent version.

Once the user has made their selections they can choose to SET DEFAULT which will store the parameters and execute the search given those parameters. Otherwise the user can click SEARCH and execute a search with the given parameters without affecting the default settings.

Viewing Reports


ImageUsers can view reports in a number of ways. The most obvious way is to interact directly with the Google Maps interface by clicking on any map marker. Clicking on a map marker will bring up the report in a text bubble pointing to that marker. Markers are colored by age with red being the hottest (newest) transitioning down to blue being the coldest (oldest).

Users can also use the accordion next to the map, see image, by clicking on the name of the person reporting in the header which will expand a list of reports associated with that user. Most recent report will be at the top in descending date order. For example clicking MediaLabs Scientist will bring up the list of reports, the number of which is controlled by the component parameter setting (max # tweets for frontend).

When a user clicks a report link in the accordion the same text bubble will appear on the Google Map pointing at the appropriate map marker.

The user can also choose to click the View All Reports link which will show a detailed view of reports associated to the chosen user. This detail view brings up in chronological order, newest at the top to the oldest, regardless of what the search parameters are. The detail view will show the most recent 50 reports by the given user.

There is a special parameter that the site administrator can set that will bring in an article into the right column of the detail view. By setting the Article Identifier ID to an existing Joomla! article's ID, Tweetports will bring in that article's title and text and format it next to the detail view, otherwise the area will be left empty and the title will be the users defined alias.

Special Notes

Geo-capable Twitter Clients

Site users who are submitting reports using geo-capable Twitter clients, like many found on cellular phones or other GPS-enabled devices, must configure their Twitter account to allow for geographic information to be included with tweets. When reports are received from these devices the GPS coordinates associated to the device are transmitted along with the tweet and Tweetports will place the marker tag exactly at that transmitted location.

In some cases users may choose to override their geo-location by using a #hashtag recognized by Tweetports (#hashtags take precedence over geo-location transmitted with the tweet) . This typically happens when a user wants to tweet about a specific location but do it after the fact, like when they are at home, but they don't want their home location to be the target of report they want the associated geographic location to be the target.

Locations and hashtags

Because of the nature of the way Google Maps works; Tweetports has to manipulate the exact location of a specific report when it has used a #hashtag. If Tweetports were to place a marker for each report for a #hastag location exactly at the coordinates given all of the markers would stack exactly on top of each other. This would mean that the user could only interact with the last marker drawn at that location and there is no way to drill down through the stack of markers to get to a specific report.

So in these cases Tweetports manipulates the location by a random amount to spread the markers out within a certain radius, which at the moment is .6 mile radius. If you want to remove this fudge factor for instance in the case of a very localized implementation edit the /components/com_tweetports/includes/classes/GoogleMapApi.class.php file. In this file on or about line 297 modifiy the $variance, which is currently 10000 or approximately .6 miles, to 0 or very close to zero.

Users will still be able to get to reports using the accordion even if the map markers are piled on top of each other. Keep in mind that this variance is applied to the report as it is added to the cache, so make sure you set it up the way you want prior to ingesting reports. This was done to improve processing speed from the cache so that these coordinates are not calculated every time a report is accessed. The #hashtag ID is stored in the cache record as we plan to have a script that will recalculate the cache but it is not available currently.