THIS README

INTRODUCTION

Current version is 1.4.1. This document is dated March 29, 2014.

THIS is not unlike a Blog or CMS PHP application. THIS is small, efficient and "anti-complex":

No Objects No Classes No Globals No Javascript

It has Themes, Templates, customizable Markup, Rules for URL strings, something called Usercode and has a Plugin-like capability. We want people to examine this code, not just use it. Oh yeah, the code is small.

Needs Work

The code, although stable and we run several websites with it, is not an "Internet Ready" application in some respects.

THIS code requires much manual maintenance to configure.

It is highly recommended that you test this program thoroughly on LOCALHOST, and to not just place it on the Internet and try it from there (but you can, of course). There are several configuration files and web template files that will need to be customized before anything will work for you.

What THIS Ain't

THIS claims not to be some kind of "adaptable", "advanced and powerful", "maintainable", and "easy to install" application — everyone claims that — this ain't that. Some of the code is good, some of the code is not bad and some of the code needs improvement.

THIS claims these qualities: "clear", "concise", "understandable" and "efficient" and that there are enough of these qualities in the code to warrant further development.

INSTALLATION

THIS is ready to run as a Blog with many pre-installed, text file based simulated posts which explain how it works and how to setup the database. Just copy the directory to a place on a server and go to it. Initially, ADMIN.PHP (Admin) runs without a login/password, and you use it to setup a name, password and MySQL connection. You can also use Admin to configure the site and edit the HTML templates.

It is highly recommended to install THIS on LOCALHOST first

Since all the configuration files are text files, either INI or PHP formats, you can also configure everything by editing those files with a text editor. You will have to "get your hands dirty" and understand the format of several files to get a good grasp of how to customize the site.

Admin was designed to edit configuration files and HTML templates, therefore, many files and some directories need to be writeable. This is so even on a remote server. (But this is not a requirement.) No sensitive data is stored in any configuration file.

File permissions are retained from the ZIP file, uploading via FTP does not, but FTP has the chmod command. There may be other tools to manage files on a remote server available such as cPanel.

The basic site configuration files are CONFIG.INI and SECTION.INI. How to customize these — and other aspects of the site — is explained by running the site and reading the posts and the documentation files.

Directory Hierarchy

This is a description of all the directories (those writeable for configuration are marked *, and for file mode *).

dat: Admin support code
doc: documentation and highlighted source files
files: image upload directory; file download directory *
htm: HTML templates/themes; Admin templates *
import: filemode text files; Admin export/import directory **
inc: API source files
mod: Module source files
pages: text "pages" directory **

Of those, the doc directory is not required. The files directory can be considered optional. The subdirectories of import are optional and if THIS is to be setup to use a MySQL database can be removed. The contents (pages) of the subdirectories of pages can be removed or overwritten.

Modes of Operation

There are two modes of operation: File Mode and MySQL Mode.

In File Mode all posts, pages and comments are stored as text files. This is the default mode. Out of the archive THIS runs at a pre-configured, pre-populated, fully operational website.

MySQL Mode of course requires an existing MySQL user to be available. An Admin account/password and a database are created during setup. The single Admin user and posts and comments will be stored in the database. Pages, however, will still be stored as text files (they may be moved into the database in some later version).

Both modes are described in the documentation.

UPGRADING

The many changes we make assuredly make things for someone actually trying to use this code very difficult to upgrade. This is our fault, but modifying the architecture at any time for efficiency reasons has been a core "feature" of the code.

The only way to upgrade — that is incorporating modifications into an already installed site — is manually.

However, THIS is not about to modify any database schema as they have been designed to adapt to new data without ever needing to be changed (a bold claim, but supported by the code). Therefore, if one happened to a have a database setup that included many database entries, the core code will always work with it.

But we are going on the assumption that very few people are actually using this code. We assume some people install the code and fool around with it and delete it.

PROBLEM CODE

THIS has had some poorly implemented code in the past. This release removes it all.

But THIS code still has several files with what we call a kind of "code weakness". This is the characteristic of having too much complexity, which makes the code "non-obvious." Such code is, perhaps, difficult to understand. The weaknesses are in the following files.

ADMIN.PHP

The Admin code deserves a special mention only. That code, as we have been saying since version 1.0.0, is a very sloppily built doghouse. However — and this could very well be only because we built it — we kind of like it. But it sure is sloppy! We want to get the core code in a better state (less complex, more understandable) before reshaping it.

We have though with this version greatly improved, again, several of the Admin support files in the DAT/ directory.

HTML.PHP

Several functions that dynamically produce an HTML "menu" and "navigation bar" are complicated. Since the previous version, though, they have been quite stable. See file TEMPLATES.

USERCODE.PHP

The "Usercode" idea itself is a complex one and the code to implement it is actually little used. However, it can be hard to follow so we list it here. This code need not even be used and the site would run file if the file were simply deleted. See file USERCODE. But the code and the idea is worthy of your understanding.

VISITORS.PHP

What is called "visitor code" is code to register users without user registration. This is truly offbeat code and took a while to get working and at one point we thought we had come up with a disaster. However, the code finally has become stable with just one known design problem (which will be fixed in the next version). See file VISITORS.

This code is simply storing data for each visitor who makes a comment and who has chosen to enter something in a "code" text-input field. When that happens the visitor is "registered" by the association of a name/code pair stored in the database. (Which is all the code does right now but we have plans for adding features.)

Summary

All in all though, the amount of code in those files is manageable. The average file length is about 240 lines.

And we always write many comments blocks around the complicated code. So, some of the code is complicated and hard to follow, but it is quite small and is therefore, perhaps, quite manageable.

LICENSE

This program, which consists of PHP source code files, configuration files, 
HTML data files and text documentation files, and is distributed under the name 
"THIS - This HTML Is Simple" (or simply "THIS"), is Copyright (C) 2012-2014 by 
Greg Jennings.

This program is distributed in the hope that it will be useful, but WITHOUT ANY 
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 
ANY PARTICULAR PURPOSE.

                       The "THIS" License Version 1.1

This LICENSE explains the copying and use permissions of this program.

You can redistribute this program in whole only under the terms of this LICENSE. 

You can redistribute parts of this program under the auspices of "fair use", 
where "parts" is defined and is as understood by current copyright law (which is 
a freedom that this LICENSE cannot deny you).

You can run this program for any purpose, without restriction.

You can modify this program for your own use, without restriction.

You can redistribute copies of this program ONLY as expressly outlined in this 
LICENSE.

You can redistribute modified versions of this program ONLY as expressly 
outlined in this LICENSE.

You can redistribute modified copies of this program ONLY if you agree that the 
modified program will also be covered by this LICENSE.

You can redistribute modified copies of this program ONLY if you expressly make 
prominent that it is a modified version of this program.

You cannot charge any fee for the redistribution of this program, modified or 
unmodified; this includes "shipping and handling" fees, "transfer" fees and 
"medium" fees.

You cannot offer any support or any warranty for this program.

You cannot redistribute this program without this LICENSE.

You cannot modify or append this LICENSE or it's terms in any way.

You cannot redistribute this program for any commercial purpose.

You cannot modify any copyright notice(s) in any of the files except for program 
output as outlined below.

You may modify any of this program's output without restriction. This includes 
copyright notices and "titles" or any HTML or other "markup language text" the 
program may output.

--
License Version history:

1.0 - Initial release.
1.1 - Removed 'BETA' anti-redistribution clause.