Resources Tools Docs FAQ CMS

Tutorial 4: Tafsir End-to-End

This tutorial is for users who want to download tafsir data and render ayah-linked commentary reliably.

1) What This Resource Is

Tafsir resources provide commentary linked to ayah keys, with support for grouped commentary that can cover multiple ayahs.

Depending on the selected package, tafsir may include:

  • Ayah-linked tafsir text
  • Grouped tafsir mapping (one main ayah key shared by multiple ayahs)
  • Optional HTML formatting tags inside text (<b>, <i>, etc.)

Primary category:

2) When to Use It

Use tafsir data when you are building:

  • Ayah detail views with commentary
  • Study panels below Arabic/translation text
  • Research experiences that compare tafsir sources

2A) Tafsir vs Translation

  • Translation provides direct meaning transfer of ayah text into another language.
  • Tafsir provides explanation, interpretation, and context around ayah meaning.
  • Translation is usually one ayah-to-text mapping, while tafsir can be grouped across multiple ayahs.
  • In integration terms: translation is mostly direct key-based rendering; tafsir needs grouped/pointer resolution.

3) How to Get Your First Example Resource

  1. Open https://qul.tarteel.ai/resources/tafsir.
  2. Keep the default listing order and open the first published card.
  3. Confirm the resource detail page includes:
    • Tafsir Preview tab
    • Help tab
  4. Confirm available downloads on the detail page:
    • json
    • sqlite

This keeps onboarding concrete without hardcoding a resource ID.

4) What the Preview Shows (Website-Aligned)

On the tafsir detail page:

  • Tafsir Preview tab:
    • Jump to Ayah selector
    • Previous/next ayah navigation
    • Arabic ayah block + tafsir text block
  • Help tab:
    • JSON export model for grouped tafsir
    • SQLite columns for grouped/shared commentary
    • Notes about tafsir text including formatting tags

Practical meaning:

  • Tafsir is not always one-ayah = one-unique-text.
  • Your app must resolve grouped/shared tafsir references correctly.

5) Download and Use (Step-by-Step)

  1. Download your selected tafsir package (json or sqlite).
  2. Inspect payload shape:
    • JSON keys are ayah keys like 2:3
    • Value may be an object (main tafsir group) or a string (pointer to group ayah key)
  3. Normalize ayah keys in one format (surah:ayah).
  4. Build a tafsir resolver:
    • If current ayah maps to an object, use its text.
    • If current ayah maps to a string, follow that pointer and use the target group text.
  5. Join with Quran Script and optionally Translation by ayah key.
  6. Render commentary safely (sanitize HTML if rendering tags in production).
  7. Validate grouped cases across consecutive ayahs.

Starter integration snippet (JavaScript):

JavaScript
// Resolve tafsir text for an ayah key.
// JSON model can be:
// - object: { text, ayah_keys }
// - string: pointer to another ayah key where main text is stored
const resolveTafsirText = (tafsirByAyahKey, ayahKey) => {
  const value = tafsirByAyahKey[ayahKey];
  if (!value) return null;

  // Main group record.
  if (typeof value === "object" && value.text) {
    return {
      groupAyahKey: ayahKey,
      ayahKeys: Array.isArray(value.ayah_keys) ? value.ayah_keys : [ayahKey],
      text: value.text
    };
  }

  // Pointer record. Example: "2:4": "2:3"
  if (typeof value === "string") {
    const main = tafsirByAyahKey[value];
    if (main && typeof main === "object" && main.text) {
      return {
        groupAyahKey: value,
        ayahKeys: Array.isArray(main.ayah_keys) ? main.ayah_keys : [value],
        text: main.text
      };
    }
  }

  return null;
};

6) Real-World Example: One Tafsir for Multiple Ayahs

Goal:

  • User opens an ayah and sees the correct tafsir even when commentary is shared across a range.

Inputs:

  • Tafsir package (json or sqlite)
  • Quran Script package

Processing:

  1. User selects ayah key (example: 2:4).
  2. App looks up tafsir by ayah key.
  3. If value is pointer ("2:3"), app resolves to main group record.
  4. App renders resolved tafsir text and shows covered ayah keys.

Expected output:

  • Correct commentary appears for both main ayah and grouped ayahs.
  • No blank tafsir for grouped/pointer ayahs.

Interactive preview (temporary sandbox):

You can edit this code for testing. Edits are not saved and may not persist after refresh.

JavaScript Playground
Editor
Preview

7) Common Mistakes to Avoid

  • Assuming every ayah key contains direct tafsir text.
  • Ignoring string-pointer records in JSON grouped exports.
  • Failing to resolve group_ayah_key in SQLite exports.
  • Rendering tafsir HTML without sanitization in production apps.

8) When to Request Updates or Changes

Open an issue if you find:

  • Grouped ayah references pointing to missing source keys
  • Tafsir text assigned to wrong ayah ranges
  • Broken json/sqlite download links
  • Missing or inconsistent source metadata

Issue tracker:

Related Docs