# File Structure

To fully understand the inter workings of a TNG site, it is imperative that you first understand the file structure of the site. Both the main site and the admin site follow the same structure, although the files of the Admin area are not as extensive as the main site.

# Assets Folder/Files

The **assets** folder contains subfolders and files used across the site. The files are included in an assets folder of the project. The items listed below are subfolders within the **assets** folder.

##### <span style="color: #ba372a;">**Main Level Files**</span>

The main level assets files are those used on basically every page on the site. Files to set the configuration, navigation, header, and footer. See the section on *Page Structure* for more detail on some of these files.

##### <span style="color: #ba372a;">**Assets Subfolders**</span>

<span style="color: #000000;">Within the assets folder are several subfolders as detailed below.</span>

1. **ajax** - Ajax files are used to obtain records from tables in the database. The term ajax comes for the JavaScript method for obtaining records from a database. Files are named 'ajax\_*Module*.php' where *Module* generally identifies the associated database table.
2. **builds** - These files are used to concatenate specific multiple files into a single file. This provides for faster page loading for the site. Specific build routines include: 
    - **buildAllConfigPhp.php** - This *build* routine concatenates the following files in the *json* folder and places the output (i.e., common\_Config.php) in the *assets* folder. <span style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400;">Only the output file is uploaded to the main server. Note: the *Name* indicated in the below file names indicates the County name (e.g., Fannin).</span>
        - County\_master.json
        - *Name*\_config.json
        - *Name*\_navbar.json
        - *Name*\_footer.json
    - **buildAllFunctionsJava.php** - This *build* routine concatenates the following files in the assets/functions\_java folder. The output file (e.g., allFunctionsJava.js) is placed in the *assets/functions\_java* folder. Only the output file is uploaded to the main server. Note: the *Name* indicated in the below files names indicates the County name (e.g., Fannin). 
        - *Name*\_config.js - various js configuration values used is js code.
        - *Name*\_article.js - various js values used in *articles*.
        - *Name*\_maps.js - various js valued used in maps.
        - \_functionName.js - various js functions used throughout the site.
    - **buildAllFunctionsPhp.php** - This *build* routine concatenates the following files in the assets/functions\_php folder. The output file (e.g., allFunctionsPhp.php) is placed in the *assets/functions\_php* folder. Only the output file is uploaded to the main server. Note: the *Name* indicated in the below files names indicates the County name (e.g., Fannin). 
        - \_functionName.php - various php functions used throughout the site. Note: some of the functions are used more than others and are thus included first.
    - **buildAllStylesCSS.php** - This *build* routine concatenates the following files in the scss/base folder. The output file (e.g., allStylesCSS.scss) is placed in the scss/base folder. Because of the nature of the 'variables' files they must be included first. This *build* routine is much more complicated that the previous *build* routine. 
        - common\_variables-root.scss - all css variables used throughout the site.
        - common\_variables-sass.scss - the sass variables used for media breaks.
        - \_common-nn-\*.scss - various 'base' style files based on category of use.
    - **IMPORTANT:** Given that these *build* routines concatenate multiple modules into one file, it is therefore *required* that if any one of the concatenated items is modified, then the *build* routine must be used to include the change into the built file.
    - **NOTE:** - Within the vsCode IDE are individual task used to invoke a specific build and also one that will invoke all builds.
3. **functions\_java** - JavaScript functions are used by JavaScript files across the site. All file names begin with an underscore character (\_). This prevents individual function files from being uploaded to the server when saved after an update. See 2. above for important information about these elements. 
    - **\_functionName.js** - individual function files used throughout the site.
    - **allFunctionsJava.js** - This is the output of the build routine mentioned above. *County* in these files would be the county name. 
        - *County*\_article.js - A js array detailing the elements used with article files
        - *County*\_co\_maps.js - A js array detailing the map elements used for headings and coordinates.
        - *County*\_config.js - A js array similar to the *County*\_config.php file.
4. **functions\_php** - PHP functions are used by PHP files across the site. All names begin with an underscore character (\_). As with the JavaScript functions the individual function files are combined into one file. 
    - **\_functionName.php** - individual php functions.
    - **allFunctionsPhp.php** - concatenated php functions combined with build routine mentioned above.
5. **json** - Several json files are used to specify various entities of the site. Except for the *County\_master.json* file, each file MUST begin with the name of the county (i.e., Delta, Fannin, Holmes, etc.). See the section on *Special Files* for more detail. See the Json chapter for more detail about these files. 
    - **geojson** - Included within the json folder is a folder for the geojson files. These files detail the coordinates of an entity, The files are of two varieties. See the section on *Special Files* for more detail. Files for both Counties and Towns are included in this subfolder. 
        - **geopoly\_cty\_*name*.json** - Provides the outline coordinates for the main county and the surrounding counties. The *name* part of the filename indicates the county name in lowercase letters.
        - **geopoly\_twn\_*name*.json** - Provides the outline coordinates for any towns within the area of the main county.
    - **County\_master.json** - Master information for the home county.
    - ***Name*\_config.json** - Configuration information for the county
    - ***Name*\_database.json** - Information needed to connect to the Database. This file MUST be included in the gitIgnore file to prohibit its being uploaded to the git Responsory. See the Git Chapter for more information on git.
    - ***Name*\_footer.json** - Configuration information for footer displays fields.
    - ***Name*\_navbar.json** - Configuration information for menu display fields.
    - ***Name*\_sitemap.json** - Configuration information for creation of sitemap records. See the sitemap chapter for more informaton.
    - ***Name*\_subnav.json** - Configuration information for creation of the dropdown menu items on a page.

The files listed below reside at the main level of the assets folder.

- **common\_Config.php** -
- **common\_CronReport.php** - Code used to display results of a manual CRON script run.
- **common\_Dbconn.php** - Code used to connect to the Database.
- **common\_Footer.php** - Code used to build the Footer.
- **common\_LoadCSS.php** - Code used to load the necessary CSS files.
- **common\_LoadJava.php** - Code used to load the necessary js files.
- **common\_LoadSite.php** - Code used to load the site specific files.
- **common\_Navbar.php** - Code used to build the Navbar.
- **common\_SiteSearch.php** - Code used to build the Site Search parameters.
- ***Name*\_config.js** -
- ***Name*\_search.js** -
- **reports\_cron.php** - Code used to display the results of a manual CRON script run.

# CRON Job Files

##### <span style="color: #ba372a;">**Cron Jobs**</span>

**Cron** is a time-based job scheduler. A scheduled job is known as a *cron job*. <sup class="reference" id="bkmrk-"></sup><sup class="reference" id="bkmrk--0"></sup><sup class="reference" id="bkmrk--1"></sup><sup class="reference" id="bkmrk--2"></sup>Although typically used to automate system maintenance and administration it can be used to automate any task. Cron is most suitable for scheduling repetitive tasks. These are scripts that are set to run at selected times (day, week, month). The desired time and frequency is set using the site cPanel.

Because the 'jobs' are scheduled and run via the main cPanel the files are placed in the main file structure. Some of the primary Cron files are:

1. **Missing Images** - Provides a list of all Memorial records that reference an image file but the file cannot be located in the *images/cem\_images* directory. This should be scheduled to run weekly.
2. **Not Used Images** - This is the reverse of *Missing Images*. This provides a list of all images in the *images/cem\_images* directory that are not referenced in any Memorial record. This should be scheduled to run weekly.
3. **Missing GPS** - Searches all *images/cem\_images* directories for image files that contain GPS coordinates. For such records the memorial record Id and file name are included on the report. This should be scheduled to run weekly.
4. **Missing Credits** - Provides a list of all Memorial records that contain image references but do no include a reference to the person credited for providing the image. This should be scheduled to run weekly.
5. **Sitemap** - Provides a series of .xml files used by bots that crawl websites to gather page results for SEO (<span class="gs_tkn show">Search </span><span class="gs_tkn show">Engine </span><span class="gs_tkn show">Optimization) </span>statistics. The module uses the *County*\_search.json file to produce the *sitemap* directory files. This is run on the first day of each month.

Cron Jobs that create a 'report' send an email to the County Coordinator. Additionally, the Admin area contains links to each report so Admin level users can generate a report as desired. These requests will display the report results in the user's browser.

##### <span style="color: #ba372a;">**Scheduled Run Time**</span>

Depending on the number of Memorial records, it may take several minutes for some of the Cron jobs to finish. Thus, it is best to schedule the 'jobs' at a low traffic period. Early morning (1-2 a.m.) is a good window to schedule. Additionally, some time during the hour rather than just on the hour (e.g., 1:18 a.m.). Further, for a job scheduled once a week, Monday morning is a good time.

# CSS Files

##### <span style="color: #ba372a;">**CSS File Structure**</span>

The **css** folder contains the files generated by the *vsCode IDE* when a **scss** file is saved. This is accomplished by vsCode settings for the *Live Sass Compiler* extension.

The compiled css files are stored in the main part of this folder. Compiling and placement of these files requires an IDE extension and a setting in the vsCode IDE. See the section on *IDE Setup &amp; Usage* for more detail.

##### <span style="color: #ba372a;">**Distribution File Folder**</span>

1. **dist** - This subfolder contains the compiled and minified SASS files. The *module.min.css* files are used for loading to save time.

# Image Files

<span style="color: #000000;">The **images** folder contains all image files used throughout the system.</span>

##### <span style="color: #ba372a;">**Main Level Files**</span>

There are no files at the main level of the **images** folder. All files are contain in subfolders as indicated below.

##### <span style="color: #ba372a;">**Sublevel Images Folders**</span>

All images used by the system are placed in **images** subfolders. The file structure is not that complicated but it is very structured. Folders within the *images* folder are named with a three character prefix that identifies the type of files within the subfolder. Thus, *cem\_images* indicates cemetery images, *chu\_images* indicates church images, and *twn\_images* indicates town images. Some second level folders may also have third level folders. For example within the *twn\_images* folder a third level folder could be used to indicated the town, (e.g., images/twn\_images/bonham). The following details some of the folders used.

1. **cem\_images** - Includes all cemetery images used by the system. See more on structure and file naming in the *File Naming Convention* section in the *Admin Modules* book.
2. **mis\_images** - Contains miscellaaneous files used throughout the system. 
    - **arrows** - Arrow images are used to indicate the sort direction of table columns. (**May not be needed**).
    - **awards** - Images for state awards presented to the county and coordinator.
    - **icons** - Icon images used on maps and memorial pages to display content types. The county favicon.ico file is also included here.
    - **logos** - Contains the county, state, and national GenWeb logos.
    - **masters** - Contains all images used on the main pages of a section (e.g., the page that lists all cemeteries, churches, etc.).
    - **sort** - Icon images used to indicate sort direction on tables. (**May duplicate arrows above**)
3. **chu\_images** - Images for all churches. Can be separated into individual folders for each church.
4. **mkr\_images** - Images for all historical markers. Can be separated into individual folders for each marker.
5. **sch\_images** - Images for all schools. Can be separated into individual folders for each school.
6. **twn\_images** - Images for all towns. Can be separated into individual folders for each town.
7. **???\_images** - Additional images folders as need. Include a 3-digit identifier for the type of files in the folder.

# SCSS Files

##### <span style="color: #ba372a;">**SCSS Folder Structure**</span>

The scss files are contained in five subfolders as follows.

1. **base** - There are 13 *\_common-nn-category.scss* files where nn indicates order and category indicates the content type (e.g., header,, topography, footer, etc.). All files begin with the underscore character. The underscore indicates to the scss compiler that the individual file is not to be compiled when saved after an update. See the Integrated Development Environment (IDE) chapter for detailed information of this process. 
    - The **base** and **common** files are concatenated and compiled into a single file (*allStylesCSS.css*) that is invoked using the **buildAllStylesCSS** builds script.
2. **common** - This folder contains two files which are common to both the main and admin areas. 
    - **common\_variables-root.scss** - Contains the css variables used throughout the system.
    - **common\_variables-sass.scss** - Contains the sass variables used throughout the system. The sass variables are used in css @media queries to indicate breakpoints for multiple monitor/mobile viewport sizes.
3. **mixins** - Mixins are scss **functions** used to expand the capability of css. An individual mixin is used to do a specific task, usually indicated by the name.
4. **pages** - Contains the individual scss files relating to the specific main php file (e.g., the school.scss file is loaded by the school.php file).
5. **vendor** - Some vendor APIs require there own css files. This folder contains these files. If an element of the vendor file needs to be modified it is suggested that the change be made the corresponding base file that would override the vendor style.

# Sitemap Files

**sitemaps** - Sitemap files are used by the site to enhance the SEO bots that crawl the site. The files are created by one of the CRON scripts usually on a weekly basis. Once the CRON job is established in the cPanel this folder can be ignored. (reword).

# Main PHP Files

<div id="bkmrk-please-follow-these-">The PHP files in the main directory are the defining structure for each page of the site. Follow these guidelines for naming the main level PHP files and their associated assets:</div>##### <span style="color: #ba372a;">**Naming Convention**</span>

- Use lowercase letters with words separated by hyphens (-) or underscores (\_).
- Avoid spaces or special characters; use only A–Z, a–z, 0–9, \_, and -.

##### <span style="color: #ba372a;">**Usage**</span>

<div id="bkmrk-file-names-should-cl">File names should clearly identify the purpose of the page. For example, cemeter**ies**.php should be used for a list of all county cemeteries, while cemeter**y**.php should be used for an individual cemetery page. Likewise for church/churches, school/schools, and town/towns.</div>##### <span style="color: #ba372a;">**Related File Names**</span>

<div id="bkmrk-each-php-file-must-h">Each PHP file must have an associated JS (.js) and CSS (.scss) file. To ensure consistent file loading, these files must share the exact same name as the PHP file (e.g., cemetery.php, cemetery.js, and cemetery.scss).</div><div id="bkmrk-"></div>