Code Doco - warwickfoster/qurantools GitHub Wiki

app/browse_sura.php

This PHP file appears to be part of a web application for conducting searches on the Quran's text. It's responsible for generating a dynamic search form which users can use to construct their queries.

Here's a breakdown of its main functionality:

  1. Form Generation: It dynamically generates search form rows. Each row consists of two radio buttons that allow users to choose whether they want to search by an Arabic Root or by English translation text. The form also includes dropdown menus for each row where users can select specific roots or input English text.
  2. Search Query Construction: The script has a JavaScript function process_search() that constructs the search query based on the user's form inputs. It creates a search string that combines all search terms and conditions selected by the user.
  3. Search Scope Selection: The script allows users to specify the scope of the search. Users can choose to search in all Suras, only in Meccan Suras, only in Medinan Suras, or in a specific Sura.
  4. Dynamic Search Terms Addition and Removal: Users can add or remove search terms dynamically. The script provides '+' and '-' buttons for each search term that the user can click to add or remove search terms from the query.
  5. HTML Structure and Styling: In addition to generating the search form, the script also includes HTML structure and styling for the page. It includes standard headers, titles, buttons, and footers. It also includes tooltips for different elements to provide users with more information.
  6. Data Pre-loading: The script pre-loads certain data from the database, such as a list of roots and a list of Sura numbers, which are then used to populate the form's dropdown menus.
  7. Integration with Other Components: The script includes several external PHP files at the beginning, suggesting that this file is part of a larger system. These files likely provide necessary functions and configurations for database interactions, authentication, Arabic text processing, and transliteration.

Overall, this PHP file is a significant part of the Quran Tools project, providing an interface for users to conduct customized searches on the Quran's text.

app/browse_sura.php

The PHP file provided in the context is primarily responsible for displaying a list of chapters (Suras) from the Qur'an in a tabular format. This is part of the Quran Tools project that aims to provide users with detailed insights into the Qur'an's structure, composition, and message.

Here's a detailed breakdown of what this PHP file does:

  1. Sorting and Filtering: It sorts and filters Suras based on user input. Users can sort by different fields like Sura Number, Arabic Name, English Name, number of verses, words, etc. Also, users can filter Suras based on their provenance, either Meccan or Medinan.
  2. Database Interaction: It interacts with a database to retrieve data about each Sura. This includes the Sura's number, Arabic and English names, its provenance, number of verses, words, etc. It also performs some calculations like the total number of words (discounting Qur'anic initials), and the number of words that are part of a formula.
  3. Data Presentation: It presents this data to the user in a table format, including a report title and various report options. Each row corresponds to a Sura and each column represents a specific characteristic of the Sura. Users can click on certain cells to get more detailed insights.
  4. Data Visualization: It includes data visualization functionality. There are links embedded within the table that direct to charts showing various statistics about the Suras.
  5. Interactivity: It provides a user-friendly interface for users to interact with the data. It includes buttons for showing all Suras, only Meccan Suras, or only Medinan Suras. Moreover, it offers a tooltip feature for additional information about the data.
  6. Multiple Views: It supports multiple views based on the user's device. It checks if the user is on a mobile device and modifies the display accordingly.

In summary, this PHP file is a crucial part of the Quran Tools project, allowing users to browse, sort, filter, and visualize data about the Suras in the Qur'an.