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 JavascriptIt 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.
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.
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.