extension docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

extension docs

willwade
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?
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

mojavelinux
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'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.


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



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

willwade
Thanks for that.

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

Thanks again

w
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

mojavelinux
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
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

willwade
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??!)
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

willwade
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
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

mojavelinux
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
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

willwade
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!)
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

mojavelinux
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
  end
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 class="paragraph">
<p><span class="image fancybox-effects-a"><a class="image" href="images/4.jpg"><img src="images/4-thumb.jpg" alt="4" title="Some title"></a></span>
<span class="image fancybox-effects-b"><a class="image" href="images/3.jpg"><img src="images/3-thumb.jpg" alt="3" title="Some title"></a></span></p>
</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



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

willwade
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..)
Reply | Threaded
Open this post in threaded view
|

Re: extension docs

mojavelinux
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



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