Tutorial: Install and Configure Bearsampp Stats Grid

A step-by-step guide for site builders. Suitable for Joomla.org documentation or a knowledgebase article.

Before you begin

You need:

Joomla 5.0 or later (Joomla 6 is supported). Joomla 3 and Joomla 4 are not supported.
PHP 8.1 or later.
A template that loads Bootstrap 5 (Joomla's default templates do).
At least one GitHub repository whose stats workflow has run. It produces downloads.json, the charts and a dashboard.md - creating the dashboard automatically if the repository does not already have one (see the note below).

Outbound HTTPS access to raw.githubusercontent.com and to the Marked.js / DOMPurify CDNs is required at runtime.

The stats workflow is required first. The module does not generate any data itself - it only renders the dashboard.md file (and its charts) that exist in the repository. The GitHub Downloads Action emits only downloads.json and the charts (not a dashboard); it is Bearsampp's stats-daily-with-chart workflow that adds a render step to write dashboard.md. Run that workflow at least once manually before configuring the module: open the repository's Actions tab, select stats-daily-with-chart, click Run workflow, and wait for it to finish (it opens and merges a pull request that adds the stats/ folder). If the repository has no dashboard.md, the workflow creates a default one from the generated downloads.json - a title, description, badges, charts and data table - so you get a working dashboard without writing any Markdown; if it already exists, only its data table is refreshed and your content is preserved. Until the workflow has run, the module displays its "Stats coming soon" fallback for that repository.

Step 1 - Install the module

Download the release ZIP (mod_bearsampp_stats_<version>.zip) from https://github.com/Bearsampp/mod_bearsampp_stats/releases
In the Joomla Administrator, go to System → Install → Extensions.
On the Upload Package File tab, drop the ZIP onto the upload area.
Wait for the "Installation of the module was successful" message.

The ZIP must contain the module files at its root (mod_bearsampp_stats.xml, mod_bearsampp_stats.php, helper.php, tmpl/, media/, language/), not nested in an extra folder. The official release ZIPs are already packaged correctly.

Step 2 - Create the module

Go to Content → Site Modules.
Click New and choose Bearsampp Stats Grid.
Give the module a Title (for example, "Project statistics").

Step 3 - Configure the data source

Work through the Basic options:

Option	Set it to	Notes
Modules list	one or more repo names	Comma or newline separated. Use the repository names as they appear on GitHub, for example `mod_bearsampp_stats`.
Repository owner	your GitHub org/user	Defaults to `Bearsampp`. Accepts `Bearsampp`, `github.com/Bearsampp` or a full `https://github.com/Bearsampp` URL.
Branch	`main`	The branch that contains the stats folder.
Stats folder	`stats`	Folder inside each repo that holds `dashboard.md` and its charts. Change it if your workflow writes elsewhere (for example `gh-dl`).

The raw URL the module builds for each entry is:

https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<stats-folder>/dashboard.md

So with owner Bearsampp, repo mod_bearsampp_stats, branch main and folder stats, it fetches:

https://raw.githubusercontent.com/Bearsampp/mod_bearsampp_stats/main/stats/dashboard.md

Step 4 - Choose the display mode

The module automatically picks a mode based on how many entries you listed:

One entry → a single-article layout: the dashboard renders directly on the page (no card, no modal).
Two or more entries → a grid of cards is shown; clicking a card opens its dashboard in a Bootstrap 5 modal.

When using the grid, set Grid columns to a value from 1 to 7 to control how many cards appear per row. A 1-column grid stacks full-width cards that still open the modal.

Step 5 - Tune appearance and caching

Option	Default	What it does
Cache TTL (minutes)	`30`	How long rendered Markdown is cached in the browser. Set to `0` to always re-fetch.
Show stats icon	`Yes`	Show the icon on each card (grid mode).
Stats icon (FA code)	`fas fa-chart-bar`	Any Font Awesome classes. Leave empty to use the built-in SVG icon.

Advanced options (Module Class Suffix, Alternate Layout) are available on the Advanced tab for theme integration and template overrides.

Step 6 - Publish and assign

Choose a Position available in your template (often sidebar, footer or a custom position).
On the Menu Assignment tab, select the pages where the module should appear. For a dedicated statistics page, assign it to that menu item only.
Set Status to Published.
Click Save & Close.

Step 7 - Verify

Open the front end where the module is assigned.
For a single entry, the dashboard should render inline; for multiple entries, click a card and confirm the modal opens and scrolls.
Open your browser developer tools and check the Network tab: the raw dashboard.md request should return HTTP 200.
Reload the page and confirm the request is served from cache (or re-fetched after the TTL, if you set caching low for testing).

Adding more modules later

Add repository names to the Modules list, one per line, save, and the grid grows. Order in the list is the order in the grid (left to right, top to bottom).