Previous page Section 4.4. Rich media content Section 5. Content inclusion (12 / 14)   Table of Contents Section 5.3. The implementation of transclusion in XMLmind XML Editor. Next page

5. Content inclusion Previous topic Parent topic Child topic Next topic

In the next two sections, we'll learn how to reference in topic A some contents found in a topic B. We'll first learn how to do it the easy way by using Copy as Reference/Paste. Then, for those who prefer to control everything to the finest degree, we'll learn how to achieve the same results using a low-level method.

5.1. Easy content inclusion Previous topic Parent topic Child topic Next topic

Before you begin

The transclusion of elements having a @conref attribute must be turned on (which is the case by default).
Note
Note
As of XMLmind XML Editor v4.9, it's possible to completely turn off the transclusion of conref by using menu item Options → Customize Configuration → Conref Transclusion. Note that this user preference is specified separately for topics and for maps.

About this task

The @conref attribute of an element allows to reference the contents (text, child elements, some of the attributes) of another element.
Instead of just seeing an empty element having a @conref attribute (that is, the ``pointer''), it is nicer to see the referenced contents. This process is called transclusion and XMLmind XML Editor can do it for you.
Note
Note
Everything explained here should also work for DITA maps.
Note
Note
The following procedure (Copy as Reference then Paste) is not specific to DITA. The same procedure could be used to add references to DocBook or XHTML documents. This is why it is explained in great details in our tutorial Opens in new window.

Procedure

  1. Open in XMLmind XML Editor the topic containing the element you want to reference.
  2. Select this element.
    Let's call this element the conref target.
    conref_source.gif
  3. If this selected element has no @id attribute, specify one using the Attributes tool.
  4. If you want to reference a range of nodes rather a single element, extend the selection (Select → Extend Selection to Following Sibling, Esc Right-Arrow) to some nodes following this first selected element.
    Just make sure that the end of the node range is an element having the same type as the first selected element and that this end of range element has an @id attribute.
  5. Press Ctrl+Shift-C (Edit → Reference → Copy as Reference).
    You'll see the name of the element copied as reference displayed in dimmed blue at the bottom right of XMLmind XML Editor main window.
    clipboard.gif
  6. Switch to the topic where you want to create the reference.
  7. Use Ctrl-U (Edit → Paste Before), Ctrl-V (Edit → Paste) or Ctrl-W (Edit → Paste After) to paste a reference to the conref source.
    Let's call this pasted reference the conref source.
    transcluded_conref_target.gif
  8. Sometimes, you'll want to add attributes which are specific to the conref source (typically an @id attribute). In such case:
    1. Select the conref source.
    2. Use Edit → Reference → Untransclude to un-transclude the conref source.
      You'll see an element having the same name as the conref source but having no content and having a @conref attribute pointing the conref target.
    3. Use the Attributes tool to specify one or more attributes.
    4. Use Edit → Reference → Retransclude to re-transclude the conref source.

Related information

‣ Section 5.2. Content inclusion: an alternative, low-level, method

5.2. Content inclusion: an alternative, low-level, method Previous topic Parent topic Child topic Next topic

Procedure

  1. Insert the element (the conref source) you wish to transform into a reference to another element contained elsewhere (the conref target).
    You may use Ctrl-H (Edit → Insert Before), Ctrl-I (Edit → Insert) or Ctrl-J (Edit → Insert After) to do this.
  2. Using the Attributes tool, specify a @conref attribute for the conref source.
    Specifying a value “by hand” for the @conref attribute is tedious and error-prone. That's why using this method rather than the easy one described in Section 5.1. Easy content inclusion is not recommended.
  3. If you want to reference a range of nodes rather a single element, use to Attributes tool to also give a @conrefend attribute to the conref source.
  4. Specify other attributes, for example an @id attribute, if you want.
  5. Use Edit → Reference → Retransclude to transclude the conref source.

Related information

‣ Section 5.1. Easy content inclusion

Previous page Section 4.4. Rich media content Section 5. Content inclusion (12 / 14)   Table of Contents Section 5.3. The implementation of transclusion in XMLmind XML Editor. Next page