Quickstart

Get the GitHub Contributions Chart application up and running in minutes

Prerequisites

Before you begin, ensure you have the following installed:

1. Delphi or C++Builder IDE

   You need a Delphi or C++Builder IDE to open and compile the project. The project uses VCL (Visual Component Library) components.

2. TeeChart VCL

   TeeChart VCL must be installed in your IDE. This is a commercial charting component library that powers the visualizations.

   The application will not compile without TeeChart VCL properly installed and configured in your IDE.

Installation

1. Clone the Repository

   Clone the GitHub Contributions Chart repository to your local machine:

   git clone https://github.com/Steema/GitHub-Contributions-Chart-with-TeeChart-VCL.git
   cd GitHub-Contributions-Chart-with-TeeChart-VCL
   
2. Open the Project

   Launch your Delphi or C++Builder IDE and open the project file:

   GitHubContributions.dpr
   

   This is the main project file that includes:

   • Unit1.pas - Main form and application logic
   • Themes.pas - Theme definitions for light and dark modes
3. Build the Project

   Build the project using your IDE’s build command (typically Project > Build or Ctrl+F9).

   The project will compile and link all necessary units and resources.

4. Run the Application

   Run the compiled application using your IDE’s run command (typically Run > Run or F9).

   The main form will appear with the GitHub Contributions Chart interface.

Using the Application

Fetching Contribution Data

1. Enter a GitHub Username

   In the username field, enter any valid GitHub username. The default example is sallar:

   // Default username set on form creation (Unit1.pas:289)
   EUsername.Text := 'sallar';
   

   You can change this to any GitHub user, for example: torvalds, gvanrossum, or your own username.

2. Click 'Get Contributions'

   Click the “Get Contributions” button to fetch data from the API. The application will:

   1. Make an HTTP request to https://github-contributions.vercel.app/api/v1/{username}
   2. Parse the JSON response containing years and contribution data
   3. Populate the year selector with available years

   // API call implementation (Unit1.pas:70)
   response := DownloadWeb(Format('https://github-contributions.vercel.app/api/v1/%s', [username]));
   Result := TJSONObject.ParseJSONValue(TEncoding.ASCII.GetBytes(response), 0) as TJSONObject;
   
3. Wait for Data to Load

   The cursor will change to an hourglass while fetching data. Once complete, the chart will display the most recent year’s contributions.

   The application requires an active internet connection to fetch contribution data from the API.

Viewing Contributions

Once data is loaded, you’ll see:

• Contribution Chart: A grid-style chart where each point represents a day
• Color-Coded Intensity: Different colors indicate contribution levels (0-4)
  • Level 0: Light gray (no contributions)
  • Level 1-4: Progressively darker shades of green (more contributions)
• Month Labels: Short month names (Jan, Feb, Mar, etc.) across the top
• Day Labels: Abbreviated day names (Mon, Wed, Fri) on the left side

// Theme color grades (Themes.pas:20)
Grades: ($F0EDEB, $A8E99B, $63C440, $4EA130, $396E21);
// 5 intensity levels from light to dark green

Interactive Features

Selecting Different Years

Use the year dropdown to view contributions from different years:

// Year selection change handler (Unit1.pas:280-283)
procedure TForm1.CBYearsChange(Sender: TObject);
begin
  DrawChart;
end;

The chart will immediately update to show the selected year’s data.

Switching Themes

Click the “Dark” or “Light” button to toggle between themes:

// Theme toggle implementation (Unit1.pas:145-173)
if BTheme.Caption = 'Dark' then
begin
  currentTheme := GithubDarkTheme;
  BTheme.Caption := 'Light';
end
else
begin
  currentTheme := StandardTheme;
  BTheme.Caption := 'Dark';
end;

The theme affects:

• Background color
• Text color
• Chart colors
• Control colors (edit boxes, combo boxes)

Changing First Day of Week

Use the “First Day of Week” dropdown to choose between Sunday (0) or Monday (1):

// Custom week calculation (Unit1.pas:122-143)
procedure CustomWeekDayOfTheYear(ADate: TDateTime; AFirstDayOfWeek: Integer; 
                                 var AWeek, ADay: Integer);

This adjusts the chart layout to match your regional preferences.

Viewing Daily Details

Hover over any point in the chart to see a tooltip with the formatted date:

// Tooltip formatting (Unit1.pas:109-120)
function FormatMark(ADate: TDateTime): string;
begin
  Result := Format('%s %d', [TFormatSettings.Invariant.LongMonthNames[MonthOf(ADate)], 
                             DayOf(ADate)]);
  // Adds proper suffix: 1st, 2nd, 3rd, 4th, etc.
end;

Example tooltip: “January 1st”, “March 23rd”

Code Examples

Fetching Contributions from API

Here’s how the application downloads and parses GitHub contribution data:

// Download web content (Unit1.pas:55-64)
function DownloadWeb(aURL: string): string;
var httpClient: TNetHTTPClient;
begin
  httpClient := TNetHTTPClient.Create(nil);
  try
    Result := httpClient.Get(aURL).ContentAsString;
  finally
    httpClient.Free;
  end;
end;

// Get GitHub contributions (Unit1.pas:66-72)
function GetGitHubContributions(username: string): TJSONObject;
var
  response: string;
begin
  response := DownloadWeb(Format('https://github-contributions.vercel.app/api/v1/%s', [username]));
  Result := TJSONObject.ParseJSONValue(TEncoding.ASCII.GetBytes(response), 0) as TJSONObject;
end;

Drawing the Contribution Chart

The chart plotting logic maps each contribution day to a point with color-coded intensity:

// Add contribution point to chart (Unit1.pas:238)
Series1.AddXY(tmpWeek, 7-tmpDay, FormatMark(tmpDate), IntensityThemeColor(tmpIntensity));

// Intensity-based color selection (Unit1.pas:175-178)
function IntensityThemeColor(AIntensity: Integer): TColor;
begin
  Result := currentTheme.Grades[AIntensity];
end;

Troubleshooting

Project Won't Compile

Error: Missing TeeChart components or units

Solution: Ensure TeeChart VCL is properly installed in your IDE. Check that all required units are in your library path:

• VCLTee.TeEngine
• VCLTee.TeeProcs
• VCLTee.Chart
• VCLTee.Series
• VCLTee.TeeTools

No Data Appears After Clicking Get Contributions

Possible causes:

• No internet connection
• Invalid GitHub username
• API endpoint is down
• Firewall blocking HTTP requests

Solution: Verify your internet connection and try a known valid username like sallar or torvalds.

Chart Displays Incorrectly

Issue: Points are misaligned or overlapping

Solution: Try changing the “First Day of Week” setting or selecting a different year. The chart layout is calculated based on week boundaries.

Next Steps

Now that you have the application running:

• Explore the source code in Unit1.pas to understand the implementation
• Examine Themes.pas to see how to create custom color themes
• Modify the chart properties in the form designer to customize appearance
• Extend the application with additional features like date range filtering or contribution statistics

View Source Code

Check out the full source code on GitHub