Login  Register

How to introduce a new Slim template

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

How to introduce a new Slim template

torngat
12 posts
Hi everyone,

I thought I should start a new thread for this topic instead of continuing to overload another.  In essence, I'm still not clear on how I can create a new Slim template such that it is recognized by Asciidoctor as something valid (and used when running via the Maven plugin and not CLI).

How could I reproduce the "yell" example from the user manual if I want to use a Slim template approach instead of a Java based extension?  How can/should "yell" get registered?  Not being sure how to go about it, I created a Slim template called "block_yell.html.slim" and tried variations like this:

----
[yell]
Hey! Ho! Let's go!

[yell]
--
Hey! Ho! Let's go!
--

[name=yell]
Hey! Ho! Let's go!
----

The first two warn of invalid styles.  The third simply outputs the string and doesn't use the template.  I have also tried other variations, but to no avail.   Is this possible?

Thanks!

Sebastien


Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to introduce a new Slim template

mojavelinux
Administrator
2681 posts
Sebastien,

You still have to use the extension API to register the new block, but you can put all the logic in the template.

Here's how you register the block (shout-extension.rb):

require 'asciidoctor/extensions'
Asciidoctor::Extensions.register do
  block do
    named :shout
    on_context :paragraph
    name_attributes 'vol'
    process do |parent, reader, attrs|
      create_block parent, 'shout', reader.lines, attrs
    end
  end
end

The key line is this:

create_block parent, 'shout', reader.lines, attrs

That introduces a new type of block which you can then handle using a custom template.

Here's the template (shout.html.slim):

= content.upcase
= '!' * (attr 'vol', 1).to_i

This will handle the following AsciiDoc:

[shout, 5]
Just do it

Now you load it using:

 $ asciidoctor -r ./shout-extension.rb -T /path/to/templates doc.adoc

Of course, you could introduce a whole family of custom blocks by reading the name of the block from an attribute. For instance, let's say you make the second positional attribute the block name and the style something generic.

[custom, shout]
Just do it

Then the extension would change to:

Asciidoctor::Extensions.register do
  block do
    named :custom
    on_context :paragraph
    name_attributes 'name'
    process do |parent, reader, attrs|
      create_block parent, attrs['name'], reader.lines, attrs
    end
  end
end

Now, you only need one extension to cover an arbitrary number of custom blocks.

Keep in mind you'll need to change the value of `on_context` (or `on_contexts`) if you want to apply this to another type of block, such as an open block.

I hope that gets you started.

Cheers,

-Dan

On Wed, May 20, 2015 at 4:02 PM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi everyone,

I thought I should start a new thread for this topic instead of continuing to overload another.  In essence, I'm still not clear on how I can create a new Slim template such that it is recognized by Asciidoctor as something valid (and used when running via the Maven plugin and not CLI).

How could I reproduce the "yell" example from the user manual if I want to use a Slim template approach instead of a Java based extension?  How can/should "yell" get registered?  Not being sure how to go about it, I created a Slim template called "block_yell.html.slim" and tried variations like this:

----
[yell]
Hey! Ho! Let's go!

[yell]
--
Hey! Ho! Let's go!
--

[name=yell]
Hey! Ho! Let's go!
----

The first two warn of invalid styles.  The third simply outputs the string and doesn't use the template.  I have also tried other variations, but to no avail.   Is this possible?

Thanks!

Sebastien





If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/How-to-introduce-a-new-Slim-template-tp3248.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to introduce a new Slim template

torngat
12 posts
Hi Dan,

Two things:

1) Thanks a lot!  It worked beautifully and now I can extract my Bootstrap-enabled tabs and accordions into their own components!    Just out of curiosity, is it possible to package Ruby extensions into a library of some sort and refer to that archive via the <requires> configuration instead of explicitly defining every extension?  Of course, I guess the easiest approach would be to put all my new block definitions into a single Ruby file.

2) A thousand apologies, because you had already given me a lot of this information in the previous thread as a third way to achieve my goals.  The first having worked for the initial easy stuff, I forgot to go back and check your other suggestions.  I feel pretty bad about it, so I'll try to make it up in a documentation effort.  :/

Cheers!

Sebastien
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to introduce a new Slim template

mojavelinux
Administrator
2681 posts

On Fri, May 22, 2015 at 8:20 AM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks a lot!  It worked beautifully and now I can extract my Bootstrap-enabled tabs and accordions into their own components!  

Super!

 is it possible to package Ruby extensions into a library of some sort and refer to that archive via the <requires> configuration instead of explicitly defining every extension?
 
Absolutely. That's precisely what Asciidoctor Diagram does. See https://github.com/asciidoctor/asciidoctor-diagram

There's still an outstanding issue of being able to resolve templates from the LOAD_PATH. That would allow the templates to be packaged inside the gem as well. See https://github.com/asciidoctor/asciidoctor/issues/1352

No need to apologize. You've been asking some really great questions. If you want a concrete place to start with documentation, it's pretty clear we need that "how to use write and load custom templates to custom a converter" guide :) See https://github.com/asciidoctor/asciidoctor/issues/1167

Cheers,