/doc/doc.tex

% Created 2016-10-03 Mon 16:12
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{fixltx2e}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{float}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{marvosym}
\usepackage{wasysym}
\usepackage{amssymb}
\usepackage{hyperref}
\tolerance=1000
\usepackage{minted}
\usepackage{geometry}  \geometry{ a4paper,  total={6.7in,8in}}
\usepackage{indentfirst}
\usepackage{xcolor}
\author{Ibrahim Mohamed Shaatha}
\date{\today}
\title{Programmer's Documentation for Binary Tree Subsystem}
\hypersetup{
  pdfkeywords={},
  pdfsubject={Documentation for the SBC Project's Binary Tree Subsystem.},
  pdfcreator={Emacs 24.4.1 (Org mode 8.2.10)}}
\begin{document}

\maketitle
\setcounter{tocdepth}{3}
\tableofcontents



\section{Design notes}
\label{sec-1}
\begin{itemize}
\item Module requires you to enable mysql specific PDO drivers (php\_\_pdo\_\_mysql.so) installed in the server. (uncomment the line from php ini). Note: This maybe already enabled in Windows based stacks such as WAMP.
\item This module uses MySQL PDO to to interact with the database.
\item The visualizer uses a layer called, 'Repository interface' to access the database. This repository feature can be used individually by the programmer to easily read from the database.
\item Repository works using 'generic database' php interface, which can be passed to it's constructor. Any database system of your choice can be implemented using this interface. By default it uses MySQL PDO driver.
\item System needs a function to update the mapping table ("personally\_\_enrolled"), occasionally.
\item The system does not really enforce a binary tree structure.
\end{itemize}
\subsection{Information}
\label{sec-1-1}
\begin{itemize}
\item Binary Tree nodes can contain any type of data you prefer.
\item If a \emph{TreeGenerator} class is used to create a binary tree it will create a tree by reading data from the database; and the resulting tree node's data will be \emph{UserModel} objects.
\end{itemize}

\subsection{Conflicts}
\label{sec-1-2}
Repetition in binary node label in the database may cause unexpected behaviour. We need to either fix this issue, or focus on avoiding entry of invalid data. 

\section{How to Use}
\label{sec-2}
\subsection{Download and Update}
\label{sec-2-1}
\subsubsection{By Dropbox or e-mail.}
\label{sec-2-1-1}
Download and extract the files to the project directory. Give the directory a name you prefer.

\subsubsection{Get the latest version from git.}
\label{sec-2-1-2}
If you have git installed on your computer, you can easily download and install the latest version to the project. Latest version of, Git can be downloaded from \url{https://git-scm.com/}. If you have a linux, OSX or a unix family operating system, you can get the latest version using your package manager software.

Once inside the project directory, to download the script:
\begin{verbatim}
git clone https://gitlab.com/z80lives/btvis.git
\end{verbatim}
To update the script, simply execute:
\begin{verbatim}
git pull
\end{verbatim}

\subsection{Checklist}
\label{sec-2-2}
\begin{itemize}
\item To run the examples here, make sure you have pdo\_\_mysql drivers enabled. The current version uses PDO objects, on lower level to access the database. On a linux based system, run the following command and check whether it returns an output:
\end{itemize}
\begin{verbatim}
php -i | grep 'pdo_mysql'
\end{verbatim}

\begin{itemize}
\item Make sure the database is setup and configured.
\item Make sure data exists in the tables. Test data queries can be found in the "test" folder.
\end{itemize}

\subsection{Installing}
\label{sec-2-3}
\begin{enumerate}
\item Copy the contents to the web folder.
\item Insert test data to the database (Optional).

\item During the final production phase, you can remove the test and doc folder, just to be safe. You can also remove .git folder.
\end{enumerate}

If there exists a file with the name 'config.php', add the configuration class under the \emph{BinaryTreeVisualizer} namespace of that file.

\subsection{Quick setup: Displaying the Binary Tree}
\label{sec-2-4}
Make sure the tables have data, before using the module. Most of the objects in this package are not configured to display user any error message or a fallback item. Therefore it is possible to get an empty '<div>' container as an output if the visualizer cannot read anything from the database.

This module has a quick layer, for the programmer to access and generate the code if they need require it. 

\subsubsection{Create a config.php file}
\label{sec-2-4-1}

Config file can be placed directly outside the package folder, or inside the package folder.
\begin{minted}[frame=leftline,framesep=2mm,linenos]{php}
<?php
    namespace BinaryTreeVisualizer;
    class Config{
	public static $db_config = array(
	    'host' => "localhost",
	    'pass' => "123",
	    'name' => 'mlm_database',
	    'user' => 'root'
	);

    }
?>
\end{minted}

\subsubsection{Display the entire tree, The most basic use.}
\label{sec-2-4-2}
Assume 'btviz' is the name of the module folder, the following script will generate the entire html content, which includes <head> and <body> for you.

Simple example to Display the entire tree. 
\begin{minted}[frame=leftline,framesep=2mm,linenos]{php}
<?php
  include "btvis/src/BTVisualizer.php";
  use BinaryTreeVisualizer\QuickVisualizer as QuickVis;

  $qvis = new QuickVis();  

  //The root node will be 'SBC0' here, since we didn't set anything.
  echo $qvis->getVis()->getHTML();
?>
\end{minted}
In practice, we can fetch the necessary code for  <script>, <head> and <div> in form of string using the visualizer object. 

Note, in the example:
\begin{minted}[frame=leftline,framesep=2mm,linenos]{perl}
$qvis = new QuickVis();   //Abstraction layer
$vis  = $qvis->getVis();  //The actual visualizer object.
\end{minted}

QuickVisualizer class is an abstraction layer, which configures a default visualizer. The actual visualizer object is retrieved using the \emph{getVis()} method. More information about \emph{VisualizerInterface} can be found in the API documentation.

\subsection{Recommended Setup}
\label{sec-2-5}
\subsubsection{Basic API Access}
\label{sec-2-5-1}

\subsubsection{Using an existing PDO to connect to the database}
\label{sec-2-5-2}

\subsection{Tree Walking methods}
\label{sec-2-6}
Using the binary tree walker methods you can walk around the tree and execute your own code on specified nodes.
 The walker itself has 5 states:
\includegraphics[width=.9\linewidth]{images/walker_states.png}

For the programmer's purposes, the above diagram provides sufficient information on how the walker works.
\subsection{Tree Display Functions}
\label{sec-2-7}
The system by default, reads from the database and maps the data to a UserModel class (src/UserModel.class.php).  
\subsubsection{Change the label for the node.}
\label{sec-2-7-1}
\subsubsection{Change the colour and shape of the node.}
\label{sec-2-7-2}
\subsubsection{Use HTML View Helpers to customize what is being displayed.}
\label{sec-2-7-3}
\subsubsection{Use Views to customize what is bieng showed when hovered.}
\label{sec-2-7-4}
\subsubsection{Write actions to perform when clicked}
\label{sec-2-7-5}

\subsubsection{Styling and using fallback contents}
\label{sec-2-7-6}


\subsection{The User Repository Functions}
\label{sec-2-8}
\subsubsection{Getting the subtree for a specific user.}
\label{sec-2-8-1}
\begin{minted}[frame=leftline,framesep=2mm,linenos]{php}
<?php
  //include files 
  //...
  $userId = $_SESSION['id'];   //Assume that userId is stored in the  session.
  $repository = new UserRepository();
  $repository->getUser('')
?>
\end{minted}

Note: Storing the actual userId in the session, might not be the best idea. An unexpected change in the database (removal of the record, and insertion of a new record) may result in a user of a different access level gaining access to the session. 

\subsection{Database Functions}
\label{sec-2-9}
\subsubsection{Configuring database: Using non-default configurations}
\label{sec-2-9-1}

\subsection{Testing the Modules}
\label{sec-2-10}
On a Unix based system, open the test directory.
\begin{verbatim}
./runtests
\end{verbatim}
\subsection{Updating}
\label{sec-2-11}
\subsection{Error resolving.}
\label{sec-2-12}
\subsubsection{Produce the log files and e-mail it back to me.}
\label{sec-2-12-1}

\section{How the system works}
\label{sec-3}
The sub system was designed according to the requirements given.

Pre-req:
\begin{itemize}
\item The system requires following two tables to be present.
\item User table must be configured.
\end{itemize}

Early version:
The system does the following, once connected to the database.
\begin{enumerate}
\item All user records are read from the user table.
\item Binary tree mappings are created by reading the "person\_enrolled" table.
\item Binary tree nodes are created only for records present in the user table.
\item Binary tree is parsed into a readable markup format.
\item Readable markup format is read and processed by the Visualizer Code.
\item Visualizer Code uses a plugin to generate the vector image file.
\item Visualizer add meta data to be processed by the java script.
\end{enumerate}

V2.0:
The system does the following, once given database connection.
\begin{enumerate}
\item Pick an existing current user for the system to center at.
\item Find the tree and position id of that user.
\item Retrieve all user\_keys belonging to the tree.
\item Map the tree into the memory from the database. Store all the necessary datafields, to avoid multiple database queries.
\item Programmer can use the tree data structure, convert it into a markup language or into graph format. Any changes made cannot be committed.
\begin{enumerate}
\item Use the Tree data structure to visualize the tree.
\end{enumerate}
\end{enumerate}

System consists of two major parts.
\begin{enumerate}
\item Data handling system (The database layer and Repository Layer )
\item Visualization System
\end{enumerate}

The  visualization part of the code is responsible for generating required code and data to display the tree. 

The Database layer code is consists of classes which wraps around PHP's existing database system. It is used by the repository classes. The base Repository class uses database to manipulate database objects. It's subclasses should contain the table layout defined, to let the developer easily access specific Data Objects.

Finally, nodejs can be used in client side to either create a fully interactive html canvas using the graph or just display a static image.


\subsection{Create the Binary tree by reading the database}
\label{sec-3-1}
There are two possible ways to do this:
\subsubsection{Reading the user table recursively.}
\label{sec-3-1-1}

\includegraphics[width=.9\linewidth]{images/user_table.png}

Each user have an enroller\_id and enrolled id, which gives each record a single reference to it's parent. (The enroller)

Therefore it is possible to generate the index table (\emph{personally\_enrolled}), using the data from this table.

\subsubsection{Reading the personally enrolled table.}
\label{sec-3-1-2}

\subsection{Create an error logging system}
\label{sec-3-2}
Right now we are throwing out error message to the user view. We have to devise an error logging mechanism, and show user appropriate fallback content.

\subsubsection{Must have different levels of error.}
\label{sec-3-2-1}

\subsection{Helper HTML/String.}
\label{sec-3-3}
\subsubsection{Let the user insert data from the model into a string.}
\label{sec-3-3-1}

\subsection{Implement for callable/callback interface, for the user to process all graphs.}
\label{sec-3-4}


\section{Features to implement}
\label{sec-4}
\begin{itemize}
\item $\boxtimes$ Add an independent config file, and allow programmer to read config from that file.
\item $\square$ Allow programmer to configure database settings.
\item $\square$ Allow programmer to configure table layouts.
\item $\square$ Allow the programmer to select graphics engine.
\item $\square$ Allow designer to modify style and color.
\item $\square$ Add thumbnail to side.
\end{itemize}


\section{Note to the programmers}
\label{sec-5}
\begin{itemize}
\item Make sure the database is consistent; such that the information in the database is sufficient enough for this module to generate a valid binary tree.
\item To run the tests, its necessary to setup database configurations. Tests were done using a remote database, during the development.
\item You are not really locked down to use a specific graphics renderer. Infact, you can use any java script renderer to display the graph, on client side. All javascript writer will need is an accessible copy of the binary tree.
\item For better performance use this API to retrieve the Binary tree only, and use a third party library to display the tree on the client's browser. (ie, avoid graphics processing on server side.). Most JavaScript libraries are optimized to perform effectively in limited hardware.
\item It is also possible to scale, zoom, and view the tree, using some renderers.
\end{itemize}
% Emacs 24.4.1 (Org mode 8.2.10)
\end{document}