ap file and folder structure

File naming and folder structure is not just convention in ap, but it is used extensively to automate the functions of this web engine.

File extensions

The Apache file server has a number of file extensions that it recognizes and consequently processes them in a specific way. In particular *.php will be processed by the php processor to produce it's output. I make extensive use of php include scripts, but these are incomplete components. I don't want the user to accidentally try to run them. Thus I given them different file extensions and use the .htacess file to deny internet access to them. The running php scripts can ofcourse include them explicitly. In particular:

*.i
general purpose include
*.en
a page script (without all the framework around it) in English which has been set as the default language. These files form a template for what is available on the site and will be substiruted when there is no matching page in the user's chosen language.
*.de (and similar)
foreign language translation of the default (english) version.

Different functionality can be installed simply by uploading the necessary include files to the http_root folder. Whatever is present of the following types gets included, and there is no need configure anything. The scripts have file types with the following effects:

*.head
Gets included in the html header section
*.body
Is included in the site navigation section
*.done
Is included just before the final </body> tag

Those head, body and done files are included in alphabetical order, so if you want to set a predetermined sequence I recommend using an alpha-numeric prefix.

Site structure

It is the intention that each topic on the site is a self contained entity, that consists of the various pages and resources relating to the topic. Each topic is implemented as a sub folder of the http_root folder. Folders that don't contain a default page called topic will not be listed. Translated pages (e.g. topic.de) will reside alongside their corresponding default (e.g. topic.en).

Whenever a topic is selected the main drop down menu is replaced by a topic menu. This menu is defined in a file named _menu.ap (or translated equivalent). The leading _ in the name indicates it is an auto-generated file. This happens automatically when there isn't one found on entry to the topic. The way it works, is to extract all the <h1> tags that have been given an id from all the pages (substituting translated versions to produce foreign menus when requested)

After fetching the topic menu the system tacks on a link back to the root level home page as the last entry in the topic menu. Foreign language navigation items need translated legends, so rather than recode all the navigation the system cincludes a file called nav.en (for English). There in are defined all the translatable words. To add another language, simply copy this file, replace the English definitions and give it the appropriate two letter language extension. TODO: have a go at R2L

Support Folders

config.php defines the paths used on the server and a few generic function. It needs to reside in the root folder where it can be found. For security reasons, e.g. to conceal database passwords, other include files that have the .i extension and so are denied public access can be stored in the root folder but if there is a folder called "ap" paralllel to the http root folder on the server file system then that is where it looks for them these and includes other than the web pages.

A folder called public can be used to share documents in public, while one called private is for documents that can only be accessed by the scripts. Temporary symbolic links may be created to give temporary access. Such temporary links reside in the folder _tmp. TODO: expire the links.

Optimized and reduced size images are derived automatically from large high resolution originals on first access (using 404_images and 404_thumbs file not found scripts). These reside in _images and _thumbs folders and have an extra file extension tacked on (typically .WebP) to further distinguish them from the originals.

Conclusion

Understanding how the file extensions and folder structure is used is crucial to make the system work for you. In particular it is currently still necessary to delete _menu files to force a new one to be generate if and when page links change.