section-ref

Usually a reference to a section to which this element's owning content item (content element) belongs. Since a content item can belong to many sections, a content element may contain many section-ref elements.

A section-ref element may, however, also appear as the child of a collection field element, in which case it usually references a section that has been interactively selected by an end user (a Content Studio user, for example).

A section can be referenced using any of the following attributes:

  • id-ref

  • source and source-id

  • dbid

  • unique-name

Import considerations

The referenced section must either be defined prior to this element in the syndication file or else already exist in the target publication.

Syntax
<section-ref
    id-ref="text"?
    publication-name="text"?
    (source="text" sourceid="text")?
    dbid="text"?
    unique-name="text"?
    todesk="(true|false)"?
    home-section="(true|false)"?
  />
Examples
  • This example imports an "image" content item. It includes a reference to a section to which the content item is to belong. This section is set to be the content item's home section. The referenced section must already exist in the database or appear before this content element in the syndication file.

    Note the use of JSON syntax to include soft crop information in the representations field. For more information about this, see Importing Soft Crop Definitions.

    <content source="ex" sourceid="20" type="picture" state="published">
      <section-ref source="ex" sourceid="s2" home-section="true"/>
      <field name="title">Croc</field>
      <field name="caption">A Croc on the beach</field>
      <field name="binary" title="crocodile">/tmp/escenic/import/croc.jpg</field>
      <field name="representations">
          {
            "thumbnail":
              {
                "crop":
                  {
                    "width":400,
                    "height":400,
                    "x":0,
                    "y":54
                  }
              },
            "narrow":
              {
                "crop":
                  {
                    "width":250,
                    "height":200,
                    "x":0,
                    "y":54
                  }
              },
            "wide":
              {
                "crop":
                  {
                    "width":400,
                    "height":400,
                    "x":102,
                    "y":100
                  }
              }
          }
        </field>
    </content>
  • This example imports a content item and inserts it into four different sections, two of which belong to a different publication. One of the local sections is set to be the content item's home section. In addition, one of the remote sections is set to be the content item's home section in that publication.

    <content source="ex" sourceid="99" type="news" state="published">
      <section-ref unique-name="sports" home-section="true"/>
      <section-ref unique-name="ece_frontpage"/>
      <section-ref unique-name="sports" home-section="true" publication-name="other"/>
      <section-ref unique-name="ece_frontpage" publication-name="other"/>
      <field name="title">Local Cup Fiasco</field>
      <field name="leadtext">...</field>
      <field name="body">...</field>
    </content>
Attributes
id-ref="text" (optional)

The id of the section to which the content item represented by the owning content element belongs/is to be added. If this attribute is specified, a section element with an id attribute that matches this attribute must appear somewhere before this section-ref element in the syndication file.

If dbid or source and sourceid are specified, then this attribute is ignored.

publication-name="text" (optional)

The name of the publication to which the referenced content item or section belongs. This attribute may only be used in combination with the source and source-id attributes. It is needed to ensure unique identification in situations where cross-publishing is in use and the referenced content item or section does not belong to the current publication.

source="text" (optional)

The source of the section to which the content item represented by the owning content element belongs/is to be added. If this attribute is specified, then sourceid must also be specified. One of the following two conditions must be satisfied:

  • The target publication must already contain a section with source and sourceid attributes that match source and sourceid, or

  • A section element with source and sourceid attributes that match source and sourceid must appear somewhere before this section-ref element in the syndication file.

If dbid is specified, then source and sourceid are ignored.

sourceid="text" (optional)

The sourceid of the section to which the content item represented by the owning content element belongs/is to be added. If this attribute is specified, then source must also be specified. One of the following two conditions must be satisfied:

  • The target publication must already contain a section with source and sourceid attributes that match source and sourceid, or

  • A section element with source and sourceid attributes that match source and sourceid must appear somewhere before this section-ref element in the syndication file.

If dbid is specified, then source and sourceid are ignored.

dbid="text" (optional)

The dbid of the section to which the content item represented by the owning content element belongs/is to be added. If this attribute is specified then one of the following two conditions must be satisfied:

  • The target publication must already contain a section with a dbid attribute that matches this attribute, or

  • A section element with a dbid attribute that matches this attribute must appear somewhere before this section-ref element in the syndication file.

unique-name="text" (optional)

The unique-name or name of the section to which the content item represented by the owning content element belongs/is to be added. If this attribute is specified, then one of the following conditions must be satisified:

  • The target publication must already contain a section with a uniquename or name attribute that matches this attribute, or

  • A section element with a unique-name or name attribute that matches this attribute must appear somewhere before this section-ref element in the syndication file.

If this is not the case, or if there is a matching name attribute but it is not unique, then import will fail.

If dbid or source and sourceid or id are specified, then this attribute is ignored.

todesk="(true|false)" (optional)

If set to true, then content item represented by the owning content element is added to this section's default inbox (INBOX).

home-section="(true|false)" (optional)

If set to true then this section is the home section of the content item represented by the owning content element. If the publication-name attribute is also specified, then this section is the content item's local home section in the named publication.