Giters

richpeck / exception_handler

Ruby on Rails Custom Error Pages

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Readme is impractical

vasilakisfil opened this issue · comments

commented

Thanks for the gem.

But the readme is so fancy that is impractical. May I ask why there are pictures instead of regular code blocks which you can copy/paste them ?

commented

I was experimenting with the pictures.

I'll change the Readme in the next update, unless you'd like to submit a PR?

commented

ok. I don't want to ruin your style, everyone has its own and I think having such fancy pictures in the beginning of the Readme is unique and funny. I am mostly interested in the practical part, the code blocks.

I ll try to find some time during the weekend.

commented

Yep - I'm not bothered, I put them on all the things I do. I do agree though that they get in the way for many aspects -- I was going to upgrade the Readme when I had to do a new update but haven't got around to it yet

commented

This README is awesome. Maybe a little lense flare on the logo would make it 💯 .

I tend to copy/paste things when coming across a new projects, so I agree it'd be helpful if the code blocks were text instead of images.

commented

Thanks bud - yes I'll change it later. In terms of copy/paste, yes I do this too - I will be updating the readme after I finish a project I've been involved with.

commented

If I could throw my 2 cents in.. I'd really like to use this gem but I have no practical idea as how to. The README has links to "install/setup/config" but they just link to different sections with pictures. As far as I can tell, everything in the README lends to what the gem does but not what I need to do to get it working.

I think the look is creative and it truly showcases the gem and makes me want to use it but it's getting frustrating having to search all over on how to actually get it working. I understand
that you just install it and it runs but there's no clear guide on how to customize the exceptions_controller and other things that go on behind the scenes to make work in the way that I envision.

I'm not going to give up on trying to get it working but if the README at least included clear step-by-step instructions just to get it off the ground, that would be a major step forward imo. But from everything that I have seen/heard so far, this gem looks awesome, now I just need to get it functional for my needs.

commented

Hey man, thank you for the feedback

The current readme was meant to be updated but lots of other stuff has taken precedent recently 😞 I'll be updating the Readme soon as well as the gem (had some other stuff to work on recently). I did intend to fix up the Readme but just haven't got around to it yet.

--

In terms of getting it working, you're welcome to email me directly at rpeck@frontlineutilities.co.uk for specific help if you need it. For a general overview, here's what you need to do:

  • Add the gem to your Gemfile

  • Once the gem installs (don't worry about precompiling assets because that's done automatically), it will just work in production. Your 40x error pages will be the same as your controller's layout and your 50x pages will be the custom layout provided in the gem (this will get a makeover next version).

  • To get the Gem to show up in development, you will need to add the following to one of Rails' environment files (config/application.rb or config/environments/development.rb) ↴
    config.exception_handler = { dev: true }

  • This will use exception handler in dev mode

  • If you want to change any of the text that's shown by EH, you can add it to a new locale in config/locales/en.yml:

#config/locales/en.yml
exception_handler:
    not_found: "Text here"

This can be changed for any of the errors listed here (unfortunately, didn't get around to doing 40x/50x general error locales yet): https://gist.github.com/mlanett/a31c340b132ddefa9cca

For example, you may want to change the 500 error text, which is done with:

#config/locales/en.yml
exception_handler:
    internal_server_error: "Text here"
  • To change the layouts etc, you're going to have to use one of the generators to copy over the various view/asset files (detailed the readme)

Again, if you need further support, you're very welcome to email rpeck@frontlineutilities.co.uk and I'll be able to give specific info on code etc

commented

@richpeck thank you very much for responding both in a timely manner and with an insightful answer! I'm in the process of developing an intricate app myself so I fully understand prioritizing important tasks efficiently, so no worries. My post was only to provide feedback on how to make it easier for first time users to implement it but more importantly, to customize it appropriately without detracting from any of its great features.

I'll be sending you an email with a couple quick questions so that I don't hijack this thread. Thank you again for taking the time to answer a question that I'm sure you've answered hundreds of times 👍

commented

i appreciate the creativity, but the readme is overdone. i kept waiting for you to ask for my money. i'd be glad to pay because it's a useful gem, but hey.

your comments here should be the readme imo

also, why is the 5xx error page different than 4xx? the design won't fit with anybody's application. just let us handle that.

by the way, i've dropped nil in my 5xx series layouts in application.rb and it's still defaulting to your view....

commented

Firstly, thank you for taking the time to post, much appreciated.

kept waiting for you to ask for my money.

That's the world I come from so that's actually a compliment (thank you).

I fully appreciate the issue with the Readme and will be allocating time to update it. I have been fixing something else and as such have not got around to it yet. I also wanted to do a video to actually explain how it works properly. The reason the documentation is hyped is partly because I wanted to make it appealing, but also to practice my sales copy skills, which seems to have been moderately successful... even if it did defeat the point.

why is the 5xx error page different than 4xx

50x errors are server-related and since most people (me) have DB calls in their standard layout, it was best to use a different layout otherwise it would likely lead to an infinite loop (500 error... show layout... 500 error).

If you replace the nil with application (or whatever your main layout is called), it should start working again...

untitled
untitled

At present, you'll need to explicitly define each 50x error with the layout you need/want to use:

untitled

Sorry for the confusion - this should clear things up.

commented

Aye, Richard! Yeah, the "nil" for 5xx started working like five minutes after I sent in the comment. Was probably browser cache or something.

I do a lot of sales copywriting myself, so I get it. Separate discussion but I think gem creators should charge for their work.

Anyway thanks for the gem. Got it rolling in production now. Cheers!

commented

The Readme really looks like you are trying to sell something :P

commented

Thanks for the feedback - I just bought RailsHosting.com which is going to be a free way to deploy & manage rails-based VPS servers so I guess it is (in a way). Currently re-doing the Readme to be more practical as well as adding extra functionality.

commented

I just wanted to add a +1 to this thread. I was trying to debug a problem with this gem, in an older Rails project that I've just inherited. It's can be time-consuming and frustrating to view a README for a gem and not have it immediately list it's basic usage in plain text. The best kind of promotional advertising for a gem is that it is 1) actively maintained, and 2) appropriately documented.

commented

Working on a new Readme, thanks for the input.

commented

To me this is one of the best READMEs' on github. Cheers 👍

commented

lol - you'll like the new one even more in that case

commented

Making progress with new Readme - removed tons of crap and focused on functionality. Release will be soon.

commented

👍 on readme being impractical. Thanks for the effort you've put into it!

However, "Installation" link doesn't work for example, and that's the most crucial part of the readme.

The explanation of how it works is nice, but I'd leave it for some other part or below Installation and Usage.

❤️

commented

Just to add. There is no gem name...anywhere in the entire Readme. (There's no Installation section)

commented

As a beginner, I couldn't find any usage instructions in the README. I'm eagerly waiting for the new release/update to the README. :)

And, any suggestions for a resource regarding how to use this gem would be appreciated. :)

commented

I removed 90% of bullshit from Readme and will be updating further (0.8 branch)

For the resource - https://medium.com/ruby-on-rails-web-application-development/custom-400-500-error-pages-in-ruby-on-rails-exception-handler-3a04975e4677

commented

Dude. I really appreciate the work you've put into this, but being really frank, the README is still very impractical. Your audience is the dev community, we really just want to get in quickly and understand how to get up and running taking the shorted number of steps and then hopefully have pertinent details for all of the other stuff and to be honest, one really has to scroll through a lot of stuff to get to the important items and the important items like getting up and running quickly seem to lack clarity, whereas there are details what feels like the wrong places.

I don't want to be unproductive in my comment here, but dude... i want to use this and the README is getting in the way of that.

commented

Yes, I've thought the same thing for some time - I'll update it

commented

I've updated it - is it better now?