<permStart> (Range Permission Start)

This element specifies the start of a range permission within a WordprocessingML document. This start marker is matched with the appropriately paired end marker by matching the value of the @id attribute from the associated <permEnd> element.

If no <permEnd> element exists subsequent to this element in document order with a matching @id attribute value, then this element is ignored and no range permission is present in the document.

If a range permission begins and ends within a single table, it is possible for that permission to cover discontiguous parts of that table which are logically related (e.g. a single column in a table). This type of placement for a range permission is accomplished (and described in detail) on the @colFirst and @colLast attributes on this element.

example: 
<w:p>
  <w:r>
    <w:t xml:space="preserve">This is sentence one.</w:t>
  </w:r>
  <w:permStart w:id="0" w:edGrp="everyone"/>
  <w:r>
    <w:t>This is sentence two.</w:t>
  </w:r>
</w:p>
<w:p>
  <w:r>
    <w:t xml:space="preserve">This </w:t>
  </w:r>
  <w:permEnd w:id="0"/>
  <w:r>
    <w:t>is sentence three.</w:t>
  </w:r>
</w:p>

The <permStart> element specifies the start of the region for the range permission. This element is then linked to the <permEnd> element which also has an @id attribute value of 0. ]

Parent Elements

<body> (§2.2.2); <comment> (§2.13.4.2); <customXml> (§2.5.1.3); <customXml> (§2.5.1.4); <customXml> (§2.5.1.5); <customXml> (§2.5.1.6); <deg> (§7.1.2.26); <del> (§2.13.5.12); <den> (§7.1.2.28); <docPartBody> (§2.12.6); <e> (§7.1.2.32); <endnote> (§2.11.2); <fldSimple> (§2.16.21); <fName> (§7.1.2.37); <footnote> (§2.11.10); <ftr> (§2.10.3); <hdr> (§2.10.4); <hyperlink> (§2.16.24); <ins> (§2.13.5.20); <lim> (§7.1.2.52); <moveFrom> (§2.13.5.21); <moveTo> (§2.13.5.26); <num> (§7.1.2.75); <oMath> (§7.1.2.77); <p> (§2.3.1.22); <rt> (§2.3.3.23); <rubyBase> (§2.3.3.26); <sdtContent> (§2.5.2.32); <sdtContent> (§2.5.2.33); <sdtContent> (§2.5.2.34); <sdtContent> (§2.5.2.35); <smartTag> (§2.5.1.9); <sub> (§7.1.2.112); <sup> (§7.1.2.114); <tbl> (§2.4.36); <tc> (§2.4.62); <tr> (§2.4.75); <txbxContent> (§2.17.1.1)

Attributes

Description

<colFirst> (First Table Column Covered By Range Permission)

Specifies the zero-based index of the first column in this row which shall be part of this range permission.

When a range permission is contained within a table, it is possible for that range permission to only cover cells within a certain column and row range within that table, by specifying:

  • The first row for which the specified columns are part of the table range permission. This is accomplished by placing the <permStart> element in the first table cell in that row.

  • The first column included in the range permission for each of the specified row(s) via this attribute.

  • The last column included in the range permission for each of the specified row(s) via the @colLast attribute.

  • The last row for which the specified columns are part of the table range permission. This is accomplished by placing the <permEnd> element at the end of that table row.

If this attribute appears, then the @colLast attribute must also appear (regardless of where this bookmark is located) or the document shall be considered non-conformant. If this attibute and its pair occur on a range permission which is not contained in a table, then their values should be ignored. If this value exceeds the value of @colLast or the number of columns in the table, then both values should be ignored.

This bookmark would be specified using the following WordprocessingML for the table's conents:

<w:tbl>
  …
  <w:tr>
    <w:tc>
      <w:permStart w:colFirst="0" w:colLast="1" w:id="0" w:edGrp="everyone"/>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
  </w:tr>
  <w:tr>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:permEnd w:id="0" />
  </w:tr>
  <w:tr>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
  </w:tr>
</w:tbl>

The @colFirst attribute specifies that all columns starting with the first column shall be included in the table range permission. This will apply starting with the first row and ending with the second row (the two rows within the range permission's start and end). ]

The possible values for this attribute are defined by the ST_DecimalNumber simple type (§2.18.16).

<colLast> (Last Table Column Covered By Range Permission)

Specifies the zero-based index of the last column in this row which shall be part of this range permission.

When a range permission is contained within a table, it is possible for that range permission to only cover cells within a certain column and row range within that table, by specifying:

  • The first row for which the specified columns are part of the table range permission. This is accomplished by placing the <permStart> element in the first table cell in that row.

  • The first column included in the range permission for each of the specified row(s) via the @colFirst attribute.

  • The last column included in the range permission for each of the specified row(s) via this attribute.

  • The last row for which the specified columns are part of the table range permission. This is accomplished by placing the <permEnd> element at the end of that table row.

If this attribute appears, then the @colFirst attribute must also appear (regardless of where this bookmark is located) or the document shall be considered non-conformant. If this attibute and its pair occur on a bookmark which is not contained in a table, then their values should be ignored. If this value does not equal or exceed the value of @colFirst or the number of columns in the table, then both values should be ignored.

This bookmark would be specified using the following WordprocessingML for the table's conents:

<w:tbl>
  …
  <w:tr>
    <w:tc>
      <w:permStart w:colFirst="0" w:colLast="1" w:id="0" w:edGrp="everyone"/>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
  </w:tr>
  <w:tr>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:permEnd w:id="0" />
  </w:tr>
  <w:tr>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:p/>
    </w:tc>
  </w:tr>
</w:tbl>

The @colLast attribute specifies that the last column that shall be included in the table range permission is the second column. This will apply starting with the first row and ending with the second row (the two rows within the range permission's start and end). ]

The possible values for this attribute are defined by the ST_DecimalNumber simple type (§2.18.16).

<displacedByCustomXml> (Annotation Displaced By Custom XML Markup)

Specifies that the parent annotation's placement shall be directly linked with the location of the physical presentation of a custom XML element in the document. This element only has an effect when the custom XML element is block-level (i.e. surrounds an entire paragraph), as in this scenario the logical and physical placement of the annotation and custom XML element may differ.

Specifically, in this case, the custom XML is presented *around* the block-level object it encloses (the paragraph, table, table row, or table cell), but is physically represented within that same object (i.e. within the paragraph, table, table row or table cell). This requirement stems from the fact that there is no location for the location of the annotation within the document at its logical location (around a table, for example).

If this element is omitted, then the annotation shall be anchored inside of all block-level custom XML elements in the paragraph. If this element is present, but no block-level custom XML tag is located at the position it specifies (before or after), then it shall be ignored.

Since all three of these items are around the entire paragraph, they are stored outside of the paragraph. However, in order to ensure that their relative positions are stored correctly, any annotation which shall be displaced by the physical custom XML element specifies this information, resulting in the following WordprocessingML:

<w:commentRangeStart w:id="0" />
<w:commentRangeStart w:id="1" w:displaced byCustomXml="next" />
<w:customXml w:element="spec" … />
<w:p>
  …
</w:p>

The @displacedByCustomXml attribute specifies that even though all three of these items are around the paragraph and will be moved inside the paragraph to be represented physically, the comment with ID 0 shall be inside the custom XML, but the comment with ID 1 shall be displaced to stay outside of the relative location of the next custom XML element (the spec element). ]

The possible values for this attribute are defined by the ST_DisplacedByCustomXml simple type (§2.18.17).

<ed> (Single User For Range Permission)

Specifies a single user for which this range permission shall be enabled (i.e. a user which shall be able to edit this range when document protection is enabled).

This editor can be stored in one of the following forms:

  • DOMAIN\username - for users whose access shall be authenticated using the current user's domain credentials

  • user@domain.com - for users whose access shall be authenticated using the user's e-mail address as credentials

  • user - for users whose access shall be authenticated using the current user's machine credentials 

<w:permStart w:id="0" w:ed="example@contoso.com" … />
…
<w:permEnd w:id="0" />

The @ed attribute value of example@contoso.com specifies that only user(s) who can authenticate with an application as associated with that e-mail address shall be allowed to edit the contents between the start and end markers when document protection is being enforced. ]

The possible values for this attribute are defined by the ST_String simple type (§2.18.89).

<edGrp> (Editor Group For Range Permission)

Specifies an alias (or editing group) which shall be used to determine if the current user shall be allowed to edit this range of the document. This mechanism simply provides a set of predefined editing groups which may be associated with user accounts by applications in any desired manner.

<w:permStart w:id="0" w:edGrp="editors" … />
…
<w:permEnd w:id="0" />

The @edGrp attribute value of editors specifies that only user(s) who the current application associates with the editors group shall be allowed to edit the contents between the start and end markers when document protection is being enforced. ]

The possible values for this attribute are defined by the ST_EdGrp simple type (§2.18.25).

<id> (Annotation ID)

Specifies a unique identifier for an annotation within a WordprocessingML document. The restrictions on the @id attribute, if any, are defined by the parent XML element.

If this attribute is omitted, then the document is non-conformant.

<w:… w:id="1" … >
  …
</w:…>

The <id> attribute specifies that the ID of the current annotation is 1. This value is used to uniquely identify this annotation within the document content. ]

The possible values for this attribute are defined by the ST_String simple type (§2.18.89).

The following XML Schema fragment defines the contents of this element:

<complexType name="CT_PermStart">
	<complexContent>
	<extension base="CT_Perm">
	<attribute name="edGrp" type="ST_EdGrp" use="optional"/>
	<attribute name="ed" type="ST_String" use="optional"/>
	<attribute name="colFirst" type="ST_DecimalNumber" use="optional"/>
	<attribute name="colLast" type="ST_DecimalNumber" use="optional"/>
	</extension>
	</complexContent>
</complexType>