Is it possible in quarto to create custom cross-references to callout blocks? - r-markdown

Task
I'm using quarto to write an online book and need to mimic the environments and counters of a published book. The latter employs five custom framed environments (examples, exercises, remarks, theorems, definitions) with a joined counter (within the chapter).
I'm considering to use the readily available callout blocks for these because these are styled quite nicely by default. I haven't been successful, though, to create a custom counter for these callout blocks so that I can cross-reference from the text. Is there a way to do so?
(Remark: I've also tried to do this via standard amsthm environments provided through quarto, see Shared counter in quarto for exercises, examples, etc.)
Demo
I would have hoped that something like the following existed so that I can create a new #callout counter. But I couldn't find infrastructure for this:
The first definition is #callout-1.
:::{.callout-note}
## Definition {#callout-1}
This should be Definition 1.1.
:::
It is followed by the first example, #callout-2
:::{.callout-tip}
## Example {#callout-2}
This should be Example 1.2.
:::
Because this doesn't work like this quarto renders this to:
But what I'm looking for is a result like this:

The only way I was able to do this was to add an ID to the callout
::: {#callout-1 .callout-note}
## Definition {#callout-1}
This should be Definition 1.1.
:::
And then manually call it in your markdown through:
Please refer to the [note 1](#callout-1)

You can refer Examples or Exercises within callout blocks by extending this answer to your other question related to this question, like this,
# Introduction
The first example is #exm-1.
::: {#exm-1}
This should be Example 1.1.
:::
It is followed by the first exercise, [Exercise #exm-2]
::: {#exm-2 .custom}
This should be Exercise 1.2.
:::
:::: {.callout-note}
::: {#exm-3}
This should be Example 1.3
:::
::::
:::: {.callout-tip}
::: {#exm-4 .custom}
This should be Exercise 1.4
:::
::::
Please refer to the #exm-3
Please refer to the [Exercise #exm-4]
and add these two lines in your project yaml _quarto.yaml
_quarto.yaml
callout-appearance: simple
callout-icon: false
The rendered output looks like,
Again, Note that when you want to render the Example environments as Exercise, use the .custom class, so that the javascript code written in this post will apply.
Also, you can also write javascript code to handle the Definition tag in the same way as this.

Related

Can JS-DOM test code that uses Tailwind's peer / peer-invalid mechanism?

Tailwind offers a feature where you can give an input element the peer class and then, in a sibling element use the peer-invalid: pseudoclass to apply conditional stylings. This is commonly used to provide helper text when a form field is not valid.
I don't see how this can be tested in JS-DOM though, as JS-DOM doesn't have access to the actual CSS when it is just rendering components in unit tests.
The information I have seen about getting JS-DOM to use CSS at all is kinda sketchy, so I was wondering if it's even worth trying to get it to evaluate a bunch of tailwind classes in a NextJS/Jest/RTL project. I'm using Tailwind 3 so it's not even like I have a big file full of generated classes I could try and pass to JS-DOM :/
So can it be done? (Note the hard fact please mods!!!)
(And, somewhat more subjectively, should it be done? Or is there a better way to approach this?)

Auto-increment integers for POD items

Would anyone know of a way to dynamically increment an integer for item titles? This is mainly to avoid having to change every step number in the event that a new step would need to be added/removed somewhere in the middle of a ton of steps. Below is a small three-step procedure to give you a rough idea of the template structure:
=step_wash 1. Wash
<p>Add washing steps here</p>
=cut
# Throw some perl code here to wash stuff
=step_dry 2. Dry
<p>Add drying steps here</p>
=cut
# Throw some perl code here to dry things
=step_fold 3. Fold
<p>Add folding steps here</p>
=cut
# Fold all of the things Perl!
Disregarding the item names and structure of this, the goal is to try and eliminate the use of statically numbering the title of each item. I am wondering if there is a possible way to generate an integer that increments; pretty much like replacing 1, 2, 3, etc with something like { print $i++ } instead.. but in POD.
POD is pretty Plain and doesn't do that sort of thing.
An extension of POD called PseudoPod in theory does (see https://metacpan.org/pod/distribution/Pod-PseudoPod/lib/Pod/PseudoPod/Tutorial.pod#Lists) but when I tried it it gave an error.
There is nothing built into POD that allows doing automatic numbering.
I see that you are using custom POD regions which encompass HTML markup, your POD also doesn't look like normal documentation. If you are trying to do Literate Programming, there should exist systems that don't require you to write POD. If this is just normal documentation, you should probably remove the HTML, as docs are often viewed via perldoc – on the command line.
Sometimes it isn't neccessary to use numbering at all. Bullet points • are pretty as well.

Using Type-safe URLs with setMessage? (shamlet versus hamlet)

How do I use a type-safe url with setMessage?
I want to change
...
setMessage [shamlet|<span .warning>Warning! See Help.|]
...
to a message that contains a link.
From what I could gather thus far, it ought to work somehow like this
...
renderer <- getUrlRender
let html = [hamlet|<span .warning>Warning! See #
<a href=#{HelpR}> Help!|]
setMessage $ toHtml $ html renderer
...
but that code just gives me confusing error messages all over the file.
I did read the printed Yesod Book Chapter on Shakespearian Templates, but I found that it is not very explicit on the involved types. For instance what type does [hamlet|...|]| produce? Without URL-Interpolation, ghci reports t -> Markup but with URL-Interpolation inside, I just get errors.
I am further confused by all the type synonyms involved, e.g. [shamlet|...|] delivers something of type Html, while setMessage expects a Html (). I do not know how to look these up easily: Hoogle often finds nothing on the topic, while Google always finds possibly outdated versions (with examples that no longer work) - sure I get to the newest version eventually, but is there a place where I get an easy overview over these? (Can ghci list all synonyms for a type?)
Note that I actually want to produce the message in a purely functional code fragment, which is later on used by a handler. So that is why I would like to separate the URL rendering from where the hamlet is specified. Thanks for any pointer in the right direction!
I think you want to use getUrlRenderParams. Strangely enough, a related discussion came up on IRC today. Hamlet templates take a URL rendering function as their first argument, and that function must take two parameters: a type-safe URL, and a list of query string parameters. getUrlRender returns a function that doesn't take the query string parameters, which is why you need getUrlRenderParams instead.

Scala / Lift - Trying to understand Lift's simultaneous claim to use valid html and propensity for lift: tags and tag rewriting in render

All of the Seven Things (http://seventhings.liftweb.net/) are certainly nice, but I was particularly enthusiastic about the claim in Templates (http://seventhings.liftweb.net/templates) that "Lift supports designer friendly templates."
As one of my steps in learning Lift's way of doing things I'm attempting to create a simple object creation form: take a few parameters, use them as constructor arguments, then stow the object away. After some research and experimentation, tho, I have two concerns:
There seems to be a considerable propensity for significantly rewriting/embellishing the template markup in snippets.
Forms don't seem to use valid or recognizable html elements.
What I'm basing this on:
The form examples/documentation seems all about special lift: tags. Exploring Lift suggests that a form should look like this: (http://exploring.liftweb.net/master/index-6.html)
<lift:Ledger.add form="POST">
<entry:description />
<entry:amount /><br />
<entry:submit />
</lift:Ledger.add>
I'm not sure that's even valid html5 and while it might be valid xhtml, it doesn't feel like that meets the spirit of having your templates look like real html for our designer friends. I read somewhere else (can't find it again) that we did have the option of using actual input tags, but then we wouldn't get some parts of Lift's fancy form wire-up or somesuch, the passage wasn't very clear on what exactly I'd be missing out and the examples don't seem interested in my writing a plain html form making a plain html post.
The code for a demo.liftweb.net example (1) suggests that your template should look like this (2)
<lift:surround with="default" at="content">
<div class="lift:PersonScreen"></div>
</lift:surround>
The code for PersonScreen snippet isn't exactly illuminating, either (3). There are several other examples of a template that has, e.g. only a ul tag in a particular location only to generate a whole series of complex li's with nested elements in the snippet. Sure, you can use xml in Scala and it reads tolerably, but it's still scattering your markup everywhere. This seems to violate the spirit of "designer friendly templates".
What I want to understand.
For a long time I've strictly followed two rules in my webapp development:
No markup in 'code' (controllers, business models).
No business logic in the templates whatsoever.
Idiomatic Lift seems to completely forego the first rule and completely miss the value of the second rule. These rules have served me well and I'm not ready to just follow along with the examples that seem to be violating them without understanding why its not going to create a mess. I want to understand why it's okay in Lift to have so much display code generated in the Snippets. I also want to understand why its okay that the markup in the templates so rarely reflects the output.
What I (think I) want:
I want all of my markup with very few, if any, exceptions to be in my templates. I want my snippets to do minimal template mangling, generally only replacing element text on "leaf" tags and possibly tweaking attribute values. I think I've done this for a reasonably complex display example and I suspect I could use the same technique to generate a vanilla html form and then handle the params myself. Is that what I need to do if I want my template to look like the end-result form?
Responses and any other thoughts, especially on understand the Lift mindset regarding this stuff, would be tremendously appreciated.
Thanks!
http://demo.liftweb.net/simple_screen?F674431078927QJVVYD=_
https://github.com/lift/examples/blob/master/combo/example/src/main/webapp/simple_screen.html
https://github.com/lift/examples/blob/master/combo/example/src/main/scala/net/liftweb/example/snippet/Wizard.scala#L94
EDIT
In response to #OXMO456. (Thanks for the response.)
I have, and they seem to just confirm my concerns: E.g. we start with:
Lift templates contain no executable code. They are pure, raw, valid HTML.
which is awesome. Then later:
The latter two mechanisms for invoking snippets will not result in valid Html5 templates.
and yet everyone seems to use the first of those two mechanisms. Also, it says:
Third, the designers don’t have to worry about learning to program anything in order to design HTML pages because the program execution is abstracted away from the HTML rather than embedded in the HTML.
But pretty consistently the example snippets like the one I referenced in the OP generate markup entirely programmatically. This seems counter to the goals (a) of having designer friendly templates so the designers don't have to be bothered with Freemarker markup and (b) separating display logic from business logic.
The second link is helpful and instructive, but it makes it pretty clear that this isn't The Lift Way. However, The Lift Way also seems to drag a whole load of markup generation into snippets, which is (I think) a huge compounding of markup and business logic. Is that The Lift Way?
Those are old-style tags, not designer-friendly tags.
<lift:MySnippet>
<b:field />
</lift:MySnippet>
becomes
<div class="lift:MySnippet">
<div class="field"></div>
</div>
Old-style Lift templates are valid XML, not XHTML - so you can't have unclosed tags or anything - this differentiates Lift from most frameworks, which treat templates as raw strings with bits of code intertwined throughout, without regard to tags or structure.
BTW, in old-style tags, those fields are all fabricated - they aren't part of some standard set of Lift tags. I could just as easily do:
<lift:MySnippet>
<frobnicate:blorb />
</lift:MySnippet>
as long as my snippet code is looking for that specific tag.
Lift doesn't allow any logic in your templates. All of the logic happens in your Snippet class. So for the designer-friendly example above, I might have a snippet class like this:
class MySnippet {
def render(in: NodeSeq): NodeSeq = ".field" #> Text("some text here")
}
which would yield this result:
<div>
<div class="field">some text here</div>
</div>
It's impossible to put any logic in Lift templates - all they can do is invoke Lift snippets, which are regular Scala classes where all of the work happens.
Lift discards the rule that you shouldn't have any display logic in your real code. Why? Because it makes for more reusable code, because Scala has powerful XML support baked into the language and because all of your logic is now treated as plain old Scala code.
If I define a Lift snippet called CurrentTime, I can simply drop that in to any template and it will display the current time - with old-school MVC frameworks, each action method needs to set the time as a page variable and then my templates would need to be modified to print it out. For more complicated logic, old-school frameworks would probably require a conditional in the templates. Lift doesn't allow that - all of your logic is regular Scala code, eligible for refactoring, easily testable, and compatible with modern IDE's.
In answer to you're "what I think I want" question, sure you can do that no problem. Lift is really all about choices, and understanding your use case. Often the samples you see with Lift intermingle code and markup, which is of course sub-optiomal. The important thing to note is that snippets conceptually are solely designed to produce markup, and render the view.
In addition, as Lift follows its view first paradigm the only thing that the view actually requires is a notation to outline which sections of markup you want to process in which rendering snippets. There are several ways, as illustrate by both the OP and "Bill", but personally I prefer:
<div lift="YourSnippet.method">
<p>Some other code</p>
</div>
This is preferable because you're then not culturing up the class attribute which (IMO) can be confusing for designers. Lift can be very designer friendly, but I think the main problem here is that you have to be both disciplined when writing your snippets whilst ignoring many of the samples available today which mix Scala and markup.
You may also be interested in this post ( http://blog.getintheloop.eu/2011/04/11/using-type-classes-for-lift-snippet-binding/ ); using this sort of pattern you can define decoupled, reusable parts of rendering logic whilst keeping your business logic safely out of the snippets.
Finally, and without wanting to shamelessly promote my own product, but I specifically went out of my way to not use any mixed Scala xml literals in my example code for Lift in Action (other than to illustrate that its possible), so perhaps it might be of assistance if you're looking at Lift ( http://manning.com/perrett/ )

Opinion: Where to put this code in django app:

Trying to figure out the best way to accomplish this. I have inhereted a Django project that is pretty well done.
There are a number of pre coded modules that a user can include in a page's (a page and a module are models in this app) left well in the admin (ie: side links, ads, constant contact).
A new requirement involves inserting a module of internal links in the same well. These links are not associated with a page in the same way the other modules, they are a seperate many to many join - ie one link can be reused in a set across all the pages.
the template pseudo code is:
if page has modules:
loop through modules:
write the pre coded content of module
Since the links need to be in the same well as the modules, I have created a "link placeholder module" with a slug of link-placeholder.
The new pseudo code is:
if page has modules:
loop through modules:
if module.slug is "link-placeholder":
loop through page.links and output each
else:
write pre-coded module
My question is where is the best place to write this output for the links? As I see it, my options are:
Build the out put in the template (easy, but kind of gets messy - code is nice and neat now)
Build a function in the page model that is called when the "link placeholder is encountered) page.get_internal_link_ouutput. Essentially this would query, build and print internal link module output.
Do the same thing with a custom template tag.
I am leaning towards 2 or 3, but it doesn't seem like the right place to do it. I guess I sometimes get a little confused about the best place to put code in django apps, though I do really like the framework.
Thanks in advance for any advice.
I'd recommend using a custom template tag.
Writing the code directly into the template is not the right place for that much logic, and I don't believe a model should have template-specific methods added to it. Better to have template-specific logic live in template-specific classes and functions (e.g. template tags).