In this entry we are going to look at a new custom field, an HTML editor field, and instead of the broad overview that we did with the Masked Input field we are going to focus on one of the two parts that make up a custom field. Again, the source code for this project is at the bottom of this post. In this case we are going to focus on the code that actually draws the field on the view (Editiew, DetailView and so on). The HTML Editor (SugarCRM Uses a Javascript library called TinyMCE for it’s HTML editor) is a complex field to render and it really uses the template part of the custom field to it’s fullest, so it will be a great example. Now I am sure there are several ways to code this and mine might not be the very best, but it works and it’s small so it’s good enough in my book.
So this custom field follows Masked Input in format, it has all the same files but we are going to look at only 5 of them in this post.
custom/include/SugarFields/Fields/Htmleditor/EditView.tpl
custom/include/SugarFields/Fields/Htmleditor/WirelessEditView.tpl
custom/include/SugarFields/Fields/Htmleditor/WirelessDetailView.tpl
custom/include/SugarFields/Fields/Htmleditor/SugarFieldHtmleditor.php
custom/include/SugarFields/Fields/Htmleditor/DetailView.tpl
These five files are responsible for putting each instance of the HTML Editor on the view. These files are ONLY run when the cached TPL file needs to be created NOT every time the view is drawn. So if you run a Quick Repair and Rebuild, the next time a view with an HTML Editor field on it is drawn these files will be run to create the cached TPL file. This, of course, would change if you are in Developer Mode. In Addition to all of that, it is possible that there would be more than 5 files here as there were for the Masked Input field, but you really only need to define the views where your field would differ from the stock presentation. So, lets start with SugarFieldHtmleditor.php. This is the file that calls the appropiate TPL when it is time to render the field onto the cached TPL.
SugarFieldHtmleditor.php
OK, first notice the capitolization on the class name, it is required that you follow the standard for naming your field as stated in the Developers guide. The first two functions in the class, “getDetailViewSmarty” and “getEditViewSmarty” are called to create the field on the appropriate view’s TPL. For the DetailView I just used the standard code as I don’t really need to reformat anything. You cannot reformat the value here as this function will only get run once to create the cached TPL file, once that TPL file is created this function is not called again. So I reformat the HTML in the actual DetailView.tpl file. We will examine that later. For the Editiew I customized the code to create the instance of the TimeMCE editor. I load and instantiate the class “SugarTimeMCE()” (the SuagrCRM loader file for the TimeMCE class), then feed it some parameters like size and a unique ID so that mutliple HTML Editors can exist on the page. Then, with the “$tinyMCE->getInstance($id);” command I get the JavaScript that will initialize the TinyMCE editor on the View. From there I add the TinyMCE code to the $vardef array and set it all off to the parser in the Setup function. We will see how this data gets onto the View in the next section.
The next function “getVardefValue()” simply returns a value to display in this field. If there is not data in the field then it adds the default. Now in this field there is no default value so really this function is unneeded but I always include it anyway.
The last function is the “save()” function. This function gets called when a EditView is submitted for saving. In this code I run the HTML that was typed into the HTMP Editor through a few scrubbing routines before it is sent off to the database. The first function is $tinyMCE->cleanEncodedMCEHtml() and this just removes any TinyMCE code from the HTML. The second function is $purifier->purify() which is a 3rd party standards-compliant HTML filter library. It filters out most malicious code (better known as XSS) and reformats the code to be standards compliant. Not really 100% needed, but it shows how you can process the input from the editview and affect changes before it gets committed to the database. Maybe you could do some math here or alter the contents of another field based on whats in this one. It can be a very powerful function for creating custom fields that do more than just accept data from the EditView and shove it into the database.
So in this file we see the two $vardef’s we added in the SugarFieldHtmleditor.php file. The variables “TinyID” and “tinyMCE” are rendered onto this view by placing them in double curly braces. I believe this is part of a two pass conversion that goes on in the Smarty template system. The first pass converts these to actual PHP variable names and the second pass converts them to the values of those variables. This contrasts with the single curly brace variables like {$vals}. These represent actual smarty values that were assigned before the templating began. If you are anything like me you will spend alot of time figuring out how to render a value by trial and error. Another thing you might notice are the {literal} tags. Since $vardef.tinyMCE actually contains a JavaScript like this
<script type="text/javascript" language="Javascript">
tinyMCE.init({"convert_urls":false,"height":"500","width":"50%","theme":"advanced","theme_advanced_toolbar_align":...
</script>
-
and since that code contains curly braces you have to put {literal} tags around it so that smarty won’t try to compile it. Anyway, our TinyMCE code that we got in SugarFieldHtmleditor.php replaces the TEXTAREA we have in the editview.tpl file. Thats why on some systems you will see the TEXTAREA for a second or two before the TinyMCE comes up. Now for the WirelessEditView.tpl we just render a TEXTAREA. I’m not sure what a WAP browser is going to do with the HTML,so it might be a better idea to make the text non-editable in a WAP browser by putting the HTML in a hidden field and rendering it in a DIV or just straight on the screen. That would be your call.
detailview.tpl
This is the detailview.tpl file. What I am doing here is rendering the HTML in a scrollable DIV. That way if there is alot of HTML to render it doesnt make the page 4 miles long. It renders in a window that is the same size as the TinyMCE window and puts a scroll bar on the right hand side. For the WirelessDetailView.tpl we do the same thing without the DIV.
I have 2 or 3 other fields I am going to blog about, but if you have any other ideas on fields you would like to see just go to the SugarCRM forums and look for this post and add your comments to it.
I have made my source code for this custom field available as a loadable module here.
and I love it. It runs great in Linux using a program called 
I just added a