Třída TXFADataStructure

TXFADataStructure, deklarovaná v HPDFXFADataStructure, udržuje ohraničené strukturální editace stávajícího nativního stromu uzlů XFA a vlastní všechny odpojené stromy elementů vytvořené, klonované či odebrané přes graf

CreateDataNode obsluhuje elementy Data DOM, zatímco CreateElement navíc podporuje konstrukci elementů modelu používanou TXFAFormStructure

Konstruktor si půjčí Root a validuje stávající strom proti TXFADataStructureLimits, dřív než se vrátí; graf se musí zničit, dřív než vlastník vypůjčeného kořene

Všechny veřejné názvy, namespace URI i textové hodnoty AnsiString obsahují UTF-8 bajty

Graph := TXFADataStructure.Create(DatasetsRoot, Limits, OnTick);
try
  Graph.BeginOperation(OnTick);
  try
    Node := Graph.CreateDataNode('dataValue', 'amount');
    Graph.SetValue(Node, '42');
    Graph.Append(RecordNode, Node);
  finally
    Graph.EndOperation;
  end;
finally
  Graph.Free;
end;

Scope operace

BeginOperation(OnTick) zahájí scope a odmítne vnořený scope; EndOperation uvolní uložený callback a je bezpečné ho volat během úklidu

Konstruktor provede vlastní preflight scope a uvolní konstruktorový callback, dřív než se vrátí; následné metody vyžadují nový aktivní scope

OnTick je Delphi anonymní procedura či FPC vnořená procedura typu TXFADataStructureTick; může vyhodit výjimku, čímž práci zruší, či vynutí deadline volajícího či počítadlo operací

Metody připraví alokace, kapacitu vlastnictví i vyžadované deklarace namespace, dřív před svou finální kontrolou zrušení i strukturální mutací; odmítnutá jednotlivá editace zachová stávající dokumentový graf

Série úspěšných přímých grafových volání se při pozdějším selhání automaticky odroluje; kompletní transakci události dodává skriptovací runtime a společně obnoví svůj dokument, odpojený graf, skriptové identity, lexický stav i journal

Tvorba a klonování

CreateDataNode(ClassName, Name, NamespaceURI = '') přijme dataGroup či dataValue, vytvoří čerstvý odpojený element a zaznamená explicitní metadata třídy datového uzlu

CreateElement(ClassName, Name, NamespaceURI) vytvoří odpojený modelový element, jehož XML lokální název je ClassName, s volitelným atributem XFA name i explicitní deklarací default namespace

CreateElement validuje XML syntaxi, skalární hodnoty, rezervované namespace URI i kapacitu grafu; vyšší úroveň form factory validuje podporované schema tříd XFA

Name může být XML lokální název či kvalifikovaný název, jehož neprázdný prefix má dodané neprázdné namespace URI; rezervované bindingy xml a xmlns se validují

Prázdný název je dovolený u odpojeného konstrukčního kroku; před připojením nastavte platný název přes Rename

Clone(Node, Recursive = True) vytvoří odpojenou kopii s čerstvými nativními identitami; mělká kopie si uchová hodnotu, atributy i deklarace namespace elementu, zatímco potomky vyloučí

Zděděné deklarace namespace se materializují před klonem či přesunem, takže prefixované atributy si uchovají původní namespace mimo scope svého předchozího předka

Edity vlastnictví

Append(Parent, Node) přesune tentýž uzel na konec uspořádaných potomků rodiče; InsertBefore(Parent, Node, Before) ho přesune před existujícího přímého potomka, přičemž Before = nil je ekvivalent appendu

Remove(Parent, Node) odpojí existujícího přímého potomka a přenese jeho vlastnictví na graf; objekt, potomci i nativní identity zůstávají platné až do zničení grafu či obnovení odpojeného snapshotu

Cizí grafy, cykly, přesun vypůjčeného kořene, připojení bez názvu, neplatné sourozenecké reference i přetečení uzlů/hloubky/bajtů vyhodí EHPDFXFAError

Edity hodnot a názvů

Rename(Node, Name) změní lokální XML název elementu, při zachování prefixu, URI namespace, pozice, potomků i nativní identity; připojený element vyžaduje neprázdný platný XML název

SetValue(Node, Value) validuje UTF-8 i XML skalární hodnoty, nahradí běžné textové potomky a zachová komentáře i processing instructions; prázdný text odstraní běžné textové potomky

SetAttribute(Node, Name, Value) přidá či nahradí atribut po validaci syntaxe kvalifikovaného názvu, UTF-8 hodnoty i odhadnutého bajtového rozpočtu; prázdná hodnota zůstane explicitně prázdným atributem

SetNamespace(Node, NamespaceURI) změní expandovaný namespace elementu a aktualizuje deklaraci pro jeho aktuální prefix, při validaci rezervovaných bindingů

DeclareNamespace(Node, Prefix, NamespaceURI) přidá či nahradí deklaraci namespace, aniž by změnila expandovaný název elementu; rozpornou deklaraci pro vlastní prefix elementu odmítne

Přímí grafoví volající koordinují prefixované atributy s deklaracemi namespace a drží složené editace uvnitř vlastní rollback transakce

Bajtové i uzlové rozpočty zahrnují agregátní hodnotu elementu i jeho skutečně vlastněný textový uzel, namísto účtování jen jedné reprezentace textu

Preflight XML importu

ValidateImport(Node, Incoming, Overwrite, OnTick) zkontroluje odhadnutý agregátní graf, dřív než volající importuje vlastněný seznam příchozích XML potomků

Když je Overwrite true, odhadnutá velikost vylučuje nahrazované potomky i agregátní hodnotu cíle; jinak stávající potomci zůstávají v rozpočtu

Metoda nechá příchozí seznam i dokument beze změny a dočasný operační scope vytvoří jen tehdy, když už žádný scope není aktivní

Odpojené snapshoty

CaptureDetached vrátí hodnotový snapshot každého odpojeného kořene i potomka, tedy textu, CDATA, komentářů, processing instructions, atributů i deklarací namespace

RestoreDetached(Snapshot) validuje a připraví náhradní odpojený les, dřív než vymění vlastnictví; jeho vrácené pole uzlů řídí pořadí snapshotu a obsahuje čerstvé nativní identity pro přemapování volajícím

Pole záznamů i pravidla identit popisuje TXFADataStructureSnapshot

Prohlížení

Root vystavuje vypůjčený kořen a DetachedRoots kořeny vlastněné grafem k prohlédnutí; změny provádějte grafovými metodami, aby vlastnictví i rozpočty zůstaly koherentní

Transakční skriptování Data DOM · Transakční skriptování form stromu · TXFANode