You are here: Designing an Application > Working with Components, Kony Marketplace, and Masters

Working with Components, Kony Marketplace, and Masters

In Kony Visualizer version 7.2 and earlier, masters helped streamline mobile application developing by letting you define multiple user interface elements and action sequences as a single entity. In Kony Visualizer version 7.3, components go one step further by letting you extend that ability beyond your application to the Kony Marketplace. You can create components that can be used in other applications, or use third party components in your applications. If you have created masters in previous versions of Kony Visualizer, you can import them into Kony Visualizer version 7.3.

Note: Components are a beta feature of Kony Visualizer version 7.3.

Like masters, components may be nested within the following widgets:

The following topics describe how to create and work with components, Kony Marketplace, and masters:

Import a Component or Master

Create a Component

Manage Properties, Events, and Methods of a Component with a Contract

Add a Component to a Library

Using a Component in a Project

Control the Cascading of Changes from a Component to Its Instances

Reset the Values in a Component Instance

Use the Segment2 Widget in a Component

Move the Templates Tab

Duplicate a Component

Delete a Component

Import a Component or Master

You can simplify and speed up development of mobile applications by using existing components. You can download a variety of components from Kony Marketplace and import them into your projects, or import reusable components that you have created yourself. For information on creating a component, see Create a Component.

You can also add a master created in Kony Visualizer version 7.2 and earlier to your project by importing the project containing the master into your project. You can continue to use it in your application as a master, or make it available as a reusable component that can be published to Kony Marketplace by converting it to a component with a contract. A master is the equivalent of a component without a contract in Kony Visualizer version 7.3.

To download a component from Kony Marketplace (Beta):

  1. Navigate to the Kony Marketplace web site in your web browser.
  2. Select the component you want to download, and then click the Download button. Click Save to download the component to the default download location on your computer, or Save As to download it to a different location.

To import a downloaded component into your project (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Hover over Components, click its context menu arrow, and then select Import Component. Kony Visualizer displays the Import Component dialog box.
  3. Click Browse to navigate to the location of the component, select the component, and then click Open. Kony Visualizer adds the component to your project.

To import a master:

  1. On the File menu, hover over Import, and then select Masters.
  2. Click Browse to navigate to the location of the master, select the master, and then click Open. Kony Visualizer adds the master to the Masters node on the Templates tab in Project Explorer. If a Masters node does not exist, Kony Visualizer creates one.

Create a Component

The key to creating reusable components that can be published to Kony Marketplace is to create a component that includes a defined contract. The contract is a JSON file that species the component's exposed properties, methods, and events. You can specify those properties, methods, and events within the Visualizer interface, or by adding code to the component's controller module.

When you create a component, you have a choice of creating a component with or without a contract. A component without a contract is the functional equivalent of a master in Kony Visualizer versions 7.2 and earlier. You can also convert a component that does not have a contract, or an imported master, to a component with a contract.

To create a reusable component that can be published to Kony Marketplace, create a component with a contract. Components with a contract use the Kony Reference Architecture, a structured, modular framework based on the Model-View-Controller (MVC) architecture.

For information on managing a component's properties, methods, and events, see Managing Component Properties, Methods, and Events. For information on creating a Kony Reference Architecture project, see Create a Kony Reference Architecture Project.

To create a component without a contract (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Hover over Components, click its context menu arrow, hover over New, and then select w/o Contract.
  3. Kony Visualizer displays the Create New Component without Contract dialog box.

  4. Enter a namespace and name for the component.
  5. The namespace should follow the naming convention <first part>.<second part>; for example, my.namespace.

    Kony Visualizer creates a new component, including a FlexContainer to contain any widgets that you add to the component, and a Modules node containing the component's controller and actions controller JavaScript modules. The actions controller module is autogenerated and contains any defined action sequences.

  6. Add widgets to the flex container just as you would on a standard form.
  7. Add code to the component's controller module, or to actions for widgets on the form. To add code to widget actions, select the flex container, then on the Properties pane, on the Action tab, click the Edit button of the event to which you want to add code. For more information, see Add Actions.

To create a component with a contract (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Hover over Components, click its context menu arrow, hover over New, and then select with Contract.
  3. Kony Visualizer displays the Create New Component with Contract dialog box.

  4. Enter a namespace and name for the component
  5. The namespace should follow the naming convention <first part>.<second part>; for example, my.namespace.

    Kony Visualizer creates a new component, including a FlexContainer to contain any widgets that you add to the component, and a Modules node containing the component's controller and actions controller JavaScript modules. The actions controller module is autogenerated and contains any defined action sequences.

  6. Add widgets to the flex container just as you would on a standard form.
  7. Add code to the component's controller module, or to actions for widgets on the form. To add code to widget actions, select the flex container, then on the Properties pane, on the Action tab, click the Edit button of the event to which you want to add code. For more information, see Add Actions.
  8. Manage properties, events, and methods for the contract component. For more information, see Managing Contract Component Properties, Methods, and Events.

Each component's controller module contains the JavaScript code associated with the component.  You can add additional modules containing any supporting code to the Modules node. The actions controller module is auto-generated and should not be modified. A component creator can also use Mobile Fabric services as part of the component.

Manage Properties, Events, and Methods of a Component with a Contract

If you create a component with a contract, you can control what is exposed to users of the component by managing the component's properties, events, and methods. You can expose only the properties, events, and methods that you want to make available to your target audience, enhancing your ability to rapidly create and deploy mobile applications for different audiences. The exposed properties, events, and methods are part of the contract. You can then use the component in other applications, and make the component available in Kony Marketplace.

You can specify which existing properties, events, and methods of the component that you want to expose by defining pass through properties, events, and methods. You can also define custom properties, events, and methods.

To manage properties of a component with a contract (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Expand the components node, if necessary, and then select the component.
  3. In the Properties pane, click the Component tab.
  4. Click Manage Properties. Kony Visualizer displays the Manage Properties dialog box.
  5. To define pass through properties, select the Pass Through tab on the Manage Properties dialog box.
  6. Click the plus sign (+) for each pass through property you want to define. Click the delete symbol (X) to delete an existing property. To define a new pass through property, specify the following for each property:

    Click Apply to add the pass through property. Kony Visualizer adds the property to the Pass Through section of the Properties pane's Component tab.

    Note: You can also designate a widget's property as a pass through property by navigating to the widget and right-clicking on the property name.

  7. To define custom properties, select the Custom tab on the Manage Properties dialog box.
  8. Click the plus sign (+) for each custom property you want to define. Click the delete symbol (X) to delete an existing property. To define a new custom property, specify the following for each property:

    Click Apply to add the custom property. Kony Visualizer adds the property to the Custom section of the Properties pane's Component tab.

    Important: Unlike a pass-through property, which is based on an existing property of the component, a custom property has no built-in behavior. You must define the property's behavior programmatically. On the Templates tab, expand the component's Modules node, open the controller module, and add code defining the property's behavior to the controller code. For more information, see Defining the Behavior of a Custom Property, Event, or Method in Code.

To manage events of a component with a contract (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Expand the components node, if necessary, and then select the component.
  3. In the Properties pane, click the Action tab.
  4. Click Manage Events. Kony Visualizer displays the Manage Events dialog box.
  5. To define pass through events, select the Pass Through tab on the Manage Events dialog box.
  6. Click the plus sign (+) for each pass through event you want to define. To delete an existing event, select the event and click the delete symbol (X). To define a new pass through event, specify the following for each event:

    Click Apply to add the pass through event. Kony Visualizer adds the event to the Pass Through section of the Properties pane's Action tab.

    Note: You can also designate a widget's event as a pass through event by navigating to the widget and right-clicking on the event name.

  7. To define custom events, select the Custom tab on the Manage Events dialog box.
  8. Click the plus sign (+) for each custom event you want to define. Click the delete symbol (X) to delete an existing event. To define a new custom event, specify the following for each event:

    To add parameters to the custom event, click the Manage Events button and specify the parameter information in the dialog box.

    Click Apply to add the custom event. Kony Visualizer adds the event to the Custom section of the Properties pane's Action tab.

    Important: Unlike a pass-through event, which is based on an existing event of the component, a custom event has no built-in behavior. You must define the event's behavior programmatically. On the Templates tab, expand the component's Modules node, open the controller module, and add code defining the event's behavior to the controller code. For more information, see Defining the Behavior of a Custom Property, Event, or Method in Code.

To manage methods of a component with a contract (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Expand the components node, if necessary, and then select the component.
  3. In the Properties pane, click the Action tab.
  4. Click Manage Methods. Kony Visualizer displays the Manage Methods dialog box.
  5. To define pass through methods, select the Pass Through tab on the Manage Methods dialog box.
  6. Click the plus sign (+) for each pass through method you want to define. Click the delete symbol (X) to delete an existing method. To define a new pass through method, specify the following for each method:

    Click Apply to add the pass through method.

  7. To define custom properties, select the Custom tab on the Manage Methods dialog box.
  8. Click the plus sign (+) for each custom method you want to define. Click the delete symbol (X) to delete an existing method. To define a new custom method, specify the following for each method:

    To add parameters to the custom method, click the Manage Methods button and specify the parameter information in the dialog box.

    Click Apply to add the custom method.

    Important: Unlike a pass-through method, which is based on an existing method of the component, a custom method has no built-in behavior. You must define the method's behavior programmatically. On the Templates tab, expand the component's Modules node, open the controller module, and add code defining the method's behavior to the controller code. For more information, see Defining the Behavior of a Custom Property, Event, or Method in Code.

Add a Component to a Library

Once you have created a component, you can add it to a library and use it in your applications, or publish it to Kony Marketplace.

To add a component to a library (Beta):

  1. Click the Templates tab in the Project Explorer or the Library Explorer.
  2. Expand the components node, if necessary, and then select the component.
  3. Click the component's context menu arrow, hover over Add to Collection, hover over the name of the library to which you want to add the component, and then select the collection to which you want to add the component. You can also create a new library or collection. Kony Visualizer adds the component to the specified library and collection.

Note: You can import and export components to and from the library. The complete library can also be shared, including the component.

Using a Component in a Project

You can use a component in a project in virtually any form scenario, including using components within another component.

You can simplify the process of using a component by moving the Templates tab from the Project Explorer to the Library Explorer. By doing so, the Templates tab (which displays components) and the Project tab (which displays forms) become viewable at the same time since they're no longer occupying the same pane. To move the Templates tab from the Project Explorer to the Library Explorer, on the Project Explorer, right-click the Templates tab, and then click Dock to Library.

To use a component (Beta):

  1. On the Project tab of the Project Explorer, locate and open the form that you want to apply the component to. The form displays on the Visualizer Canvas and is now the form with focus.
  2. On the Templates tab, locate the component that you want to apply to the form.
  3. Do either of the following:

The instance appears in the Project Explorer as blue text with a different icon, making it easy to identify as a component instance. The instance has the same name as the top widget or container in the component.

Note: You can also download a component from Kony Marketplace using your web browser.

Control the Cascading of Changes from a Component to Its Instances

For a component without a contract or a master created in Kony Visualizer version 7.2 and earlier, you can control whether changes are inherited by its instances. For a component with a contract, you can use contract properties, events, and default values to accomplish the same result.

The types of changes are divided into two categories:

In other cases, you may want an instance to vary from the component , such as in the particular data that the instances contain.

By default, an instance of a component does not automatically inherit changes made to the component. To enable such inheritance, you need to select the instance and set it to inherit the reference data and/or reference flex properties of the component.

To control the cascading of changes from the component to its instances (Beta):

  1. On either the Project tab of the Project Explorer, or on the Visualizer Canvas, locate and select the parent container of the instance for which you want to change data and properties inheritance.
  2. From the Properties pane, Click the FlexContainer tab.
  3. Depending on what your need is, do any of the following:
  4. Important: If the data or flex properties of your instance vary from the source component, and you set the instance to inherit from the component, all variations will be overwritten, and you cannot undo this operation.

    The types of widgets in which you can change data are listed in the following table. The changes you make are specialized to that widget without affecting the component. Any future changes made to the component involving the widget are not reflected in the widget you just modified.

    Widget Data
    Button
    • Button Text
    • All properties in the Flex section of the Look tab on the Properties pane
    • Action Sequences
    • Review tab
    Calendar
    • All properties in the Flex section of the Look tab on the Properties pane
    • Default date on the Calendar tab
    • Action Sequences
    • Review tab
    Check Box Group
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the Check Box Group tab
    • Action Sequences
    • Review tab
    Data Grid
    • All properties in the Flex section of the Look tab on the Properties pane
    • Data, located on the Data Grid tab
    • Action Sequences
    • Review tab
    Image
    • All properties in the Flex section of the Look tab on the Properties pane
    • All properties in the General section of the Image tab on the Properties pane
    • Action Sequences
    • Review tab
    Label
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • All properties in the General section of the Image tab on the Properties pane
    • Action Sequences
    • Review tab
    List Box
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the List Box tab
    • Action Sequences
    • Review tab
    Radio Button Group
    • All properties in the Flex section of the Look tab on the Properties pane
    • property, on the Radio Button Group tab
    • Action Sequences
    • Review tab
    Rich Text
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • Action Sequences
    • Review tab
    Slider
    • All properties in the Flex section of the Look tab on the Properties pane
    • Min Label and Max Label values on the Slider tab
    • Action Sequences
    • Review tab
    TextArea2
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • The following properties on the Text Area tab: Max Characters, Input Mode, Placeholder, Auto Capitalize
    • Action Sequences
    • Review tab
    TextBox2
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • The following properties on the Text Area tab: Max Characters, Input Mode, Placeholder, Auto Capitalize
    • Action Sequences
    • Review tab
    Browser
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the Browser tab
    • Action Sequences
    • Review tab
    CordovaBrowser
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the CordovaBrowser tab
    • Action Sequences
    • Review tab
    Camera
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • Action Sequences
    • Review tab
    Map
    • All properties in the Flex section of the Look tab on the Properties pane
    • Action Sequences
    • Review tab
    Phone
    • All properties in the Flex section, and the Text property, on the Look tab on the Properties pane
    • Action Sequences
    • Review tab
    Picker View
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the Picker View tab
    • Action Sequences
    • Review tab
    Segment
    • All properties in the Flex section of the Look tab on the Properties pane
    • Master Data property, on the Segment tab
    • Action Sequences
    • Review tab
    Switch
    • All properties in the Flex section of the Look tab on the Properties pane
    • The following properties on the Text Area tab: Left Text, Right Text
    • Action Sequences
    • Review tab
    Video
    • All properties in the Flex section of the Look tab on the Properties pane
    • Action Sequences
    • Review tab

Reset the Values in a Component Instance

For a component without a contract or a master created in Kony Visualizer version 7.2 and earlier, you can reset values in an instance of a component or master created in Kony Visualizer version 7.2 and earlier if they have changed to differ from those of the component or master itself. You can clear them and cause the instance of the component to inherit all the values of the component. Resetting these values does not prevent you from continuing to customize the values of the instance, it just resets them to the original component values.

To reset the values in a component instance (Beta):

  1. On the Project tab of the Project Explorer, locate and select the parent container of the instance for which you want to reset its values. The instance becomes selected and is the item of focus on the Visualizer Canvas.
  2. Right-click the instance on the Visualizer Canvas, and then click Reset Instance Values. all the values in the instance are cleared, and inherit the values of the component.

Use the Segment2 Widget in a Component

One you add a Segment2 widget to a component, you cannot drop other widgets onto that segment widget because it is inside a component. To get around this limitation, you create a segment row template, populate it with the widgets you want it to have, and then you configure the segment widget in the component to reference that row template. Once the segment widget in your component is populated width content from the row template, you can edit the segment widget's master data to have the per-row customized data that you need.

Note: A segment template can only apply to one channel. To work around this, create the segment template for one channel, copy it, and then paste it into the other channels.

To use a Segment2 widget in a component (Beta):

  1. Create a segment row template. To do so, in the Project Explorer, click the Templates tab, open the channel you want to create the segment template for (e.g. Mobile), click the context menu arrow of Segments, and then click New Template. The template is created and opens on the Visualizer Canvas. It might be a good idea to rename the template to something descriptive, such as rowMobile. To do so, on the Templates tab, click the context menu arrow of the newly-created template, and then click Rename.
  2. Drag a FlexContainer widget onto the new template on the Visualizer Canvas, and configure it how you want.
  3. Drag onto the FlexContainer the widgets that you want the segment row template to have, and configure them how you want.
  4. Once you have the segment row template configured the way you want it, if you want to copy it to other channels, click the context menu arrow of the configured template, and then click Copy. Navigate to and open the channel you want to paste it to, click the context menu arrow of Segments, and then click Paste. Rename the template if you'd like, and then make any needed modifications so that it looks and behaves correctly in that channel.
  5. On the File menu (the Project menu in Kony Visualizer Starter), click Save All.
  6. Add a Segment2 widget to the component . To do so, in the Project Explorer, on the Templates tab, in the Components section, select the component so that it opens on the Visualizer Canvas, ad (or select an existing) container widget in the master, and then drag a Segment2 widget onto it.
  7. In the Properties Editor for the Segment2 widget you just added, click the Segment tab. Then from the Row Template drop-down list, select the row template you want to use.
  8. From the Segment tab, click the Edit button for Master Data, and make any changes needed to the segment data.
  9. On the File menu (the Project menu in Kony Visualizer Starter), click Save All.

Move the Templates Tab

By default, the Templates tab (which displays components and masters) and the Project tab (which displays forms) occupy the same pane (i.e. the Project Explorer) and are therefore not viewable at the same time. If you prefer, you can move the Templates tab from the Project Explorer to the Library Explorer, which makes it possible to view both tabs at the same time since they're no longer occupying the same pane.

To move the Templates tab:

  1. On the Project Explorer, right-click the Templates tab.
  2. Click Dock to Library. The Templates tab moves from the Project Explorer to the Library Explorer.

Duplicate a Component

To duplicate a component (Beta):

  1. Depending on where you've placed the Templates tab, on either the Project Explorer or the Library Explorer, click the Templates tab.
  2. If it isn't expanded already, expand the Components node.
  3. Hover over the name of the component you want to duplicate, click its context menu arrow, and then click Duplicate.

Delete a Component

Important: Deleting a component also deletes every instance of that component from your application.

To delete a component (Beta):

  1. Depending on where you've placed the Templates tab, on either the Project Explorer or the Library Explorer, click the Templates tab.
  2. If it isn't expanded already, expand the Components node.
  3. Hover over the name of the component you want to delete, click its context menu arrow, and then click Delete.

 

 

 

 

Rev Author Edits
7.3 SHS SHS
Copyright © 2013 Kony, Inc. All rights reserved.