CountryHawk comes with several sample files which you can
use to confirm it is working properly. Getting these set up and working is
pretty straightforward. There is an installer that is recommended, and makes
setup more-or-less brainless, but in my case I went the less-recommended but
still effective manual setup route. Setting up manually for an ASP.NET site
involves dropping the assembly in your application's /bin folder along with
your license file, countries data file (countries.cdd), and
CountryHawk.properties file. Set a couple of self-explanatory (and
well-documented) values in the .properties file and things pretty much just
work.
Figure 1 below shows some sample CountryHawk code. First,
the component is created using the CountryObj.GetCountry() static method.
Then, the instance is used to pull back the user's country code, country name
(not available in Standard Edition), and IP Address. Enterprise edition
customers can also pull back a count of hits for this particular country, which
can of course be logged to a database for statistical analysis.
Figure 1 - Sample CountryHawk Usage
CountryObj chObj = null;
chObj = CountryObj.GetCountry();
string userIP = CountryObj.IPAddr;
string userCountryCode = chObj.CountryCode;
string userCountryName = chObj.CountryName;
long hitCount = chObj.HitCount; // always 0 for non-Enterprise editions
Once these variables are populated, it is of course a simple
matter to log them to a database or use them to customize the application based
on the user's geographic location.
Another very common requirement on web sites is the capture
of the user's country (and often, state). I don't know how many times I have
to fill in a dropdownlist with my country every week, but it's quite a few. It
would be a nice user interface feature if more sites could automatically "guess"
my country based on information coming from my computer so that, at least most
of the time, it would be pre-filled correctly. CountryHawk allows this
scenario to be accomplished quite easily.
Let's assume as part of a web form for user registration or
part of your checkout process you ask for the user's country, as in Figure 2
below. Rather than having to hard code the countries or better, create a
database call to fetch the countries, you can simply use CountryHawk to
populate the list of countries in the DropDownList. But better still,
CountryHawk will automatically set the user's country as the default selected
item. This requires all of two lines of code, shown in Figure 3.
Figure 2 - Sample CountryDropDownList on ASPX Page
Select Country:
<asp:DropDownList runat="server" ID="CountryDropDownList" />
Figure 3 - CountryHawk Populating DropDownList
Values
private void Page_Load(object sender, System.EventArgs e)
{
CountryObj chObj = CountryObj.GetCountry();
chObj.GetSelectList(false, null, null, null,
CountryDropDownList.Items);
}The GetSelectList() method accepts several parameters to
control how the DropDownList is populated, making it very flexible. Naturally
this simply affects the default selection - the user is still free to choose
whatever option is appropriate. This just saves them some effort (in my case,
hitting the "u" key as many times as it takes to find "United States").
CountryHawk can also be configured to provide reporting on
where your site's visitors are coming from. The CountryStats class which comes
with the product will let easily enumerate through all of the country/region
combinations that have visited your site and see the number of visitors you've
received from each.
