Using the domain

Domain configuration

Once you've created the definitions of your domain types, you can begin creating elements. To do this, navigate to Menu -> Domain -> Domain configuration.

Creating main elements

Every element in a domain, with the exception of the root element, is a component of another element. The elements that are components of the root element are refferred to as main throughout this tutorial.

When you enter the Domain configuration screen, you will see the domain tree on the left, the components of your ROOT element on the right. You can add new elements by clicking +Add. You will be prompted for a code and a name of the new element.

  • code is the identifier of the element used by programming interfaces. Please note that it's not possible to change the code once an element has been created. The code has to be unique within any given component collection, but does not have to be unique for all elements of a given type.
  • name is the descriptive name of your element. While it's possible to access the name of an element through programming interfaces, it's generally not advised - it's generally better to create an attribute like DISPLAYED_NAME to store the name used by client applications, and use the element's name for easier recognition within the Hyperon Studio.

In our example, we created a single PRODUCT element. Once the element is created, you can navigate to it by clicking on it, or by selecting it from the left-side tree.

You can always return to the main element screen by clicking the Home button in the upper-right part of the screen.

Creating non-main components

Non-main components are created in much the same way as main elements, but we have to navigate to a specific component first.

You can navigate to a component screen of an element, from the element screen. In the lowest section of the screen, you will see labels representing all components of a given element type, along with the number of elements currently assigned to the component. Clicking on the label will take you to the component screen, where you can add new elements in the same way as main elements on the root element.

In our example, we've created 3 COVERAGES and 2 DISCOUNTS for our PRODUCT.

If a given component is marked as in tree in the type definition, you can also navigate to the component screen, and to any elements assigned to that component by clicking on the label on the left-side tree.

Creating references

In addition to creating new elements as components, you can also create references to existing elements. This comes in useful if some components have specific roles and are often accessed directly, or if they are shared between many parent objects.

You can create a reference in much the same way as you create a new element by navigating to the component screen and clicking the +Add reference button. This will bring up a popup screen with a list of all created elements of the required type. You can filter those elements by code, name or path (you can read more about paths in the next section of this tutorial), and select the ones you want to add as references to your component.

In our example, we're setting the MAIN_COVERAGE component to a reference to the P1MAIN coverage from the COVERAGES collection of the product. This is because while most operations we have in our application operate on all coverages, there are specific cases when the main coverage needs to be accessed directly.

A reference is a pointer to an element that is created in another branch of the domain tree. It's important to remember that this is not a copy - navigating to a reference of an element will bring you to the actual element screen of that element, and anych changes made in it's configuration will affect the actual element and all references to it.

While you have the freedom of choosing where you want your actual elements to be, and where the references are, it's important to keep it consistent throughout your configuration. If you have additional components that point to elements that need to be accessed directly or treated in a special way, it's generally better to have them as references to elements that are created in the component representing the whole collection.

*Likewise, it's better to have separate "storage" components for elements that are used throughout many *main* element components - if you decided, for example, that multiple products can share the same coverages, it's better to create a main component holding all the possible coverages, and reference them inside products, then to reference coverages from one product onto another. This way, it's more readable to the users that the given element is shared, and that changes to it will affect multiple products.

References are marked with a link icon on the domain tree and on component lists.

The element path

Any element and component in the domain has a specific path. This is very important when using the domain in programming interfaces, but it also allows for quicker navigation in certain UI components of the Hyperon Studio.

A path to an element is a list of elements and components that need to be navigated from the root element to access the element. This path is a set of / separated component names, with element codes specifying specific object inside a component collection given in [square bracers] after the component name. If a given component is not a collection (it's not designated as multiple in the type definition), the element code can be ommited.

For example, the path to the Example product 1 we've created for our example is /PRODUCTS[PROD1], and the main coverage in the product can be accessed through /PRODUCTS[PROD1]/COVERAGES[P1MAIN] (path to the actual element in the COVERAGES component collection, or through /PRODUCTS[PROD1]/MAIN_COVERAGE.

While paths are mostly used by programming interfaces, some UI elements inside the Hyperon Studio will allow you to filter elements by path - understanding how they are created will help you quickly limit your results to the elements you are interested in.

If, for example, we hand many more products and coverages created in our domain, selecting the MAIN_COVERAGE reference might take some time - but you can filter it by providing a partial path, for example /PRODUCTS[PROD1]/COVERAGES - this will limit the displayed elements to those defined inside our product.

Removing elements and references

You can remove an element by selecting the Remove action from the utility action bar in the upper right corner of the element screen. Please note, this will remove the element, even if you navigated to it through a reference.

Alternatively, elements can be removed from the component screen by pressing the x button next to an element. This will remove elements that were created for this component, and it will remove the reference. The referenced element will not be removed.

When you delete an element, all elements created as components of that element are also removed, along with any references that point to the elements being removed.

Parameters and functions used as values for ATTRIBUTES of removed elements are not removed.