Debian Codegraph @

README

raw
1 NAME
2 RDF::RDFa::Generator - Generate data for RDFa serialization
3
4 DESCRIPTION
5 Constructor
6 `$gen = RDF::RDFa::Generator->new(style => $style, %options)`
7 Creates a new generator object. $style is one of the following
8 case-sensitive strings: 'HTML::Head' (the default), 'HTML::Hidden' or
9 'HTML::Pretty'. You can also construct an object like this:
10
11 $gen = RDF::RDFa::Generator::HTML::Head->new(%options);
12
13 Options include:
14
15 * base - the base URL where the output data will be published. This
16 allows in some cases for the generated RDFa to include relative
17 URIs.
18
19 * data_context - if non-null, an Attean Blank or IRI object or an
20 RDF::Trine::Node which indicates the context (named graph)
21 containing the data to generate RDFa for.
22
23 * namespacemap - a URI::NamespaceMap object containing preferred
24 CURIE prefixes. This is the preferred method, see note below.
25
26 * namespaces - a {prefix=>uri} hashref of preferred CURIE prefixes.
27
28 * ns - a {uri=>prefix} hashref of preferred CURIE prefixes.
29 DEPRECATED - use namespaces instead.
30
31 * prefix_attr - use the @prefix attribute for CURIE prefixes (RDFa
32 1.1 only). Boolean, defaults to false.
33
34 * safe_xml_literals - prevents XML literals from injecting arbitrary
35 XHTML into the output. Boolean, defaults to FALSE.
36
37 * title - assign a <title> element for generated XHTML documents.
38
39 * version - set generated RDFa version. Valid values are '1.0' (the
40 default) or '1.1'.
41
42 Public Methods
43 `$gen->create_document($model, %opts)`
44 Creates a new RDFa file containing triples. $model is an
45 Attean::QuadModel (where the graph name is not used) object providing
46 the triples. Returns an XML::LibXML::Document object suitable for
47 serializing using its `toString` method.
48
49 If you're planning on serving the RDFa with the text/html media type,
50 then it is recommended that you use HTML::HTML5::Writer to serialize
51 the document rather than `toString`.
52
53 Can also be called as a class method:
54
55 $document = RDF::RDFa::Generator->create_document($model)
56 # Same as:
57 # $document = RDF::RDFa::Generator->new->create_document($model)
58
59 Options can also be passed as a HASH. This is typically used for
60 style-specific options.
61
62 `$gen->inject_document($document, $model)`
63 Injects an existing document with triples. $document is an
64 XML::LibXML::Document to inject, or a well-formed XML string. $model
65 is an Attean::QuadModel (where the graph name is not used) object
66 providing the triples. Returns an XML::LibXML::Document object
67 suitable for serializing using its `toString` method.
68
69 See `create_document` for information about serving the RDFa with the
70 text/html media type.
71
72 Can also be called as a class method. See `create_document` for
73 details.
74
75 `$gen->nodes($model)`
76 Provides triple-laden XML::LibXML::Elements to be added to a document.
77 $model is an Attean::QuadModel (where the graph name is not used)
78 object providing the triples. If called in list context, returns a
79 list of XML::LibXML::Element objects which can be added to a document;
80 otherwise returns an XML::LibXML::NodeList containing a list of such
81 elements.
82
83 Can also be called as a class method. See `create_document` for
84 details.
85
86 The HTML::Pretty generator can be passed a couple of additional
87 options:
88
89 $gen->nodes($model, notes_heading=>'Additional Info', notes=>\@notes);
90
91 The notes are a list of RDF::RDFa::Generator::HTML::Pretty::Note
92 objects which are added as notes to the end of each subject's data.
93
94 UPGRADING TO 0.200
95 The recommended upgrade path is to migrate your application to use Attean
96 rather than RDF::Trine as your RDF library. If that is not an option, you
97 may continue to use RDF::Trine, by using a compatibility layer. If you are
98 using this module directly, to upgrade from earlier releases, you would
99 simply add
100
101 use RDF::TrineX::Compatibility::Attean;
102
103 alongside the import of this module. It is in a separate distribution that
104 needs to be installed. If you use the RDF::Trine::Serializer methods, you
105 should instead use RDF::Trine::Serializer::RDFa.
106
107 NOTE
108 Version 0.200 introduced a large number of changes to be compatible with
109 both Attean and RDF::Trine. Some of these were backwards-incompatible,
110 some were to support new features, such as the use of URI::NamespaceMap.
111
112 Backwards-incompatible changes
113 The methods `serialize_model_to_file`, `serialize_model_to_string`,
114 `serialize_iterator_to_file` and `serialize_iterator_to_string` that were
115 provided for compatibility with the RDF::Trine::Serializer interface have
116 been moved to a module RDF::Trine::Serializer::RDFa that has to be
117 installed separately to use this with RDF::Trine.
118
119 `data_context` previously accepted a plain-text string URI. Now, it
120 requires an appropriate object, as documented.
121
122 Since RDF 1.1 abandons untyped literals, this module also ceases to emit
123 them.
124
125 Namespace mappings
126 The way namespace mappings are handled have been rewritten. Now, the
127 preferred method to add them is to pass an URI::NamespaceMap object to
128 `namespacemap`. This will override any other options.
129
130 The namespace mappings for the following prefixes will always be added:
131 `rdfa`, `rdf`, `rdfs` and `xsd`.
132
133 If URI::NamespaceMap is not used, but `namespaces` is given as a hashref
134 of prefix-URI pairs, the pairs will be added. If neither are given, all
135 mappings from RDF::NS::Curated, which includes all if RDFa Initial Context
136 will be added. Finally, any pairs from the deprecated `ns` option will be
137 added, but a warning will be emitted.
138
139 BUGS
140 Please report any bugs to
141 <https://github.com/kjetilk/p5-rdf-rdfa-generator/issues>.
142
143 SEE ALSO
144 You may want to use the framework-specific frontends:
145 RDF::Trine::Serializer::RDFa or AtteanX::Serializer::RDFa.
146
147 Other relevant modules:
148
149 HTML::HTML5::Writer, XML::LibXML, RDF::RDFa::Parser, RDF::Trine,
150 URI::NamespaceMap, Attean.
151
152 AUTHOR
153 Toby Inkster <[email protected]>.
154
155 Kjetil Kjernsmo <[email protected]>.
156
157 COPYRIGHT AND LICENCE
158 Copyright (C) 2010 by Toby Inkster, 2017, 2018 Kjetil Kjernsmo
159
160 This library is free software; you can redistribute it and/or modify it
161 under the same terms as Perl itself, either Perl version 5.8 or, at your
162 option, any later version of Perl 5 you may have available.
163
164 Icons
165 RDF::RDFa::Generator::HTML::Pretty uses the FamFamFam Silk icons; see
166 <http://famfamfam.com/lab/icons/silk/>.
167