Developers

From Cliquesoft
Revision as of 06:45, 27 March 2012 by Digitalpipe (Talk | contribs)

Jump to: navigation, search

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


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 explaination of the other preceeding "octets", here we go...


  • (M)ajor: is incremented when serious changes to the codebase occur. This number reflects the long-term-ness 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 files' contained API parameters change
* The code base is re-written for any reason in any 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 - mostly. The case where code would not work would be the deletion or migration of a used API, however, we're hoping for mostly addition and not deletion. Also, it shouldn't be that complex for developers to find the alternative to their prior API call and provide a small patch to work with the updated codebase. Our criteria for numeric increases in this "octet" are:
* New API's are added to the file
* Existing API's within a file are deleted or merged (to provide an alternative to prior (relavent) functionality)
  • (f)ix: will definitely be the "highest mileage" digit of the version number. This is basically the "whatever's left" changes increase this "octet". Below are just a few of the criteria, but in the real world, there's most like more:
* Bug fixes
* I/O modification
* Modification to the internal code of a function - NOT API
* Modification of "root-level" 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 so that any developer can easily work on our projects. Currently we're on verion 1.6 of this layout, but further updates may occur based on unforseen/unencountered circumstances that take place. Below we'll give an explaination of the top-level directories so that everyone can have a general idea as to where files should be located.

  • images: contains the various image sets installed by the 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 other individuals. Image sets are specific to a particular layout due to the naming conventions used by that developer. Each installed image set has it's own sub-directory containing its graphics with a fixed-name symlink (Current) pointing to it that identifies which image set is currently selected for use by the user. 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.
  • layouts: also contains one-third (1/3) of the individual customizable GUI aspects. Contained within this directory will be the .tpl (or similar format for non-php languages) files responsible for the physical placement of the form objects on the page. Please note that this parent directory contains sub-folders that include all languages used within this software. Just like the image sets mentioned above, each layout will have it's own sub-directory and uses the same symlink naming conventions to mark which one is currently selected by the user.
  • libraries: is used to store the various toolsets, frameworks, and other software to increase functionality. Examples of sub-directories would be smarty, markdown, jquery, and more. It's also important to note that each used language of the project will have its own sub-directory as well - php, perl, js, etc. Those directories will contain 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 notes, journal, email, etc for Threads. 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 module should have it's own sub-directory just like in the images and layouts directories above.
  • styling: contains the styling of the form objects and will most likely consist of css files. Just like the images and layouts 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.
  • temp: should be used for all temp files used within the project instead of /tmp for security reasons.
  • users: is really only used for websites as a place to store specific data on a per-user basic such as avatar pictures, uploads, etc.

NOTE: The images, layouts, and styling directories each contain a mandatory, fixed-name directory called "Default" that will house the the modules developer-default data. This acts as a fallback in the event that a third party replacement doesn't support a particular module. The modules directory also contains a mandatory, fixed-name directory called "Default" as well. It contains the code for the "core" of the project. 


Draft:		1.6
Created:	2012/01/28 by Dave Henderson (dhenderson@cliquesoft.org)
Updated:	2012/03/20 by Dave Henderson (dhenderson@cliquesoft.org)


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

   images/
	Current > ./$IMAGE_SET_NAME/			< a FIXED-name symlink pointing to the user selected image set to use

	Default/					< the "fallback" directory where each module-developers' default graphics go
	   Default/					< a FIXED directory name for the graphics of the "core" of the project
		whatever.png
		... other graphics ...

		languages/				< stores specific files relating to the language
		   $USERNAME				< a FIXED-name symlink for each individual's preference
		   en/
		   es/
		   ... other languages (2 char) ...
	   $MODULE_NAME/				< a DYNAMIC directory name that houses the modules' developer-made image set
		whatever.png
		... other graphics ...

		languages/
	   ... other $MODULE_NAME dirs .../
	$IMAGE_SET_NAME/				< a DYNAMIC directory name that houses the image sets' developer-made graphics
	   Default/
	   $MODULE_NAME/
	   ... other $MODULE_NAME dirs .../
	... other $IMAGE_SET_NAME dirs .../

   layouts/
	Current > ./$LAYOUT_NAME			< a FIXED-name symlink pointing to the user selected layout to use

	Default/					< the "fallback" directory where each module-developers' default layout goes
	   Default/					< a FIXED directory name for the layout of the "core" of the project
		whatever.tpl
		whatever.js
		... other module layout files ...

		languages/				< stores specific files relating to the language
		   $USERNAME				< a FIXED-name symlink for each individual's preference
		   en/
		   es/
		   ... other languages (2 char) ...
	   $MODULE_NAME/				< a DYNAMIC directory name that houses the modules' developer-made layout
		whatever.tpl
		whatever.js
		... other module layout files ...

		languages/
	   ... other $MODULE_NAME dirs .../
	$LAYOUT_NAME/					< a DYNAMIC directory name that houses the image sets' developer-made layout
	   Default/
	   $MODULE_NAME/
	   ... other $MODULE_NAME dirs .../
	... other $LAYOUT_NAME dirs .../

   libraries/
	cache/
	js/
	   envars.js					< A FIXED filename containing globally accessible variables
	   global.js					< A FIXED filename containing globally accessible, repetitive-called functions
	   whatever.js
	   ... javascript files ...
	php/
	   envars.php
	   global.php
	   whatever.php
	   ... php files ...
	perl
	   envars.pl
	   global.pl
	   whatever.pl
	   ... perl files ...
	jquery/
	   jquery.js
	   ... jquery files ...
	smarty/
	   ... smarty files ...
	markdown/
	   ... markdown files ...
	... other globally used libraries dirs ...

   modules/
	Default/					< a FIXED directory name that houses the "core" of the project
	   app.log					< a FIXED filename that stores all logging for the "core" module
	   whatever.php
	   ... other module specific files ...

	   images > ../../images/Current/Default	< a FIXED-name symlink pointing to the current image set for the project
							NOTE: since this is the "core" of the application, there's no need to worry
								about this NOT being supported in an image set
	   include/					< contains global included files like global.js, jquery.js, etc
		js/					< a FIXED directory name containing all module-specific javascript
		   whatever.js
		   ... other javascript files ...
		php/					< a FIXED directory name containing all module-specific php files
		   whatever.php
		   ... other php files ...
		perl/
		   whatever.pl
		   ... other perl files ...
	   layouts > ../../layouts/Current/Calendar	< a FIXED symlink that points to the current layout for the module
	   styling > ../../styling/Current/Calendar	< a FIXED symlink that points to the current styling for the module
	$MODULE_NAME/					< a DYNAMIC directory name that houses the modules' developer-made layout
	   module.log					< a FIXED filename that stores all logging for the module
	   whatever.php
	   ... other module specific files ...

	   images > ../../images/Current/$MODULE_NAME	< a FIXED-name symlink pointing to the current image set for theproject
							NOTE: if the module isn't supported in the image set, this symlink will point
							to "../../images/Default/$MODULE_NAME" so that the module can work with the
							developer-made modules images
	   include/
	   layouts > ../../layouts/Current/Calendar
	   styling > ../../styling/Current/Calendar
	... other $MODULE_NAME dirs .../

   styling/
	Current > ./$STYLE_NAME/			< a FIXED-name symlink pointing to the user selected style to use

	Default/					< the "fallback" directory where each module-developers' default styling goes
	   global.css					< a FIXED filename containing all the global styling

	   Default/					< a FIXED directory name for the styling of the "core" of the project
		small.css				< a FIXED filename representing the style for small screened devices
		mobile.css				< a FIXED filename representing the style for mini's and tablets
		large.css				< a FIXED filename representing the style for large screened devices
		... other module styling files ...
	   $MODULE_NAME/				< a DYNAMIC directory name that houses the modules' developer-made styling
		small.css
		mobile.css
		large.css
		... other module styling files ...
	   ... other $MODULE_NAME dirs .../
	$STYLE_NAME/					< a DYNAMIC directory name that houses the styles' developer-made layout files
	   Default/
	   $MODULE_NAME/
	   ... other $MODULE_NAME dirs .../
	... other styling dirs .../

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


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

To access module images, use the fixed path:
	$PROJECT/modules/Default/images/*file*		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/images/*file*	< for modules

To access module includes, use the fixed path:
	$PROJECT/modules/Default/include/*file*		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/include/*file*	< for modules

To access the users' language preference, use the fixed path:
	$PROJECT/modules/Default/layouts/*file*		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/layouts/*file*	< for modules

To access module layouts (.tpl), use the fixed path:
	$PROJECT/modules/Default/layouts/*file*		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/layouts/*file*	< for modules

To access logs, use the fixed path:
	$PROJECT/modules/Default/app.log		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/module.log	< for modules

To access module styling (.css), use the fixed path:
	$PROJECT/modules/Default/styling/*file*		< for "mandatory default module" (aka core)
	$PROJECT/modules/$MODULE_NAME/styling/*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 $PROJECT/temp/install/$MODULE_NAME.tgz
	  -OR-
	obtain from user input and store to $PROJECT/temp/install/$MODULE_NAME.tgz

	uncompress $PROJECT/temp/install/$MODULE_NAME.tgz
	copy $PROJECT/temp/install/$MODULE_NAME/modules/* $PROJECT/modules/$MODULE_NAME
	copy $PROJECT/temp/install/$MODULE_NAME/images/*  $PROJECT/images/Default/$MODULE_NAME
	copy $PROJECT/temp/install/$MODULE_NAME/layouts/* $PROJECT/layouts/Default/$MODULE_NAME
	copy $PROJECT/temp/install/$MODULE_NAME/styling/* $PROJECT/styling/Default/$MODULE_NAME
	for ( images/Current, layouts/Current, styling/Current ); do
	   test if that directory exists, if not
		symlink $PROJECT/modules/$MODULE_NAME/images > $PROJECT/images/Default/$MODULE_NAME
		symlink $PROJECT/modules/$MODULE_NAME/layouts > $PROJECT/layouts/Default/$MODULE_NAME
		symlink $PROJECT/modules/$MODULE_NAME/styling > $PROJECT/styling/Default/$MODULE_NAME
	   ; if so,
		symlink $PROJECT/modules/$MODULE_NAME/images > $PROJECT/images/Current/$MODULE_NAME
		symlink $PROJECT/modules/$MODULE_NAME/layouts > $PROJECT/layouts/Current/$MODULE_NAME
		symlink $PROJECT/modules/$MODULE_NAME/styling > $PROJECT/styling/Current/$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 of 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 lets 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
}

...

?>
Retrieved from "https://wiki.cliquesoft.org/index.php?title=Developers&oldid=5156"