Panels (template panels) tutorial

From Tygron Support wiki
Jump to navigation Jump to search

Template:Learned

This article is a stub.

Prerequisites

The following prerequisites should be met before starting this tutorial:

  • This tutorial is a continuation of the panels tutorial. If you have not already done so, please complete that tutorial first. If you have not yet followed the tutorials related to those subjects please do so first.
  • This tutorial can be followed with any project of any arbitrary location. Recommended is to create or load a project in the editor with 3 or more neighborhoods at least partially within the project area
  • Microsoft Excel is required for completing this tutorial. 

Preparations

Take the following steps as preparation for following this tutorial:

  • Start your project. This can be a pre-existing project, or a newly created project.
  • Start Microsoft Excel. Excel will be required in the later stages of the tutorial.

Adding a Template Excel panel

In the editor, go to: Template:Editor ribbon You can add a Template excel either by selecting the "Add Simple Template" option in the ribbon hover menu, or by selecting TEMPLATE_EXCEL_PANEL in the left panel, followed by "Add". The panel will be added in the Template Panels category.

The Template excel panel has been added.

Generally, the configuration options for the Template panel are the same as for the other panels, with 2 important differences. It is not possible to open the panel or to place it in the 3D world as a popup. Instead, there are options to apply the template on spatial data, such as neighborhoods or areas. This will create an instance of this panel, based on how you configured the Template Excel panel, for every spatial datum which meets your specification.

Create an Excel file

In Excel, create a new Excel File with the following information (note that this is the same excel definition as in the first panels tutorial. You can reuse that file directly.):

  • Cell A1 has the content “EXPLANATION: “
  • Cell B1 has the name “EXPLANATION”
  • Cell B1 has a color, indicating that this cell is named and provides output.
  • Cell B1 has the content “=B2&B3”
  • Cell A2 has the content “Text:”
  • Cell B2 has the content “This is my excel panel. There are this many houses in this location: ”
  • Cell A3 has the content “Houses:”
  • Cell B3 has the name “SELECT_UNITS_WHERE_MAP_IS_MAQUETTE”
  • Cell B3 has the content “1234”. This is a placeholder value.
  • Cell B3 has a color, indicating that this cell is named and provides input.
The setup for the first excel file.

(Note that in the above image, in column C the names of the cells in column B are displayed as well, for a more complete overview of how this Excel should be composed.) (Note that in your file the colors are not required, but help to maintain an overview of how the sheet functions. i.e. Where information comes in, and where it goes out.) Save the Excel file.

Import the excel file and apply it to the Template excel panel.

Creating instances of a Template Excel panel

Make sure “Apply Template on” is set to “NEIGHBORHOODS”, and click on “Apply Template”. You will get a notification of the amount of panels which will be created based on this Template Excel panel. In this case, one for each neighborhood.

The notification shown when applying a Template excel panel.

Click “Yes”, and the panels will be created. The panels will be visible in the 3D world, and can be found in the left panel as sub-items of the Template Excel panel.

The Template excel panel has been applied, and instanced of the panel have been added.

When you select one of the instances of the Template Excel Panel, you will see in the right panel that the configuration options for a panel created based on a Template Excel Panel are effectively the same as those for an Excel Panel. The properties of the instanced panel will be the same as the properties of the Template Excel panel. For example: the model, whether it requests attention or not, to which stakeholder it is assigned, etc. The name is always a composite of the name of the Template Excel panel, and the spatial item this instance relates to.

It is possible to tweak the properties of an instance of a Template Excel Panel, for example change its model or underlying excel sheet, but this is discouraged. When the Template Excel Panel is updated and reapplied, all existing instances of that Template Excel Panel are removed, and new ones are created. Any changes you have made to those instances will be lost. Open any of the instanced panels, either by selecting them in the editor and clicking “Open Panel”, or by clicking on their popup in the 3D world.

The Template excel panel instance displays content as generated by the excel file applied to the Template excel panel.

You will see that the content of the instanced panel is exactly the same content as is created by the sheet we selected for the Template Excel Panel.

ID-queries

When creating a panel for every neighborhood, or every area, or every spatial datum of a given type, most use-cases desire that information related to that specific item is displayed or used in determining the content of that panel. For this, a new syntax can be used in TQL called an “ID” query. A specific id in a query can be replaced by “ID” to mean as much as “(of) the item concerned”. The following will demonstrate its usage and effect.

Update your excel sheet, make the following changes:

  • Cell B1 has the content “=B5&B6&B7&B8&B9”
  • Cells A5, A7 and A9 have the content “Text:”
  • Cell B5 has the content “In “
  • Cell B7 has the content “ there are “
  • Cell B9 has the content “houses”.
  • Cell A6 has the content “Neighborhood name”
  • Cell B6 has the name “SELECT_NAME_WHERE_NEIGHBORHOOD_IS_ID”
  • Cell B6 has the content “Location”. This is a placeholder value.
  • Cell A8 has the content “Houses”
  • Cell B8 has the name “SELECT_UNITS_WHERE_MAP_IS_MAQUETTE_AND_NEIGHBORHOOD_IS_ID”
  • Cell B8 has the content “1234”. This is a placeholder value.
  • Cells B6 and B8 have a color, indicating that these cells are named and provide input.
The setup for the second excel file.

Save the Excel file.

In the editor, select your Template Excel panel (not an instance of the Template Excel Panel, but the original Template Excel Panel) and click “Select Excelsheet”. Update the excelsheet of the Template Excel panel by clicking the “Update” icon.

Select the "Update" icon to upload your file, replacing the previous file.