View source for Documentation:Part 7 Files and images in reports and UI

You can model images and files, present them in a [[Documentation:ViewModel|ViewModel]], place images in OpenDocument reports, and publish your model as an XPS documentation file; this page is for MDriven Designer users building the rental-model example.

<html>
<h4>
  Take a look at images and files in the UI and in reports and Word on extended documentation. Create an overview of the model
    XPS file report. 
</h4>
<p  class="video-warn" >
  <em>To make your experience smooth, we set the main tags mentioned in the video to the right bar menu of this mini-player. Choose an interesting subtitle on the list and immediately get to the exact theme navigation item place in the video. Now you can pick any topic to be instructed on without watching the whole video.</em>
</p>
<div class="video">
  <div class="video__wrapper">
<iframe src="https://www.youtube.com/embed/yBcKVm9O1GU?rel=0&autoplay=0" frameborder="0" allowfullscreen></iframe>
</div>
<div class="video__navigation">
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="22" tabindex="0"> Blob type attribute </span>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="134" tabindex="0"> Image in UI </span>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="498" tabindex="0"> Image in the report</span>
  <h5>Documentation:</h5>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="841" tabindex="0"> Code comment </span>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="925" tabindex="0"> Documentation Tab </span>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="1045" tabindex="0">Publish Documentation Function </span>
  <span class="navigation-item" data-video="yBcKVm9O1GU" data-start="1085" tabindex="0"> XPS file: overview of the model </span>
== What you will create ==
In this part, a <code>House</code> has a <code>Picture</code> attribute. You add that picture to a House ViewModel, upload an image in the prototype, and use the same value in a report.

You also add descriptions to model elements and publish an overview of the model as an XPS file.
== Model an image or file with BLOB ==
A '''BLOB''' is an attribute that holds binary data, such as an image or a document. The BLOB type tells a client how it should present the data; it does not change the fact that the value is binary data.

# In MDriven Designer, select the class that should own the data. For example, select <code>House</code>.
# Add an attribute and name it <code>Picture</code>.
# Set the attribute type to '''BLOB'''.
# Set the BLOB type to '''Image'''.

When you set BLOB type to Image, a ViewModel can treat the value as an image. If the attribute contains another kind of file, leave it as a regular BLOB instead.

{| class="wikitable"
! BLOB type
! Intended content
! Expected presentation
|-
| Image
| Image binary data, such as the <code>House.Picture</code> example
| An image presentation and, when editing is allowed, a control for choosing a replacement image.
|-
| BLOB
| A general binary file
| A control for uploading a file or a link for downloading it; the file has no visual image representation.
|-
| XML
| XML binary data
| The WPF prototype attempts to inspect compliant XML and render it.
|}

For a broader introduction to types and image settings, see [[Documentation:Types, images, value stores, pick lists]].
== Show an image in the UI ==
Add the BLOB attribute to the ViewModel that presents its owning object.

# Open the House ViewModel.
# Add the <code>Picture</code> attribute as a ViewModel column.
# Resize the column or its UI area so that the image has enough room to display.
# Remove the column presentation text when a label is not useful for the image.
# Refresh the prototype, open a House, and use the displayed selection control to upload an image.
# Save the changed object. The BLOB data is now stored on <code>House.Picture</code>.

A non-read-only image column allows the user to change the image. A read-only expression removes the control used to edit the picture, so the image is presented without upload capability.

The same pattern applies to ordinary files: add the BLOB attribute to the ViewModel and allow editing when users must upload a replacement. The dedicated Turnkey behavior, including file names, content types, download links, external storage, and multiple-file upload, is documented in [[HowTos:Upload and Download Files and Images in MDriven Turnkey]].
=== Image values reached through an expression ===
When a ViewModel column reaches image bytes through an expression rather than directly through an Image BLOB attribute, Turnkey cannot infer that the bytes represent an image. Add the <code>Eco.BlobType=Image</code> tagged value to that ViewModel column. See [[HowTos:Upload and Download Files and Images in MDriven Turnkey]] for the complete Turnkey procedure.
== Put an image in an OpenDocument report ==
You can replace a placeholder image in an OpenDocument word-processing template with an image BLOB exposed by the report ViewModel.

# Create or open the report template described in [[Documentation:Part 6 openDocument reports]].
# Insert a placeholder image at the position where the report image should appear.
# Open the placeholder image's '''Format Picture''' settings.
# Set its '''Alt Text''' to the tag for the image BLOB column. For the rental example, use the tag that resolves to <code>Picture</code> from the report's current context.
# Save the template.
# Ensure that the report ViewModel can navigate from its starting object to the object that owns the image.
# Generate the report and verify that the placeholder is replaced by the image data.

For example, if a rent bill starts at a billable period and the desired image belongs to the rented apartment's house, the expression must navigate from the current report object. Use an expression based on <code>self</code>, such as <code>self.LeaseContract.RentedApartments.Picture</code>, when that is the intended single navigation path.

Do not use an expression beginning with <code>BillablePeriod.allInstances</code> for this purpose. That expression produces a collection of pictures, not the picture for the current report object. A report image placeholder requires the value reached from the report context.

OpenDocument reports can combine simple values, images, and tables. Tables can also be arranged to create more complex layouts. For template tags, report setup, formatting, and image aspect-ratio behavior, see [[Training:Microsoft office and OpenDocument as a Report generator]] and [[Documentation:OpenDocument]].
== Document the model ==
Documenting classes, attributes, methods, associations, and diagram elements makes the model usable as an architecture document as well as an implementation model.
=== Add short code comments ===
Use a code comment for a concise explanation close to the modeled element.

* On <code>House</code>, describe the business meaning of the class, for example: <code>Place where tenants live.</code>
* On <code>Picture</code>, describe the value, for example: <code>Image of the house at its address.</code>
* On an association end such as <code>Owner</code>, describe the role, for example: <code>Owner of this house.</code>

Code comments are included in the published model overview.
=== Add diagram documentation ===
Use the '''Documentation''' tab when you need richer text for a selected diagram element.

# Select an element in a diagram, such as the <code>House</code> class or a location element.
# Open the '''Documentation''' tab.
# Enter the explanatory text and apply the available rich-text formatting when needed.
# Select another element to document it separately. The tab shows the text for the current selection.

For example, document a location with <code>Geographical place.</code> and document the House class with the business description used by your team.
== Publish an XPS model overview ==
Publish documentation when you need a shareable overview of the model's diagrams, documentation text, and code comments.

# Right-click a class in the model.
# Choose '''Screen Functions'''.
# Choose '''Publish Documentation'''.
# Choose the output location when MDriven Designer prompts you to save.
# Open the generated XPS file and review the diagrams, rich documentation, and code comments.

The resulting XPS file is a model overview, suitable for reviewing the architecture and the explanations attached to its elements.
== See also ==
* [[Documentation:Part 6 openDocument reports]]
* [[Training:Microsoft office and OpenDocument as a Report generator]]
* [[HowTos:Upload and Download Files and Images in MDriven Turnkey]]
* [[Documentation:Types, images, value stores, pick lists]]
* [[Documentation:PDF]]

[[Category:Data Import & Export]]
[[Category:Exporting Data and Reports (Excel, PDF)]]
[[Category:Integration]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 60]]