X

Technical Articles relating to Oracle Development Tools and Frameworks

  • JET
    February 6, 2017

JET Custom Components X - Custom Property Parsing

Duncan Mills
Architect

Introduction

In Part IV of this series, I discussed how the the underling JET Composite Component framework was capable of carrying out basic parsing tasks to manage the conversion of string values, supplied in the tag attribute, to the type defined in the custom component metadata. We saw how basic conversion can take place to both primitives, arrays and simple objects. In some cases, however, you may need to carry out a more sophisticated parsing task, maybe where the supplied object is missing defaults or a string needs formatting / conversion.

One way that you could achieve this by defining the attribute as a simple string and then managing the parse within your property processing. The framework, however, does provide a slightly more elegant approach by allowing your component to specify a custom parsing function. 

I'm sure that 99% of you will never need to use this capability, but just in case, here we go. 

Plugging in a Custom Property Parser

You specify the use of a custom parser as part of the register() function for the JET Custom Component. In the previous examples of the register() call we've seen how this looks in broad terms:

    oj.Composite.register('«tag name»',{«configuration properties»});

The custom parsing function is simply added as an additional property to the configuration properties argument (and is of course optional). So here's a version of the register call with the new configuration property parseFunction added:
Version prior to JET 5.0.0

    oj.Composite.register('ccdemo-name-badge',
    {
      metadata: {inline: JSON.parse(metadata)},
      viewModel: {inline: ComponentModel},
      view: {inline: view},
      parseFunction:customParseFunction
    });
Version in JET 5.0.0 or above where the register call is a little simpler
    oj.Composite.register('ccdemo-name-badge',
    {
      metadata: JSON.parse(metadata),
      viewModel:ComponentModel,
      view: view
      parseFunction:customParseFunction
    });

So in this case I've added the name of a function to do the parsing - customParseFunction. This function can be placed anywhere that is accessible in / from the loader script. If it is simple enough you can also define the function anonymously inline:

    oj.Composite.register('ccdemo-name-badge',
    {
      …
      parseFunction: function(value, name, meta, defaultParseFunction){
        …
      })
    });

Once defined, this parsing function will be called for every tag attribute that is being passed to the component, except for those bound to observables/variables through {{...}} and [[...]] which bypass this parsing all together.

Defining a Custom Parse Function

The custom property parse function takes four parameters:

  1. value - the string value supplied for the tag attribute being processed
  2. name - the name of the property (not the mapped tag attribute,) being processed
  3. meta - the metadata definition for the property that is being processed. This gives you access to information such as type, the default value and any extension metadata
  4. defaultParseFunction - a handle to the default framework parsing function, so that you can pass-though properties that you don't have any special processing for.

As an example let's imagine that I have a custom component that allows the user to specify a range for a metering component based on a start month, (with the end date being the current date):

    {
      "properties" : {
        "fromMonth" : {
          "description" : "Start of display range",
          "type" : "date"
        },
        "utility" : {
          "description" : "gas | electricity",
          "type" : "string"
        }
      }
    }

Used thus:

    <ccdemo-meter-display from-month="10" utility="gas">

Internally I want to convert the numerical value for from-month into a date object. Here's what the parse function might look like:

    function (value, name, meta, defaultParseFunction) {
      if (name === 'fromMonth'){
        var year = new Date().getFullYear();
        return new Date(year,value-1,1);
      }
      else {
        //Pass through to the default processing
        return defaultParseFunction(value);
      }
    }

Note how I use the name argument of the function to decide if special processing is needed for this property, or if the default conversion routine should be used via defaultParseFunction. You could also use some of the other information provided to the function to manage this process, for example the metadata injected through the meta parameter.

The value returned by the custom function is assigned to the relevant property and will then be made available via the properties context to the component. This property parsing takes place in the lifecycle before the viewModel instance is created.

What's Next?

In the next couple of articles I'll be examining some advanced topics, the extension of custom component metadata.


JET Custom Component Series

If you've just arrived at Custom JET components and would like to learn more, then you can access the whole series of articles on the topic from the Custom JET Component Learning Path

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha