.. include:: header.rst .. _Xml: ================ Xml ================ .. role:: htmlTag(emphasis) * New in v1.21.0 This represents an HTML or an XML node. It is a helper class intended to access the DOM (Document Object Model) content of a :ref:`Story` object. There is no need to ever directly construct an :ref:`Xml` object: after creating a :ref:`Story`, simply take :attr:`Story.body` -- which is an Xml node -- and use it to navigate your way through the story's DOM. ================================ =========================================================================================== **Method / Attribute** **Description** ================================ =========================================================================================== :meth:`~.add_bullet_list` Add a :htmlTag:`ul` tag - bulleted list, context manager. :meth:`~.add_codeblock` Add a :htmlTag:`pre` tag, context manager. :meth:`~.add_description_list` Add a :htmlTag:`dl` tag, context manager. :meth:`~.add_division` add a :htmlTag:`div` tag (renamed from “section”), context manager. :meth:`~.add_header` Add a header tag (one of :htmlTag:`h1` to :htmlTag:`h6`), context manager. :meth:`~.add_horizontal_line` Add a :htmlTag:`hr` tag. :meth:`~.add_image` Add a :htmlTag:`img` tag. :meth:`~.add_link` Add a :htmlTag:`a` tag. :meth:`~.add_number_list` Add a :htmlTag:`ol` tag, context manager. :meth:`~.add_paragraph` Add a :htmlTag:`p` tag. :meth:`~.add_span` Add a :htmlTag:`span` tag, context manager. :meth:`~.add_subscript` Add subscript text(:htmlTag:`sub` tag) - inline element, treated like text. :meth:`~.add_superscript` Add subscript text (:htmlTag:`sup` tag) - inline element, treated like text. :meth:`~.add_code` Add code text (:htmlTag:`code` tag) - inline element, treated like text. :meth:`~.add_var` Add code text (:htmlTag:`code` tag) - inline element, treated like text. :meth:`~.add_samp` Add code text (:htmlTag:`code` tag) - inline element, treated like text. :meth:`~.add_kbd` Add code text (:htmlTag:`code` tag) - inline element, treated like text. :meth:`~.add_text` Add a text string. Line breaks ``\n`` are honored as :htmlTag:`br` tags. :meth:`~.append_child` Append a child node. :meth:`~.clone` Make a copy if this node. :meth:`~.create_element` Make a new node with a given tag name. :meth:`~.create_text_node` Create direct text for the current node. :meth:`~.find` Find a sub-node with given properties. :meth:`~.find_next` Repeat previous "find" with the same criteria. :meth:`~.insert_after` Insert an element after current node. :meth:`~.insert_before` Insert an element before current node. :meth:`~.remove` Remove this node. :meth:`~.set_align` Set the alignment using a CSS style spec. Only works for block-level tags. :meth:`~.set_attribute` Set an arbitrary key to some value (which may be empty). :meth:`~.set_bgcolor` Set the background color. Only works for block-level tags. :meth:`~.set_bold` Set bold on or off or to some string value. :meth:`~.set_color` Set text color. :meth:`~.set_columns` Set the number of columns. Argument may be any valid number or string. :meth:`~.set_font` Set the font-family, e.g. “sans-serif”. :meth:`~.set_fontsize` Set the font size. Either a float or a valid HTML/CSS string. :meth:`~.set_id` Set a :htmlTag:`id`. A check for uniqueness is performed. :meth:`~.set_italic` Set italic on or off or to some string value. :meth:`~.set_leading` Set inter-block text distance (`-mupdf-leading`), only works on block-level nodes. :meth:`~.set_lineheight` Set height of a line. Float like 1.5, which sets to `1.5 * fontsize`. :meth:`~.set_margins` Set the margin(s), float or string with up to 4 values. :meth:`~.set_pagebreak_after` Insert a page break after this node. :meth:`~.set_pagebreak_before` Insert a page break before this node. :meth:`~.set_properties` Set any or all desired properties in one call. :meth:`~.add_style` Set (add) a “style” that is not supported by its own `set_` method. :meth:`~.add_class` Set (add) a “class” attribute. :meth:`~.set_text_indent` Set indentation for first textblock line. Only works for block-level nodes. :attr:`~.tagname` Either the HTML tag name like :htmlTag:`p` or `None` if a text node. :attr:`~.text` Either the node's text or `None` if a tag node. :attr:`~.is_text` Check if the node is a text. :attr:`~.first_child` Contains the first node one level below this one (or `None`). :attr:`~.last_child` Contains the last node one level below this one (or `None`). :attr:`~.next` The next node at the same level (or `None`). :attr:`~.previous` The previous node at the same level. :attr:`~.root` The top node of the DOM, which hence has the tagname :htmlTag:`html`. ================================ =========================================================================================== **Class API** .. class:: Xml .. method:: add_bullet_list Add an :htmlTag:`ul` tag - bulleted list, context manager. See `ul `_. .. method:: add_codeblock Add a :htmlTag:`pre` tag, context manager. See `pre `_. .. method:: add_description_list Add a :htmlTag:`dl` tag, context manager. See `dl `_. .. method:: add_division Add a :htmlTag:`div` tag, context manager. See `div `_. .. method:: add_header(value) Add a header tag (one of :htmlTag:`h1` to :htmlTag:`h6`), context manager. See `headings `_. :arg int value: a value 1 - 6. .. method:: add_horizontal_line Add a :htmlTag:`hr` tag. See `hr `_. .. method:: add_image(name, width=None, height=None) Add an :htmlTag:`img` tag. This causes the inclusion of the named image in the DOM. :arg str name: the filename of the image. This **must be the member name** of some entry of the :ref:`Archive` parameter of the :ref:`Story` constructor. :arg width: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the width of the specified `where` rectangle in :meth:`Story.place`. If this value is provided and `height` is omitted, the image will be included keeping its aspect ratio. :arg height: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the height of the specified `where` rectangle in :meth:`Story.place`. If this value is provided and `width` is omitted, the image's aspect ratio will be honored. .. method:: add_link(href, text=None) Add an :htmlTag:`a` tag - inline element, treated like text. :arg str href: the URL target. :arg str text: the text to display. If omitted, the `href` text is shown instead. .. method:: add_number_list Add an :htmlTag:`ol` tag, context manager. .. method:: add_paragraph Add a :htmlTag:`p` tag, context manager. .. method:: add_span Add a :htmlTag:`span` tag, context manager. See `span`_ .. method:: add_subscript(text) Add "subscript" text(:htmlTag:`sub` tag) - inline element, treated like text. .. method:: add_superscript(text) Add "superscript" text (:htmlTag:`sup` tag) - inline element, treated like text. .. method:: add_code(text) Add "code" text (:htmlTag:`code` tag) - inline element, treated like text. .. method:: add_var(text) Add "variable" text (:htmlTag:`var` tag) - inline element, treated like text. .. method:: add_samp(text) Add "sample output" text (:htmlTag:`samp` tag) - inline element, treated like text. .. method:: add_kbd(text) Add "keyboard input" text (:htmlTag:`kbd` tag) - inline element, treated like text. .. method:: add_text(text) Add a text string. Line breaks ``\n`` are honored as :htmlTag:`br` tags. .. method:: set_align(value) Set the text alignment. Only works for block-level tags. :arg value: either one of the :ref:`TextAlign` or the `text-align `_ values. .. method:: set_attribute(key, value=None) Set an arbitrary key to some value (which may be empty). :arg str key: the name of the attribute. :arg str value: the (optional) value of the attribute. .. method:: get_attributes() Retrieve all attributes of the current nodes as a dictionary. :returns: a dictionary with the attributes and their values of the node. .. method:: get_attribute_value(key) Get the attribute value of `key`. :arg str key: the name of the attribute. :returns: a string with the value of `key`. .. method:: remove_attribute(key) Remove the attribute `key` from the node. :arg str key: the name of the attribute. .. method:: set_bgcolor(value) Set the background color. Only works for block-level tags. :arg value: either an RGB value like (255, 0, 0) (for "red") or a valid `background-color `_ value. .. method:: set_bold(value) Set bold on or off or to some string value. :arg value: `True`, `False` or a valid `font-weight `_ value. .. method:: set_color(value) Set the color of the text following. :arg value: either an RGB value like (255, 0, 0) (for "red") or a valid `color `_ value. .. method:: set_columns(value) Set the number of columns. :arg value: a valid `columns `_ value. .. note:: Currently ignored - supported in a future MuPDF version. .. method:: set_font(value) Set the font-family. :arg str value: e.g. "sans-serif". .. method:: set_fontsize(value) Set the font size for text following. :arg value: a float or a valid `font-size `_ value. .. method:: set_id(unqid) Set a :htmlTag:`id`. This serves as a unique identification of the node within the DOM. Use it to easily locate the node to inspect or modify it. A check for uniqueness is performed. :arg str unqid: id string of the node. .. method:: set_italic(value) Set italic on or off or to some string value for the text following it. :arg value: `True`, `False` or some valid `font-style `_ value. .. method:: set_leading(value) Set inter-block text distance (`-mupdf-leading`), only works on block-level nodes. :arg float value: the distance in points to the previous block. .. method:: set_lineheight(value) Set height of a line. :arg value: a float like 1.5 (which sets to `1.5 * fontsize`), or some valid `line-height `_ value. .. method:: set_margins(value) Set the margin(s). :arg value: float or string with up to 4 values. See `CSS documentation `_. .. method:: set_pagebreak_after Insert a page break after this node. .. method:: set_pagebreak_before Insert a page break before this node. .. method:: set_properties(align=None, bgcolor=None, bold=None, color=None, columns=None, font=None, fontsize=None, indent=None, italic=None, leading=None, lineheight=None, margins=None, pagebreak_after=False, pagebreak_before=False, unqid=None, cls=None) Set any or all desired properties in one call. The meaning of argument values equal the values of the corresponding `set_` methods. .. note:: The properties set by this method are directly attached to the node, whereas every `set_` method generates a new :htmlTag:`span` below the current node that has the respective property. So to e.g. "globally" set some property for the :htmlTag:`body`, this method must be used. .. method:: add_style(value) Set (add) some style attribute not supported by its own `set_` method. :arg str value: any valid CSS style value. .. method:: add_class(value) Set (add) some "class" attribute. :arg str value: the name of the class. Must have been defined in either the HTML or the CSS source of the DOM. .. method:: set_text_indent(value) Set indentation for the first textblock line. Only works for block-level nodes. :arg value: a valid `text-indent `_ value. Please note that negative values do not work. .. method:: append_child(node) Append a child node. This is a low-level method used by other methods like :meth:`Xml.add_paragraph`. :arg node: the :ref:`Xml` node to append. .. method:: create_text_node(text) Create direct text for the current node. :arg str text: the text to append. :rtype: :ref:`Xml` :returns: the created element. .. method:: create_element(tag) Create a new node with a given tag. This a low-level method used by other methods like :meth:`Xml.add_paragraph`. :arg str tag: the element tag. :rtype: :ref:`Xml` :returns: the created element. To actually bind it to the DOM, use :meth:`Xml.append_child`. .. method:: insert_before(elem) Insert the given element `elem` before this node. :arg elem: some :ref:`Xml` element. .. method:: insert_after(elem) Insert the given element `elem` after this node. :arg elem: some :ref:`Xml` element. .. method:: clone() Make a copy of this node, which then may be appended (using :meth:`Xml.append_child`) or inserted (using one of :meth:`Xml.insert_before`, :meth:`Xml.insert_after`) in this DOM. :returns: the clone (:ref:`Xml`) of the current node. .. method:: remove() Remove this node from the DOM. .. method:: debug() For debugging purposes, print this node's structure in a simplified form. .. method:: find(tag, att, match) Under the current node, find the first node with the given `tag`, attribute `att` and value `match`. :arg str tag: restrict search to this tag. May be `None` for unrestricted searches. :arg str att: check this attribute. May be `None`. :arg str match: the desired attribute value to match. May be `None`. :rtype: :ref:`Xml`. :returns: `None` if nothing found, otherwise the first matching node. .. method:: find_next( tag, att, match) Continue a previous :meth:`Xml.find` (or :meth:`find_next`) with the same values. :rtype: :ref:`Xml`. :returns: `None` if none more found, otherwise the next matching node. .. attribute:: tagname Either the HTML tag name like :htmlTag:`p` or `None` if a text node. .. attribute:: text Either the node's text or `None` if a tag node. .. attribute:: is_text Check if a text node. .. attribute:: first_child Contains the first node one level below this one (or `None`). .. attribute:: last_child Contains the last node one level below this one (or `None`). .. attribute:: next The next node at the same level (or `None`). .. attribute:: previous The previous node at the same level. .. attribute:: root The top node of the DOM, which hence has the tagname :htmlTag:`html`. Setting Text properties ------------------------ In HTML tags can be nested such that innermost text **inherits properties** from the tag enveloping its parent tag. For example `

some bold textthis is bold and italicregular text

`. To achieve the same effect, methods like :meth:`Xml.set_bold` and :meth:`Xml.set_italic` each open a temporary :htmlTag:`span` with the desired property underneath the current node. In addition, these methods return there parent node, so they can be concatenated with each other. Context Manager support ------------------------ The standard way to add nodes to a DOM is this:: body = story.body para = body.add_paragraph() # add a paragraph para.set_bold() # text that follows will be bold para.add_text("some bold text") para.set_italic() # text that follows will additionally be italic para.add_txt("this is bold and italic") para.set_italic(False).set_bold(False) # all following text will be regular para.add_text("regular text") Methods that are flagged as "context managers" can conveniently be used in this way:: body = story.body with body.add_paragraph() as para: para.set_bold().add_text("some bold text") para.set_italic().add_text("this is bold and italic") para.set_italic(False).set_bold(False).add_text("regular text") para.add_text("more regular text") .. include:: footer.rst .. External links: .. _span: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span