search

thoughtbot / administrate

A Rails engine that helps you put together a super-flexible admin dashboard.
http://administrate-demo.herokuapp.com
MIT License
5.88k stars 1.11k forks source link

Plugin structure and best practices #123

Closed rikkipitt closed 8 years ago

rikkipitt commented 8 years ago

Hey guys,

I've been waiting for you to release this to the public, it's great so far! Are you planning to put together a set of best practices for creating addons/plugins to add field types like WYSIWYG editors and integrations with things like Paperclip? It would be awesome to be able to share them and find useful extensions in a directory of some sort...

Cheers, Rikki

c-lliope commented 8 years ago

@rikkipitt absolutely!

We still need to iron out specifics, but I'm hoping we can break out gems with supporting functionality.

For custom field types, supporting gems might be as simple as running rails generate administrate:field my_field_name, and then packaging up the output into a gem.

I'll try splitting out the image field into a separate gem to set a precedent.

c-lliope commented 8 years ago

@rikkipitt while we're at it, can you give me an example of plugins that you'd find useful? I want to make sure I'm supporting all the common use cases.

rikkipitt commented 8 years ago

@graysonwright fantastic news!

I'll take a look today, but I think a good start would be image/file upload and a rich editor field. https://github.com/galetahub/ckeditor tends to be a good choice when using RailsAdmin. The ckeditor gem has the ability to integrate with Paperclip and thus any external asset host.

Some field types such as sorting might require the addition of a custom controller action, but we can get into that at a later date.

c-lliope commented 8 years ago

I'm starting to think that plugins could have a Administrate::Plugin subclass that defines:

The root-level javascript and CSS files could require the other stylesheets and scripts for the plugin. Custom view templates would be a bit tricker, because we would need to be careful that plugins don't collide with one another by overwriting the same templates.

rikkipitt commented 8 years ago

@graysonwright #187 is an offshoot of this, sorry about that. But this sounds great. An entry point for javascript and stylesheets would be great for custom plugins. I assume extra views would be for things like fields with modals etc.

I had a play last night at creating a WYSIWYG plugin but the limitations on includes was a bit tricky and the workarounds weren't pretty! I.e. content_for :javascript.

Once you've ironed out a few of these ideas, it would be great for you to release the image field as you mentioned before. It's own gem, as an example for everyone, will help keep things uniform in the community that I'm sure that will form around Administrate.

Rikki

5minpause commented 8 years ago

@graysonwright this sounds like a good direction for plugins. We always have to provide multiple-selection <select>'s and tend to include chosen.js for usability. I could imagine writing a plugin to have it available in every project.

rikkipitt commented 8 years ago

I think we have two cases here...

  1. Custom, one off fields for a particular project that might require the use of javascript/scss.
  2. Plugins created by the community and packaged up as gems.

Packaged gems should be easier and have their own asset paths etc. But I assume that they'll all follow the same sort of build process so that custom fields can be easily extracted and released independently.

DropsOfSerenity commented 8 years ago

@graysonwright A common use case may (one that i'm coming up against right now) is creating a text field that is a markdown entry and previewer with javascript. Much like Ghosts markdown previewer, or even github's write/preview paradigm for a text field.

Just throwing in here since I noticed activity taper off, I'm digging through the source right now and i'll see what I can come up with.

Tensho commented 8 years ago

Just to remind, that this discussion is related to #267, particularly about image/file field.

c-lliope commented 8 years ago

We just released version 0.2.0, which supports plugins!

The administrate-field-image gem at https://github.com/graysonwright/administrate-field-image is a good template to model new plugins off of – that repository demonstrates the file structure that Administrate requires for custom field type plugins.

After you've built your plugin, let me know where it lives (on GitHub and on rubygems.org) so I can share it with others.

rikkipitt commented 8 years ago

Hi @graysonwright sorry for the radio silence on this. Thought you'd like to know I've sketched out and released a ckeditor plugin that follows on from your style.

References: https://github.com/jemcode/administrate-field-ckeditor https://rubygems.org/gems/administrate-field-ckeditor

Just a v0.0.1 so far, but hopefully they should evolve over time with the help of the community.

Rikki

c-lliope commented 8 years ago

573 adds a few helper methods that you can use in your plugin's Engine class to add stylesheets and javascripts to Administrate.

Administrate::Engine.add_javascript "my_plugin/script"
Administrate::Engine.add_stylesheet "my_plugin/styles"

For an example, see https://github.com/graysonwright/administrate-field-nested_has_many/blob/master/lib/administrate/field/nested_has_many.rb#L12-L14

rikkipitt commented 8 years ago

Thanks @graysonwright, I've just updated my plugin successfully and released a new version. Works well!

schovi commented 7 years ago

Hello there.

I am just put Administrate into my app instead of active admin and it is awesome sofar. Having few questions, but will see after some time of using. But there is one challenge ahead me. I want to visualise tree structure on dasboard#index action with moving entities around tree, sorting, collapsing etc. Have anybody tried to do something larger like this?

nickcharlton commented 7 years ago

Hi @schovi!

As this issue is closed, could I get you to open a new one? It's easier for everyone to keep track of them if they're more defined!

To answer you specifically: I'd have a look at the reverse dependencies and see if someone else has already built a plugin that does some of what you'd be looking for.