توثيق بوابة "مصاحف"

مقدمة‫:‬

تعد بوابة مصاحف من أهم البوابات في موقع IslamHouse‪.‬com إذ توفر البوابة مجموعة متنوعة من التلاوات المسموعة لمشاهير قراء العالم الإسلامي، وأيضًا توفر قراءات مسموعة لترجمات معاني القرآن الكريم بعدد من اللغات، وكذلك مجموعة متنوعة من التلاوات بالقراءات والروايات، وأيضًا تلاوات أئمة الحرمين الشريفين، والمصاحف المُعلِّمة للأطفال.
إذا كنت من مطوري مواقع الإنترنت أو تطبيقات الأجهزة الذكية فيمكنك الآن استنساخ جميع محتويات بوابة “مصاحف” بسهولة ويسر دون الحاجة إلى جمع محتويات هذه البوابة يدويًا؛ حيث توفر بوابة البيانات API‪.‬IslamHouse‪.‬com جميع ما تحتاجه لعمل ذلك.

مكونات البنية التحتية‫:‬

تحتوى بوابة “مصاحف” على مجموعة أقسام رئيسة يتفرع منها باقي محتويات البوابة .. وهي:
- أسماء القراء.
- أسماء السور.
- المصاحف المجودة.
- المصاحف المرتلة.
- المصاحف المُعلِّمة.
- روايات وقراءات.
- مصاحف الحرمين.
- مصاحف مترجمة.
حيث تعد هذه التصانيف هي الأقسام الرئيسة للبوابة والتي يتفرع منها التلاوات أو القراء حسب التصنيف المخصص .. فجميع الأقسام متشابهة فيما عدى قسمين وهما:
- أسماء القراء: حيث يتم عرض ترتيب أبجدي لأسماء القراء، ثم يتفرع من كل قارئ التلاوات الخاصة به.
- أسماء السور: حيث يتم عرض جميع سور القرآن الكريم، ثم يمكنك تصفح التلاوات المتوفرة باسم كل سورة، ثم تختار التلاوة التي تريدها حسب السورة الواحدة.

الأقسام الرئيسة لبوابة ‫“‬مصاحف‫”:‬

للحصول على البيانات الخاصة بالتصانيف الرئيسة لبوابة “مصاحف” من بوابة البيانات API‪.‬IslamHouse‪.‬com يتم ذلك من خلال الرابط التالي:

http://api.islamhouse.com/v1/XXXXXXXX/quran/get-categories/ar/json

حيث تقوم باستبدال المتغير XXXXXXXX بمفتاح الاتصال الخاص بك الذي قمت بإنشائه من قبل .. ويمكنك مراجعة الرابط التالي لمعرفة كيفية الحصول على “مفتاح اتصال” خاص بك: http://api2.islamhouse.com/ar/how-to-use?%D8%A7%D8%B6%D8%BA%D8%B7%20%D9%87%D9%86%D8%A7

والملاحظ أيضًا أنه يتم إرسال لغة العرض المطلوب جلب البيانات بها، وفي مثالنا في الرابط الآنف الذكر تم تحديد اللغة العربية والتي رمزها الدولي ar.

وفيما يلي مثال على الناتج الذي يظهر لك:

[
{
id: 364794,
title: "أسماء القراء",
type: "authors",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364794/ar/json/"
},
{
id: 462298,
title: "أسماء السور",
type: "suras",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/462298/ar/json/"
},
{
id: 364765,
title: "المصاحف المجودة",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364765/ar/json/"
},
{
id: 364764,
title: "المصاحف المرتلة",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364764/ar/json/"
},
{
id: 364777,
title: "المصاحف المعلمة",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364777/ar/json/"
},
{
id: 364774,
title: "روايات وقراءات",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364774/ar/json/"
},
{
id: 364771,
title: "مصاحف الحرمين",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364771/ar/json/"
},
{
id: 364768,
title: "مصاحف مترجمة",
type: "category",
api_url: "http://api.islamhouse.com/v1/XXXXXXXX/quran/get-category/364768/ar/json/"
}
]

وللحصول على اللغات المتاحة التي يمكن جلب البيانات بها يمكنك طلب الرابط التالي:

http://api.islamhouse.com/v1/XXXXXXXX/quran/get-available-languages/json
  

ملاحظة‫:‬

في المثال السابق سوف تجد أن رقم الـ id الخاص بكل قسم ثابت لا يتغير ! ، وهذا يساعدك في التفريق بين الأقسام المختلفة برمجيًا؛ وبذلك يمكنك حجب أو إظهار أقسام بعينها.

الأقسام الداخليلة لبوابة ‫“‬مصاحف‫”:‬

للدخول على أي قسم داخلي يتم ذلك بطلبه من خلال الرابط التالي:

/quran/get-category/{category_id}/{flang}/{format}

حيث أن المتغير category_id يمثل رقم المعرف الخاص بالقسم المطلوب جلب التلاوات له، فعلى سبيل المثال: لجلب التلاوات من قسم المصاحف المُعلِّمة وهو برقم 364777 فيكون الرابط كما يلي:

http://api.islamhouse.com/v1/XXXXXXXXX/quran/get-category/364777/ar/json/

ويلاحظ أيضًا في تركيبة الرابط أنه تم طلب البيانات بأحد اللغات المتوفرة، وفي مثالنا اخترنا اللغة العربية ‪/‬ar‪/‬ ، وأيضًا في نهاية تركيبة الرابط اعتمدنا صيغة جلب البيانات /json/ وبذلك سيكون الناتج كما يلي:

{
  id: 364777,
  add_date: 1313407841,
  title: "المصاحف المعلمة",
  description: "مجموعة من المصاحف المعلمة للأطفال.",
locales: [
        "ak",
        "ar",
        "bm",
        "bn",
        "bs"
],
recitations: [
        {
        id: 422962,
        title: "المصحف المعلم للقارئ الحسيني العزازي",
        add_date: 1367372376,
        type: "recitation",
        prepared_by: [
        {
        id: 335306,
        source_id: 335306,
        title: "الحسيني العزازي",
        type: "author",
        kind: "author"
        },
        {
        id: 179366,
        source_id: 179366,
        title: "موقع طريق الإسلام www.islamway.net",
        type: "source",
        kind: "source"
        }
        ],
        api_url: "http://api.islamhouse.com/v1/XXXXXXXXX/quran/get-recitation/422962/ar/json/"
        },
        {
        id: 422812,
        title: "المصحف المعلم للقارئ محمد صديق المنشاوي",
        add_date: 1367272291,
        type: "recitation",
        prepared_by: [
        {
        id: 111670,
        source_id: 111670,
        title: "محمد صديق المنشاوي",
        type: "author",
        kind: "author"
        },
        {
        id: 174056,
        source_id: 174056,
        title: "موقع نداء الإيمان www.al-eman.com",
        type: "source",
        kind: "source"
        }
        ],
        api_url: "http://api.islamhouse.com/v1/XXXXXXXXX/quran/get-recitation/422812/ar/json/"
        }
]
}

يلاحظ في المثال السابق أن البيانات تنقسم إلى جزئين رئيسين: الجزء الأول العلوي هو بيانات القسم (رقم القسم - العنوان - الوصف - تاريخ الإضافة - ترجمات القسم)، ويلاحظ أن المتغير locales يحتوي على لغات تقوم بدور الترجمة التعريفية لهذا القسم والتي تساعد على تصفح هذا القسم بلغة أخرى، وبالتالي توسيع نطاق المستهدفين لبوابة مصاحف للناطقين بالعديد من اللغات.

أما الجزء الثاني من الناتج فهو محتويات المصفوفة المسماه recitations والتي تمثل الألبومات المتوفرة في هذا القسم، حيث تحتوي على بيانات الألبوم التالية: (رقم الألبوم - الاسم - تاريخ النشر في الموقع - النوع) وكذلك بيانات القراء الذي قاموا بالتلاوة في الألبوم وناشر هذا الألبوم إن وُجد.

استعراض محتويات ألبوم مصحف:‬

لكي يمكن استعراض ألبوم مصحف فيمكن ذلك من خلال الرابط التالي:

/quran/get-recitation/{recitation_id}/{flang}/{format}

حيث يتم طلب التلاوة من خلال رقم recitation_id .
فعلى سبيل المثال‪:‬ لطلب السور الخاصة بـ “المصحف المعلم للقارئ محمد صديق المنشاوي” فيتم ذلك من خلال الرابط:

http://api.islamhouse.com/v1/XXXXXX/quran/get-recitation/422812/ar/json/

ويكون الناتج على النحو التالي:
- ملاحظة: تم عرض آخر ثلاث سور لتقليل حجم البيانات في المثال -

{
  id: 422812,
  title: "المصحف المعلم للقارئ محمد صديق المنشاوي",
  type: "recitation",
  add_date: 1367272291,
  orginal_item: "yes",
  translation_language: "ar",
  source_language: "ar",
  category_info: {
  id: 364777,
  title: "المصاحف المعلمة",
  description: "مجموعة من المصاحف المعلمة للأطفال."
},
prepared_by: [
{
  id: 111670,
  source_id: 111670,
  title: "محمد صديق المنشاوي",
  type: "author",
  kind: "author"
},
{
  id: 174056,
  source_id: 174056,
  title: "موقع نداء الإيمان www.al-eman.com",
  type: "source",
  kind: "source"
}
],
attachments: [
  {
  id: 422924,
  order: 112,
  title: "سورة الإخلاص",
  duration: 35.631,
  size: "566.9 KB",
  extension_type: "MP3",
  description: null,
  url: "http://d1.islamhouse.com/data/ar/ih_quran/ar_Full_Quran_Teacher_Menshawe/ar_Quran_Teacher_Menshawe_112.mp3",
  api_url: "http://api.islamhouse.com/v1/75EajTL1VqFO9ne6/quran/get-sura/422924/ar/json/"
  },
  {
  id: 422925,
  order: 113,
  title: "سورة الفلق",
  duration: 56.26775,
  size: "889.4 KB",
  extension_type: "MP3",
  description: null,
  url: "http://d1.islamhouse.com/data/ar/ih_quran/ar_Full_Quran_Teacher_Menshawe/ar_Quran_Teacher_Menshawe_113.mp3",
  api_url: "http://api.islamhouse.com/v1/75EajTL1VqFO9ne6/quran/get-sura/422925/ar/json/"
  },
  {
  id: 422926,
  order: 114,
  title: "سورة الناس",
  duration: 61.20488,
  size: "966.5 KB",
  extension_type: "MP3",
  description: null,
  url: "http://d1.islamhouse.com/data/ar/ih_quran/ar_Full_Quran_Teacher_Menshawe/ar_Quran_Teacher_Menshawe_114.mp3",
  api_url: "http://api.islamhouse.com/v1/75EajTL1VqFO9ne6/quran/get-sura/422926/ar/json/"
  }
],
locales: [
      "ar",
      "ur",
      "ku",
      "ug",
      "bn",
      "bs"
]
}

تحتوي النتيجة على ثلاثة أجزاء رئيسة:
- بيانات الألبوم الأساسية.
- بيانات بمرفقات الألبوم والتي هي ملفات صوتية بالتلاوات.
- الترجمات التعريفية المتوفرة لهذا الألبوم.

يمكنك التعامل مباشرة مع الملفات وعرضها بالطريقة التي تريد؛ حيث يعتبر هذا الجزء هو نهاية المطاف في هيكلة الروابط الشجرية لبوابة “مصاحف”.

ملاحظات هامة‫:‬

هذه الأقسام: (المصاحف المجودة - المصاحف المرتلة - المصاحف المُعلِّمة - روايات وقراءات - مصاحف الحرمين - مصاحف مترجمة ) متطابقة من حيث مفهوم طريقة العرض الشجرية: (الألبومات المتوفرة -> السور الخاصة بالألبوم)، وهذا يختلف عن طريقة العرض الشجرية في قسم (أسماء القراء) حيث يتفرع بهذا الشكل: (اسم القارئ -> الألبومات المتوفرة للقارئ -> السور الخاصة بالألبوم)، حيث يزيد في التفرع بمستوى واحد نظرًا لعرض الألبومات المتوفرة للقارئ بعد اسم القارئ. وكذلك أيضًا قسم (أسماء السور) إذ يتفرع إلى (اسم السورة -> التلاوات المتوفرة للسورة من ألبومات القراء).