RLM_Instructions.doc - Bitbucket

braintreesmileSoftware and s/w Development

Aug 15, 2012 (4 years and 11 months ago)

329 views

Table of Contents
Mercurial Installation

................................
................................
................................
................................
.

2

Windows Users

................................
................................
................................
................................
.

2

Linux Users

................................
................................
................................
................................
......

2

RLM App installation
................................
................................
................................
................................
.

3

Get the code base

................................
................................
................................
..............................

3

Install the database

................................
................................
................................
...........................

3

Working with Mercurial

................................
................................
................................
.............................

4

Before You Start

................................
................................
................................
...............................

4

Start working with Mercurial

................................
................................
................................
...........

5

Handling conflicts

................................
................................
................................
............................

5

Ch
ecking the changes

................................
................................
................................
.......................

6

Working on the Development Server

................................
................................
................................
.........

7

PhpMyAdmin for development server

................................
................................
.............................

7

Development

................................
................................
................................
................................
..............

8

Database Class

................................
................................
................................
................................
..

8

Querying the Database

................................
................................
................................
.....................

8

Using Returned Data

................................
................................
................................
........................

8

Freeing Memory

................................
................................
................................
...............................

9

Inserting Records

................................
................................
................................
..............................

9

Updating Records

................................
................................
................................
.............................

9

Other Functionality

................................
................................
................................
..........................

9

Use With
in Functions

................................
................................
................................
.......................

9

Static files

................................
................................
................................
................................
.......

10

Posting to the XML Bridge

................................
................................
................................
............

10

Coding standards

................................
................................
................................
............................

10


Mercurial Installation


Windows Users

If you have a windows PC, install Mercurial by downloading:

http://bitbu
cket.org/tortoisehg/stable/downloads/

You will need to reboot your Computer.


Linux Users

Debian:

sudo apt
-
get install mercurial

Fedora/RedHat

sudo rpm
-
i mercurial

Suse

sudo yum install mercurial


To install a graphical view of the repository please use t
his:

Debian

sudo apt
-
get install hgview

Fedora/RedHat

sudo rpm
-
i hgview

Suse

sudo yum install mercurial

or use NetBeans 6.x which has Mercurial built
-
in support. (
http://netbeans.org
)


Also please install kdiff3 for to

deal with merge conflicts:

sudo apt
-
get install kdiff3

sudo rpm
-
i kdiff3

sudo yum install kdiff3








After installation please create a .hgrc file into your home directory like /home/you_user:

[email]

from = First_Name Last_Name <
myemail@gmail.com
>

[ui]

username =
myemail@gmail.com

[merge
-
tools]

kdiff3.executable = /usr/bin/kdiff3

kdiff3.args = $base $local $other
-
o $output

kidff3.priority = 1


Replace First_Name and Las
t_Name with your name and
myemail@gmail.com

with your
email address. Don't modify all the other lines unless you know what you are doing.



RLM App installation


Get the code base

Once you have successfully installed
Mercurial, then you are able to install the RLM app on
you computer.

Move to a directory where you would like rlm_lamp3 project to be created (eg.
/home/jack/projects/ or c:
\
projects
\
) and issue the following command:

hg clone
http://mercurial.intuxication.org/hg/rlm_lamp3/

After this you should see a new directory called rlm_lamp3 in your current directory (eg.
/home/jack/projects/rlm_lamp3 or c:
\
projects
\
rlm_lamp3).

Right now you need to get

the db config files from the development server. These files are not
included into the repository because they contain sensitive information which should not be
made publicly available. You can get the files from:
http://66.147.231.156/p093_includes_site.zip

Inside the zip you will find a directory called p093_includes_site. Please copy that folder into
your rlm_lamp3 directory, created following the above steps.


Install the database

You can expo
rt the database from here using PhpMyAdmin export tool:

http://66.147.231.156:2082/3rdparty/phpMyAdmin/index.php

User: rlmcoma

Password: 76IARxkcC


After you have download the MySql d
ump file, open a console and type:

mysql
-
u your_mysql_user
-
ppassword

Now you should be connected to your local mysql server.

> CREATE DATABASE rlmcoma_rlm3hr char set utf8;

> CREATE USER `rlmcoma`@`localhost` IDENTIFIED BY '76IARxkcC';

> GRANT ALL PRIVIL
EGES ON `rlmcoma_rlm3hr`.* TO `rlmcoma`@`localhost`;

Log out from your MySQL session and issue the following command:

mysql
-
u rlmcoma
-
p76IARxkcC rlmcoma < /path/to/mysql_dump_file.sql

Where /path/to/mysql_dump_file.sql is the path to you mysql dump file

exported with
PhpMyAdmin export tool.

Now you should have an working copy of RLM app.



Working with Mercurial


Before You Start

It's critical to understand that folder (and files from inside folder) p093_includes_site
SHOULD NOT BE ADDED TO THE REPOSITORY
. They need to remain isolated from the
repository. It's very easy to do make sure that is not going happen.

Go to your rlm_lamp3 directory and being inside that directory issues the following command:

hg st

This will give you the status of your Mercurial

repo. The p093_includes_site should appear in
the listing as new folder which is not being tracked. (the line should be prefixed with a “*” ).

Create a
.hgignore

file inside
rlm_lamp3
directory (eg.
/home/jack/project/rlm_lamp3/.hgignore or c:
\
project
\
rl
m_lamp3
\
.hgignore


depending on
where you have installed it) and type into that file all the filename matches that you need to be
exclude from being tracked or commited. For example:

nbproject

p093_includes_site

sql

.settings

.project

.buildpath

tmp

Right

now your .hgignore file should contain only the bolded line from above. Remember
these are regular expression and not actually the file path. To make sure you've done
everything right, type “hg st” again and see if p093_includes_site has disappeared from
the
listing.







Start working with Mercurial

Before you start developing each session, it's critically important that you have the latest files
to work with. Always pull the latest changes before start working. With Mercurial, this is very
easy. Simply o
pen a command prompt or terminal window in the directory where your
rlm_lamp3

folder resides and issue the commands:

hg pull

hg update

The pull command will load the most recent changes from the Mercurial server. The update
command will merge these changes

with your local files.

Before committing anything you should always check the status of your local repository with
the command:

hg st

This will display all the modified files or untracked files (newly added or removed files). If you
have new or removed fi
les please that need to be tracked type:

hg addremove *

or

hg add

or

hg remove


When you're done making the changes, it's necessary to “push” the changes back to the
Mercurial server. To do this, you simply need to commit the changes and push them. To
commit the changes, run:

hg commit
-
m “Message here”

Where “Message here” is a short message describing the changes you've made. Please use
short and descriptive message like: “Fixed SM screen calendar popup box show bug” or use
the task title instead: “Fe
ature #208
-

Car delivery month changed”. Don't write short stories or
messages like this “This is the biggest chunk of data” or “bug fix”. Please commit only working
code!


After these run:

hg push

In order to save the changes to the Mercurial server. Don
't push anything into the repository if
the task is not finished and still in progress except you need to test on development server.
(this situation should be very rare because you should have a working development
environment on your pc).



Handling confl
icts

Before you start each day you should either issue the command:

hg pull


or right mouse button and select Synchronize and PULL.


If you do get a conflict type:

hg heads


You'll see an output similar to:

changeset: 7:8ea2224c11f5

tag: tip

pare
nt: 5:e15eafd2af82

user: Viorel Craescu
<
vcraescu@gmail.com
>

date: sat Jun 06 15:39:13 2009 +0300

summary:
Feature #208
-

Car delivery month changed


changeset: 6:63c0bf1a1160

user: js

date: Sat Jun 06 22:42:32 2009 +1000

summary: james 6


You are looking for the Change Set at the top (above "tip") then type

hg merge
-
r xxxxxxxxx

Where xxxxx
xxxx in this case would be 8ea2224c11f5

Remember you cannot merge if you have any uncommitted changes. Be sure you have
committed all the changes before you try to merge.

A very nice screen will appear showing the possibilities for a merge. After you did
the merge
of the two heads, you need to commit again.

hg commit
-
m 'merge xxxxxxxxxx'

Where xxxxxxxx is head changeset code you merged with. Please always use a similar
message when committing changes from merging two heads.



Checking the changes

You can
check the repository history by going to

http://mercurial.intuxication.org/hg/rlm_lamp3

or by installing
hgview

or
NetBeans 6.x
. Please consult Google for any documentation how
to install hgvi
ew or NetBeans because they are very well known apps and both work on
Windows and Linux. The advantage is you can see your local repository history too.
Accessing those links you will only see the changes from development repo you probably
didn't push yet.



Working on the Development Server

We have a development server where you can test your changes before they go live. The
development server is the final step into the development cycle because it replicates a similar
environment with the live server.

Reme
mber to test the changes only when they already work on your own computer. DON'T
USE OUR SERVER FOR DEVELOPMENT because testing on this server will require you to
push the change into the repository. Test on our dev server only everything is already workin
g
on your local PC. Pushing erroneous code into the repository could cause problems on the
production server.


You can pull & update the development by using the following app:

http://66.147.231
.156/~rlmcoma/hgapp/index.php

This is a web interface for Mercurial. The buttons are the same commands you are already
using on your local PC. The RLM application can be accessed from here:

http://66.147
.231.156/p078_dealerd1/

Username: js

Password: js




PhpMyAdmin for development server

http://66.147.231.156:2082/3rdparty/phpMyAdmin/index.php

User: rlmcoma

Password: 76IARxkcC

Remem
ber, our development is the final step before your changes will go live!



Development


Database Class

The RLM software is using a custom database abstraction class which provides many
benefits including:

-

Parameters are automatically sanitized to prevent a
ccidental or deliberate MySQL injection

-

Simplified debugging as queries are tracked and timed for you

-

Resources and link identifiers are stored internally

-

Commands are shorter and less typing is generally required

-

INSERT and UPDATE commands can be
passed PHP arrays for code simplicity



Querying the Database

You can query the database as follows:

$db
-
>query(“SELECT * FROM `table_name` WHERE `id`='%%1' OR `date`>'%%2'”, $id,
$date);

The %%1 and %%2 specify which supplied parameter to pass. $id is para
meter 1 and $date
is parameter 2. There is no need to use addslashes() or mysql_real_escape_string() as the
supplied parameters are automatically escaped.


Using Returned Data

Making use of returned data is simple:

$db
-
>query(“SELECT * FROM `table_name` WH
ERE `id`='%%1' OR `date`>'%%2'”, $id,
$date);

while ($row=$db
-
>fetch()) {


echo “Record #{$row['id']}
\
n”;

}

$db
-
>free();


There's no need to supply a link identifier as it's tracked for you by the database class. If you
know only a single row and colu
mn will be returned, you can use fetchSingle() to save time:


$db
-
>query(“SELECT `name` FROM `users` WHERE `id`='500'”);

$name = $db
-
>fetchSingle();

$db
-
>free();


To return a count of records, use the count() method:

$number_of_records = $db
-
>count();


Free
ing Memory

It's a good practice to always use $db
-
>free(); when you're done interacting with the most
recent query's data in order to free up the resource and conserve memory.



Inserting Records

You can insert a record into a table as follows:

$data=array(
'name'=>'Bill Smith',



'address'=>'123 Fake Street',



'number'=>'123456');

$db
-
>insert('table_name', $data);


All data is escaped so no additional function calls are necessary.



Updating Records

You can update the contents of an existing record as follow
s:

$data = array('name'=>'Jane Jacks',



'address'=>'456 New Address');

$db
-
>update('table_name', $data, array('id'=>900));


The preceding code will change the `name` and `address` columns of the database table
`table_name` for the record with id 90
0. If additional columns exist other than name and
address in the given row, they will not be altered.




Other Functionality

Please consult /p093_includes/dbclass.inc.php for more available methods you can use.




Use Within Functions

To use the database inst
ance $db within functions and methods, you'll need to declare it as a
global as follows:


function test_function() {


global $db;


$db
-
>query(“SELECT * FROM `test` WHERE 1”);

}

Please build classes to embed related functionality instead of spreading them e
verywhere.
See /p093_includes/Lead.php for an example.

All the model classes you create, place them inside /p093_includes and name them using
camelCase notation for classes (first letter capitalized. eg. LeadStatus). Name the php file
exactly the same as t
he class name. Classes will be auto loaded If you don't stray from
conventions so you will not have to include anywhere.

You can also see Colors.php and see how we used classes and we would like you to do the
same.


Static files

Place your static files into

/p093_includes folder under the specific folder:

/p093_includes/css


stylesheets files

/p093_includes/js


javascript scripts files

/p093_includes/images


image files (use only gif/png/jpg)


For stylesheets please use /p093_includes/css/p078_dealerd2.cs
s which is the main
stylesheet file and /p093_includes/css/p078_dealerd2_print.css the equivalent for printing.



Posting to the XML Bridge

The XML bridge can be POSTed to at the following URL:

http://adsl2.rlm.com.au/p078_dealerd1/XML/A/m015_App_Bridge_ADD.php

XML data must match the schema available in the file
rlm_lamp3/p128_Doco/Programming
Standards/rlm.xml
available in the Mercurial repository. The XML data ca
n either be POSTed
as raw data in the POST variable named “xml_data”, or it can be uploaded as a POST file,
with a variable name of “xml_file”. Alternately the XML data can be posted as the raw HTTP
POST string itself. The follow code must be interfaced in

the m015_App_Bridge_ADD.php file:

//see how the data is supplied:

if (isset($_POST['xml_data'])) {


$xml=$_POST['xml_data'];

} elseif (isset($_FILES['xml_file'])) {


if (is_uploaded_file($_FILES['xml_file']['tmp_name'])) {



$xml=file_get_contents($_FILES
['xml_file']['tmp_name']);


}

} else {


$xml= $HTTP_RAW_POST_DATA;

}



Coding standards

Please stick to these rules of coding:

1.

Set your PHP editor to use 1 tab indent (4 spaces) and set it to use 4 spaces chars to
indentation and NOT 1 tab char. If you edit
or doesn't have this function then you have
to change it to a more advanced editor like NetBeans 6.x (
http://netbeans.org
)

2.

Use camelCase notation for functions, classes or variables and not C style notation
(using under
scores).

3.

Keep your classes, functions and variables names short and meaningful. No $c, $k
names with no meaning.

4.

Keep your code lines under 80
-
100 chars long (except XHTML code). Sometimes
when the line is too long it may contain the wrong logic or the log
ic can be expressed
using shorter code. Please think about this!

5.

If you spot badly formatted code, try to fix it because it will make your life easier later
when you will get a merging conflict.

6.

Try to use classes and objects instead of orphaned functions.

7.

Try to develop general purpose code and not specific code which can be used only in
one place.

8.

Write XHTML and NOT HTML code. You XHTML should adhere to W3C doctype
standards.

<!DOCTYPE html PUBLIC "
-
//W3C//DTD XHTML 1.0 Strict//EN"
"
http://www.w3.org/TR/xhtml1/DTD/xhtml1
-
strict.dtd
">

9.

Even though you can spot
SLOPPY

code, don't write sloppy code. We are trying to get
rid of it.

10.

Always prefer to use CSS classes instead of inline stylesheet. W
rite general purpose
CSS classes and use one or more classes if necessary. Example:

<span class=”font
-
16 bold red”>Some text here that is bold and red and 16
height</span>

Also name your CSS classes meaningfully.

11.


Write XHTML W3C valid code and format it a
ccordingly using 1 tab indentation.

12.

If the JavaScript code is too long (over 30 lines) please consider placing it into a
separate file named according to where it is used.

13.

Use jQuery toolkit everywhere you can instead of BOM or DOM model.

14.

The JavaScript/c
ss should be cross browser (IE6+, FireFox 3+, Chrome) and should
be displayed proper on 1024 x 768 resolution. Use
https://addons.mozilla.org/en
-
US/firefox/addon/60

to easily resize your bro
wser window for that resolution.