Support (800) 775-8378 Contact Us

    SugarCRM Tutorial: How to Create a Re-Usable SugarField

    By Ionut Tonita • February 1st, 2013
    Audiences: Developers

    SugarFields are methods to store and display data in a SugarCRM system.  For instance SugarCRM comes standard with a wide variety of data field types such as text boxes, integers, checkboxes, picture fields, date and time fields, web links and many more.  While this covers most usage scenarios, once in a while we receive the request to store or display data fields that behave differently than these standard fields.  SugarCRM provides a way to add any such field types to a Sugar system but it will require a little PHP code to do it.

    There are a bunch of tutorials available on the web that demonstrate the creation of custom SugarFields that change an already existing database field and then use that SugarField as a List/Edit/Detail view template via the vardefs.php file.

    While these are useful tutorials, we’ve noticed that there is a distinct lack of information on how to create a reusable SugarField. A reusable field means we are adding a new field type to SugarCRM that any SugarCRM administrator can add to any module form using Sugar Studio tools.

    This tutorial will show you how you can create a proof-of-concept SugarCRM Studio enabled AutoIncrement SugarField.  This field will be an integer type field that automatically increments by a number each type a record is created in SugarCRM.  For instance you may want to create a field that adds auto increments a new customer number each time you add a customer record to SugarCRM.

    The base module, which deals with rendering the SugarField template and controlling its behavior in Studio is, called DynamicFields. In our case, we’re interested in creating a template for adding (or editing) the field, so, we’ll need to create a couple of new files under the path:

    custom/modules/DynamicFields/templates/Fields/

    so let’s add the following files:

    custom/modules/DynamicFields/templates/Fields/TemplateAutoincrement.php

    custom/modules/DynamicFields/templates/Fields/Forms/autoincrement.php

    custom/modules/DynamicFields/templates/Fields/Forms/autoincrement.tpl

    The TemplateAutoincrement.php file deals with the SugarField definition, while the other two render the file inside the module editor. The contents of the file should look something like this:

     

     

    ...and the template file, autoincrement.tpl

     

     

    Note that we are extending our field from the TemplateText base class, which we then modify to suit our needs. We are wrapping the custom extension fields ext1 and ext2 with the purpose of storing the start value and the incrementation value for the field. We are also modifying the database type of the field to be int.

    Let’s go about modifying the other two files as well, first: autoincrement.php

     

     

    The php file is responsible for setting the properties of the template, generating the combobox items, and lastly, rendering the template file itself. Field validation is important and we’re using the native SugarCRM function addToValidateMoreThan to make sure that the user is not allowed to input erroneous data.

    There’s one more step into making this field available in the Studio though, and that is adding it to the Language dictionary that populates the ComboBox which allows you to select it. We do that by creating the following file:

    custom/Extension/modules/ModuleBuilder/Ext/Language/en_us.FieldAutoIncrement.php and put in the following:

     

     

    Good! Now we’re almost done. If you do a Quick Repair&Rebuild the field should be fully functional in Studio, but what about after we add it to a module view?  We haven’t actually created the functional field template yet, so we’ll do it now, by creating the following files in the path:  custom/include/SugarFields/Fields/Autoincrement/

    SugarFieldAutoincrement.php – Is the most important file. Besides handling the fetching of rendered views, it also handles the saving of the field, which we will need to customize in order to auto-generate the incremented value. It should look something like this:

     

     

    EditView.tpl, DetailView.tpl, ListView.tpl – considering this is an auto-generated value, these should all be read-only views, so a simple content like {{sugarvar key='value'}} should suffice.

    SearchView.tpl – this is where the templating gets a bit more complex, as we’ll need to support searching, so we need to create a view for it as well. This should contain something like the following markup:

     

     

    The content is mostly copied from the text field EditView template. 

    And voilà! We now have a fully functional, reusable SugarField, which we can package with a simple manifest file and then deploy it on SugarCRM systems in a straightforward manner. 

    More From This Author
    Ionut Tonita
    Development Practice Manager at UpCurve Cloud