Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

504 previews with sample source code #667

Merged
merged 43 commits into from Jun 25, 2021

Conversation

johannesengl
Copy link
Collaborator

@johannesengl johannesengl commented Mar 17, 2021

Summary

This PR introduces a source code example snippet on view component previews.

Screenshot 2021-06-02 at 20 12 00

In order to add syntax highlighting we rely on prism.js. To use the library we need to add one js and one css asset file. Those files are served as static assets from the gems assets/vendor directory and we therefore don't require the host app to use a specific setup for handling assets like webpacker or the assets pipeline.

The prism javascript file includes syntax highlighting for the following languages: ruby, erb, haml.

To enable the source previews users can set config.view_component.show_previews_source = true. The config option defaults to false. A view helper method preview_source is added to render the preview source.
The helper method is conditionally called based on the config option at the end of the preview.html.erb view file.
Users can also use the helper in their views for more flexibility of where to render the preview source.

@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch from 0eb3d7c to b0fb20e Compare Mar 22, 2021
Returns the method body from the preview file located in the host location under test/components/previews. This is being used if the preview file does not use render_template.
@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch from b0fb20e to 3299f47 Compare Mar 22, 2021
@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch from 3299f47 to d711993 Compare Mar 25, 2021
@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch from 43d14f8 to fc06afb Compare Apr 15, 2021
@jonspalmer
Copy link
Collaborator

@jonspalmer jonspalmer commented Apr 15, 2021

A few thoughts:

  1. Can we come up with a better mechanism for including the prism css and js?
  • Are they necessary?
  • What are the alternatives?
  • How can we avoid snapshotting a particular version which makes upgrades and maintenance a PITA. is there an npm type solution?
  1. Can we add test coverage of this new behavior?

A more meta level question would be how much do we want to add the Previews? Other solutions, such as Storybook, have many of these features already baked into them and likely offer a superior end user experience with many additional features. I wonder if this is one of the places where we defer to that?

@johannesengl
Copy link
Collaborator Author

@johannesengl johannesengl commented Apr 15, 2021

@jonspalmer thanks for your input on this! ❤️

I had a call with @joelhawksley before getting started on this and we decided on using prism and starting simple by just adding the assets via the assets pipeline. The benefit of using the assets pipeline is that we don't force users to use a specific tool for managing assets which keeps the deployment setup easy - no webpacker or npm required for using view component.

  1. Can we come up with a better mechanism for including the prism css and js?
  • Are they necessary?

If we want to give users syntax highlighting I guess the most adequate approach would be to rely on a library like prism.js for this which requires us to add assets.

  • What are the alternatives?

Do you mean alternative ways to include the assets or alternative libraries for syntax highlighting?

  • How can we avoid snapshotting a particular version which makes upgrades and maintenance a PITA. is there an npm type solution?

Interesting. Yes, it would be nice if we could update the prim assets in an easier matter. Wondering how frequent we need to update the prim version and if it justifies making the asset setup of the gem more complex.

  1. Can we add test coverage of this new behavior?

Sure. This is still WIP and I will add tests for this shortly.

Users can use other templating languages like haml. The template file extention can be used to retrieve the correct language. Fallback to ruby if there is not specific syntax highlighting available for the fiel extention.
…annesengl/view_component into 504-previews-with-sample-source-code
@jonspalmer
Copy link
Collaborator

@jonspalmer jonspalmer commented Apr 15, 2021

@johannesengl Thanks for the feedback. Sounds like you're way ahead of most of my questions.

I'm curious about use of the asset pipeline usage. How does that play with apps that are using pure Webpacker and none of the traditional asset pipeline? Have we tested that combination?

-  use content_for for including code example within body
- remove stylesheet_link_tag. The stylesheet should be included explicitly via the host application.
@johannesengl johannesengl marked this pull request as ready for review Apr 15, 2021
@johannesengl
Copy link
Collaborator Author

@johannesengl johannesengl commented Apr 19, 2021

@johannesengl Thanks for the feedback. Sounds like you're way ahead of most of my questions.

I'm curious about use of the asset pipeline usage. How does that play with apps that are using pure Webpacker and none of the traditional asset pipeline? Have we tested that combination?

I just spend some more time testing out different setups as you suggested and indeed when removing sprockets in the host application the following raises an error:

    initializer "view_component.assets.precompile" do |app|
      app.config.assets.precompile << "view_component/prism.css"
      app.config.assets.precompile << "view_component/prism.min.js"
    end

https://github.com/github/view_component/pull/667/files#diff-fe26dc052312860cc076b99a7f3c0913bf834fc73fe246def378024ffc038164R89

I did some research of how other rails engines include assets in the host application and found the following discussion:
https://discuss.rubyonrails.org/t/how-to-pack-js-from-a-different-gem-engine-in-rails-6-webpacker-it-seems-frustrating/75364/10

My resolution is that if I need to share js between projects I am better of keeping the js in npm, like rails-ujs, like turbolinks for example. They don’t come as engines, but as npms. Much cleaner.

Sidekiq Web UI
Looking at sidekiq web UI they register their own rack app and rely on Rack::Static to reference the static assets. I don't think this is a valid solution for us:
https://github.com/mperham/sidekiq/blob/f0a20b1a5e6b06853083774d35b79d39821085b7/lib/sidekiq/web.rb#L146
https://github.com/mperham/sidekiq/blob/f0a20b1a5e6b06853083774d35b79d39821085b7/web/views/layout.erb#L21

Active Admin
I also had a look at the gem active admin . They provide two different generators depending if your using webpacker or not and copy the assets files into the right location in the host application.

https://github.com/activeadmin/activeadmin/blob/master/lib/generators/active_admin/webpacker/webpacker_generator.rb

I don't really like the idea of adding an extra step to setup view component and requiring users to run a generator for installation.

Resolution

Given that rails 6 comes by default with webpack for including javascript and sprocket for including other assets I feel like view component should support both webpack and sprocket for including the assets.

I am wondering how about we just don't add assets at all for a specific library like prism.js and let this step be up to the users of the gem?

@jonspalmer @joelhawksley What is your opinion on the above?

@joelhawksley
Copy link
Contributor

@joelhawksley joelhawksley commented Apr 19, 2021

@johannesengl this might not be a great long-term solution, but since this is only meant for diagnostic use, could we start by vendoring the JS and CSS assets directly into the gem and serve them inline on the page? It's not ideal, but could unblock our work here.

@johannesengl
Copy link
Collaborator Author

@johannesengl johannesengl commented Jun 4, 2021

@jonspalmer Mind having another look? I updated the PR based on your suggestions.

@johannesengl johannesengl requested review from jonspalmer, Spone and joelhawksley and removed request for jonspalmer and joelhawksley Jun 10, 2021
@johannesengl
Copy link
Collaborator Author

@johannesengl johannesengl commented Jun 15, 2021

@jonspalmer Mind having another look? I updated the PR based on your suggestions.

Would love seeing this being used at some point :) @joelhawksley or @jonspalmer mind having another look?

@Spone
Copy link
Collaborator

@Spone Spone commented Jun 15, 2021

Just to reiterate on #667 (comment), I really think the method signature (def render) should be stripped, I see no point in displaying it.

CHANGELOG.md Outdated Show resolved Hide resolved
@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch 2 times, most recently from 0f58048 to fd24109 Compare Jun 23, 2021
@johannesengl johannesengl requested a review from Spone Jun 23, 2021
@johannesengl johannesengl force-pushed the 504-previews-with-sample-source-code branch from fd24109 to 6e9f3ef Compare Jun 23, 2021
CHANGELOG.md Show resolved Hide resolved
docs/CHANGELOG.md Outdated Show resolved Hide resolved
CHANGELOG.md Show resolved Hide resolved
lib/view_component/base.rb Show resolved Hide resolved
Spone
Spone approved these changes Jun 25, 2021
@Spone Spone merged commit e3d801c into github:main Jun 25, 2021
16 checks passed
@Spone
Copy link
Collaborator

@Spone Spone commented Jun 25, 2021

Here you go! Thanks again for your contribution @johannesengl 🚀

@johannesengl johannesengl deleted the 504-previews-with-sample-source-code branch Jun 28, 2021
@joelhawksley
Copy link
Contributor

@joelhawksley joelhawksley commented Jul 2, 2021

@johannesengl would you be willing to add slim highlighting support to this feature?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants