Developers

Below we cover several uniform design aspects of our software to make it easy to work on, even if you're not (one of) the original author(s)! This can be considered our version of "software industrialization" so parts can easily be swapped out for third-party replacements without running into problems.

Copyright Notice

All of our software requires the following copyright notice located at the top of each file included within the project. This applies to all contributed work of our sponsored projects, however, this is not applicable to any non-sponsored extensions or themes of that software.

# FILENAME	DESCRIPTION
#
# Created	YYYY/MM/DD by AUTHOR (AUTHOR_EMAIL or support@cliquesoft.org)
# Updated	YYYY/MM/DD by AUTHOR (AUTHOR_EMAIL or support@cliquesoft.org)
#
# Unless a valid CPL license has been purchased, this software is distributed
# using the AGPLv3 license as found on the Cliquesoft website located at:
# http://www.cliquesoft.org.

Version Numbers

Similar to our XiniX distribution of Linux, our version numbers do not adhere to any standards that may be established. Instead we have broken this information down into four groups - (M)ajor.(m)inor.(f)ix.(s)tate. And for those who don't care for indepth knowledge of this topic, the one thing you should commit to memory is the (s)tate "octet". This will ALWAYS be either a zero (0) or a one (1) indicating a beta or stable version respectively.

Now for those who are interested in the indepth explanation of the other preceeding "octets", here we go...

(M)ajor: is incremented when serious changes to the codebase occur. This number reflects the long-termness of the software version and should be incremented rarely by combining at one time as many changes as possible that fall under the below criteria. Using this method should attract developers since there's no need to constantly update their projects that rely on ours as well as to establish solid, reliable functionality of our own products. Our criteria that falls under this "octet" are:

* The parameters of an API change
* Existing API's are deleted or merged
  (to provide an alternative to prior (relavent) functionality with little or no modification of legacy code)
* The code base is ported to a new programming language

(m)inor: is anticipated to have single to lower two-digit numbers as well, especially in modular based projects. By restricting the changing of this number to the below criteria, we've also provided developers with increased longevity of their efforts due to all referenced API's in their code not changing. This should not, however, foster continued development of additional features so functionality can continue to expand with the ever changing demands of the projects user-base. Our criteria for numeric increases in this "octet" are:

* New API's are added to the file

(f)ix: will definitely be the "highest mileage" digit of the version number and basically constitues all other types of modification to the source code ranging from bug fixes to complete re-writes of the internal code of an API. Below are just a few of the criteria, but in the real world, there's most likely more:

* Bug fixes
* I/O modification
* Modification to the internal code of a function - NOT the API though!
* Modification of "root-level" (non-function) code within the file

(s)tate: changes when the beta or stable state of the code has changed and will ALWAYS be a zero (0) or one (1) respectively.

Directory Structure

Obviously every developer is going to have their own naming conventions, directory layouts, and other unique traits within their projects. While there's nothing wrong with this as every person is a unique individual, it can pose problems when developers have to work on a codebase that's not their original work. As a result, we've put together a directory structure and file naming convention so that any developer can easily work on our projects. Currently we're on verion 1.7 of this layout, but further updates may occur based on unforseen/unencountered circumstances that take place. Below we'll give an explanation of the top-level directories so that everyone can have a general idea as to where files should be located.

data: is used as a place to store specific data or on a per-user basis such as avatar pictures, uploads, etc.

libraries: contains the various toolsets, frameworks, and other software to increase functionality contained in their respective languages. Examples of sub-directories would be "javascript", "php", "perl", "ruby", etc. Those directories will contain the "envars" (discussed below) and "global" (discussed below) files containing environment various and globally accessed functions for the project.

modules: will be used to house each installed module for the project or website. An example of a module for a project would be "threads", "tracker", etc. with add-ons for those projects using a naming convention such as "threads.notes", "threads.journal", "threads.email", etc. Examples of modules for websites might be "contact_us," "road_map," "products," "terms_and_conditions," etc. This is a way to isolate code for specific tasks that can be easily migrated between projects. Each "master" project (e.g. websites) should use "default" for its directory with modules (e.g. threads, tracker, etc.) having their "default" directory be the name of the project.

temp: should be used for all temp files used within the project instead of /tmp for security reasons.

themes: can be considered the parent directory to the three aspects of theming for the project, modules, and add-ons. Developers can individually customize the images sets (png, jpg, gif, etc.), layouts (html, javascript, php, etc.), and styling (css). Here you will find directories storing the layouts (a.k.a. skins) with each of those having two mandatory, fixed-named sub-directories - images and styles.

images: contains the various image sets installed by the administrator(s) and/or user(s) of the project. This directory is responsible for one-third (1/3) of the individual GUI aspects that can be customized by artists, businesses, and individuals. Image sets are specific to a particular layout due to the naming conventions used by that developer. Each installed image set will be stored in a directory containing its graphics. In the event that the project must handle multiple users, instead of the single fixed-name symlink (current), a dynamically-named symlink (members' username) will be used to accomplish this goal on a per-user basis.

styles: contains the styling of the form objects of the related layout and will most likely consist of css files. Just like the images directory, each installed style will have it's own sub-directory while also using the same symlinking system to mark the currently selected style by the user(s). These are also layout specific due to developer-specific naming conventions.

NOTE: The "themes" and related "images" and "styles" directories each contain a mandatory, fixed-name directory called "default" that will house the modules developer-default data. This acts as a fallback in the event that a third party replacement doesn't support a particular module or add-on.

Draft: 1.7
Created: 2012/01/28 by Dave Henderson (dhenderson@cliquesoft.org)
Updated: 2012/10/10 by Dave Henderson (dhenderson@cliquesoft.org)

$PROJECT/ < projects root directory
{index|default}.php < a FIXED filename that bootstraps the loading of the project

[data/]
verify/ < e.g. email verfication processing scripts
avatars/ < e.g. directory containing users avatar pictures
drivers/
ads/
... other user data dirs .../

libraries/
cache/
javascript/
envars.js < A FIXED filename containing globally accessible variables
global.js < A FIXED filename containing globally accessible, repetitive-called functions, etc.
jquery.js
whatever.js
... other javascript files ...
php/
envars.php
global.php
whatever.php
... other php files ...
perl/
envars.pl
global.pl
whatever.pl
... other perl files ...
$LANGUAGE_NAME/
envars.?
global.?
whatever.?
... other language/framework files ...

modules/
default/ < a FIXED directory name that houses the "core" of a "master" project
engine/ < a FIXED directory name that contains the modules' backend scripts
whatever.php
... other core files ...
layout > ../../themes/current < a FIXED symlink pointing to the current layout for the module
$MODULE_NAME/ < a DYNAMIC directory name that houses the modules' developer-made layout
engine/
whatever.php
... other core files ...
layout > ../../themes/current

temp/

themes/
current > ./default < a FIXED symlink pointing to the currently selected layout
default/ < a FIXED directory name that stores the default layouts for the "master" project as well as all the module and add-on default developer layouts
whatever.html
whatever.js
whatever.tpl
$MODULE_NAME.whatever.html < a DYNAMIC filename for installed modules (e.g. tracker.default.html)
$MODULE_NAME.whatever.js
$MODULE_NAME.whatever.tpl
... other layout files ...
images/ < a FIXED directory name that contains this themes' installed image sets
current > ./default < a FIXED symlink pointing to the currently selected image set of this theme
default/ < a FIXED directory name that stores the default image set for this theme
whatever.png
$MODULE_NAME.whatever.png
... other image set files ...
$IMAGE_SET_NAME < a DYNAMIC directory name storing the installed image sets for this layout
whatever.png
$MODULE_NAME.whatever.png
... other image set files ...
styles/ < a FIXED directory name housing this themes' installed styling sets
current > ./default < a FIXED symlink pointing to the currently selected style set of this theme
default/ < a FIXED directory name that stores the default style set for this theme
whatever.css
$MODULE_NAME.whatever.css
... other style set files ...
$STYLE_SET_NAME < a DYNAMIC directory name storing the installed style sets for this layout
whatever.css
$MODULE_NAME.whatever.css
... other style set files ...

$LAYOUT_NAME/ < a DYNAMIC directory name that houses the installed layouts
whatever.html
whatever.js
whatever.tpl
... other layout files ...
images/ < a FIXED directory name that contains this themes' installed image sets
current > ./default < a FIXED symlink pointing to the currently selected image set of this theme
default/ < a FIXED directory name that stores the default image set for this theme
whatever.png
... other image set files ...
$IMAGE_SET_NAME < a DYNAMIC directory name storing the installed image sets for this layout
whatever.png
... other image set files ...
styles/ < a FIXED directory name housing this themes' installed styling sets
current > ./default < a FIXED symlink pointing to the currently selected style set of this theme
default/ < a FIXED directory name that stores the default style set for this theme
whatever.css
... other style set files ...
$STYLE_SET_NAME < a DYNAMIC directory name storing the installed style sets for this layout
whatever.css
... other style set files ...

Developers can enjoy the following fixed-paths to access the various data within each root-level directory.

To access module layouts (.html, .js, .tpl), use the fixed path:
	modules/default/layout/*file*				< for the "master" project
	modules/$MODULE_NAME/layout/*file*			< for modules

To access module images (.png, .jpg, .gif), use the fixed path:
	modules/default/layout/images/current/*file*		< for the currently selected image set
	modules/$MODULE_NAME/layout/images/current/*file*	< for modules

To access module styling (.css), use the fixed path:
	modules/default/layout/styles/current/*file*		< for the currently selected style set
	modules/$MODULE_NAME/layout/styles/current/*file*	< for modules

Since this wiki page is for general use, we'll provide the following psuedo code to accomplish various tasks when dealing with the modules of a project. As we obtain submissions for the various languages (e.g. php, perl, asp, etc), we'll add download links.

Psuedo code for installation of a module:
	download from repository to temp/install/$MODULE_NAME.tgz
	  -OR-
	obtain from user input and store to temp/install/$MODULE_NAME.tgz

	uncompress temp/install/$MODULE_NAME.tgz
	copy temp/install/$MODULE_NAME/libraries/* libraries
	copy temp/install/$MODULE_NAME/modules/*   modules
	copy temp/install/$MODULE_NAME/themes/*    themes

	for ( layouts/current, layouts/current/images/current, layouts/current/styling/current ); do
	   if that any of the module files exist,
		symlink themes/current/images/current > themes/current/images/
		symlink modules/$MODULE_NAME/layouts > layouts/current/$MODULE_NAME
		symlink modules/$MODULE_NAME/styling > styling/current/$MODULE_NAME
	   ; if not,
		symlink modules/$MODULE_NAME/images > images/default/$MODULE_NAME
		symlink modules/$MODULE_NAME/layouts > layouts/default/$MODULE_NAME
		symlink modules/$MODULE_NAME/styling > styling/default/$MODULE_NAME
	   done
	done
	start modules installation scripts

Psuedo code for uninstallation of a module:
	delete $PROJECT/modules/$MODULE_NAME
	delete $PROJECT/images/Default/$MODULE_NAME
	delete $PROJECT/layouts/Default/$MODULE_NAME
	delete $PROJECT/styling/Default/$MODULE_NAME

Psuedo code for image set changing:
	for $DIRECTORY in $PROJECT/modules; do
	   test if $PROJECT/images/Current/$MODULE_NAME directory exists, if not
		symlink $PROJECT/modules/$DIRECTORY/images > $PROJECT/images/Default/$DIRECTORY
	   ; if so,
		symlink $PROJECT/modules/$DIRECTORY/images > $PROJECT/images/Current/$DIRECTORY
	   done
	done

Psuedo code for layout changing:
	for $DIRECTORY in $PROJECT/modules; do
	   test if $PROJECT/layouts/Current/$MODULE_NAME directory exists, if not
		symlink $PROJECT/modules/$DIRECTORY/layouts > $PROJECT/layouts/Default/$DIRECTORY
	   ; if so,
		symlink $PROJECT/modules/$DIRECTORY/layouts > $PROJECT/layouts/Current/$DIRECTORY
	   done
	done

Psuedo code for styling changing:
	for $DIRECTORY in $PROJECT/modules; do
	   test if $PROJECT/layouts/Current/$MODULE_NAME directory exists, if not
		symlink $PROJECT/modules/$DIRECTORY/styling > $PROJECT/styling/Default/$DIRECTORY
	   ; if so,
		symlink $PROJECT/modules/$DIRECTORY/styling > $PROJECT/styling/Current/$DIRECTORY
	   done
	done

ENVARS

As the name suggests, these files contain the environment variables for the project according to which sub-directory (language) is used. For example /libraries/php/envars.php, would contain the environment variables for php whereas the /libraries/js/envars.js file contains the global javascript variables. We've included some examples below.

Examples

We'll start off with an example of the envars.php file...

<?php
# Constant Definitions
define("TIMEOUT",1800);
define("SCRIPT",'default.php');
define("SERVER",'sql.mydomain.org');
define("DB",'db_name');
define("DBUSER",'db_username');
define("DBPASS",'db_password');
define("PubCaptcha", 'public_captcha_key';
define("PriCaptcha", 'private_captcha_key';

# Site Specific
$site='Site Name';
$emailName='Email Name';
$urlShort='mydomain.org';
$urlWhole='www.mydomain.org';
$attempts=5;						# the number of authentication attempts prior to locking an account

# Directories
$dirVerify='./verify';					# the directory to store the email verification scripts
$dirMail='./email';					# the directory to storing email
$dirTemp='../../tmp';
$dirLogs='../../mylogs/mydomain.org';

# Filenames
$logMail='email.log';
$logApp='app.log';

Now lets go over an example envars.js file...

# Site Specific
var site='Site Name';
var emailName='Email Name';
var urlShort='mydomain.org';
var urlWhole='www.mydomain.org';
var attempts=5;						# the number of authentication attempts prior to locking an account

GLOBALS

Used in various places around the above directory structure, each file should contain information that's global to the entire project. The majority of these files are located under /libraries within their respective sub-diectory (e.g. /libraries/php/global.php, /libraries/perl/global.pl, /libraries/js/global.js, etc). As a result, they should contain globally accessible functions and other data (not variables - see ENVARS). Currently the only other location of these files is under the /styling/$MODULE directories and each contains the global css definitions for that specific style.

Examples

This section will provide some examples of what these files might contain. We'll start off with the global.css file:

* { margin: 0; padding: 0; }

html {
/*	NOTE: if we use “min-height: 100%” instead of just “height: 100%” here, then the content of
	#Body will extend beyond the height of the window, with the background expanding as well.

	http://www.tutwow.com/htmlcss/quick-tip-css-100-height/
*/
  height: 100%;
}


body {
  background: #337fc6 url("../images/bg.jpg") top center repeat-y;
  font: 12px verdana;
  height: 100%;
  color: #fff;
  cursor: default; }

a, a:visited { color: #396AA4; font-weight: bold; text-decoration: none; }
a:hover { color: #fff; }

.button {
  color: #76a7dc;
  background-color: transparent;
  cursor: pointer;
  border: solid 1px #ccc; }
.button:hover { color: #808080; }

.checkbox, .radio { }

.combobox, .listbox, .password, .textbox, .textarea {		/* the combobox are multi-row listboxes */
  color: #000;
  border: 1px solid #666; }

.disabled, .disabled:hover {
  color: #808080;
  background-color: #e8e8e8;
  cursor: default; }

h1 {
  font-size: 60px;
  color: #000;
  font-weight: normal;
  opacity: 0.4;
  text-align: center; }

h2 {
  margin-top: 0;
  font-size: 14px;
  font-variant:small-caps;
  color: #000;
  letter-spacing: 2px;
  opacity: 0.4;
  text-align: center; }

h3 { }

img { border: 0px; }

p {
  margin-bottom: 20px;
  text-align: justify; }

ul {
  list-style: none;
  margin:0;
  padding:0; }

.show { display: block; }
.hide { display: none; }

.bold { font-weight: bold; }
.italic { font-style: italic; }
.underline { text-decoration: underline; }

.right { text-align: right; }
.center { text-align: center; }
.left { text-align: left; }
.justify { text-align: justify; }

.cleft  { clear: left; }
.cright { clear: right; }
.cboth  { clear: both; }
.fleft  { float: left; }
.fright { float: right; }
.noover { overflow: hidden; }

.uroman { list-style-type: upper-roman; }
.lroman { list-style-type: lower-roman; }
.ulatin { list-style-type: upper-latin; }
.llatin { list-style-type: lower-latin; }
.ualpha { list-style-type: upper-alpha; }
.lalpha { list-style-type: lower-alpha; }
.decimal { list-style-type: decimal; }
.disc { list-style-type: disc; }
.circle { list-style-type: circle; }
.square { list-style-type: square; }

.note { color: #bbb; font-size: 10px; }

.divMsgs {							/* general message popup */
  margin: 10px 4px 20px 5px;
  padding-left: 80px;
  height: 52px;
  -moz-border-radius: 0.4em;
  -webkit-border-radius: 0.4em;
  overflow: auto; }
.divFail {							/* failure message popup */
  border: 1px solid #ff0000;
  background: #ffadad url(../images/errs.jpg) 15px 5px no-repeat; }
.divSucc {							/* success message popup */
  border: 1px solid #a9d260;
  background: #fafff1 url(../images/cfrm.gif) 15px 5px no-repeat; }
.divWarn {							/* warning message popup */
  border: 1px solid #7ca0bf;
  background: #f0f7fa url(../images/info.png) 15px 5px no-repeat; }

Now let's provide an example of what might be included in the global.php file. Please note that although this is in php, the same principles apply to perl, javascript, and other languages.

<?php

function connect2DB(...) {
   // connects to the requested database for further interaction by this script
}

function safeSQL(...) {
   // used to make sure that form input is safely processed before written the the db
}

function sendMail(...) {
   // sends an email to the user
}

...

?>

Developers

Contents

Copyright Notice

Version Numbers

Directory Structure

ENVARS

Examples

GLOBALS

Examples

Navigation menu

Views

Personal tools

Navigation

Search

Tools