search

quran / quran-ios

QuranEngine is the engine powering the Quran.com iOS app.
Apache License 2.0
457 stars 158 forks source link

documentation to extend Quran app for Hifz #218

Closed knail1 closed 6 years ago

knail1 commented 6 years ago

First of all,

May Allah Reward you and Bless you for opensourcing this amazing work. I'm a father, currently trying to help his son learn the Quran. he has learnt a few Juz, but now is struggling with his historical chapters (manzil). I'm trying to find patterns and track progress so our revisions can become much more efficient, but since we use a paper quran, the annotations become very convoluted and hard to follow.

That has made me look towards an IOS app on the ipad to help with this... I am trying to extend your app to be able to annotate on it to track his mistakes and trend them over time.

1. Word by word: However, i'm trying to track this not by page but by ayah, and ideally by word. I'd started to create my own app pulling gif Quran pages down from the internet but soon realized this would not allow me to track to the level of granularity (i'd only be able to track # of mistakes/stucks/tajweed issues by page).

it was when I saw in one of your bug fixes that you have introduced word by word translation, started thinking you have to have metadata recorded per word somewhere, which is exactly what I want to extend to add history of the mistakes with that word, and the datestamp when recorded.

2. annotations per page I am also wanting to extend some visuals, track annotations page by page, something like this image below.

mockup-of-annotations

These same annotations would drive the new metadata per word I was mentioning in #1 so in the above example something like

dateReviewed,surah#,page#,ayah#,word#,typeOfIssue 010618,002,003,008,007,Mistake 010618,002,003,008,009,Mistake 010618,002,003,010,008,TajwidError 010618,002,003,010,009,TajwidError 010618,002,003,010,013,TajwidError ... and so on... I've shown only the first 2 mistakes and 3 tajwid errors on the page in the metadata, but you get the idea...

since i'm sort of a newbie IOS developer, i'm trying to learn this over weekends; i'm not as adept in knowing where to look right now. once I understand how ios unit test framework works (like the maven convention for src/tests/...) I'll try to learn backwards from there as well..

at this point though, i'm quite lost!

I had a few questions if you could help me start off on...

  1. Q1 how could I go about understanding where you keep metadata for your ayahs , and what the documentation or schema is.. so I can extend it for #1 above
  2. Q2 any tips on how I can go about adding the columns and annotations on each page as shown, e.g. how do you render the page, where would i be adding these columns, and any other ideas on what Objects in the object library in your estimation would be best suited to capture these. I was thinking TableView and TableViewCell, but ended up crashing Xcode trying to add columns!
  3. Q3 finally do you have any basic documentation or pointers where I could start to understand your code has been laid out. historically when trying to reverse engineer code, I start from the file which the front page references and then categorically document each call from there on... but in this case , because of my own weak knowledge, i dont even know what file that would be :)

JAK again for your support and may Allah give you Jaza for every line of code you've written for this app and every bug you've fixed and each feature you've produced.. InshaAllah if I can extend your app to enable my child's hifz to become more efficient, May Allah Give you the Reward of his becoming a Hafiz too one day. Ameen

mohamede1945 commented 6 years ago

Asslam Alikom we rahamat Allah we barakatoh,

First of all sorry for the late reply.

I would definitely love to help you address these things and hopefully, you can create such a wonderful app.

Regarding word-by-word metadata. We have this sqlite db located here https://github.com/quran/quran-ios/blob/master/Quran/Resources/words.db. It mainly gives each word in the Quran in Arabic and English. But if you want to know where is that word located on the Quran, you can use this sqlite db https://github.com/quran/quran-ios/blob/master/Quran/Resources/images/images_1280/databases/ayahinfo_1280.db It contains each word and its location in the images of the Quran https://github.com/quran/quran-ios/tree/master/Quran/Resources/images/images_1280/width_1280

Unfortunately, currently, we have 0 test cases for the app, which is something we should definitely fix.

Regarding your questions:

  1. Replied above.
  2. Here https://github.com/quran/quran-ios/blob/master/Quran/QuranImagePageCollectionViewCell.swift and https://github.com/quran/quran-ios/blob/master/Quran/QuranImagePageCollectionViewCell.xib is the cell that displays the Quran page, you can add your code inside that. You can simply resize the UIImageView and add 3 new UIViews to the right of that UIImageView. You might need to read a little bit about auto-layout to know how you can lay those UIViews besides the UIImageView.
  3. Most of the classes end with ViewController is a screen. So the list of suras is named SurasViewController and the Quran screen is called QuranViewController.

I'm so flattered. I hope Allah accept from you as well and make your child memorize the Quran and help you in the hereafter.

knail1 commented 6 years ago

JazakAllah Kher . This is wonderful! I'll dive into it after work today. really appreciate you taking the time to provide all the details..

Omer