Panel: Difference between revisions

From Tygron Preview Support Wiki
Jump to navigation Jump to search
 
(124 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{learned|what panels are|how panels relate to the {{software}}|what types of panels are available to you|common use-cases which can be fulfilled using panels|how to add and edit panels in a project}}
[[File:Api_current_situation_calculation.png|thumb|right|400px|[[Panel]]s in comparison to [[Excel]]s, [[Overlay]]s and [[Indicator]]s]]
[[File:Panel-example.jpg|left|thumb|300px|A custom Panel open in the [[Viewer ]]interface.]]
Panels are custom, user-defined interface elements, which can be created and configured in the [[Editor]]. Panels are purposefully left generic and abstract, as their intent is to allow for as much freedom as possible to implement a [[Project]]-specific or [[Template]]-specific component. Panels can be given a location in the [[project area]], which makes them accessible via a [[Popup]] in the [[3D Visualization]]. Clicking the [[Popup]] opens the Panel as part of the [[Viewer ]]interface. Panels can also be [[show custom panel Client Event|opened]] via an [[Event]], or even left entirely inaccessible.


==Panels==
Most panels render HTML-content, which means they can display text without additional formatting. Further layout and styling can be implemented by using [[HTML|HTML, CSS]], and [[javascript]]. This enables Panels to also be opened in a web browser or included in the rendering of a [[Web interface]].
Panels, in a software context, are windows, dialogs or similar generic interface elements which are presented to a user. They can be small prompts or dialogs which facilitate an inquiry or message towards a user. They can also be larger, more complex interface components with multiple texts and/or elements on them.


==Panels in the {{software}}==
The content of a number of types of Panels can be made more dynamic by using [[tag]]s, or by using an [[Excel]] to compute its contents intelligently based on [[TQL|data in the project]]. This allows Panels to display information specific to a Panel or specific data in the [[Project]], such as [[Attribute]]s and [[Stakeholder]]s.
<!--[[File:ReleaseNotesPanel.jpg|thumb|left|180px|Release Notes Panel from Editor]]-->
In a [[project]], panels are a term specifically used for a user-defined interface element, which can be created and configured in the [[editor]]. They are purposefully left generic and abstract. The contents are entirely left open for a project- or template-specific implementation. Panels can be placed in the [[3D world]], where they are represented by a popup which can be clicked to open the panel. They can also be opened via a [[client event]], or left entirely unavailable.


Most panels render a html content. This means they can display text without additional formatting, but can also be styled using html, css, and javascript. This has the added benefit that those panels can also be opened in a web browser, or included in the rendering of a [[web interface]].
Additionally, most panels can also support certain [[tag]]s, which allows users to display information specific to a panel, such as the owner and attributes assigned to this panel.
{{clear|left}}
{{clear|left}}


==Panel types==
==When to use==
There are 5 types of panels available in the {{software}}.
There are a number of use-cases for which the use of Panels can be desirable. Most of those situations revolve around having custom interface elements, providing information or interaction for the end-user.
 
===Information===
Panels are primarily used to provide information to the end user. Any text or images they display, provide a source of (static) content in the session. Especially text and web panels fall into this category. Excel panels can also provide dynamic information on the current state of affairs in the session.
 
===Interaction===
Panels can also offer options to interact with the session. This can be done by means of predefined {{inlink|answers}} or through buttons defined by the HTML content, which send instructions to the project via the [[API]]. Depending on the amount of effort that went into its making, panels allow for very complex interaction in the [[3D Visualization]]. All types of panels allow for the implementation of "answers", though text and Excel panels also work well with HTML buttons and input elements.
 
===Calculation model===
Another utility of panels is in the form of a hidden [[calculation model]]. The Excel spreadsheet attached to an Excel panel can contain a number of equations and formulations ([[TQL|queries]]) that yield a specific outcome. For example, in the case of a dynamic traffic model, information can be retrieved first (using SELECT-queries), after which these data are processed according the following specifications in the Excel file. The end product may be the calculated traffic intensities at various locations in the [[project area]]. Using UPDATE-queries, these results can subsequently adjusted the visibility of the Excel panel's Popup. Stakeholders will not notice anything of the underlying calculation model, except for its results (e.g., changing traffic intensities).
 
===Web interface===
: '' Main article: [[Web interface]]''
The [[Web interface]] can be enriched by adding a Panel to it with [[HTML|HTML, CSS and/or javascript code]]. The content of the Panel is directly injected into the [[Web interface]].
 
==Types==
There are a number of types of panels available in the {{software}}.


{| class="wikitable"
{| class="wikitable"
Line 18: Line 33:
! Panel type
! Panel type
! Description
! Description
! Functioning
! Function
! Templatable
|-
|-
| Text panel
| Text Panel
| The contents of the panel are defined directly as text.
| Its contents are defined directly as text.
| The text is interpreted as html content and directly displayed as content of the panel. If it's html-formatted content, it will be displayed in that styled manner.  
| The text is interpreted as HTML-content and directly displayed as content of the panel. If it is HTML-formatted text, it will be displayed according the specified styling.
| Text [[Template Panel]]
|-
|-
| Web panel
| Web Panel
| The contents of the panel are defined by a url.
| Its contents are defined by a URL (web address).
| The web page at that url is used as content for the panel. When attempting to open the panel in a web browser, the web page will be accessed directly (i.e. not via the {{software}}).
| The web page to which is referred constitutes the content of the panel. When attempting to open the panel in a web browser, the web page will be accessed directly (i.e. not via the {{software}}).
|
|-
|-
| Global panel
| Global Panel
| One or more [[global]]s are linked to this panel, allowing an end-user to edit the values of those globals during a session.
| One or more [[global]]s are linked to this panel, allowing an end-user to edit the values of those globals during a session.
| The panel has a predefined structure in the [[session interface]], and a fixed location. For each linked global, an input field with that global's value is displayed. The value can be changed and submitted by an end-user in the session. This will change the value of the global to the entered value. This panel does not have an html representation, and cannot be opened in the web browser or be made part of the [[web interface]].
| The panel has a predefined structure in the [[Viewer ]]interface and a fixed location. For each linked global an input field with that global's value is displayed. This value can be altered and submitted by the end-user in the session. The value of the global will be changed accordingly. This panel does not have an HTML-representation, hence it can neither be opened in a web browser nor can it be integrated in the [[web interface]].
|
|-
|-
| Excel panel
| Excel Panel
| The contents of the panel are defined by an [[excel]] file.
| Its contents are defined by an [[Excel]] file.
| Each time data in the [[project]] or [[session]] is updated, the excel file is recalculated. The results are interpreted as (html-formatted) text, and displayed as such. Effectively, this panel is similar to a text panel, but rather than a static definition for the text contents, the definition is dynamically generated via the excel.
| Each time data in the [[project]] or [[session]] are updated, the Excel file is recalculated. The results are interpreted as HTML-formatted text and displayed as such. Effectively, this panel is similar to a text panel, but rather than a static definition of the text content, the definition is dynamically generated through the spreadsheet.
|-
| Excel [[Template Panel]]
| Template excel panel
| This is not a panel by itself, but forms a definition by which panels can be generated automatically. The "instances" of these panels behave as regular panels.
| Based on how the template panel is defined, a number of "instances" of the panel will be generated. Configurations such as the size, model, and [[attribute]]s of the panel are carried over directly. The panel name, the assigned [[stakeholder]], and certain [[TQL|queries]] in the excel are modified based on what the template panel is applied on.
|}
|}


==Properties of panels==
===Template Panels===
Panels have a number of properties which can be configured in the editor. They also allow for the definitions of arbitrary [[attribute]]s.
{{main|Template Panel}}
Some Panels can also be generated through the use of [[Template Panel]]s. These behave mostly like normal Panels but are not directly accessible to the end-user. Instead, based on a [[Template Panel]], Panels can be generated automatically, related to specific data in the [[Project]].


===Name===
==Properties==
When a panel is opened, the name of the panel is displayed at the top, so the end-user knows what the panel is about.
Panels have a number of properties, which can be configured in the editor. They define how the Panel is shown, and what is displayed.


===Sizing===
===General properties===
The size of the panel can be adjusted, so that it fits the content properly without cutting it off or leaving a large amount of empty space. It's also possible to set where in the interface the panel should appear.
The general properties of the Panel represent the overall configuration, excluding the actual content which is specific to the type of Panel itself.


===Availability===
[[File:panels-right-name.jpg|right|thumb|Input field for the panel name.]]
When the panel is placed in the 3D world, it can be set to be visible or invisible. If it is visible, it can also be set to draw attention or not. They can also be configured so that a panel is only accessible by one specific stakeholder, rather than all stakeholders.
; Name
: When a panel is opened, the name of the Panel is displayed at the top, informing the end-user what the panel is about.
{{clear}}


===Visualization===
[[File:panels-right-layout.jpg|right|thumb|Input fields for the panel location.]]
When the panel is placed in the 3D world, the popup representing it, and which can be clicked to open, is a green tick mark by default. This icon can be changed to a different symbol, as offered by the editor. The selected symbol has both a 3D representation, and a 2D representation for higher [[zoom level]]s, and for the [[web interface]].
; Interface location
: The location of the Panel within the interface. The X-value represents the distance from the left-hand side of the [[Viewer ]]interface. The Y-value represents the distance from the bottom of the [[Viewer ]]interface.
{{clear}}


===Overlay===
[[File:panels-right-wh.jpg|right|thumb|Input fields for the panel size.]]
A panel, by itself, may not provide all the information you wish to show. It's possible it's related to geographical information, visualized in an overlay. A panel can be related to an overlay, such that when the panel is opened the related overlay is opened as well.
; Dimensions
: The size of the panel, so that it fits the content of the Panel. Ideally, a Panel should be large enough to fit the content without the need to scroll, but not so large as to leave space of the Panel empty.
{{clear}}
 
[[File:panels-right-visible.jpg|right|thumb|Checkbox for the panel visibility.]]
; Visibility
: When the Panel has a location in the [[project area]], it is represented by a [[Popup]] in the [[3D Visualization]]. That [[Popup]] is either visible or not, based on this setting. [[Visible (Panel Attribute)|Visibility]] is also accessible as an [[Attribute]], allowing it to be set or modified through [[TQL|queries]].
{{clear}}
 
[[File:panels-right-attention.jpg|right|thumb|Checkbox for the panel attention.]]
; Attention
: When the Panel has a location in the  [[project area]], the resulting [[Popup]] can draw attention. If it does, arrows will appear in the [[Viewer ]]interface of all [[Stakeholder]]s who are allowed to see the Panel. [[Attention (Panel Attribute)|Attention]] is also accessible as an [[Attribute]], allowing it to be set or modified through [[TQL|queries]].
{{clear}}
 
[[File:panels-right-stakeholder.jpg|right|thumb|Checkbox and drop-down for the assigned stakeholder(s).]]
; Stakeholder
: Either all [[Stakeholder]]s are permitted to open a Panel, or only a single [[Stakeholder]] is permitted to open a Panel. If only a single [[Stakeholder]] is permitted to view the Panel, other [[Stakeholder]]s will not see the Panel's [[Popup]] in the [[3D Visualization]], even if it is set to be visible. If a [[Stakeholder]] does open the Panel through another route, but does not have permission to view it, the user will see a notice that they are not allowed to view the Panel.
{{clear}}
 
[[File:panels-right-model.jpg|right|thumb|Pop-up model used for in-map visualization.]]
; Popup model
: The model of the Panel's [[Popup]], which consists of both a 3D model and a 2D icon. The latter is used instead of the former for high [[Zoom Level]]s and the [[web interface]]. A selection of models is available in the drop-down menu.
{{clear}}
 
[[File:panels-right-overlay.jpg|right|thumb|Overlay activated when opening the panel.]]
; Overlay
: A panel, in itself, may not provide all the information the user wishes to show. If its content is related to specific geographic information that belongs to a certain overlay, the panel can be coupled to that overlay. Whenever the panel is opened in the future, the coupled overlay will be applied simultaneously.
{{clear}}
 
[[File:panels-right-point.jpg|right|thumb|Settings regarding the geographical location of the [[Popup]].]]
; Location in the [[project area]]
: A Panel's [[Popup]] can be given a location in the [[project area]]. This can be done by selecting the button ''Set Point'' and using the [[brush]] to select its position. To remove it again from the project area, select the button ''Remove Point''.
{{clear}}


===Content===
===Content===
The core functionality of the panels is the content. Depending on the type of panel, the type of content differs. However, if a panel has no content, the panel generally has no purpose.
Depending on the type of panel, it may have different adjustable elements that control its content.
 
===Attributes===
Panels can have any number of arbitrary [[attribute]]s, which allow for additional data to be attached to them in an accessible and alterable manner. Some attribute names are reserved and have a special function.


{| class="wikitable"
{| class="wikitable"
! Attribute
! Unit
! Description
|-
|-
|{{anchor|ATTENTION|ATTENTION}}
! Type
|boolean
! Configuring
|Whether the panel is drawing attention. This is an attribute representation of the attention property. Changing this attribute causes the panel to draw attention or not.
! Rendering
! Example
|-
|-
|{{anchor|COLOR|COLOR}}
| Text
|color
| Enter a text in the ''Panel Text'' field to make it the content of the panel. If the content is HTML-formatted, the content of the panel will be formatted accordingly.
|The color of the 2D icon of the panel's popup. This can be used to differentiate popups from one another. An additional effect of different colors is that when you zoom out to the 2D view, icons of different colors are not combined.
| Dynamically rendered content
| [[File:panels-right-conent-text.jpg|center|The text content input field.]]
|-
|-
|{{anchor|COLOR|COLOR}}
| Web
|{{color}}
| Enter a URL in the ''Web Link'' field and the assigned web page will be opened as content of the panel.
|The color of the 2D icon of the panel's popup. This can be used to differentiate popups from one another. An additional effect of different colors is that when you zoom out to the 2D view, icons of different colors are not combined.
| A frame with the displayed website.
| [[File:panels-right-conent-web.jpg|center|The URL input field.]]
|-
|-
|{{anchor|POPUP_TYPE|POPUP_TYPE}}
| Globals
|nominal integer
| Select the globals that should be accessible through the panel.
|The model of the panel's popup. Changing this attribute changes the icon of this popup.
| A predefined interface with input fields and a button so submit new values.
| [[File:panels-right-conent-global.jpg|center|The globals selection list.]]
|-
|-
|{{anchor|SCALE|SCALE}}
| Excel
|decimal value
| Select the [[Excel#Using_Excel_files|Excel]] spreadsheet which should calculate the content for this panel.
|The size of the 2D icons of the panel's popup in the 3D world. Note that the size is only updated when the visibility of the panel is updated. Either because it is (re)placed in the world, or the visibility is toggled.
| Dynamically rendered content
|-
| [[File:panels-right-conent-excel.jpg|center|The Excel selection button.]]
|{{anchor|VISIBLE|VISIBLE}}
|boolean
|Whether the panel is visible. This is an attribute representation of the visibility property. Changing this attribute causes the panel to become visible or invisible.
|-
|{{anchor|VISIBLE_TIMEFRAME|VISIBLE_TIMEFRAME}}
|integer
|Starting from which timeframe this panel should be visible. VISIBLE should be set to 1 for the panel to visible at all. This dynamic visibility of the panel is applied when viewing a [[weather]] effect. The visualisation and division of timeframes is automatically derived from [[Water Overlay]]s present in the [[project]].
|}
|}


===Answers===
====Dynamically rendered content====
A panel can be given "Answers". These are buttons that are added to a panel, which allow an end-user to close it by selecting a specific response or option. These answers can be further enriched by adding [[event]]s to them. When the user views the panel, and they select an answer with one or more events attached to it, the events are fired and changes can be effected in the session.
When the content of a Panel is dynamically rendered (i.e. when using a Text Panel or an Excel Panel), the Panel will output some string of text which will be displayed in the Panel to the end-user. Rendering of the content of a Panel occurs in three steps:
# The content of the Panel itself is processed as appropriate. Text is plain text, an Excel is recalculated, etc. This occurs regardless of whether an end-user is viewing the Panel or not.
# The content's output is processed for any [[tag]]s in the content. These allow data to be inserted dynamically in fixed locations of the content. This occurs on-demand when a user views the Panel.
# The content with the [[tag]]s processed is interpreted and displayed as [[HTML]], allowing styling of content and structuring of information according to a flexible and well-known standard. Note that if the resulting content is plain-text, the content will be displayed as plain-text as well.


==Use-cases for panels==
When a panel with [[HTML]] content is opened, any [[javascript]] script tags are interpreted as well, allowing for more complex client-side functionalities.


===Information===
===Attributes===
The most obvious use for panels is to provide information to the end-user. By making a panel accessible, any text or images displayed on it provide a source of (static) content in the session. Especially text panels and web panels are used primarily for this purpose, but especially excel panels can provide information, even dynamically, about the current state of things in the session.
Panels can have any number of arbitrary [[Attribute]]s, which allows for the definition of additional data in an accessible and versatile fashion. Panels have a number of [[Attribute]]s predefined, which fulfill a special function.


===Interaction===
It's possible to access and modify the [[Attribute]]s of Panels using [[TQL|queries]].
Panels can offer options to interact with the session as well. Either {{inlink|answers}} can be added to a panel, or the html content can define buttons which send instructions to the project via the [[API]]. With some work, it's possible to define complex interactions with the 3D world via panels. Text, web, and excel panels can all be used with answers. Text and excel panels can most easily be used to add html buttons and input elements as well.


===Calculation model===
{{panel attributes|suppresscategory=true|allowselflink=true|
By not placing the panel anywhere in the world, and not making the panel otherwise accessible by the end-users, it is possible to add a [[calculation model]] to a [[project]] without "unintended" side effects. For example, if a project requires a dynamic traffic model, an excel panel can be added to the project, with an excel sheet with the appropriate calculations and [[TQL|queries]]. It would use SELECT queries to retrieve information from the project, use some calculation to determine the appropriate amount of traffic in the various locations in the 3D world, and then use UPDATE statements to change the traffic intensities in the 3D world. By placing this calculation model in an unreachable panel, no stakeholder will see any trace of this calculation model, other than the changing traffic intensities.
{{:attention (Panel Attribute)}}
{{:color (Panel Attribute)}}
{{:popup type (Panel Attribute)}}
{{:scale (Panel Attribute)}}
{{:visible (Panel Attribute)}}
{{:visible timeframe (Panel Attribute)}}
}}


===Web interface===
===Answers===
: '' Main article: [[Web interface]]''
A Panel can be given [[Answer (Panel)|Answer]]s. These are buttons that are added to a Panel and allow the end-user to close the Panel by selecting from the specified options. These [[Answer (Panel)|Answer]]s can be further supplemented through the inclusion of [[Event]]s. When the user selects an [[Answer (Panel)|Answer]] that has one or more [[Event]]s attached to it, those [[Event]]s will get fired (triggered) and will affect the [[Session]] accordingly.
In the web interface functionality, it is possible to enrich the web interface with your own [[HTML|html, css, and javascript]], to provide the functionality you want to the end-users experience. Panels provide the primary means of adding your own information and programming.
 
==Adding and editing single panels==
 
===Adding/removing panels===
{{Editor ribbon|header=Indicators|bar=Panels}}
[[File:panels-left.jpg|framed|left|The [[left panel]] for panels in the editor.]]
 
{{Editor steps|title=add a single panel|Select the desired panel type at the bottom of the [[left panel]].|Select "Add Panel".}}
{{Editor steps|title=remove a single panel|Select the "Single Panels" category in the [[left panel]].|Select the specific panel you wish to remove.|Select "Remove".}}
{{clear|both}}
 
===Configuring panels===
{{Editor ribbon|header=Indicators|bar=Panels|left panel=Panel}}
When you select a single panel, the [[right panel]] will be filled with the information pertaining to the panel. A number of properties can be configured.
 
[[File:panels-right.jpg|framed|left|The [[right panel]] for panels in the editor.]]
 
====Name====
[[File:panels-right-name.jpg|frame|right|The field for the "name".]]
: ''The name of the panel. You can change this by altering the text in the "Name" field.''{{clear|right}}
 
====Panel Layout====
[[File:panels-right-layout.jpg|frame|right|The fields for the location.]]
: ''The location of the panel, in pixels of distance from the bottom-left corner of the screen. "-1" places the panel in the default location. You can change this by changing the value in the first input field for the horizontal location, and the second input field for the vertical location.''{{clear|right}}
 
====Panel Width &amp; Height====
[[File:panels-right-wh.jpg|frame|right|The fields for the size.]]
: ''The size of the panel, in pixels. The size set is the outer edge of the panel, there is some distance between the outer edge and the edge of the content placed in the panel. You can change the size by changind the value in the first input field for the width, and the second input field for the height.''{{clear|right}}
 
====Visible====
[[File:panels-right-visible.jpg|frame|right|The checkbox for visibility.]]
: ''Whether the panel's popup should be visible in the 3D world. If the panel has a location in the 3D world, and the panel is visible, a popup is present in the 3D world, clickable by the end-user. If the panel has no location in the 3D world, or is not set to be visible, the panel's popup is not visible in the 3D world.''{{clear|right}}
 
====Request Attention====
[[File:panels-right-attention.jpg|frame|right|The checkbox for attention.]]
: ''Whether the panel's popup should draw [[attention]] in the 3D world. If the panel has a location in the 3D world, and the panel is visible, and the panel draws attention, an arrow will appear for the end-user indicating where the panel is.''{{clear|right}}
 
====Assign to Specific Stakeholder====
[[File:panels-right-stakeholder.jpg|frame|right|The checkbox and dropdown for the panel's stakeholder.]]
: ''Whether the panel is only available to one stakeholder, or to all. If the checkbox is unchecked, the panel is available to all stakeholders. If checked, only the stakeholder indicated in the dropdown can see or access the panel. Other stakeholders will not be able to see the panel in the 3D world. If another stakeholder attempts to open the panel, for example via the [[web interface]], they will get an error message that they are not allowed to access the panel.''{{clear|right}}
 
====Model====
[[File:panels-right-model.jpg|frame|right|The model to use for in-map visualization.]]
: ''The model used for the panel's popup. The model consists of both a 3D model for most [[zoom level]]s, and a 2D icon for the higher zoom levels and the [[web interface]]. Change the selection in the dropdown to change the used model and icon.''{{clear|right}}
 
====Overlay====
[[File:panels-right-overlay.jpg|frame|right|The overlay to activate when the panel is opened.]]
: ''When the panel is opened, this overlay should be activated to provide (additional) geographical information to the end-user. If set to "NONE", no overlay is used. Change the selection in the dropdown to change the used overlay.''{{clear|right}}
 
====Point in 3D World====
[[File:panels-right-point.jpg|frame|right|The options to assign the panel to a geographical location.]]
: ''A panel can be given a location in the [[3D world]]. To do so, select "Set Point", and use the [[brush]] to select a position. To remove it from the 3D world, select "Remove Point".''{{clear|right}}
 
====Open Panel====
[[File:panels-right-open.jpg|frame|right|The button to open the panel in the session interface.]]
: ''To open the panel for testing purposes, you can select "Open Panel" to open the panel in the session interface. You can also open the panel in the web browser by selecting "Open in Web Browser".''{{clear|right}}
 
====Content====
Depending on the exact type of panel, different elements may exist to configure the contents for the panel.
 
=====Text=====
[[File:panels-right-conent-text.jpg|frame|right|The text content input field.]]
: ''Enter a text in the "Panel Text" field, and that text will be set as the content of the panel. If the content is html-formatted, the content of the panel will be formatted accordingly.''{{clear|right}}
 
=====Web=====
[[File:panels-right-conent-web.jpg|frame|right|The URL input field.]]
: ''Enter a url in the "Web link" field, and the indicated web page will be opened as content of the panel.''{{clear|right}}
=====Globals=====
[[File:panels-right-conent-global.jpg|frame|right|The globals selection list.]]
: ''Select the globals which should be accessible via the panel, and those globals will be added to the panel.''{{clear|right}}
=====Excel=====
[[File:panels-right-conent-excel.jpg|frame|right|The excel selection option.]]
: ''Select the [[Excel#Using_Excel_files|excel]] which should calculate the content for this panel.''{{clear|both}}
 
==Adding and editing template panels==
 
===Adding/removing template panels===
{{Editor ribbon|header=Indicators|bar=Panels}}
 
{{Editor steps|title=add a template panel|Select the "TEMPLATE_EXCEL_PANEL" type at the bottom of the [[left panel]].|Select "Add Panel".}}
 
{{Editor steps|title=remove an instance of a template panel|Select the "Template Panels" category in the [[left panel]].|Select the template panel from which the instance was generated.| Select the specific panel you wish to remove.|Select "Remove".}}
 
{{Editor steps|title=remove a template panel and all derived instances|Select the "Template Panels" category in the [[left panel]]. Select the template panel you wish to remove.|Select "Remove".}}
 
===Configuring and instantiating template panels===
{{Editor ribbon|header=Indicators|bar=Panels|left panel=Template Panel}}
When you select a template panel, the right panel will be filled with the information pertaining to the template panel. A number of properties can be configured. Most properties are the same as for single panels. The important differences are listed here.
 
[[File:panels-right-template.jpg|framed|left|The [[right panel]] for template panels in the editor.]]
 
====Name for template panel====
[[File:panels-right-template-name.jpg|frame|right|The field for the "name".]]
: ''The name of the panel. The name of an instance of a panel is composed of the name of the template panel, and the name of the item the template is applied on.''{{clear|right}}
 
====Stakeholder for template panel====
[[File:panels-right-template-stakeholder.jpg|frame|right|The additional fields for the "stakeholder".]]
: ''The stakeholder who has access to this panel. Rather than set a specific stakeholder, you can specify the type of relation the stakeholder should have with the item in question. For example, the "Use Owner" checkbox indicates that whoever owns an item at the time that the template panel is applied, is set to be the stakeholder with access to the panel.
 
: ''The "Relational Filter" will make instances of panels appear only if the configured stakeholder has the indicated relation with the item the template panel is applied on. For example, if the filter is set to "Net Owner", and a stakeholder is set for the panel, there will only be instances of this template panel generated for those items of which the stakeholder is the net owner.''{{clear|right}}
 
====Template====
[[File:panels-right-template-template.jpg|frame|right|The options for applying the template panel.]]
: ''"Apply Template on" indicates what kind of item the template should be applied to. "With Attribute" allows a filtering on what items to apply the template panel to. If set, it will only be the items of the specified kind, with this specified attribute set to a non-zero value, for which panels will be created.''{{clear|right}}
 
====Not viewable====
: ''Note that there are no options to directly test what this panel will look like. This is because the template panel is merely a definition of how the actual instances should be structured, but which by itself is not an actual instance.''{{clear|right}}
 
====Applying====
[[File:panels-right-template-apply.jpg|frame|right|The "Apply Template" button will cause the actual instances of the panels to appear.]]
: ''When the template panel is configured correctly, it can be used to create the actual panel instances which appear in the project. Select "Apply Template" to create the panel instances. You will be prompted with a message indicating how many panels will be created, which you can verify before creating the panel instances.''{{clear|right}}
 
===Editing panel instances===
After applying a template panel, so that one or more panel instances are created based on the template panel, it is possible to edit them as though they were single panels. However, this practice is discouraged, because it is a common possibility that after applying the template, the template should be tweaked slightly to improve it and the instanced panels derived from it. After re-applying the template, any alterations made to specific instances of the panels are lost, as the instances are created anew. Instead, it is recommended to tag the items the panels are applied on using [[attribute]]s, and including in the template panel itself some logic to handle the situations where that attribute is or isn't present.
 
==Adding and editing answers==
 
===Adding/removing answers===
{{Editor ribbon|header=Indicators|bar=Panels|left panel=Panel}}
 
{{Editor steps|title=add a template panel|Select the panel you wish to add an answer to in the [[left panel]].|Select "Add Answer".}}
 
{{Editor steps|title=remove an answer from a panel|Select the answer you wish to remove.|Select "Remove".}}
 
===Configuring answers===
{{Editor ribbon|header=Indicators|bar=Panels|left panel=Answer of a panel}}
 
When you select an answer, the [[right panel]] will be filled with information pertaining to the answer. A few properties can be configured.
 
[[File:panels-right-answer.jpg|framed|left|The [[right panel]] for answers of panels in the editor.]]
 
====Name for answer====
[[File:panels-right-answer-name.jpg|frame|right|The field for the "name".]]
: ''The name of the answer. The name is displayed to the end-user when the panels is opened, and is the text of the answer the end-user may choose. The name can be changed by changing the value in the name field.{{clear|right}}


====Events====
{{article end
[[File:panels-right-answer-events.jpg|frame|right|The events fired when the answer is selected.]]
|howtos=
: ''The events fired when this answer is selected. The events are decided into server events and client events. Server events will also trigger changes in the state of the [[session]]. Client events will only affect the visualization of the end-user who selected the answer.
* [[How to add a Panel]]
: ''{{:Editing Events}}
* [[How to remove a Panel]]
{{clear|both}}
* [[How to add a spatial Panel]]
* [[How to add a Panel which can be opened from an Action Menu]]
* [[How to create an alert Panel]]
* [[How to create an Excel background calculation model]]
* [[How to assign a Panel to a specific Stakeholder]]
* [[How to inspect the contents of a Panel in a web browser]]
|seealso=
* [[Web panel]]
* [[Global panel]]
[[File:YoutubeLogo1.jpg|link=https://youtu.be/IpQxzjzi1d0|thumb|left|200px|Panels en Globals (Dutch only)]]
}}


===Answers as part of template panels===
{{Template:Editor current situation nav}}
Answers can also be added to template panels. When the template panel is applied on an item type, each event of each answer attached to the template panel is checked on whether they feature that same item type as parameters. If so, for each instance of the panel those parameters are changed to the exact item that panel instance is created for. For example, if an answer is defined with the NEIGHBORHOOD_SET_ATTRIBUTE event, and the template panel is applied on neighborhoods, each instance will have their answer with the NEIGHBORHOOD_SET_ATTRIBUTE event effect the specific neighborhood the instance is created for.
{{Panel nav}}
[[Category:Items]]

Latest revision as of 10:25, 2 March 2023

Panels in comparison to Excels, Overlays and Indicators
A custom Panel open in the Viewer interface.

Panels are custom, user-defined interface elements, which can be created and configured in the Editor. Panels are purposefully left generic and abstract, as their intent is to allow for as much freedom as possible to implement a Project-specific or Template-specific component. Panels can be given a location in the project area, which makes them accessible via a Popup in the 3D Visualization. Clicking the Popup opens the Panel as part of the Viewer interface. Panels can also be opened via an Event, or even left entirely inaccessible.

Most panels render HTML-content, which means they can display text without additional formatting. Further layout and styling can be implemented by using HTML, CSS, and javascript. This enables Panels to also be opened in a web browser or included in the rendering of a Web interface.

The content of a number of types of Panels can be made more dynamic by using tags, or by using an Excel to compute its contents intelligently based on data in the project. This allows Panels to display information specific to a Panel or specific data in the Project, such as Attributes and Stakeholders.

Additionally, most panels can also support certain tags, which allows users to display information specific to a panel, such as the owner and attributes assigned to this panel.

When to use

There are a number of use-cases for which the use of Panels can be desirable. Most of those situations revolve around having custom interface elements, providing information or interaction for the end-user.

Information

Panels are primarily used to provide information to the end user. Any text or images they display, provide a source of (static) content in the session. Especially text and web panels fall into this category. Excel panels can also provide dynamic information on the current state of affairs in the session.

Interaction

Panels can also offer options to interact with the session. This can be done by means of predefined answers or through buttons defined by the HTML content, which send instructions to the project via the API. Depending on the amount of effort that went into its making, panels allow for very complex interaction in the 3D Visualization. All types of panels allow for the implementation of "answers", though text and Excel panels also work well with HTML buttons and input elements.

Calculation model

Another utility of panels is in the form of a hidden calculation model. The Excel spreadsheet attached to an Excel panel can contain a number of equations and formulations (queries) that yield a specific outcome. For example, in the case of a dynamic traffic model, information can be retrieved first (using SELECT-queries), after which these data are processed according the following specifications in the Excel file. The end product may be the calculated traffic intensities at various locations in the project area. Using UPDATE-queries, these results can subsequently adjusted the visibility of the Excel panel's Popup. Stakeholders will not notice anything of the underlying calculation model, except for its results (e.g., changing traffic intensities).

Web interface

Main article: Web interface

The Web interface can be enriched by adding a Panel to it with HTML, CSS and/or javascript code. The content of the Panel is directly injected into the Web interface.

Types

There are a number of types of panels available in the Tygron Platform.

Panel type Description Function Templatable
Text Panel Its contents are defined directly as text. The text is interpreted as HTML-content and directly displayed as content of the panel. If it is HTML-formatted text, it will be displayed according the specified styling. Text Template Panel
Web Panel Its contents are defined by a URL (web address). The web page to which is referred constitutes the content of the panel. When attempting to open the panel in a web browser, the web page will be accessed directly (i.e. not via the Tygron Platform).
Global Panel One or more globals are linked to this panel, allowing an end-user to edit the values of those globals during a session. The panel has a predefined structure in the Viewer interface and a fixed location. For each linked global an input field with that global's value is displayed. This value can be altered and submitted by the end-user in the session. The value of the global will be changed accordingly. This panel does not have an HTML-representation, hence it can neither be opened in a web browser nor can it be integrated in the web interface.
Excel Panel Its contents are defined by an Excel file. Each time data in the project or session are updated, the Excel file is recalculated. The results are interpreted as HTML-formatted text and displayed as such. Effectively, this panel is similar to a text panel, but rather than a static definition of the text content, the definition is dynamically generated through the spreadsheet. Excel Template Panel

Template Panels

Main article: Template Panel

Some Panels can also be generated through the use of Template Panels. These behave mostly like normal Panels but are not directly accessible to the end-user. Instead, based on a Template Panel, Panels can be generated automatically, related to specific data in the Project.

Properties

Panels have a number of properties, which can be configured in the editor. They define how the Panel is shown, and what is displayed.

General properties

The general properties of the Panel represent the overall configuration, excluding the actual content which is specific to the type of Panel itself.

Input field for the panel name.
Name
When a panel is opened, the name of the Panel is displayed at the top, informing the end-user what the panel is about.
Input fields for the panel location.
Interface location
The location of the Panel within the interface. The X-value represents the distance from the left-hand side of the Viewer interface. The Y-value represents the distance from the bottom of the Viewer interface.
Input fields for the panel size.
Dimensions
The size of the panel, so that it fits the content of the Panel. Ideally, a Panel should be large enough to fit the content without the need to scroll, but not so large as to leave space of the Panel empty.
Checkbox for the panel visibility.
Visibility
When the Panel has a location in the project area, it is represented by a Popup in the 3D Visualization. That Popup is either visible or not, based on this setting. Visibility is also accessible as an Attribute, allowing it to be set or modified through queries.
Checkbox for the panel attention.
Attention
When the Panel has a location in the project area, the resulting Popup can draw attention. If it does, arrows will appear in the Viewer interface of all Stakeholders who are allowed to see the Panel. Attention is also accessible as an Attribute, allowing it to be set or modified through queries.
Checkbox and drop-down for the assigned stakeholder(s).
Stakeholder
Either all Stakeholders are permitted to open a Panel, or only a single Stakeholder is permitted to open a Panel. If only a single Stakeholder is permitted to view the Panel, other Stakeholders will not see the Panel's Popup in the 3D Visualization, even if it is set to be visible. If a Stakeholder does open the Panel through another route, but does not have permission to view it, the user will see a notice that they are not allowed to view the Panel.
Pop-up model used for in-map visualization.
Popup model
The model of the Panel's Popup, which consists of both a 3D model and a 2D icon. The latter is used instead of the former for high Zoom Levels and the web interface. A selection of models is available in the drop-down menu.
Overlay activated when opening the panel.
Overlay
A panel, in itself, may not provide all the information the user wishes to show. If its content is related to specific geographic information that belongs to a certain overlay, the panel can be coupled to that overlay. Whenever the panel is opened in the future, the coupled overlay will be applied simultaneously.
Settings regarding the geographical location of the Popup.
Location in the project area
A Panel's Popup can be given a location in the project area. This can be done by selecting the button Set Point and using the brush to select its position. To remove it again from the project area, select the button Remove Point.

Content

Depending on the type of panel, it may have different adjustable elements that control its content.

Type Configuring Rendering Example
Text Enter a text in the Panel Text field to make it the content of the panel. If the content is HTML-formatted, the content of the panel will be formatted accordingly. Dynamically rendered content
The text content input field.
Web Enter a URL in the Web Link field and the assigned web page will be opened as content of the panel. A frame with the displayed website.
The URL input field.
Globals Select the globals that should be accessible through the panel. A predefined interface with input fields and a button so submit new values.
The globals selection list.
Excel Select the Excel spreadsheet which should calculate the content for this panel. Dynamically rendered content
The Excel selection button.

Dynamically rendered content

When the content of a Panel is dynamically rendered (i.e. when using a Text Panel or an Excel Panel), the Panel will output some string of text which will be displayed in the Panel to the end-user. Rendering of the content of a Panel occurs in three steps:

  1. The content of the Panel itself is processed as appropriate. Text is plain text, an Excel is recalculated, etc. This occurs regardless of whether an end-user is viewing the Panel or not.
  2. The content's output is processed for any tags in the content. These allow data to be inserted dynamically in fixed locations of the content. This occurs on-demand when a user views the Panel.
  3. The content with the tags processed is interpreted and displayed as HTML, allowing styling of content and structuring of information according to a flexible and well-known standard. Note that if the resulting content is plain-text, the content will be displayed as plain-text as well.

When a panel with HTML content is opened, any javascript script tags are interpreted as well, allowing for more complex client-side functionalities.

Attributes

Panels can have any number of arbitrary Attributes, which allows for the definition of additional data in an accessible and versatile fashion. Panels have a number of Attributes predefined, which fulfill a special function.

It's possible to access and modify the Attributes of Panels using queries.

Attribute Unit Description
ATTENTION boolean This is an attribute representation of the attention property and determines whether or not the panel draws attention.
COLOR Color The color of the top-down model of the popup designating the panel. This can be used to differentiate between multiple popups.
POPUP_TYPE nominal value The 3D model of the Panel's Popup and its top-down counterpart. Multiple models are offered by the Tygron Platform.
SCALE factor The size of the top-down model of the popup in the 3D Visualization. Note that the size is only updated when the visibility of the panel is updated. This can be done either by adjusting its location or toggling its visibility.
VISIBLE boolean This is an attribute representation of the visibility property and determines whether or not the panel is visible.
VISIBLE_TIMEFRAME integer The timeframe as of when the panel (popup) becomes visible during simulation. This attribute requires the attribute VISIBLE to be set to 1; if not, the popup will not show at all. The dynamic visibility of the panel (popup) is only apparent when simulating a weather effect and, therefore, will not work in a normal overlay simulation run. The visualization and division of timeframes is automatically derived from the Water Overlay present in the project.

Answers

A Panel can be given Answers. These are buttons that are added to a Panel and allow the end-user to close the Panel by selecting from the specified options. These Answers can be further supplemented through the inclusion of Events. When the user selects an Answer that has one or more Events attached to it, those Events will get fired (triggered) and will affect the Session accordingly.

How-to's

See also

Panels en Globals (Dutch only)
Editor ribbon icon current.pngCurrent Situation
Current Situation
Buildings • Terrains • Administrative • Areas • Networks • Overlays • Indicators • Panels • Globals •  Queries • Geo Import
Buildings
Function • Function Override • Traffic Units
Terrain
Height sector • Elevation model • Elevation GeoTIFF • Elevation Grid Overlay • Ground Price • Terrain Type • Terrain Type Override
Administrative
Neighborhood • Zone • Permission Popup • Plot • Zip Code
Geo Import
Source • GeoShare
Network
Net Cluster • Net Function • Net Line • Net Load • Net Node • Net Setting
Editor
Current Situation • Future Design • Multi Scenario • Tools • Community


Indicators
Basics
Panel • Excel • Global • Web • Template
Public Share
Parking alert
Retrieved from "https://previewsupport.tygron.com/w/index.php?title=Panel&oldid=54153"