Alfresco: Defining new Control-Params

Question

I am working on a custom form control, and need to define a new control-parameter of type string called helptext. I understand how to call it in my share-config-custom, how to use it in my custom form control, but not how to initially declare it.

I see other control-params use the format field.control.params.${param}, but cannot locate where any of these are defined. A file search for existing control-params returns dozens of files.

Where and how do I declare control-params before using them?

Edit: After receiving some good answers, I'm still getting the same error. Here are my code excerpts below:

share-config-custom

<set appearance="title" label-id="Opportunity Registration Form" id="info"/>
<field set="info" label-id="Program Name" id="orpWorkflow:programName">
  <control template="/org/alfresco/components/form/controls/textfieldcustom.ftl">
    <control-param name="helptext">"Help text goes here."</control-param>
  </control>
</field>

textfieldcustom.ftl

<div class="form-field">
   <#if form.mode == "view">
      <div class="viewmode-field">
         <#if field.mandatory && !(field.value?is_number) && field.value == "">
            <span class="incomplete-warning"><img src="${url.context}/res/components/form/images/warning-16.png" title="${msg("form.field.incomplete")}" /><span>
         </#if>
         <span class="viewmode-label">${field.label?html}:</span>
         <#if field.control.params.activateLinks?? && field.control.params.activateLinks == "true">
            <#assign fieldValue=field.value?html?replace("((http|ftp|https):\\/\\/[\\w\\-_]+(\\.[\\w\\-_]+)+([\\w\\-\\.,@?\\^=%&:\\/~\\+#]*[\\w\\-\\@?\\^=%&\\/~\\+#])?)", "<a href=\"$1\" target=\"_blank\">$1</a>", "r")>
         <#else>
            <#if field.value?is_number>
               <#assign fieldValue=field.value?c>
            <#else>
               <#assign fieldValue=field.value?html>
            </#if>
         </#if>
         <span class="viewmode-value"><#if fieldValue == "">${msg("form.control.novalue")}<#else>${fieldValue}</#if></span>
      </div>
   <#else>
      <label for="${fieldHtmlId}">${field.label?html}:<#if field.mandatory><span class="mandatory-indicator">${msg("form.required.fields.marker")}</span></#if></label>
      <input id="${fieldHtmlId}" name="${field.name}" tabindex="0"
             <#if field.control.params.password??>type="password"<#else>type="text"</#if>
             <#if field.control.params.styleClass??>class="${field.control.params.styleClass}"</#if>
             <#if field.control.params.style??>style="${field.control.params.style}"</#if>
             <#if field.value?is_number>value="${field.value?c}"<#else>value="${field.value?html}"</#if>
             <#if field.description??>title="${field.description}"</#if>
             <#if field.control.params.maxLength??>maxlength="${field.control.params.maxLength}"</#if> 
             <#if field.control.params.size??>size="${field.control.params.size}"</#if> 
             <#if field.disabled && !(field.control.params.forceEditable?? && field.control.params.forceEditable == "true")>disabled="true"</#if> />
      <@formLib.renderFieldHelp field=field />
   <script type="text/javascript">//<![CDATA[
      (function()
      {
         new Alfresco.CustomYUIObject("${fieldHtmlId}").setOptions(
         {
            helpText:"${helpText}"
         }).setMessages(
            ${messages}
         );
      })();
      //]]></script>
   <div class="format-info">
            <span class="date-format">${msg("${field.control.params.helpText}")}</span>
      </div>
   </#if>
</div>

The error message

Caused by: freemarker.core.InvalidReferenceException: The following has evaluated to null or missing:
==> helpText  [in template "org/alfresco/components/form/controls/textfieldcustom.ftl" at line 36, column 25]

Answer 1

The variable which you are passing is defined in FTL file,which(FTL file) is referenced from share-config-custom.xml. Lets have deeper look.

share-config-custom.xml
Here Where we are declaring control parameter.

 <field-visibility>
             <show id="fieldName"/>
 </field-visibility>
 <appearance>
     <field id="fieldName" label="Name of Field">
            <control template="/path/to/ftl/textarea.ftl" />    
                <control-param name="helpText">Description of field</control-param>
            </control>
     </field>

 </appearance>

your-custom-templete.ftl
This is the location where your parameter first comes

<script type="text/javascript">//<![CDATA[
      (function()
      {
         new Alfresco.CustomYUIObject("${fieldHtmlId}").setOptions(
         {
            helpTest:"${field.control.params['helpText']}",
         }).setMessages(
            ${messages}
         );
      })();
      //]]></script>

CustomYUIObject.js
Its the place when you can do something with javascript on component.

(function() {
    var Dom = YAHOO.util.Dom, Event = YAHOO.util.Event;
    var $html = Alfresco.util.encodeHTML;
    Alfresco.CustomYUIObject = function ExportDMSD_constructor(htmlId) {
        Alfresco.CustomYUIObject.superclass.constructor.call(this,
                "Alfresco.CustomYUIObject", htmlId, [ "button", "container",
                        "datasource", "datatable", "paginator", "history",
                        "animation" ]);
        return this;
    };
    YAHOO.extend(Alfresco.CustomYUIObject, Alfresco.component.Base);
    YAHOO.lang.augmentObject(Alfresco.CustomYUIObject.prototype, {
        options : {
         helpText:null
        },
        onReady : function ExportDMSD_onReady() {
            console.log(this.options.helpText);//Its the javascript place where you can access yout variable,register and event and do javascript things
        }
    });
})();

Answer 2

This is how control parameter flow goes. For each type of form controls there are supported FTL file avilable in Alfresco.You can find all of them here.

<ALF_HOME>\tomcat\webapps\share\WEB-INF\classes\alfresco\site-webscripts\org\alfresco\components\form\controls

For Instance. Form item of data type data is handled by date.ftl.

• Create new field processor FTL (ex. customDate.ftl).

• Defined custom parameter in your custom field processer in the share-config-custom.xml for the field which you want to process using new processor.

• Handle that parameter in your FTL(customDate.ftl) file.