Asciidoctor :: Discussion

extension docs

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

11 messages Options

willwade

Jun 07, 2016; 9:16pm

extension docs

I'm slowly working my way through the docs to make a simple extension... but Im getting stuck. I dare say I have missed a page somewhere on the docs..

Basically I want to turn something like this..

[imagegallery]
image::4.jpg[title="Some title" thumb="4-b.jpg"]
image::3[title="Some title" thumb="3-b.jpg"]

into..

<p>
		<a class="fancybox-effects-a" href="4_b.jpg" title="Some title"><img src="4.jpg" alt="" /></a>
		<a class="fancybox-effects-b" href="3_b.jpg" title="Some title"><img src="3.jpg" alt="" /></a>
	</p>

And squirt in - only once - a whole load of stuff for the header (e.g. javascript embed and css lines).

My guess is to follow the shout block example (here: http://asciidoctor.org/docs/user-manual/#extensions) - but how do I actually make this work in my asciidoctor command line? How do I get it to read my funky new extension - or test it?

mojavelinux

Jun 08, 2016; 12:21am

Re: extension docs

Administrator

@willwade,

It's not currently possible to extend a built-in block macro like image. Therefore, you need to wrap them in a block that you can extend.

What you'll need is something like this:

[gallery]

image::a.jpg[thumb=a-b.jpg]

image::b.jpg[thumb=b-b.jpg]

Then, you'll need to register a custom block bound to the name "gallary" on the open context.

Inside of the process method, you need to parse the children to get all the images. Once you have the images, then you can create a new node and make it whatever you want.

You can see an example of such a "compound" block here: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/compound-block.rb

You'll probably also need a docinfo processor to add additional content to the header. The block extension may need to store state somewhere that the docinfo processor can access.

You can see an example of a docinfo processor here: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/license-url-docinfoprocessor.rb

Cheers,

-Dan

On Tue, Jun 7, 2016 at 3:16 PM, willwade [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'm slowly working my way through the docs to make a simple extension... but Im getting stuck. I dare say I have missed a page somewhere on the docs..

Basically I want to turn something like this..
[imagegallery]
image::4.jpg[title="Some title" thumb="4-b.jpg"]
image::3[title="Some title" thumb="3-b.jpg"]
into..
<p>
		<a class="fancybox-effects-a" href="4_b.jpg" title="Some title"><img src="4.jpg" alt="" /></a>
		<a class="fancybox-effects-b" href="3_b.jpg" title="Some title"><img src="3.jpg" alt="" /></a>
	</p>
And squirt in - only once - a whole load of stuff for the header (e.g. javascript embed and css lines).

My guess is to follow the shout block example (here: http://asciidoctor.org/docs/user-manual/#extensions) - but how do I actually make this work in my asciidoctor command line? How do I get it to read my funky new extension - or test it?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/extension-docs-tp4746.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

willwade

Jun 08, 2016; 6:48am

Re: extension docs

Thanks for that.

So, sorry for being dim, If I was to build this - where do I actually put it?

Thanks again

w

mojavelinux

Jun 08, 2016; 6:54am

Re: extension docs

Administrator

If you'd like to share it, we usually start out with putting it in the extensions lab. If you are talking about where to put it to use it, just anywhere you can access the file to load it when calling Asciidoctor.

-Dan

On Wed, Jun 8, 2016 at 12:48 AM, willwade [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks for that.

So, sorry for being dim, If I was to build this - where do I actually put it?

Thanks again

w

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/extension-docs-tp4746p4749.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

willwade

Jun 13, 2016; 12:35pm

Re: extension docs

Thanks. I've actually found it.. I was looking in the docs but I found what I wanted here:

https://github.com/asciidoctor/asciidoctor-extensions-lab#using-an-extension

(maybe should be in the docs??!)

willwade

Jun 13, 2016; 4:54pm

Re: extension docs

In reply to this post by mojavelinux

Sorry to have to hand hold me through this...

But when you say

mojavelinux wrote

@willwade,
Inside of the process method, you need to parse the children to get all the
images. Once you have the images, then you can create a new node and make
it whatever you want.

Do you have any examples that do something like this? I'm guessing using reader.lines and then a regex on image:: ??

Will

mojavelinux

Jun 13, 2016; 11:01pm

Re: extension docs

Administrator

On Mon, Jun 13, 2016 at 10:54 AM, willwade [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Do you have any examples that do something like this?

As I mentioned, what you want to look at is the compound block sample:

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/compound-block.rb

You don't have to any parsing yourself. You just ask the parser to process the inner content. What you get back as a result is a collection of block nodes. Those are your images.

If you run that example you will see what I mean.

Cheers,

-Dan

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

willwade

Jun 14, 2016; 8:49am

Re: extension docs

Thanks. So wrapper.blocks is the key. I can see its parsing two lines (each a block) and it knows the context is image and content_model is empty.. So I'm guessing I need to loop through each block and get the transformed content? (or raw). Looking at the API (http://asciidoctor.org/rdoc/Asciidoctor/Block.html) I can see I can access with Content or Source. So something like..

wrapper.blocks.each do |ig|
print ig.content
end

?? But I'm clearly being stupid here... !

(Sorry!)

mojavelinux

Jun 15, 2016; 2:36am

Re: extension docs

Administrator

It really depends on what you want to do. The ideal goal is to build an AST node, with child nodes attached, and return it. That way, everything stays in the Asciidoctor model. The converter is responsible for converting that to HTML.

After running parse_content, all the AsciiDoc inside the block is already parsed. The only think you need to do is create a new block, attach the children you want, decorate them with additional attributes (e.g., roles) and return.

Here's a quick sketch of how that might look:

require 'asciidoctor'

require 'asciidoctor/extensions'

Asciidoctor::Extensions.register do

block do

named :gallery

on_context :open

process do |parent, reader, attrs|

lines = []

wrapper = create_open_block parent, [], {}

parse_content wrapper, reader

counter = 'a'

wrapper.find_by(context: :image).each do |img|

src = img.attr 'target'

alt = img.attr 'alt'

thumb_src = src.sub(/\.[^.]+$/, '-thumb\0')

lines << %(image:#{thumb_src}[#{alt}, title="#{img.attr 'title'}", role=fancybox-effects-#{counter}, link=#{parent.image_uri src}])

counter.next!

end

create_paragraph parent, lines, {}

end

Since you want to create inline images, it's necessary to generate AsciiDoc. Down the road, we'll have an AST that goes all the way down into inline nodes.

This doesn't generate exactly the HTML you want because we are relying on the HTML generated from AsciiDoc.

</div>

If you want exactly the HTML you proposed, then you'd have to use a paragraph block with subs disabled and stuff raw HTML into it.

lines << %(<a class="fancybox-effects-#{counter}" href="#{parent.image_uri thumb_src}" title="#{img.attr 'title'}"><img src="#{parent.image_uri src}" alt="#{alt}"></a>)

and

create_paragraph parent, lines, {}, subs: nil

Cheers,

-Dan

On Tue, Jun 14, 2016 at 2:49 AM, willwade [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks. So wrapper.blocks is the key. I can see its parsing two lines (each a block) and it knows the context is image and content_model is empty.. So I'm guessing I need to loop through each block and get the transformed content? (or raw). Looking at the API (http://asciidoctor.org/rdoc/Asciidoctor/Block.html) I can see I can access with Content or Source. So something like..

wrapper.blocks.each do |ig|
print ig.content
end

?? But I'm clearly being stupid here... !

(Sorry!)

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/extension-docs-tp4746p4774.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

willwade

Jun 16, 2016; 3:57pm

Re: extension docs

Thanks a million!

I'm now having difficulty finding the docs for docinfo_processor..

docinfo_processor do
at_location :header
process do |doc|
backend = doc.backend
result = 'HELLO-WORLD'
end
end

This isn't outputting anything. I can't figure out how the licence demo works. How does it actually write to the header? Is it looking for the "result" variable contents?

(It isn't probably helping matters that I'm new to Ruby..)

mojavelinux

Jun 16, 2016; 5:07pm

Re: extension docs

Administrator

As of 1.5.4, the location is :head, not :header. We're reserving :header for future use. Since :head is the default, you don't even need to specify it.

> Is it looking for the "result" variable contents?

All that matters is what the process method returns.

> (It isn't probably helping matters that I'm new to Ruby..)

Don't doubt yourself.

Cheers,

-Dan

On Thu, Jun 16, 2016 at 9:57 AM, willwade [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks a million!

I'm now having difficulty finding the docs for docinfo_processor..

docinfo_processor do
at_location :header
process do |doc|
backend = doc.backend
result = 'HELLO-WORLD'
end
end

This isn't outputting anything. I can't figure out how the licence demo works. How does it actually write to the header? Is it looking for the "result" variable contents?

(It isn't probably helping matters that I'm new to Ruby..)

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/extension-docs-tp4746p4781.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux