### ----------------------------------------------------
### -- HTML::Tag
### -- Licenses: Artistic-2.0
### -- Authors: Mark Rushing, Márton Polgár
### -- File: lib/HTML/Tag/Macro/List.rakumod
### ----------------------------------------------------
use v6;
use HTML::Tag::Tags;

class HTML::Tag::Macro::List
{
    has      @.items;
    has Bool $.ordered;
    has Str  $.type;
    has Str  $.class;
    has Str  $.id;

    method link(:$to!, :$text!, *%opts) {
	self.item(HTML::Tag::a.new(:href($to),
				   :text($text),
				   |%opts));
    }

    method item($item) {
	@!items.push: $item;
    }
    
    method render() {
	my @lis;
	for @!items -> $item {
	    @lis.push: HTML::Tag::li.new(:text($item));
	}
	
	my $list;
	
	if $!ordered {
	    $list = HTML::Tag::ol.new(:text(|@lis));
	    $list.type = $.type if $.type.defined;
	}
	else {
	    $list = HTML::Tag::ul.new(:text(|@lis));
	}

	$list.class = $.class if $.class.defined;
	$list.id    = $.id    if $.id.defined;
	
	$list.render;
    }
}


=begin pod

=head1 NAME HTML::Tag::Macro::List

=head1 SYNOPSIS

    =begin code
    use HTML::Tag::Macro::List;

    my @fruit = 'fingers', 'sofa', 'airliner';
    my $html = HTML::Tag::Macro::List.new(:items(@fruit)).render;

    # ..or..

    my $list = HTML::Tag::Macro::List.new;
    $list.item(HTML::Tag::a.new(:href('http://somewhere')
				:text('rainbows')));
    $list.item(HTML::Tag::a.new(:href('http://elsewhere')
				:text('snails')));
    $list.render;

    # ..or..

    my $list = HTML::Tag::Macro::List.new;
    $list.link(:to('http://somewhere'), :text('rainbows'));
    $list.link(:to('http://elsewhere'), :text('snails'), :class('highlight'));
    $list.render;
    
    =end code

=head1 DESCRIPTION

Generates an ordered or unordered HTML list from a supplied array, or
constructs the array for you by repeated calling of the item() method.

The HTML is generated by calling the .render method, or can be
deferred for calling by other HTML::Tag objects that it might be a
part of.

=head1 ATTRIBUTES

=head2 @:items

An array of things that will be surrounded by <li> tags. These can be
other HTML::Tag things.

=head2 $:class

The class string to be assigned to the <ul> or <ol> elements.

=head2 $:id

The id string to be assigned to the <ul> or <ol> elements.

=head2 Bool $:ordered

Specifies that the list will be ordered instead of unordered. (ol vs
ul).

=head2 $:type

Specifies the HTML ordered list type to use.

=head1 METHODS

=head2 item($thing)

Things passed to item will be stored in an array for subsequent
rendering between <li> elements.

=head2 link(:$to!, :$text!, :%opts)

Lists are commonly used to create menus of anchor links. The link()
method creates an anchor link and appends it to list items to be
rendered. %opts are options to the HTML::Tag::a if desired.

=head2 render()

Assembles the list elements and places them between either a ol or ul
tag and returns the string.

=head1 AUTHOR

Mark Rushing mark@orbislumen.net

=head2 LICENSE

This is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.

=end pod


