=head1 NAME
RDF::RDFa::Generator - Generate data for RDFa serialization
=cut
package RDF::RDFa::Generator;
use 5.008;
use strict;
use warnings;
our $VERSION = '0.200';
use RDF::RDFa::Generator::HTML::Head;
use RDF::RDFa::Generator::HTML::Hidden;
use RDF::RDFa::Generator::HTML::Pretty;
use Carp;
=head1 DESCRIPTION
=head2 Constructor
=over 4
=item C<< $gen = RDF::RDFa::Generator->new(style => $style, %options) >>
Creates a new generator object. $style is one of the following case-sensitive strings:
'HTML::Head' (the default), 'HTML::Hidden' or 'HTML::Pretty'. You can also construct
an object like this:
$gen = RDF::RDFa::Generator::HTML::Head->new(%options);
Options include:
=over 4
=item * B<base> - the base URL where the output data will be published. This allows in some cases for the generated RDFa to include relative URIs.
=item * B<data_context> - if non-null, an L<Attean> Blank or IRI object or an L<RDF::Trine::Node> which indicates the context (named graph) containing the data to generate RDFa for.
=item * B<namespacemap> - a L<URI::NamespaceMap> object containing preferred CURIE prefixes. This is the preferred method, see note below.
=item * B<namespaces> - a {prefix=>uri} hashref of preferred CURIE prefixes.
=item * B<ns> - a {uri=>prefix} hashref of preferred CURIE prefixes. DEPRECATED - use B<namespaces> instead.
=item * B<prefix_attr> - use the @prefix attribute for CURIE prefixes (RDFa 1.1 only). Boolean, defaults to false.
=item * B<safe_xml_literals> - prevents XML literals from injecting arbitrary XHTML into the output. Boolean, B<defaults to FALSE>.
=item * B<title> - assign a <title> element for generated XHTML documents.
=item * B<version> - set generated RDFa version. Valid values are '1.0' (the default) or '1.1'.
=back
=back
=cut
sub new
{
my ($class, %opts) = @_;
my $implementation = sprintf('%s::%s', __PACKAGE__, $opts{'style'} || 'HTML::Head');
return $implementation->new(%opts);
}
=head2 Public Methods
=over 4
=item C<< $gen->create_document($model, %opts) >>
Creates a new RDFa file containing triples. $model is an RDF::Trine::Model object
providing the triples. Returns an XML::LibXML::Document object suitable
for serializing using its C<toString> method.
If you're planning on serving the RDFa with the text/html media type, then
it is recommended that you use HTML::HTML5::Writer to serialize the
document rather than C<toString>.
Can also be called as a class method:
$document = RDF::RDFa::Generator->create_document($model)
# Same as:
# $document = RDF::RDFa::Generator->new->create_document($model)
Options can also be passed as a HASH. This is typically used for style-specific options.
=cut
sub create_document
{
my $proto = shift;
my $self = (ref $proto) ? $proto : $proto->new;
return $self->create_document(@_);
}
=item C<< $gen->inject_document($document, $model) >>
Injects an existing document with triples. $document is an XML::LibXML::Document
to inject, or a well-formed XML string. $model is an RDF::Trine::Model object providing
the triples. Returns an XML::LibXML::Document object suitable
for serializing using its C<toString> method.
See C<create_document> for information about serving the RDFa with the
text/html media type.
Can also be called as a class method. See C<create_document> for details.
=cut
sub inject_document
{
my $proto = shift;
my $self = (ref $proto) ? $proto : $proto->new;
return $self->inject_document(@_);
}
=item C<< $gen->nodes($model) >>
Provides triple-laden XML::LibXML::Elements to be added to a document.
$model is an RDF::Trine::Model object providing the triples. If called in
list context, returns a list of XML::LibXML::Element objects which can be
added to a document; otherwise returns an XML::LibXML::NodeList containing
a list of such elements.
Can also be called as a class method. See C<create_document> for details.
The HTML::Pretty generator can be passed a couple of additional options:
$gen->nodes($model, notes_heading=>'Additional Info', notes=>\@notes);
The notes are a list of RDF::RDFa::Generator::HTML::Pretty::Note objects
which are added as notes to the end of each subject's data.
=cut
sub nodes
{
my $proto = shift;
my $self = (ref $proto) ? $proto : $proto->new;
return $self->nodes(@_);
}
=back
=head1 UPGRADING TO 0.200
The recommended upgrade path is to migrate your application to use
L<Attean> rather than L<RDF::Trine> as your RDF library. If that is
not an option, you may continue to use L<RDF::Trine>, by using a
compatibility layer. If you are using this module directly, to
upgrade from earlier releases, you would simply add
use RDF::TrineX::Compatibility::Attean;
alongside the import of this module. It is in a separate distribution
that needs to be installed. If you use the L<RDF::Trine::Serializer>
methods, you should instead use L<RDF::Trine::Serializer::RDFa>.
=head1 NOTE
Version 0.200 introduced a large number of changes to be compatible
with both L<Attean> and L<RDF::Trine>. Some of these were
backwards-incompatible, some were to support new features, such as the
use of L<URI::NamespaceMap>.
=head2 Backwards-incompatible changes
The methods C<serialize_model_to_file>, C<serialize_model_to_string>,
C<serialize_iterator_to_file> and C<serialize_iterator_to_string> that
were provided for compatibility with the L<RDF::Trine::Serializer>
interface have been moved to a module L<RDF::Trine::Serializer::RDFa>
that has to be installed separately to use this with L<RDF::Trine>.
C<data_context> previously accepted a plain-text string URI. Now, it
requires an appropriate object, as documented.
Since RDF 1.1 abandons untyped literals, this module also ceases to
emit them.
=head2 Namespace mappings
The way namespace mappings are handled have been rewritten. Now, the
preferred method to add them is to pass an L<URI::NamespaceMap> object
to C<namespacemap>. This will override any other options.
The namespace mappings for the following prefixes will always be
added: C<rdfa>, C<rdf>, C<rdfs> and C<xsd>.
If L<URI::NamespaceMap> is not used, but C<namespaces> is given as a
hashref of prefix-URI pairs, the pairs will be added. If neither are
given, all mappings from L<RDF::NS::Curated>, which includes all if
RDFa Initial Context will be added. Finally, any pairs from the
deprecated C<ns> option will be added, but a warning will be emitted.
=cut
sub serialize_model_to_string {
croak 'serialize_model_to_string have been to moved RDF::Trine::Serializer::RDFa';
}
sub serialize_model_to_file {
croak 'serialize_model_to_file have been to moved RDF::Trine::Serializer::RDFa';
}
sub serialize_iterator_to_string {
croak 'serialize_iterator_to_string have been to moved RDF::Trine::Serializer::RDFa';
}
sub serialize_iterator_to_file {
croak 'serialize_iterator_to_string have been to moved RDF::Trine::Serializer::RDFa';
}
1;
__END__
=head1 BUGS
Please report any bugs to L<https://github.com/kjetilk/p5-rdf-rdfa-generator/issues>.
=head1 SEE ALSO
You may want to use the framework-specific frontends: L<RDF::Trine::Serializer::RDFa> or L<AtteanX::Serializer::RDFa>.
Other relevant modules:
L<HTML::HTML5::Writer>, L<XML::LibXML>, L<RDF::RDFa::Parser>, L<RDF::Trine>,
L<URI::NamespaceMap>, L<Attean>.
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
Kjetil Kjernsmo E<lt>kjetilk@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
Copyright (C) 2010 by Toby Inkster, 2017, 2018 Kjetil Kjernsmo
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8 or,
at your option, any later version of Perl 5 you may have available.
=head2 Icons
RDF::RDFa::Generator::HTML::Pretty uses the FamFamFam Silk icons;
see L<http://famfamfam.com/lab/icons/silk/>.
=cut