Developers
From Cliquesoft
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.
Contents
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 Cliquesoft Private License (CPLv1) has been purchased for # this device, this software is licensed under the Cliquesoft Public # License (CPLv2) as found on the Cliquesoft website at www.cliquesoft.org # # 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 A PARTICULAR PURPOSE. See the appropriate Cliquesoft License for details.
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.8 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 an optional directory storing a wide variety of data ranging from each members' "home" directory to a place storing variable and contributed data such as drivers for particular models of electronics. NOTE: Out of all the directories in this structure, this would be the only one that would have a high recommendation for backup.
- 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 optional 'data' directory is not used, along with the project handling 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.8
Created: 2012/01/28 by Dave Henderson (dhenderson@cliquesoft.org)
Updated: 2013/04/01 by Dave Henderson (dhenderson@cliquesoft.org)
$PROJECT/ < The projects' root directory
{index|default}.php < a FIXED filename that bootstraps the loading of the project
[data/]
_verify/ < Used for the dynamically created email verfication scripts
_guest/ < The default "home" directory to use for non-logged in visitors
avatar.png < The picture used for the avatar of the user/member
_theme/
images > ../../../themes/default/images/default < a FIXED symlink pointing to the current image set for the user
layout > ../../../themes/default < a FIXED symlink pointing to the current layout for the user
styles > ../../../themes/default/styles/default < a FIXED symlink pointing to the current style set for the user
$USER/ < Each users' "home" directory
avatar.png < The picture used for the avatar of the user/member
_theme/
images > ../../../themes/default/images/default
layout > ../../../themes/default
styles > ../../../themes/default/styles/default
drivers/ < Example
ads/ < Example
... 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 < Example
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 "master" projects' backend scripts (engine)
default.php
whatever.php
... other default files ...
$MODULE_NAME/ < a DYNAMIC directory name that houses the modules' backend scripts (engine)
default.php
whatever.php
... other backend files ...
temp/
themes/
[current > ./default] < an optional 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
default.whatever.html
default.whatever.js
default.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] < an optional 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
default.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
default.whatever.png
$MODULE_NAME.whatever.png
... other image set files ...
styles/ < a FIXED directory name housing this themes' installed styling sets
[current > ./default] < an optional 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
default.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
default.whatever.css
$MODULE_NAME.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: data/$USER/_theme/layout/? To access module images (.png, .jpg, .gif), use the fixed path: data/$USER/_theme/images/? To access module styling (.css), use the fixed path: data/$USER/_theme/styles/?
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.
WARNING: this section is outdated as of the 1.8 revision! 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 $MODULE_NAME in modules/; do if that any of the module files exist in themes/current/, symlink ../../themes/current > modules/$MODULE_NAME/layout if not use the developers defaults, symlink ../../themes/default > modules/$MODULE_NAME/layout done if that any of the module files exist in themes/current/images/current, symlink ../../themes/current/images/current > modules/$MODULE_NAME/images if not use the developers defaults, symlink ../../themes/default/images/default > modules/$MODULE_NAME/images done if that any of the module files exist in themes/current/styles/current, symlink ../../themes/current/styles/current > modules/$MODULE_NAME/styles if not use the developers defaults, symlink ../../themes/default/styles/default > modules/$MODULE_NAME/styles done done start modules installation scripts Psuedo code for uninstallation of a module (from the default directory, NOT installed themes, image or style sets): delete modules/$MODULE_NAME delete themes/default/$MODULE_NAME.* delete themes/default/images/default/$MODULE_NAME.* delete themes/default/styles/default/$MODULE_NAME.* Psuedo code for image set changing: for $MODULE_NAME in modules/; do if that any of the module files exist in themes/current/images/current, symlink ../../themes/current/images/current > modules/$MODULE_NAME/images if not use the developers defaults, symlink ../../themes/default/images/default > modules/$MODULE_NAME/images done done Psuedo code for layout changing: for $MODULE_NAME in modules/; do if that any of the module files exist in themes/current/, symlink ../../themes/current > modules/$MODULE_NAME/layout if not use the developers defaults, symlink ../../themes/default > modules/$MODULE_NAME/layout done done Psuedo code for styling changing: for $DIRECTORY in $PROJECT/modules; do if that any of the module files exist in themes/current/styles/current, symlink ../../themes/current/styles/current > modules/$MODULE_NAME/styles if not use the developers defaults, symlink ../../themes/default/styles/default > modules/$MODULE_NAME/styles 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
# Global Constant Definitions
define("TIMEOUT",1800); # the amount of time (in seconds) to wait before the users' session expires; 0 disables
define("SERVER",'sql.mydomain.com'); # the FQDN of the SQL Server
define("DB",'database'); # the name of the SQL Database to connect to
define("DBUSER",'username'); # the administrators username
define("DBPASS",'password'); # the administrators password
define("PROJECT",'Project_Name'); # the name of the overall project
define("PubCaptcha", 'public_captcha_key'; # OPTIONAL definition for the publically used captcha key code
define("PriCaptcha", 'private_captcha_key'; # same as above for the private key code
# Global Directory Definitions
$gbl_dirLogs='../../temp'; # the directory to store log files in
$gbl_dirMail='../../data'; # the directory to store email in
$gbl_dirTemp='../../temp'; # the directory to store temp files in for this module (typically the same throughout the PROJECT)
$gbl_dirVerify='../../data/_verify'; # the directory to store the email verification scripts
# Global Log Definitions
$gbl_logEmail='email.log'; # the log filename that records success or failure when emailing from any scripts that make up this module
$gbl_logScript=SCRIPT.'.log'; # OPTIONAL log that would have errors specific to the script itself
$gbl_logModule=MODULE.'.log'; # OPTIONAL log that would have errors specific to the module itself
$gbl_logProject=PROJECT.'.log'; # OPTIONAL global log for the overall project - WARNING: this MUST match all the other modules!
# Global Name Definitions
$gbl_uriGlobal='mydomain.com'; # the root URI of the PROJECT DEV NOTE: this is mainly used so that parts of the system can be designed to rely on this global, base URI; (e.g. globally used email system -vs- {staging|demo|www}.domain.com)
$gbl_uriModule='demo.mydomain.com'; # same as above, but to segment parts of the system to be specific a MODULE
$gbl_nameProject='My Project'; # the name of the project DEV NOTE: can't use periods because the verification email doesn't get displayed correctly
$gbl_nameHackers='Support Staff'; # the TO name used by the automated administrative emailing (intended for your support team) from within the scripts for the PROJECT
$gbl_nameCrackers='Dev Staff'; # same as above, but for your PROJECT developers
$gbl_emailHackers='hackers@'.$gbl_uriGlobal; # the actual TO email address to send automated administrative emailing as outlined above
$gbl_emailCrackers='crackers@'.$gbl_uriGlobal; # same as above, but for your PROJECT developers
$gbl_intFailedAuth=5; # the number of failed authentication attempts allowed before automatically locking an account due to suspected cracking attempts
$gbl_intFailedCaptcha=5; # same as above, but for failed captcha attempts
$gbl_keyPubCaptcha = ''; # the public key used by any included captcha system
$gbl_keyPriCaptcha = ''; # same as above, but the private key
# Global System Variables
$gbl_intMaintenance=0; # WARNING: ONLY turn this on if the system needs maintenance!
$gbl_strMaintenance='2:30pm EST - down for 30 min'; # relates to the $gbl_maintenance variable when it's enabled and is a short message to be relayed to the users
$gbl_debug=0; # means the project is in a DEBUG state and to be verbose with output
$gbl_cfrm=array(); # same as above, but for confirmation information
$gbl_errs=array(); # the array to store any consecutive error messages for a single output
$gbl_info=array(); # same as above, but for general information
$gbl_user=array(); # an array that stores the active users account information
Now lets go over an example envars.js file...
var gbl_nameUser=(getCookie("username") == undefined) ? '_guest' : getCookie('username'); // Used for proper URI naming conventions or any other use
var gbl_aBookmark=new Array(); // Used for <a> hashtag book-marking system
var gbl_PID=0; // Process ID; used for certain AJAX calls
var gbl_uriGlobal='mydomain.com/modules/default'; // The global URI to access engine files
var gbl_uriModule='demo.mydomain.com/modules/default'; // Same as above, but for specific instances of the project
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.
*/
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; }
blockquote { margin: 10px 17px; }
.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; }
.overlay {
display: none;
position: absolute;
top: 0%;
left: 0%;
width: 100%;
height: 100%;
background-color: black;
z-index: 1001;
-moz-opacity: 0.6;
opacity: 0.6;
filter: alpha(opacity=60); }
p {
margin-bottom: 20px;
text-align: justify; }
ul { list-style: none; }
ul.ulTxt { width: 132px; } /* applicable @ ul level */
ul.ulObj { width: 202px; }
ul .liSub { padding-left: 12px; color: #ccc; } /* applicable @ li level; li "sub-category" */
.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; }
.curved { border-radius: 0.4em; }
.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; }
.nolist { list-style-type: none; }
.note { color: #bbb; font-size: 10px; }
.country { width: 100px; }
.city { width: 130px; }
.state { margin-left: 3px; width: 83px; }
.zip { margin-left: 3px; width: 45px; text-align: center; }
.date { width: 60px; text-align: center; }
.divInfo { /* 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
}
...
?>
