Hiccdown Development Notes
Notes about developing the Ruby gem Hiccdown.
Log in or sign up to participate in this discussion.
With an account, you can revise, criticize, and comment on ideas, and submit new ideas.
Hiccdown methods should live in Rails helpers as instance methods.
That isn’t a good idea because Hiccdown methods often share the same conventional names (index, show, etc), which can and does lead to conflict.
Hiccdown methods should live in Rails helpers as class methods. That way, the problem described in #302 is solved – methods can be referenced unambiguously:
ProductsHelper.indexStoresHelper.index
That would be mixing class methods an instance methods in Rails helper modules, which typically only contain instance methods. Not idiomatic Rails usage.
#327 applies here, too: no access to instance variables inside helper class methods.
Does that mean they wouldn’t have access to the view_context? If so, calling helper methods from inside these class methods wouldn’t be possible.
If so, there might be a way to bind them to the view_context. Or I could definitely pass the view_context explicitly as the first parameter:
So instead of
@helper_module.instance_method(@action_name).bind_call(view_context)
I would do
@helper_module.send(@action_name, view_context)
And the parameter list of each Hiccdown method would start accordingly:
module ProductsHelperdef self.index vc #, …vc.some_helper_methodenddef some_helper_method# …endend
Hiccdown methods should live in their own, separate classes. How about they are called ‘displays’?
class ProductsDisplaydef index vc, # …vc.some_helper_methodendend
Behind the scenes, the Hiccdown gem would need to make the instance variables available to the display class:
display = @display_module.newview_context.instance_variables.each do |iv|display.instance_variable_set(iv,view_context.instance_variable_get(iv))end
Then:
class ProductsDisplaydef index vc, # …vc.some_helper_method(@products)endend
I’m trying this now. Having to prepend every invocation of a helper method with vc. is getting really old really fast.
Then how would you call index from a helper method?
I don’t think that’s something people would do a lot, but they still easily could: ProductsRenderer.index(self)
Tested, it works. self does indeed point to the view_context in the helper. Verified by printing object_ids.
It doesn’t really matter. This would be like calling a controller action from a helper method. Not something people do.
Having explored three different ideas, I believe #302 – having regular helper methods to render Hiccdown structures – is the best.
The idea is not without its flaws, but having to qualify a method name by, say, calling it idea_form instead of form is still better than manually having to pass the view context around all the time and not being able to trivially access instance variables.
So I’ll stick with #302 for now, which is the status quo already.
I think the thing I’m really fighting here is Rails being object-oriented. Which I can’t do anything about.
Not sure the Rails team realizes how much OOP reduces the extensibility of Rails.
Could the errors around layouts be related to this?
Probably, and they're fixed. Hiccdown used to force a layout (layout: true, then layout: !request.format.turbo_stream?), overriding the layout method turbo-rails relies on, and turbo-stream requests failed with "no default layout" (fef00cb). cf92f06, in version 1.5.2, stopped forcing a layout. As of c5ce76f and 4a087e4, to be released in version 1.6.0, tests check that frame requests keep Turbo's frame layout and that turbo streams get none, and the app in test/dummy shows it in a browser.
Hiccdown should have support for ids and class names in the tag symbol. Like Hiccup.
[:'div#my-id.my-class.another-class']# => <div id="my-id" class="my-class another-class"></div>
It should also allow mixing:
[:'div#my-id.my-class.another-class', {id: 'override', class: 'additive'}]# => <div id="override" class="my-class another-class additive"></div>
In other words, the id from the hash would override the id from the symbol, and the class from the hash would be added to the classes from the symbol.
Done as of 3a304be, to be released in version 1.6.0, as described here. The id and classes can come in any order after the tag name, and two ids in one tag raise ArgumentError.
Yes. As of 4fd7a0e, to be released in version 1.6.0, the layout named X lives in XHelper#layout, just as it would in layouts/X.html.erb, so the application layout lives in ApplicationHelper#layout. yield and yield(:title) work as in an ERB layout, and layout files keep working for a gradual migration.
Is there a way to teach user-built helpers how to process Hiccdown? Or maybe intercepting capture already took care of this?
Mostly, intercepting capture already took care of it: helpers of your own that pass a block on to Rails' helpers, or return Hiccdown, worked. Hiccdown given to Rails' helpers as content didn't, as in content_tag(:div, yield), tag.div([:span, 'foo']) or link_to([:span, 'foo'], path). As of 134deb9, to be released in version 1.6.0, it does.
Redirects result in two additional requests, the first of which is a turbo-stream request that renders nothing, thus (presumably) prompting the browser to make another request for the same resource.
Doesn't reproduce as of e71df95. In the app in test/dummy, a form whose action redirects takes one POST and one GET in a headless browser, which a system test now checks.
Use frame layout for turbo frame requests? https://discuss.rubyonrails.org/t/the-right-way-to-override-render-method/84765/2
They already do: turbo-rails gives frame requests its own minimal layout, and Hiccdown leaves it be. As of c5ce76f, to be released in version 1.6.0, a test checks that frame requests keep Turbo's frame layout even where ApplicationHelper#layout exists, and a system test (e71df95) loads a frame in a browser.
When an empty block is passed to render, it results in an empty tag '<>'
Calling render with options only, such as render status: :not_found or render layout: 'admin', skips the action's helper method and looks for an ERB template instead. Without one, it raises ActionView::MissingTemplate:
class ProductsController < ApplicationControllerdef showrender status: :not_found # MissingTemplate, though ProductsHelper#show existsendend
Naming the action works around it: render :show, status: :not_found.
Fixed as of 9c46c61, to be released in version 1.6.0.
Hiccdown finds an action's helper method through params[:action] rather than the controller's action_name. When a controller runs without the router, as in ProductsController.action(:show).call(env), params[:action] is nil and rendering raises NoMethodError: undefined method 'to_sym' for nil instead of calling ProductsHelper#show.
Fixed as of 31cf174, to be released in version 1.6.0.
On Rails 8.1, Hiccdown's capture hands keyword arguments to the block as key-value pairs rather than as keywords. capture(text: 'foo') { |text:| text } raises ArgumentError: missing keyword: :text instead of returning 'foo', and a block that takes them as a hash, { |options| … }, gets [:text, 'foo'] instead of {text: 'foo'}.
Earlier versions of Rails pass keywords on to the block as a hash, which Hiccdown leaves alone.
Fixed as of 99b6280, to be released in version 1.6.0.
A helper method that calls another action's helper method by name can get another helper's. Rails mixes every helper into every view, so calling index from ItemsHelper#create runs whichever helper's index Rails included last, such as PagesHelper#index:
module ItemsHelperdef index[:ul, @items.map { |i| [:li, i.name] }]enddef createindex # PagesHelper#index, not ItemsHelper#indexendend
Action names like index, show and edit are in many helpers, and the Readme encourages helper methods calling one another.