# TNG_coGenWeb

# Integrated Development Environment (IDE)

Work in progress.

# Integrated Development Environment (IDE) Setup

##### **<span style="color: #ba372a;">IDE of Choice</span>**

<span style="color: #000000;">My IDE of choice is Microsoft Visual Studio Code (vsCode). The vsCode is available for Windows 10, 11 or MacOS 10+. The product is free and can be downloaded at: [Visual Studio Code Download](https://code.visualstudio.com/download).</span>

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

<span style="color: #000000;">The extensions mentioned below are those that I use. Not all are absolutely necessary but most provide some sort of assistance in development.</span>

1. <span style="color: #000000;">Auto Rename Tag - Auto renames paired HTML tags.</span>
2. <span style="color: #000000;"><span style="color: #000000;">Better Comments - </span></span>Improve codes commenting by annotating with alert, informational, TODOs, and more!
3. <span style="color: #000000;">ESLint - Integrates ESLint JavaScript into VS</span>
4. <span style="color: #000000;">frp-kr - Used to automatically upload files to the main server when saved. See **Settings** below.</span>
5. <span style="color: #000000;"><span style="color: #000000;">GitHub Actions - </span></span>GitHub Actions workflows and runs for github.com hosted repositories in VS Code
6. GitHub Copilot Chat - Provides AI support for development. Great tool. Basic Copilot is free. Expanded Copilot Pro is available with subscription.
7. gitIgnore - Allows specific files/folders to be ignored by GitHub.
8. HTML CSS Support - CSS Intellisense for HTML.
9. Icons - Provides colored icons that display by the files in the navigation panel.
10. Live SASS Compiler - Compile Sass or Scss to CSS at upon file save. See **Settings** below.
11. Minify - Minify with command, and (optionally) re-minify on save.
12. One Dark Pro - Theme for Visual Studio Code.
13. Prettier Code Formatter - Code formatter.
14. Print - Provides for printing of file or selected code.
15. Project Manager - Provides easy switching between multiple projects. See **Settings** below.
16. SCSS IntelliSense - Advanced autocompletion and refactoring support for SCSS.
17. TODO Highlight - Highlight TODOs, FIXMEs, and any keywords, annotations within the code.

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

<span style="color: #000000;">Some of the Extensions mentioned require a special setup. </span>

<span style="color: #000000;">**ftp-kr** - Implementation of the ftp (File Transfer Protocol) extension requires a ftp-kr.json file in the .vscode directory. The element values of lines 2-5 must be changed for each project. The element value of line 9 is the most critical. Indicating true indicates that after a file save the file will also be uploaded to the server. It is generally best to set this value to false.</span>

```JSON
{
    "host": "www.txdelta.org",
    "username": "txdelta",
    "password": "password",
    "remotePath": "public_html/",
    "protocol": "ftp",
    "port": 0,
    "fileNameEncoding": "utf8",
    "autoUpload": false,
    "autoDelete": false,
    "autoDownload": false,
    "ignore": [
        "/.unused-County",
        "/.vscode",
        ".git",
        ".html",
        ".jpeg",
        ".jpg",
        ".png",
        ".pdf"
    ]
}
```

---

<span style="color: #000000;">**Live SASS Compiler** - The SASS compiler requires the code below included in the .vscode file settings.json. Only include lines 2-15 as 1 and 16 are already included in the settings.json file. Lines 10-12 causes the compiled file to be compressed and placed in the css/dist folder.</span>

```JSON
{
"liveSassCompile.settings.generateMap": false,
	"liveSassCompile.settings.formats": [
		{
			"format": "expanded",
			"extensionName": ".css",
			"savePath": "/css"
		},
		{
			"format": "compressed",
			"extensionName": ".min.css",
			"savePath": "/css/dist"
		}
	],
	"liveSassCompile.settings.excludeList": ["/.unused/**", "/.vscode/**", "/scss/base/**"],
}
```

<span style="color: #000000;">**CAUTION**<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; background-color: #f8f8f8;">: When the extension is installed the text "Watch Sass" at the bottom of the vsCode Workspace will display. Selecting this text will turn on the compiler and change the text to "Watching Sass."</span></span>

<span style="color: #000000;"><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; background-color: #f8f8f8;">**Warning**: Be sure to select the "Watch Sass" text to ensure your changes to the file get compiled. If you don't you may spend a lot of time trying to figure out why the changes did not activate. Trust me... I know!!</span></span>

---

<span style="color: #000000;">**Project Manager** - This extension requires a JSON file that defines the structure of the various projects. The code below details the outline of just 2 of the 10 projects in the settings file. When installed an icon will appear at the bottom in the panel to the left of he navigation panel (looks like a group of file folders). Selecting this will display the baseline project list. Moving the mouse over the list will display some icons at the top. Select the pencil icon to edit the JSON file.</span>

```JSON
[
	{
		"name": "A-Main",
		"rootPath": "c:\\wamp\\www\\STCounty",
		"paths": [],
		"tags": ["Delta"],
		"enabled": true
	},
	{
		"name": "B-Admin",
		"rootPath": "c:\\wamp\\www\\STCounty-Admin",
		"paths": [],
		"tags": ["Delta"],
		"enabled": true
	}
  }
  
```

Use the *name* value to order the projects. Use the *tags* value to group the projects within a group. Set the *rootPath* value to point to each project folder on your local drive.

# File Structure Overview

The following pages detail the structure used for the organization of the TNG_coGenWeb files.

# 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>

# 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. **functions\_java** - JavaScript functions are used by JavaScript files across the site. All file names begin with an underscore character (\_). Two files in this subfolder serve a specific purpose. 
    - **\_AllBuildJava.js** - This file *combines* the individual function files into a single file (\_allFunctionsJava.js). Thus, if a change is made to a function this file must be run to update the single file.  
        The following three files are also combined into the single function file. Each file consists of a JavaScript array containing relevant information about the county. ***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.
3. **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. This is accomplished by the system at page load time so special building is not required.
4. **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. 
    - **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. 
        - **County** - Provides the outline coordinates for the main county and the surrounding counties.
        - **Town** - Provides the outline coordinates for any towns within the area of the main county.
5. **menus** - may not be needed if County\_subnav.json file is used.

# 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 is ??? 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 Job 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

Files in the in CSS folder are generated by the vsCode IDE when the .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.

1. **dist** - This subfolder contains the compiled and minified files of the individual scss files. The module.min.css files are then used for loading to save time. (reword).

Live Sass Compiler vsCode Settings

```
"liveSassCompile.settings.generateMap": false,
	"liveSassCompile.settings.formats": [
		{
			"format": "expanded",
			"extensionName": ".css",
			"savePath": "/css"
		},
		{
			"format": "compressed",
			"extensionName": ".min.css",
			"savePath": "/css/dist"
		}
	],
	"liveSassCompile.settings.excludeList": [
		"/.unused-Delta/**",
		"/.vscode/**",
		"/scss/mixins/**",
		"/scss/base/**"
	],
```

# Image Files

**images** - All images used by the system are placed in the subfolders of this folder.

1. **cem\_images** -
2. **mis\_images** - 
    - **arrors** -
    - **awards** -
    - **icons** -
    - **logos** -
    - **masters** -
    - **sort** -
3. **xxx\_images** -

# Javascript (JS) Files

**java** - This folder contains the .js files associated with the primary .php file (e.g., school.js us loaded by the school.php file)

# SCSS Files

**scss** - The scss files are contained in five subfolders as follows.

1. **base** - The 'base' scss files are used to establish the basic css styles for the site. There are 13 files with each containing a specific part (e.g., header, topography, footer) of the overall site styles. Given that each file name begin with an underscore (\_) character, these files do not get compiled individually. The file *County*\_styles.scss, which resides in the main scss folder, loads each file and compiles them as a group.
2. **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.
3. **pages** - This subfolder 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).

# 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).

# Vendor Files

**vendor** - These are specific files provided by third-party's that provide assistance to the vendor's API. Bootstrap, DataTables, and jQuery are specifically used on the TNG\_coGenWeb sites.

# New Site Process

Details the process required to implement a new TNG_coGenWeb site.