TNG_coGenWeb Site Developer Background/Overview Integrated Development Environment (IDE) Integrated Development Environment (IDE) Setup What is an IDE? An IDE provides a unified workspace that helps developers write, test, and debug code efficiently. It replaces the need to use separate tools (e.g., standalone editors, compilers, and debuggers) by integrating them into a single application. GeeksforGeeks Core Features Code Editor: Syntax highlighting, autocomplete, and real‑time error detection. Wikipedia Compiler/Interpreter: Converts source code into executable programs. Wikipedia Debugger: Allows breakpoints, variable inspection, and step‑through execution. GitHub Version Control Integration: Built‑in support for Git and other systems. GitHub Build Automation: Tools to compile and package applications. Codecademy Plugins/Extensions: Add support for additional languages and tools. Wikipedia Benefits Improved productivity: All tools in one place reduce context switching. GitHub Fewer errors: Real‑time feedback and debugging tools catch issues early. GitHub Better code organization: Project explorers and automation help manage large code bases. IDE of Choice 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. Extensions Given that vsCode is open source many extensions are available as desired. The following extensions are those that I use. Not all are necessary but most provide assistance in development. The list is divided into three groups. Essential - These extensions provide utilities that enhance the workspace environment essential to TNG structure. ftp-kr - Can be set to automatically upload files to the main server when saved. See Settings below. GitHub Actions - GitHub Actions workflows and runs for github.com hosted repositories in VS Code GitHub Copilot Chat - Provides AI support for development. Great tool. Basic Copilot is free. Expanded Copilot Pro (which I use) is available with subscription. gitIgnore - Allows specific files/folders to be ignored by GitHub. See Settings below. Live SASS Compiler - Compiles selected Sass/Scss to CSS upon file save. See Settings below. Recommended - These provide utilities that enhance the workspace but are not essential to the TNG structure. Auto Rename Tag - Auto renames paired HTML tags. Change the opening tag and the closing tag automatically changes. Prettier Code Formatter - Code formatter for Javascript, php, css, and json files. Ensures all files have standard formatting. Print - Provides for printing of file or selected code. Project Manager - Provides easy switching between multiple projects. See Settings below. SCSS IntelliSense - Advanced autocompletion and refactoring support for SCSS. TODO Highlight - Highlight TODOs, FIXMEs, and any keywords, annotations within the code. Your choice - These provide cosmetic user enhancements to the vsCode workspace and are left to your choice. Better Comments - Improve code commenting by annotating with alert, informational, TODOs, and more! Icons - Provides colored icons that display by the files in the navigation panel. ESLint - Integrates ESLint JavaScript into vsCode. Minify - Minifies Javascript files for faster page loads. Used on command, and (optionally) re-minify on save. One Dark Pro - Theme for Visual Studio Code. Settings Some of the Extensions mentioned require a special setup. Note that the following code are json code formatted files. Json files have a couple of strict format restrictions. Be sure to read the chapter on JSON Files. ftp-kr - Implementation of the ftp (File Transfer Protocol) extension requires a ftp-kr.json file in the .vscode folder. The element values of lines 2-4 must be changed for each project. The element value of line 9 is the most critical. Indicating true indicates that after a file is saved the file will also be uploaded to the server. It is generally best to set this value to false. To manually upload a file, right click the file name and select 'Upload this' from the generated dropdown menu. Folders and files that should never be uploaded to the live server can be identified in the parameters of the ignore element. Note that the inclusion of the image file types prevents local images from being automatically uploaded. { "host": "www.txfannin.org", "username": "txfannin", "password": "password", "remotePath": "public_html/", "protocol": "ftp", "port": 0, "fileNameEncoding": "utf8", "autoUpload": false, "autoDelete": false, "autoDownload": false, "ignore": [ "/.vscode", ".git", ".html", ".jpeg", ".jpg", ".png", ".pdf" ] } Live SASS Compiler - The SASS compiler requires the code below to be included in the .vscode settings.json file. 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. Note that the compiled expanded code is placed in the main css folder while the compiled compressed file is placed in the css/dist folder. Note also that the liveSassCompiler.excludeList element in line 15 excludes the files in the scss/base folder from being compiled. { "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/**"], } CAUTION: When the extension is installed the text "Watch Sass" appears at the bottom of the vsCode Workspace. Selecting the text will turn on the compiler and change the text to "Watching Sass." 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!! Project Manager - Although not identified as essential this extension is Highly Recommended. The extension is designed to facilitate the management of multiple projects. When working with 5 domains and 2 projects for each the movement between project can get very awkward. This extension provides ease of use out of caucus. The extension displays a folder icon in the left panel icon menu list. Selecting the icon displays a tree list contains all included projects from a json settings file. After installation select the folders icon to create an initial settings file. Along the top of the navigation panel are several icons. Select the pencil icon to displays the settings.json file in the editor panel. The code below illustrates the json file elements for two of the ten projects in my current settings file. [ { "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. The list of projects are always listed in alpha order by tags-name. Thus, the use of the leading A-, B- in the name element. Set the rootPath value to point to each project folder on your local drive. Note: the code presented must be in json format. The json structure has a couple of basic formatting rules. Be sure to read the json section in Book 3.IDE Usage Builds { "version": "2.0.0", "tasks": [ { "label": "Run Build Java Functions", "type": "shell", "command": "c:\\wamp\\bin\\php\\php8.3.0\\php.exe c:\\wamp\\www\\MSHolmes\\assets\\builds\\buildAllFunctionsJava.php", "problemMatcher": [], "group": "build" }, { "label": "Run Build PHP Functions", "type": "shell", "command": "c:\\wamp\\bin\\php\\php8.3.0\\php.exe c:\\wamp\\www\\MSHolmes\\assets\\builds\\buildAllFunctionsPhp.php", "problemMatcher": [], "group": "build" }, { "label": "Run Build CSS Base", "type": "shell", "command": "c:\\wamp\\bin\\php\\php8.3.0\\php.exe c:\\wamp\\www\\MSHolmes\\assets\\builds\\buildAllStylesCSS.php", "problemMatcher": [], "group": "build" }, { "label": "Run Build PHP Configs", "type": "shell", "command": "c:\\wamp\\bin\\php\\php8.3.0\\php.exe c:\\wamp\\www\\MSHolmes\\assets\\builds\\buildAllConfigsPhp.php", "problemMatcher": [], "group": "build" }, { "label": "Run Build All", "dependsOn": [ "Run Build Java Functions", "Run Build PHP Functions", "Run Build CSS Base", "Run Build PHP Configs" ], "group": "build", "problemMatcher": [] } ] } The IDE is very helpful by providing extensions and tasks for streamlining the work processes. The following details the usage of these enhancements. Extensions ftp-kr - This extension controls the upload of files to the live server based on the configuration parameters established in the file ftp-kr.json. The json file below details the elements of the file for Holmes county. { "host": "www.msholmes.org", "username": "msholmes", "password": "password", "remotePath": "public_html", "protocol": "ftp", "port": 21, "fileNameEncoding": "utf8", "autoUpload": true, "autoDelete": false, "autoDownload": false, "ignoreRemoteModification": true, "ignore": [ "/.vscode", "/.git", "/images/*", "/scss/*", "/sitemaps/*", ".html", "/builds/*", "/assets/functions_java/_*.js", "/assets/functions_php/_*.php", "/assets/json/*_database.json", "/css/*.css" ] } Live Sass Compiler - This extension is used to control the compiling of scss files. The extension will automatically compile .scss files when saved, To exclude a file from being compiled include the folder/files path in the liveSassCompile.settings.excludeList of the settings.json file. Note that specifically excluded from compiling are all files in the scss/mixins folder, all files that begin with the underline character in the scss/base folder, and all files in the scss/common folder. The mixin and common files are included in .scss files as needed and thus don't need to be compiled separately. Likewise the individual base files are concatenated into the single file allStylesCSS.css. The code shown below is on the liveSassCompile portion of the total settings.json file. { "liveSassCompile.settings.generateMap": false, "liveSassCompile.settings.formats": [ { "format": "expanded", "extensionName": ".css", "savePath": "/css" }, { "format": "compressed", "extensionName": ".min.css", "savePath": "/css/dist" } ], "liveSassCompile.settings.excludeList": [ "/.vscode/**", "/scss/mixins/**", "/scss/base/_*.scss", "/scss/common/**" ] } Project Manager - The suite of projects that management includes 6 TNG projects (Fannin, Holmes, and Delta each with a main and admin), plus 2 non-TNG projects (Willow Wild, Delta-Library each with a main and admin). With the extension installed a json file similar to the one below can be included for all projects. Note that all entered projects are listed in tags and name alpha order, so tag and name accordingly. The rootPath is the file path to the project folder on your local computer. [ { "name": "A-Main", "rootPath": "c:\\wamp\\www\\TXFannin", "paths": [], "tags": ["Fannin"], "enabled": true }, { "name": "B-Admin", "rootPath": "c:\\wamp\\www\\TXFannin-Admin", "paths": [], "tags": ["Fannin"], "enabled": true } ] GitHub Actions - The GitHub provides the mechanism to control all files of a project. GitHub controls the sourcing and versioning of each file. Specific files can be excluded by including the folder/file in a .gitIgnore file. Note that in most cases whole folders are excluded as the files contained can be easily restored. .md-docs/ .vscode/ css/ images/ scripts/ sitemaps/ jsconfig.json Tasks Builds - There are 4 tasks that are that are used to help 'build' files for the main site. They are as follows: FileZilla Implementation Critical to the development and maintenance of a TNG site is the need to move files from the local development environment to the hosted server live environment and vice versa. On a large scale FileZilla is used to accomplish this requirement. The following pages detail the setup and use of the FileZilla application. FileZilla Setup What is FileZilla FileZilla is a stand-alone software application used to transfer files between identified locations. The free client application can be downloaded from the website filezilla-project.org. All usernames and passwords are included in the Hit By a Bus document. Connecting xxxFileZilla Usage Usage Primary Volunteer Users xxx Image Files Although the image files are critical to the live environment is is not necessary to have all image files in the development environment. The only images folder that is needed in the development environment is images/mis_images and it's subfolders. What is a TNG_coGenWeb? The Next Generation County GenWeb (TNG_coGenWeb) is a website based on modern website structure with content supplied from a database. The following chapters detail how a TNG site is structured and implemented. Why are you reading this? Individuals working in the GenWeb community generally fall into one (or more) of three groups. County Coordinator - needs to know more about the structure of their present TNG site. Maybe even interested is building a new TNG site Maintainer - needs to know more about the structure and workings of their TNG site. Volunteer - As the county coordinator you are probably curious about your present site or maybe you want to create a new TNG site. You came to the right place. As the maintainer of a TNG site you maybe need some help understanding the structure or how something works.The same would apply to the developer/maintainer individual. As a volunteer you maybe need some help understanding how an Admin module or an element of a module works. In all three cases you came to the right place. For the Coordinator preparing for implementation of a new TNG site the chapter on New Site Implementation is for you. For the Maintainer needing to understand how something works the File Structure Overview along with the xxx is what you need. For the Volunteer needing to understand the parts of the Admin area look into the Admin Module Book.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. Main Level Files 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. Assets Subfolders Within the assets folder are several subfolders as detailed below. 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. 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. 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). 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. 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. 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. 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 Cron Jobs Cron is a time-based job scheduler. A scheduled job is known as a cron job. 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: 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. 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. 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. 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. Sitemap - Provides a series of .xml files used by bots that crawl websites to gather page results for SEO (Search Engine Optimization) 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. Scheduled Run Time 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 CSS File Structure 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 & Usage for more detail. Distribution File Folder dist - This subfolder contains the compiled and minified SASS files. The module.min.css files are used for loading to save time. Image Files The images folder contains all image files used throughout the system. Main Level Files There are no files at the main level of the images folder. All files are contain in subfolders as indicated below. Sublevel Images Folders 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. 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. 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) chu_images - Images for all churches. Can be separated into individual folders for each church. mkr_images - Images for all historical markers. Can be separated into individual folders for each marker. sch_images - Images for all schools. Can be separated into individual folders for each school. twn_images - Images for all towns. Can be separated into individual folders for each town. ???_images - Additional images folders as need. Include a 3-digit identifier for the type of files in the folder. SCSS Files SCSS Folder Structure The scss files are contained in five subfolders as follows. 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. 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. 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. 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). 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 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: Naming Convention Use lowercase letters with words separated by hyphens (-) or underscores (_). Avoid spaces or special characters; use only A–Z, a–z, 0–9, _, and -. Usage File names should clearly identify the purpose of the page. For example, cemeteries.php should be used for a list of all county cemeteries, while cemetery.php should be used for an individual cemetery page. Likewise for church/churches, school/schools, and town/towns. Related File Names 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). GitHub Implementation GitHub is a platform that supports your entire software development process, from planning work to deploying and operating software. Source GitHub New Site Set-up Process Details the process required to implement a new TNG_coGenWeb site.