=====Widgets=====

====FIELD_VALUE_WIDGET====

This widget takes in a set of **FieldValueWidgetDTO**s and based on them creates the table of key - value pairs (i.e. parameters).

The header of the widget can be set up via changing the relevant **EmsWidgetPermission** entry **description** fields (the header is generated automatically if the widget represents a child network element (e.g. an equipment entry) (generated by the **CHILD_ENTITIES_FIELD_VALUE_WIDGETS_SELECTOR_WIDGET**))

{{:development:applications:polaris:field_value_widget_example.png?1200|}}

\\

===Fields Retrieval Script===
The population of this widget is handled by the dedicated **RemoteDiscoveryScript** specified in the **Configuration** (**general_custom_fields_retrieval_script_id**). This script will execute for the widget under any EMS view layout, except for **SITE**, **EQUIPMENT_ROOM**, and **EQUIPMENT** (which are currently not in use).

**ARGUMENTS IN**:\\
**networkElementID** - the ID of the network element in which currently viewed EMS view layout the widget was constructed; with the exclusion of the **FIELD_VALUE_WIDGETS** constructed by the **CHILD_ENTITIES_FIELD_VALUE_WIDGETS_SELECTOR_WIDGET** - in such a case, the ID of the currently viewed network element's child network element (e.g. equipment) represented by this current widget is supplied. \\
**widgetTitle** - the title (i.e. header) of the widget\\
**elementType** - the type of the currently viewed EMS view layout the widget was constructed (refer to the **ElementType.java** enum)\\
**hardwareType** - the hardware type of the network element in which currently viewed EMS view layout the widget was constructed; with the exclusion of the **FIELD_VALUE_WIDGETS** constructed by the **CHILD_ENTITIES_FIELD_VALUE_WIDGETS_SELECTOR_WIDGET** - in such a case, the hardware type of the currently viewed network element's child network element (e.g. equipment) represented by this current widget is supplied.

**RETURN**:\\
**ArrayList<FieldValueDTO>** - a list of the field values (i.e. properties) to populate the widget

\\

===Fields Update Script===
The update of the database based on the values provided by that widget (i.e. when the **Save** button is clicked) happens via the dedicated **RemoteDiscoveryScript** specified in the **Configuration** (**general_custom_fields_update_script_id**). This script will execute for the widget on the **Save** button invocation under any EMS view layout, except for **SITE**, **EQUIPMENT_ROOM**, and **EQUIPMENT** (which are currently not in use).

**ARGUMENTS IN**:\\
**fieldValues** - a list of the updated **FieldValueDTOs**

**RETURN**:\\
**ArrayList<FieldValueDTO>** - a list of the updated field values with the **successfulUpdate** set either to **true** or **false**; if the **successfulUpdate** is set to false, it is advised to specify the reason of the update failure (use **updateNote** field of the relevant **FieldValueDTO** instance).

\\

===FieldValueDTO===

A support class used to model the entries (i.e. properties) supplied to the **FIELD_VALUE_WIDGET**.

{{:development:applications:polaris:fieldvaluedto.png?1000|}}

Notes:
  * **entity** usually refers to the Grails domain to which the modelled property is related to (i.e. the whole DTO can model a **Hardware Type** fields of the **NetworkElement** domain - in such a case, the **entity** value would be **network_element** (the name of the SQL table))
  * **value** is a list because the DTO of the **MULTIPLE_SELECT** **fieldType** can store multiple values.
  * **allowedValues** specify the values to populate **MULTIPLE_SELECT** or **SINGLE_SELECT** **fieldType** DTOs.

\\

=== FieldType ===

An enum used by the **NetworkElementProperty** and **FieldValueDTO**. Describes the type of value modelled.

{{:development:applications:polaris:field_type.png?700|}}

====CHILD_ENTITIES_FIELD_VALUE_WIDGETS_SELECTOR_WIDGET====
A widget which populates the currently viewed EMS view layout with the child **network_element**-representing (header will be the relevant network element name) **FIELD_VALUE_WIDGET**s. Used for the equipment (equipment is modelled via **network_element** with **show_in_monitor=false**) display.

The **Description** field of the relevant **EmsWidgetPermission** specifies the label near the dropdown list (default is "Displayed ER Equipment Type:").

{{:development:applications:polaris:child_entities_field_value_widget.png?700|}}

====ROOM_SELECTOR===
A widget which provides a dropdown list with the rooms under the current site. On room selection, the **FIELD_VALUE_WIDGET** below the dropdown gets updated with the room relevant value (provided by the relevant population script (refer to the **Configuration**)). 
\\
\\
The relevant room retrieval is performed via the **Data Script** specified in the relevant **Ems Widget Permission** entry. Such a script accepts the **networkElement** as an argument and returns the **ArrayList<RoomDTO>** representing the rooms under the current site (note: the **Room** domain provides the **toDTO()** method).
\\
\\
The dropdown label is set via the *Text Style* property of the relevant *Ems Widget Permission* entry.

{{:development:applications:polaris:room_selector.png?1100|}}