View source for Documentation:MDrivenDesignerPropertyInspectorHints

You can use this page to maintain the plain-text help that [[Documentation:MDriven designer overview Part 1|MDriven Designer]] shows for individual properties in the Property Inspector.
== Purpose ==
MDriven Designer fetches this page to obtain additional information for properties displayed in the [[Documentation:MDriven Designer Features & Settings|Property Inspector]]. The information helps a modeler understand a property while viewing or editing the selected model element.

This page is a data source for MDriven Designer. Write entries in the required key-and-value form so that Designer can identify the property and display its help text.
== How property hints work ==
When you select an element in MDriven Designer, the Property Inspector shows the properties available for that element. If Designer finds a matching hint entry on this page, it can show the corresponding explanatory text.

For example, an entry whose key identifies a property named <code>ExampleProperty</code> provides the text that Designer can show for that property. The key is also visible in MDriven Designer, so choose a name that identifies the property clearly.
== Authoring rules ==
Follow these rules for every property-hint entry:

{| class="wikitable"
! Rule
! What to do
|-
| Key prefix
| Start every key with <code>#</code>.
|-
| Letter case
| Keys are case-insensitive.
|-
| Key visibility
| The key is shown in MDriven Designer. Use a clear, stable property identifier.
|-
| Hint text
| Use plain text. Do not rely on wiki links, formatting, or other markup in the value; Designer does not render that markup correctly unless it has specific handling for it.
|}
== Add or update a hint ==
# Identify the Property Inspector property that needs clarification.
# Create or locate its entry on this page.
# Ensure that the key starts with <code>#</code>.
# Write a short plain-text explanation that tells the modeler what the property affects and, where useful, what value to enter.
# Save the page.
# Open MDriven Designer and verify that the key and its text appear as expected for the relevant property.
=== Example structure ===
The following is an illustrative structure only. The key must match the property identifier that MDriven Designer expects.

<syntaxhighlight lang="text">
#ExampleProperty
Explains what ExampleProperty controls and when you should set it.
</syntaxhighlight>

Keep the displayed text focused on the property. For example, describe the effect of a setting rather than documenting an entire modeling workflow in the hint.

Here are examples of property-hint entries formatted as key-value pairs:
{| class="wikitable"
!#Class.Prop
!Description
|-
|#aaa.bbb
|Longish description without markup
|-
|#attribute.codecomment
|A short documentation is available for your usage
|-
|#attribute.HasUserCode
|When used in MDriven Framework, this flag set will route all access through the code accessor that has partial methods implementation that can be implemented by you. 
|-
|#attribute.SetterVisibility
|Attributes are default public - both set and get - this property allows you to change the visibility of the set operator
|-
|#attribute.column name
|This is the name the column in the database will get - by default it is the same as the attribute - this is achieved by stating <Name>
|-
|#attribute.defaultDBValue
|When attributes are added to classes that already have data in a database - and if this attribute does not allow null - then we need to supply what default value existing rows should have. Common for state attributes: 'SomeState' [[DefaultDBValue|See also: DefaultDBValue]]
|-
|#attribute.Delayed Fetch
|If set to True, the attribute's data will not be fetched at once with the rest of the object's attributes. It will only be fetched on explicit use. Usually used BLOB och Image attributes.
|-
|#attribute.FormerNames
|Used during the evolution of the database. If a former name is specified, data will be migrated to the new name from the specified old name.
|-
|#association.derived
|A derived association is like a calculated relation between classes. You enter the DerivationOcl for one or both ends of the association, as wanted. It is always updated using a subscription to changes
|-
|#associationend.derivationocl
|An OCL statement that "calculates" the resulting item or collection for the association
|-
|#associationend.aggregation
|This sets how "tight" in a business sense a class is to another. Note that if you set Composite, deleting the owning class object deletes the owned object
|-
|#associationend.effectivename
|This is the used name. It's either the default name or the specifically set name in "Name"
|-
|#associationend.ordering
|Designates as an ordered or unordered collection of objects in the association. This is not to be confused with the orderBy OCL operator.
|-
|#associationend.embed
|Controls where database keys are placed. If true, a key attribute will be placed in the "begin end" of the association pointing to this class object id
|-
|#associationend.saveaction
|Describes how the first value is set and if it can change. None: No special action. Freeze: Save the first time, changes are not allowed. DbAssign: It's up to the database engine to maintain the association
|-
|#attribute.attributemode
|Derived uses OCL to calculate value. DerivedSettable uses EAL to reverse-derive the value from for example a string. See "Derived Settable" in the wiki.
|-
|#attribute.derivationocl
|OCL to calculate the attribute's value. See "Derived Settable" in the wiki.
|-
|#attribute.derivationoclset
|EAL to reverse-derive the value from for example a string. See "Derived Settable" in the wiki.
|-
|#attribute.presentationunit
|UI engines typically use this to render the unit of measure in the label like Presentation(Kg)
|}
== Write useful hint text ==
A good hint answers the question a modeler has at the moment they inspect the property:

* State what the property controls.
* State when the modeler should set it.
* Include an example value only when the valid value format is known.
* Keep the text short enough to be useful in the Property Inspector.
* Use terminology consistently with MDriven Designer.

Do not place wiki markup, internal links, or formatted examples in a hint value unless Designer is known to support that exact rendering. Plain text is the safe format.
== Property hints and tagged-value hints ==
Property Inspector hints are not the same as tagged-value help. Use this page for information associated with properties shown in the Property Inspector. Maintain the list and usage guidance for tagged values in [[Documentation:MDrivenDesignerTaggedValueHints]].

For how the tagged-value editor downloads and presents its help, see [[Documentation:Tagged values in the Designer]].
== See also ==
* [[Documentation:MDriven Designer Features & Settings]]
* [[Documentation:Tagged values in the Designer]]
* [[Documentation:MDrivenDesignerTaggedValueHints]]

[[Category:Intermediate-Friendly]]
[[Category:MDriven Designer]]
[[Category:Priority 50]]