Diferencias

Muestra las diferencias entre dos versiones de la página.

Enlace a la vista de comparación

es:vtapps_guide [2013/05/14 13:47] (actual)
joebordes creado
Línea 1: Línea 1:
 +====== vtigerCRM-Spain:: vtApps ======
 +
 +===== Installation =====
 +  - Install module using module manager
 +  - Apply patch to get necessary code changes:<code>patch -p 0 < modules/evvtApps/evvtApps.diff</code>
 +  - Translate to any localized version not supported and send me the file (please)
 +
 +**Note:** For installing vtApps see below the section [[vtapps#vtapps_shop|vtApps Shop. Install and update]].
 +
 +==== Infrastructure and goals ====
 +
 +The intention of the vtApps extension is to make it easy for developers to create small tools, informative dashboards and similar applications that tap into the information and power of vtiger CRM without having to go through all the hassle of new vtlib modules. At the same time we strive to create an environment where these simple apps can live and work together.
 +
 +We have developed this framework based on jquery and on the [[http://kendoui.com|kendoui toolkit]], so all vtApps directly inherit this infrastructure and can use any part of it in their solutions, but all vtApps live inside vtiger CRM and have full access to all the information that the application has and also to all the code and tools vtiger CRM gives us.
 +
 +Our ultimate goal is to completely substitute the current dashboard with equivalent vtApps to the boxes we have now, and add a full set of new services and information vtApps that will grow inside the vtApps framework.
 +
 +==== Hello World vtApp ====
 +
 +Let's create our first vtApp. The functionality will be simply to open the vtApp window and print out the text "Hello World!". This example will teach us the fundamentals of how to prepare our vtApp for distribution.
 +
 +The vtApp extension comes prepared with a template vtApp that has the minimum functionality and structure required to start creating our required functionality. This template vtApp can be found in the extension's directory:
 +
 +<code>modules/evvtApps/vtapps/templateapp</code>
 +
 +The steps to create our first vtApp are:
 +  - Copy the whole modules/evvtApps/vtapps/templateapp to a temporary directory <code>cp -a templateapp demoapp</code>
 +  - Edit the vtapp.php script and change the name of the class. Change the class name on line 11 <code>class vtApptldCompanyAppName extends vtApp {</code>As the default name encourages, we recommend you use the prefix "vtApp", followed by the Top Level Domain of your company, then you company name and finally the name of the vtApp. For example, the vtApps from TSolucio.com have these names: "vtAppcomTSolucioConfiguration", "vtAppcomTSolucioDemoGraph1".
 +  - zip the directory of the vtApp, starting at the top, where the vtApp.php file is and name it the same as your class, the same name you used in the previous step. This is specially important for importing.
 +  - That is all you need to do to have a new vtApp with no functionality. Upload this zip file to the vtApps extension through the vtApp Shop and you should have a default vtApp prepared for you to start working on.
 +
 +Once the vtApp is installed we can start editing it and adding functionality. If we go to the vtApps extension after installing the zipped file we will see a new icon with the vtEvolutivo logo. A click on the icon will open a window with the default text. Our new vtApp has been assigned an internal appid, you can easily find the appid of the new vtApp by looking in the vtiger_evvtapps database table, or simply going to the directory with the highest number, as that will be the last one installed. Now we edit the three files contained in the template vtApp:
 +  * vtapp.php: We can see some of the window settings variables that can be established and our first method "**getContents**", this is the method called when the window is opened, resized and refreshed. This is where we will add the look and feel of our vtApp, for now we will simply delete the text "This is the default template widget" and put in our Hello World! like this: <code>return 'Hello World!';</code> and now press the refresh button on the window title bar or close and open the window to see our Hello World! vtApp.
 +  * language/en_us.lang.php: you can see that the title of the window still reflects the template that the vtApp comes from as does the hover tooltip text of the vtApp icon on the canvas. To change this we must edit the language file and adapt the text variables to the desired values. Now is the time to create and translate any other language files that need to be supported. The language file prefixes are the exact same ones supported by vtiger CRM.
 +  * icon.png: you should generate an image for your vtApp, the image should be a png of size 64x64 pixels
 +
 +For our clients to get these new features all we have to do is zip the vtApp from the it's root directory and use the vtApp Shop to upgrade the code.
 +
 +==== Click me vtApp ====
 +
 +Let's add some functionality to our vtApp, We will add the icon image of the vtApp inside the window and then enable the click on the image to change the underlying image in our vtApp.
 +
 +First we will add the icon image by changing the **getContents** method with the following code:
 +
 +<code>
 +$about.= '<img src="'.$this->getAppIcon().'" style="float:left"><br/>';
 +return $about;
 +</code>
 +
 +as can be seen we are basically doing the same as in the previous example, just that in this case we are adding HTML mixed with php vtApp variables.
 +
 +Next we will add some javascript to detect the onclick event of the image and launch a function that uses our [[http://crmevolutivo.com/wiki/doku.php?id=vtapps&#vtapp_javascript_reference|vtApp javascript helper functions]] to change the underlying icon image accordingly.
 +
 +<code>
 +$about = '<script language="javascript">function vtappdemoChgIcon() { var current_image=vtAppGetIcon('.$this->appid.');';
 +$about.= 'if (current_image=="'.$this->apppath.'/evolutivo.png") next_image="icon.png"; else next_image="evolutivo.png";';
 +$about.= 'vtAppChangeIcon('.$this->appid.",'".$this->apppath."/'+next_image);}";
 +$about.= '</script>';
 +$about.= '<img src="'.$this->getAppIcon().'" style="float:left" onclick="vtappdemoChgIcon()"><br/>';
 +return $about;
 +</code>
 +
 +==== vtiger CRM. Smarty templates ====
 +
 +The hard part of doing what we just did in the previous example is balancing all the quotes between javascript world and php world. It would be ideal if we could use some templating system to help us do this type of coding. vtiger CRM to the rescue!!
 +
 +The goal of creating vtApps is to easily have access to vtiger CRM information and infrastructure, and we have accomplished that. Inside the vtApp we have full access to all of vtiger CRM functionality and information. That means that we can use the predefined and already configured Smarty templating engine. All we have to do is invoke the Smarty class, point it to our vtApp's directory and load the template. To get the previous example working with a Smarty template we would use this code.
 +
 +<code>
 +public function getContent($lang) {
 + global $adb,$current_language,$current_user;
 + $smarty = new vtigerCRM_Smarty;
 + $smarty->template_dir = $this->apppath;
 + $smarty->assign('appId',$this->appid);
 + $smarty->assign('appPath',$this->apppath);
 + $smarty->assign('appIcon',$this->getAppIcon());
 + return $smarty->fetch('demo.tpl');
 +}
 +</code>
 +
 +then we would create our demo.tpl Smarty template file INSIDE our vtApp directory with this contents:
 +
 +<code>
 +<script language="javascript">
 +var appid={$appId};
 +var apppath='{$appPath}';
 +{literal}
 +function vtappdemoChgIcon() {
 + var current_image=vtAppGetIcon(appid);
 + if (current_image==apppath+"/evolutivo.png")
 + next_image="icon.png";
 + else
 + next_image="evolutivo.png";
 + vtAppChangeIcon(appid,apppath+'/'+next_image);
 +}
 +{/literal}
 +</script>';
 +<img src="{$appIcon}" style="float:left" onclick="vtappdemoChgIcon()"><br/>';
 +</code>
 +
 +which is obviously much easier to read and debug
 +
 +==== Edit Screen ====
 +
 +Let's add a simple edit screen to our demo vtApp. This edit screen will simply contain a close button that will close the window and refresh the vtApp content.
 +
 +First we will add a dynamic component to our current demo vtApp so that when it gets refreshed we will notice the change. To do this I will simply add the current time to the contents output.
 +
 +<code>
 +$about = '<script language="javascript">function vtappdemoChgIcon() { var current_image=vtAppGetIcon('.$this->appid.');';
 +$about.= 'if (current_image=="'.$this->apppath.'/evolutivo.png") next_image="icon.png"; else next_image="evolutivo.png";';
 +$about.= 'vtAppChangeIcon('.$this->appid.",'".$this->apppath."/'+next_image);}";
 +$about.= '</script>';
 +$about.= '<img src="'.$this->getAppIcon().'" style="float:left" onclick="vtappdemoChgIcon()"><br/>';
 +$about.= date('H:i:s').'<br/>';
 +return $about;
 +</code>
 +
 +Now we create contents for our edit screen inside the **getEdit()** method.
 +
 +<code>
 +public function getEdit($lang) {
 + $editwindow='<br><b>Close me to see my main window refresh!</b><br><br>';
 + $editwindow.='<p align=center><input type=button onclick="$(\'#vtappedit'.$this->appid.'\').data(\'kendoWindow\').close()" value="Close"></p>';
 + return $editwindow;
 +}
 +</code>
 +
 +==== Canvas Javascript ====
 +
 +This next example uses the **getCanvasJavascript** method to change the vtApp's icon every 5 seconds. As explained below the goal of this method is to permit the execution of code in the canvas, without having to open the vtApp's window. This can be used to manually open the window on some given event or do some other type of notification.
 +
 +Add this code to our demo vtApp and reload the whole vtApp Canvas.
 +<code>
 +public function getCanvasJavascript($lang) {
 + $output = 'function vtappdemoCanvasChgIcon() { var current_image=vtAppGetIcon('.$this->appid.');';
 + $output.= 'if (current_image=="'.$this->apppath.'/evolutivo.png") next_image="icon.png"; else next_image="evolutivo.png";';
 + $output.= 'vtAppChangeIcon('.$this->appid.",'".$this->apppath."/'+next_image);setTimeout('vtappdemoCanvasChgIcon()',5000);}";
 + $output.= 'setTimeout("vtappdemoCanvasChgIcon()",5000);';
 + return $output;
 +}
 +</code>
 +
 +==== vtiger CRM. Accessing information ====
 +
 +This example will access the vtiger CRM account table and retrieve 10 accounts and list them in the window. As already said we have full access to all of vtiger CRM functionality in our vtApps so this is a relatively easy exercise.
 +
 +<code>
 +public function getContent($lang) {
 + global $adb,$current_language,$current_user;
 + $output='<table width="100%" border=1><th>Accounts</th>';
 + $accounts=$adb->query('select accountid from vtiger_account limit 10');
 + while ($account=$adb->fetch_array($accounts)) {
 + $acc=getEntityName('Accounts', $account['accountid']);
 + $output.='<tr><td>'.$acc[$account['accountid']].'</td></tr>';
 + }
 + $output.="</table>";
 + return $output;
 +}
 +</code>
 +
 +
 +==== Next step ====
 +
 +Now it is all up to your imagination, show me where vtApps can be taken.
 +
 +**Happy vtApping!!!**
 +
 +===== vtApps Reference for Developers =====
 +
 +[[vtapps_reference|vtApps Reference for Developers]]
 +
 +===== Todo list =====
 +  * App Store. Search and Install vtApps
 +  * Idea: when dropping vtApp on trash can, mark it as deleted. Then click on trash to open a window with all vtApps marked deleted and permit recovering of a vtApp or definitely eliminating it.
 +
 +===== Disclaimer =====
 +
 +vtApps does not pretend to be a secure environment, we do not impose any restrictions on the vtApps possibilities, just as anyone can send you a vtiger CRM module that you can install in your vtiger CRM and have it do anything to your information, also a vtApp has full access to all the information contained inside your vtiger CRM and the vtApp can do anything with it. Although we will strive to evaluate and respond to all suspicious code conducts we probably won't have time to go through all the code of all the vtApps, so the full responsibility of the acts of any vtApp is beyond our control. You will install vtApps at your own risk.