ᱪᱷᱟᱸᱪ:Infobox dam/doc
This is a documentation subpage for ᱪᱷᱟᱸᱪ:Infobox dam. It contains usage information, categories and other content that is not part of the original ᱪᱷᱟᱸᱪ page. |
This template adds an automatically generated short description. |
This template uses Lua: |
Usage
ᱥᱟᱯᱲᱟᱣUse the following infobox for all types of hydroelectric power stations involving dams, including pumped-storage. For all types of wave and tidal power stations, as well as all other types of power stations, please use {{Infobox power station}}.
{{{name}}} | |
---|---|
ᱥᱚᱨᱠᱟᱨᱤ ᱧᱩᱛᱩᱢ | {{{name_official}}} |
ᱫᱤᱥᱚᱢ | {{{country}}} |
ᱴᱷᱟᱹᱶ | {{{location}}} |
Coordinates | 0°N 0°E / 0°N 0°E |
ᱞᱟᱨᱚᱱ | {{{purpose}}} |
ᱥᱛᱷᱤᱛᱤ | {{{status}}} |
ᱵᱮᱱᱟᱣ ᱮᱦᱚᱵ | {{{construction_began}}} |
ᱪᱟᱹᱞᱩ ᱢᱟᱹᱦᱤᱛ | {{{opening}}} |
ᱨᱟᱹᱯᱩᱫ ᱢᱟᱹᱦᱤᱛ | {{{demolished}}} |
ᱵᱮᱱᱟᱣ ᱠᱷᱚᱨᱚᱪ | {{{cost}}} |
ᱵᱮᱱᱟᱣ ᱟᱠᱟᱫᱟᱭ | {{{builder}}} |
ᱱᱚᱸᱠᱥᱟᱭᱤᱡ | {{{designed_by}}} |
ᱢᱟᱹᱞᱤᱠ(ᱠᱚ) | {{{owner}}} |
ᱪᱟᱪᱞᱟᱣᱤᱡ | {{{operator}}} |
ᱩᱥᱩᱞ ᱰᱮᱢ ᱟᱨ ᱥᱯᱤᱞᱣᱮᱥ | |
ᱰᱮᱢ ᱨᱮᱭᱟᱜ ᱫᱷᱚᱨᱚᱱ | {{{dam_type}}} |
Impounds | {{{dam_crosses}}} |
ᱩᱥᱩᱞ (ᱜᱚᱸᱰᱟ) | {{{dam_height_foundation}}} |
ᱩᱥᱩᱞ (ᱛᱷᱟᱞᱣᱮᱜᱽ) | {{{dam_height_thalweg}}} |
ᱡᱮᱞᱮᱧ | {{{dam_length}}} |
ᱪᱚᱴ ᱨᱮ ᱩᱥᱩᱞ | {{{dam_elevation_crest}}} |
ᱯᱟᱥᱱᱟᱣ (ᱪᱚᱴ ᱨᱮ) | {{{dam_width_crest}}} |
ᱯᱟᱥᱱᱟᱣ (ᱜᱚᱸᱰᱟ ᱨᱮ) | {{{dam_width_base}}} |
ᱰᱮᱢ ᱨᱮᱭᱟᱜ ᱵᱷᱚᱞᱤᱭᱩᱢ | {{{dam_volume}}} |
ᱵᱟᱹᱲᱛᱤ ᱫᱟᱜ ᱚᱪᱚᱜ ᱦᱚᱨ | {{{spillway_count}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱷᱚᱨᱚᱱ | {{{spillway_type}}} |
ᱥᱯᱤᱞᱣᱮ ᱡᱮᱞᱮᱧ | {{{spillway_length}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱟᱲᱮ | {{{spillway_capacity}}} |
ᱥᱯᱤᱞᱣᱮ ᱵᱷᱚᱞᱤᱭᱩᱢ ᱞᱤᱸᱜᱤᱱ ᱫᱚᱨ | {{{spillway_volumetric_flow_rate}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱷᱚᱨᱚᱱ | {{{spillway_type2}}} |
Spillway length | {{{spillway_length2}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱟᱲᱮ | {{{spillway_capacity2}}} |
ᱥᱯᱤᱞᱣᱮ ᱵᱷᱚᱞᱤᱭᱩᱢ ᱞᱤᱸᱜᱤᱱ ᱫᱚᱨ | {{{spillway_volumetric_flow_rate2}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱷᱚᱨᱚᱱ | {{{spillway_type3}}} |
ᱥᱯᱤᱞᱣᱮ ᱡᱮᱞᱮᱧ | {{{spillway_length3}}} |
ᱥᱯᱤᱞᱣᱮ ᱫᱟᱲᱮ | {{{spillway_capacity3}}} |
ᱥᱯᱤᱞᱣᱮ ᱵᱷᱚᱞᱤᱭᱩᱢ ᱞᱤᱸᱜᱤᱱ ᱫᱚᱨ | {{{spillway_volumetric_flow_rate3}}} |
ᱪᱮᱛᱟᱱ ᱫᱟᱨᱦᱟ | |
ᱛᱮᱭᱟᱨ | {{{res_name}}} |
ᱞᱮᱠᱷᱟᱜᱩᱴ ᱫᱟᱲᱮ | {{{res_capacity_total}}} |
ᱪᱟᱹᱞᱩ ᱨᱮ ᱫᱟᱲᱮ | {{{res_capacity_active}}} |
ᱵᱟᱝ ᱪᱟᱹᱞᱩ ᱨᱮ ᱫᱟᱲᱮ | {{{res_capacity_inactive}}} |
Catchment area | {{{res_catchment}}} |
Surface area | {{{res_surface}}} |
ᱥᱟᱱᱟᱢ ᱠᱷᱚᱱ ᱡᱟᱹᱥᱛᱤ ᱡᱮᱞᱮᱧ | {{{res_max_length}}} |
ᱥᱟᱱᱟᱢ ᱠᱷᱚᱱ ᱡᱟᱹᱥᱛᱤ ᱚᱥᱟᱨ | {{{res_max_width}}} |
Maximum water depth | {{{res_max_depth}}} |
Normal elevation | {{{res_elevation}}} |
Tidal range | {{{res_tidal_range}}} |
Lower dam and spillways | |
Type of dam | {{{lower_dam_type}}} |
Impounds | {{{lower_dam_crosses}}} |
Height (foundation) | {{{lower_dam_height_foundation}}} |
Height (thalweg) | {{{lower_dam_height_thalweg}}} |
Length | {{{lower_dam_length}}} |
Elevation at crest | {{{lower_dam_elevation_crest}}} |
Width (crest) | {{{lower_dam_width_crest}}} |
Width (base) | {{{lower_dam_width_base}}} |
Dam volume | {{{lower_dam_volume}}} |
Spillways | {{{lower_spillway_count}}} |
Spillway type | {{{lower_spillway_type}}} |
Spillway length | {{{lower_spillway_length}}} |
Spillway capacity | {{{lower_spillway_capacity}}} |
Spillway volumetric flow rate | {{{lower_spillway_volumetric_flow_rate}}} |
Spillway type | {{{lower_spillway_type2}}} |
Spillway length | {{{lower_spillway_length2}}} |
Spillway capacity | {{{lower_spillway_capacity2}}} |
Spillway volumetric flow rate | {{{lower_spillway_volumetric_flow_rate2}}} |
Spillway type | {{{lower_spillway_type3}}} |
Spillway length | {{{lower_spillway_length3}}} |
Spillway capacity | {{{lower_spillway_capacity3}}} |
Spillway volumetric flow rate | {{{lower_spillway_volumetric_flow_rate3}}} |
Lower reservoir | |
Creates | {{{lower_res_name}}} |
Total capacity | {{{lower_res_capacity_total}}} |
Active capacity | {{{lower_res_capacity_active}}} |
Inactive capacity | {{{lower_res_capacity_inactive}}} |
Catchment area | {{{lower_res_catchment}}} |
Surface area | {{{lower_res_surface}}} |
Maximum length | {{{lower_res_max_length}}} |
Maximum width | {{{lower_res_max_width}}} |
Maximum water depth | {{{lower_res_max_depth}}} |
Normal elevation | {{{lower_res_elevation}}} |
Tidal range | {{{lower_res_tidal_range}}} |
{{{plant_name}}} | |
Coordinates | 1°1′1″N 1°1′1″E / 1.01694°N 1.01694°E |
Operator(s) | {{{plant_operator}}} |
Commission date | {{{plant_commission}}} |
Decommission date | {{{plant_decommission}}} |
Type | {{{plant_type}}} |
Hydraulic head | {{{plant_hydraulic_head}}} |
Turbines | {{{plant_turbines}}} |
Pump-generators | {{{plant_pumpgenerators}}} |
Pumps | {{{plant_pumps}}} |
Installed capacity | {{{plant_capacity}}} |
Capacity factor | {{{plant_capacity_factor}}} |
Overall efficiency | {{{plant_efficiency}}} |
Storage capacity | {{{plant_storage_hours}}} |
Annual generation | {{{plant_annual_gen}}} |
Website {{{website}}} | |
{{{extra}}} |
{{Infobox dam | name = | name_official = | image = | image_size = | image_caption = | image_alt = | location_map = | location_map_size = | location_map_caption = | location_map_alt = | coordinates = <!-- {{coord|..|..|type:landmark|display=inline,title}}--> | country = | location = | purpose = | status = | construction_began = | opening = | demolished = | cost = | builder = | designed_by = | owner = | operator = | dam_type = | dam_crosses = | dam_height_foundation = | dam_height_thalweg = | dam_length = | dam_elevation_crest = | dam_width_crest = | dam_width_base = | dam_volume = | spillway_count = | spillway_type = | spillway_length = | spillway_capacity = | spillway_volumetric_flow_rate = | spillway_type2 = | spillway_length2 = | spillway_capacity2 = | spillway_volumetric_flow_rate2 = | spillway_type3 = | spillway_length3 = | spillway_capacity3 = | spillway_volumetric_flow_rate3 = | res_name = | res_capacity_total = | res_capacity_active = | res_capacity_inactive = | res_catchment = | res_surface = | res_max_length = | res_max_width = | res_max_depth = | res_elevation = | res_tidal_range = | lower_dam_type = | lower_dam_crosses = | lower_dam_height_foundation = | lower_dam_height_thalweg = | lower_dam_length = | lower_dam_elevation_crest = | lower_dam_width_crest = | lower_dam_width_base = | lower_dam_volume = | lower_spillway_count = | lower_spillway_type = | lower_spillway_length = | lower_spillway_capacity = | lower_spillway_volumetric_flow_rate = | lower_spillway_type2 = | lower_spillway_length2 = | lower_spillway_capacity2 = | lower_spillway_volumetric_flow_rate2 = | lower_spillway_type3 = | lower_spillway_length3 = | lower_spillway_capacity3 = | lower_spillway_volumetric_flow_rate3 = | lower_res_name = | lower_res_capacity_total = | lower_res_capacity_active = | lower_res_capacity_inactive = | lower_res_catchment = | lower_res_surface = | lower_res_max_length = | lower_res_max_width = | lower_res_max_depth = | lower_res_elevation = | lower_res_tidal_range = | plant_name = | plant_coordinates = <!-- {{coord|..|..|type:landmark|display=inline}}--> | plant_operator = | plant_commission = | plant_decommission = | plant_type = | plant_hydraulic_head = | plant_turbines = | plant_pumpgenerators = | plant_pumps = | plant_capacity = | plant_capacity_factor = | plant_efficiency = | plant_storage_hours = | plant_annual_gen = | plant_annual_gen_year = | website = | extra = }}
Parameter names and descriptions
ᱥᱟᱯᱲᱟᱣParameter name | Description |
---|---|
name | Name of dam. |
name_official | Official name, if different from name. Preferably in native language. |
image | Image filename, without File: parameter. Animated (.gif) and media files (.ogv) are also allowed. |
image_size | Value to overrides the default 250px. |
image_caption | Caption beneath image. |
image_alt | Alternative text for image. |
location_map | Name of a location map file. The coordinates must be specified as well (see below). |
location_map_size | Value to overrides the default 250px. |
location_map_caption | Caption beneath location map. |
location_map_alt | Alternative text for location map. |
coordinates | Geographic coordinates using {{coord}}. See here for more details. Remember to avoid being overly precise. |
country | Country where the facility is located. Do not use flag icons. |
location | General area where located. Avoid being overly-detailed. |
purpose | Purpose of the dam(s). Common reasons are power, irrigation, flood control, navigation. If there are several purposes, consider using: Multi-purpose . Field codes: F =Flood control, I =Irrigation, N =Navigation, P =Power, W =Water supply.
|
status | Current status of the project. Enter any one of the following auto-expanding fields:D =Decommissioned, O =Operational, P =Proposed, UC =Under construction.
|
construction_began | Date construction began, consider using {{Start date}}. |
opening | Date, or future date, of inauguration. Consider using {{Start date}}. |
demolished | Date of demolition (i.e. removal or destruction of dam). Consider using {{End date}}. |
cost | Total cost of development. |
builder | Builder(s) of the dam. |
owner | Owner(s) of the dam. Consider limiting to the top two, and include ownership percentage if possible. Example: Owner1: 60% <br/>Owner2: 40%
|
designed_by | Designers of the dam. |
operator | Operator(s) of the dam. Only use this parameter if it is different from the owner(s) of the dam. |
DAM AND SPILLWAYS
| |
dam_type | Type of dam. Enter any one of the following auto-expanding fields: A =Arch dam, B =Barrage, E =Embankment dam, F =Earth-fill dam, G =Gravity dam, H =Rock-fill dam,AG =Arch-gravity dam.
|
dam_crosses | Body of river or stream below dam |
dam_height | Height of dam. Deprecated parameter; use only if dam_height_foundation or dam_height_thalweg is not known.
|
dam_height_foundation | Height over foundation bed, with metric conversions. |
dam_height_thalweg | Height over thalweg (riverbed), with metric conversions. |
dam_length | Length of dam crown, with metric conversions. |
dam_elevation_crest | Height of the dam's crest above sea level, with metric conversions. |
dam_width_crest | Width at crest of dam, with metric conversions. |
dam_width_base | Width at base of dam, with metric conversions. |
dam_volume | Volume of material in the dam structure. |
spillway_count | Number of spillways. |
spillway_type | Type of spillway. |
spillway_length | Length of spillway. |
spillway_capacity | Capacity of spillway. |
spillway_volumetric_flow_rate | Spillway volumetric flow rate. |
spillway_type2 | Type of 2nd spillway. |
spillway_length2 | Length of 2nd spillway. |
spillway_capacity2 | Capacity of 2nd spillway. |
spillway_volumetric_flow_rate2 | 2nd Spillway volumetric flow rate. |
spillway_type3 | Type of 3rd spillway. |
spillway_length3 | Length of 3rd spillway. |
spillway_capacity3 | Capacity of 3rd spillway. |
spillway_volumetric_flow_rate3 | 3rd Spillway volumetric flow rate. |
RESERVOIR
| |
res_name | Name of upstream body of water, if different than "dam_crosses". |
res_capacity_total | Capacity of reservoir, i.e. megalitres. |
res_capacity_active | The active, live or useful capacity (storage) of the reservoir. |
res_capacity_inactive | The inactive or dead capacity (storage) of the reservoir. |
res_catchment | Area of catchment for reservoir. |
res_surface | Surface area (top water level) of reservoir. |
res_max_length | Length of the reservoir at normal levels, with metric conversions. |
res_max_width | Maximum width of the reservoir at normal levels, perpendicular to length. With metric conversions. |
res_max_depth | Maximum water depth of reservoir. |
res_elevation | The reservoir's height above sea level at normal levels, with metric conversions. |
res_tidal_range | Tidal range, if applicable. |
POWER STATION
| |
plant_name | Name of plant, if applicable. |
plant_coordinates | Geographic coordinates of the power station using {{coord}}. See here for more details. Remember to avoid being overly precise. |
plant_operator | Operator(s) of the hydroelectric power plant. |
plant_commission | Power plant commissioning date. May be different than dam opening date. |
plant_decommission | Power plant decommissioning date. May be different than dam closing date. |
plant_type | Type of hydroelectric power station. Enter any one of the following auto-expanding fields: C =Conventional, P =Pumped-storage, R =Run-of-the-river, T =Tidal barrage.
|
plant_hydraulic_head | Hydraulic head at power station. |
plant_turbines | Number of turbines, with respective rated capacity. Exclude any reversible turbine-generators (pump/generators) and pumps from this — it should only contain conventional generation-only turbines. |
plant_pumpgenerators | Number of reversible turbine-generators (pump/generators), with respective rated capacity. For pumped storage plants only. |
plant_pumps | Number of pumps, with respective rated capacity. For pumped storage plants only. |
plant_capacity | Current installed capacity in megawatts, or planned capacity for those under development. For plants which are operational, but have additional capacity under development, please use only the current installed capacity. |
plant_capacity_factor | Capacity factor of the power station, in percentage. For pumped storage, please try to rely solely on third-party sources, as manual capacity factor calculations are overly complex for PSH and their results do not align with figures in (authoritative) third-party sources. |
plant_efficiency | Overall efficiency of the power station, in percentage. Generally only applicable to pumped storage. |
plant_storage_hours | Storage capacity of the power station, in hours (if desired, you can also provide calculated or actual GWh figures in parenthesis). Generally only applicable to pumped storage. |
plant_annual_gen | Average annual power generation. To be used in combination with the following plant_annual_gen_year parameter. GW·h suffix will auto added for number without unit or any text appended.
|
plant_annual_gen_year | Given generation value exact description. If no description is given, it will default to Annual (i.e. it will expand to Annual generation). Enter following text:
|
website | Raw wikitext for entering website(s). Use [brackets] where appropriate |
extras | Free form, spans both columns. Use sparingly. |
Coordinates
ᱥᱟᱯᱲᱟᱣThe coordinates should be specified using coordinates – with a {{coord}} template. See Wikipedia:WikiProject Geographical coordinates#Parameters for more details about setting the coordinates_type.
Microformat
ᱥᱟᱯᱲᱟᱣThe HTML mark up produced by this template includes an hCard microformat, which makes the place-name and location parsable by computers, either acting automatically to catalogue article across Wikipedia, or via a browser tool operated by a person, to (for example) add the subject to an address book. Within the hCard is a Geo microformat, which additionally makes the coordinates (latitude & longitude) parsable, so that they can be, say, looked up on a map, or downloaded to a GPS unit. For more information about the use of microformats on Wikipedia, please see the microformat project.
If the place or venue has an "established", "founded", "opened" or similar date, use {{Start date}} (unless the date is before 1583 CE).
If it has a URL, use {{URL}}.
hCard uses HTML classes including:
- adr
- agent
- category
- county-name
- extended-address
- fn
- label
- locality
- nickname
- note
- org
- region
- street-address
- url
- vcard
Geo is produced by calling {{coord}}, and uses HTML classes:
- geo
- latitude
- longitude
Please do not rename or remove these classes; nor collapse nested elements which use them.
When giving coordinates, please don't be overly precise.
Tracking category
ᱥᱟᱯᱲᱟᱣSee also
ᱥᱟᱯᱲᱟᱣᱪᱷᱟᱸᱪ:Buildings and structures infobox templates
TemplateData
ᱥᱟᱯᱲᱟᱣTemplateData for Infobox dam
Infobox for a dam
Parameter | Description | Type | Status | |
---|---|---|---|---|
Name | name | Name of dam | String | optional |
Official name | name_official | Official name, if different from name. Preferably in native language. | String | optional |
Image caption | image_caption | Caption beneath image. | String | optional |
Image alternative text | image_alt | Alternative text for image. | String | optional |
Location map caption | location_map_caption | Caption beneath location map. | String | optional |
Location map alternative text | location_map_alt | Alternative text for location map. | String | optional |
coordinates | coordinates | Geographic coordinates using the coord template | String | optional |
Country | country | Country where the facility is located. Do not use flag icons. | String | optional |
Location | location | General area where located. Avoid being overly-detailed. | String | optional |
Purpose | purpose | Purpose of the dam(s). Common reasons are power, irrigation, flood control, navigation. If there are several purposes, consider using: Multi-purpose. Field codes: F=Flood control, I=Irrigation,, N=Navigation, P=Power. | String | optional |
Status | status | Current status of the project. Enter any one of the following auto-expanding fields: D=Decommissioned, O=Operational, P=Proposed, UC=Under construction. | String | optional |
Construction began | construction_began | Date construction began, consider using {{Start date}}. | String | optional |
Opening date | opening | Date, or future date, of inauguration. Consider using {{Start date}}. | String | optional |
Demolished date | demolished | Date of demolition (i.e. removal or destruction of dam). Consider using {{End date}}. | String | optional |
Cost | cost | Total cost of development. | String | optional |
Owner | owner | Owner(s) of the dam. Consider limiting to the top two, and include ownership percentage if possible.
| String | optional |
Operator | operator | Operator(s) of the dam. Only use this parameter if it is different from the owner(s) of the dam. | String | optional |
Dam type | dam_type | Type of dam. Enter any one of the following auto-expanding fields: A=Arch dam, B=Barrage, E=Embankment dam, F=Earth-fill dam, G=Gravity dam, AG=Arch-gravity dam. | String | optional |
Dam crosses | dam_crosses | Body of river or stream below dam | String | optional |
Dam height over foundation | dam_height_foundation | Height over foundation bed, with metric conversions. | String | optional |
Dam height over thalweg | dam_height_thalweg | Height over thalweg (riverbed), with metric conversions. | String | optional |
Dam length | dam_length | Length of dam crown, with metric conversions. | String | optional |
Dam elevation crest | dam_elevation_crest | Height of the dam's crest above sea level, with metric conversions. | String | optional |
Dam width crest | dam_width_crest | Width at crest of dam, with metric conversions. | String | optional |
Dam width at base | dam_width_base | Width at base of dam, with metric conversions. | String | optional |
Dam volume | dam_volume | Volume of material in the dam structure. | String | optional |
Spillway count | spillway_count | Number of spillways. | Number | optional |
Spillway type | spillway_type | Type of spillway. | String | optional |
Spillway capacity | spillway_capacity | Capacity of spillway. | String | optional |
Reservoir name | res_name | Name of upstream body of water, if different than "dam_crosses". | String | optional |
Reservoir capacity | res_capacity_total | Capacity of reservoir, i.e. megalitres. | String | optional |
Reservoir active capacity | res_capacity_active | The active, live or useful capacity (storage) of the reservoir. | String | optional |
Reservoir inactive capacity | res_capacity_inactive | The inactive or dead capacity (storage) of the reservoir. | String | optional |
Reservoir catchment area | res_catchment | Area of catchment for reservoir. | String | optional |
Reservoir surface area | res_surface | Surface area (top water level) of reservoir. | String | optional |
Reservoir maximum length | res_max_length | Length of the reservoir at normal levels, with metric conversions. | String | optional |
Reservoir maximum width | res_max_width | Maximum width of the reservoir at normal levels, perpendicular to length. With metric conversions. | String | optional |
Reservoir maximum depth | res_max_depth | Maximum water depth of reservoir. | String | optional |
Reservoir elevation | res_elevation | The reservoir's height above sea level at normal levels, with metric conversions. | String | optional |
Reservoir tidal range | res_tidal_range | Tidal range, if applicable. | String | optional |
Plant name | plant_name | Name of plant, if applicable. | String | optional |
Plant operator | plant_operator | Operator(s) of the hydroelectric power plant. | String | optional |
Plant coordinates | plant coordinates | Geographic coordinates of the power station using the coord template | String | optional |
Plant commissioning date | plant_commission | Power plant commissioning date. May be different than dam opening date. | String | optional |
Plant decommissioning date | plant_decommission | Power plant decommissioning date. May be different than dam closing date. | String | optional |
Plant type | plant_type | Type of hydroelectric power station. Enter any one of the following auto-expanding fields: C=Conventional, P=Pumped-storage, R=Run-of-the-river, T=Tidal barrage. | String | optional |
Plant hydraulic head | plant_hydraulic_head | Hydraulic head at power station. | String | optional |
Plant turbine count/capacity | plant_turbines | Number of turbines, with respective rated capacity. | String | optional |
Plant generation capacity | plant_capacity | Installed generation capacity, measured in megawatts (MW). | String | optional |
Plant capacity factor | plant_capacity_factor | Capacity factor of the power station, in percentage. | String | optional |
Plant annual power generation | plant_annual_gen | Average annual power generation of the previous year. Measured in gigawatt-hours (GWh) | String | optional |
Website | website | Raw wikitext for entering website(s). Use [brackets] where appropriate | Content | optional |
Extra data | extra | Free form, spans both columns. Use sparingly. | String | optional |