view release on metacpan or  search on metacpan

lib/Datastar/SSE.pm  view on Meta::CPAN

Replaces the target’s outerHTML with the fragment.

=item * FRAGMENT_MERGEMODE_PREPEND

C<prepend>

Prepends the fragment to the target’s children.

=item * FRAGMENT_MERGEMODE_APPEND

C<append>

Appends the fragment to the target’s children.

=item * FRAGMENT_MERGEMODE_BEFORE

C<before>

Inserts the fragment before the target as a sibling.

=item * FRAGMENT_MERGEMODE_AFTER

C<after>

Inserts the fragment after the target as a sibling.

=item * FRAGMENT_MERGEMODE_UPSERTATTRIBUTES

C<upsertAttributes>

Merges attributes from the fragment into the target – useful for updating a signal.

=back

=cut

our @EXPORT_OK = (keys %DATASTAR_EVENTS, keys %MERGEMODES);
our %EXPORT_TAGS = ( events => [keys(%DATASTAR_EVENTS)], fragment_merge_modes => [keys(%MERGEMODES)] );

my $json; # cache
sub _encode_json($) {
	($json  ||= JSON->new->allow_blessed->convert_blessed)->encode( @_ );
}

sub _decode_json($) {
	# uncoverable subroutine
	($json  ||= JSON->new->allow_blessed->convert_blessed)->decode( @_ ); # uncoverable statement
}

=head1 METHODS

=head2 headers

	->headers();

Returns an Array Ref of the recommended headers to sent for Datastar SSE responses.

	Content-Type: text/event-stream
	Cache-Control: no-cache
	Connection: keep-alive
	Keep-Alive: timeout=300, max=100000

=cut

my $headers;
sub headers {
	$headers ||= +[
		'Content-Type', 'text/event-stream',
		'Cache-Control', 'no-cache',
		'Connection', 'keep-alive',
		'Keep-Alive', 'timeout=300, max=100000'
	]
}

=head1 EVENTS

Each Datastar SSE event is implements as a class method on L<Datastar::SSE>.  Each method accepts, but does not require,  
an options hashref as the last parameter, the options are documented per event, additionally all options from 
L<HTTP::ServerEvent> are supported.

=over

=item * id

The event id. If you send this, a client will send the "Last-Event-Id" header when reconnecting, allowing you to send the events missed 
while offline. Newlines or null characters in the event id are treated as a fatal error.

=item * retry

the amount of miliseconds to wait before reconnecting if the connection is lost. Newlines or null characters in the retry interval are 
treated as a fatal error.

=back

=head2 merge_fragments

	->merge_fragments( $html_fragment, $options_hashref );
	->merge_fragments( $html_fragment_arrayref, $options_hashref );

L<< datastar-merge-fragments|https://data-star.dev/reference/sse_events#datastar-merge-fragments >>

Merges one or more fragments into the DOM. By default, Datastar merges fragments using L<< Idiomorph|https://github.com/bigskysoftware/idiomorph >>,
which matches top level elements based on their ID.

=head3 OPTIONS

=over

=item * selector

B<Str>

Selects the target element of the merge process using a CSS selector.

=item * use_view_transition

B<Bool>

B<Default>: 0

B<Sends As>: C<useViewTransition>

Whether to use view transitions when merging into the DOM.

=item * merge_mode

B<Str|MERGEMODE>

B<Default>: FRAGMENT_MERGEMODE_MORPH