How do you learn to build Discourse plugins?

How do you guys build such amazing plugins with discourse ? I am not even able to integrate a custom field to discourse topic using a custom plugin. Is there any documentation that can help me build an advanced plugin like this?

The introduction series to Discourse plugins only touches the plugin outlet part. But how do I take that and integrate it with Discourse? I tried reading the source code of Discourse plugins, as Jeff suggested, But I only have questions like what does add_to_serializer or create_custom_field do ?

I also want to build amazing plugins / contribute to discourse… please let me know if you have any material on learning to create Discourse plugins.

4 Likes

The code is the only thing to look at.

Everything used by the plugins is defined in Discourse core… or by Rails, or by Ruby itself. It’s open source all the way down, so if you don’t know what add_to_serializer does, search the Discourse codebase for def add_to_serializer, and the learnings shall continue.

4 Likes

And how do you debug the discourse application? I am using byebug, but I was looking more into a debugger which can be easily integrated with the text editor like atom or brackets or visual studio code.

Did you read this guide yet?

9 Likes

What you want is exactly what I want. I am completely lost as well. I was going to try a work around, but it seems that a plugin is the right way to do this. As there is no documentation, I will have to break the code to figure it out.

1 Like

Between the “How to start building stuff…” guide and the “Beginner’s guide to creating Discourse plugins”, what exactly are you missing?

If you can give us more specific feedback on what you need to get started, we’ll definitely take that into consideration.

For the JavaScript side of things, you want the plugin api

The source code is well documented

https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/lib/plugin-api.js.es6

It took me a while to find it - maybe a link to the API topic could be added to the JavaScript section of the “Beginners guide to creating discourse plugins” @eviltrout

7 Likes

It seems like you’re asking for the conceptual viewpoint of how to build a plugin over the technical. I can’t say that I see myself as a great example of how to do it the right way, but here’s what I would suggest:

  1. Go through @eviltrout’s guide to building plugins and do every step. No skipping. This will give you a foundation of how to get started with a plugin and teach the core processes that you’ll need later.
  2. Pay attention to how things are done in core. What elements are used repeatedly? How do they use buttons, navigation, links, etc…? This will pay huge dividends later when you have an idea and want to know how to do it. Which brings me to 3.
  3. Learn how to trace code. When you see an element or want to use something from core (like the methods used to create new color themes in Customize), you need to know how to search the repository for the handlebars template that generates the html and trace it all the way back to the Rails routes or vice versa. If you can nail down every file and piece of code that is run to generate the front-end, you’re set up to duplicate a LOT without needing to write it all from scratch.
  4. Develop ninja skills when searching on GitHub. Knowing how to search for a code snippet within a given path in the repo or searching across repos within an organization are huge for me.
  5. Get really good with developer tools. It’s rare that I have an issue with code that I can’t decipher with the Chrome developer tools. Add the Ember Inspector extension to Chrome and pull up Meta. Open the composer, navigate to profiles, do stuff. And pay attention to how things move and change as you interact with the application. Pro tip: The network tab will give you tons of clues about how to pass data back and forth between Ruby and Ember.
  6. Read the code for other plugins. We’re all learning new ways to build plugins as we go. Cruise through the code of your favorite plugins and see how they’re doing things. This will help you translate the core code into plugin code.
  7. Just keep building. The more you try to build, the more you’ll learn how to build, and the better at building them you’ll become. We all start somewhere and we’re all still growing. Build something and share it.
  8. Don’t be afraid to ask. Sometimes it’s intimidating to post a question to something you feel is obvious. Do some searches and if you can’t find the answer, post it. Tell us what you’ve tried and where you’re stuck. We’re all problem-solving together.

That’s what I’ve got. I hope that’s along the lines you were looking for. If not, let me know. I’d love to help others get going with Discourse plugins. There’s a lot of power in being able to customize and tweak your own site via custom code.

29 Likes

Some feedback from a new user:

The lack of documentation in some places has been the most frustrating part of using Discourse so far. If there were a way for the community to contribute to a simple documentation site (like sphinx/readthedocs), I’d help write some of documentation as I figure things out. The documentation could be updated to point to the most relevant and current forum threads here for those tasks.

It would be useful to have one canonical entry point for learning how to build more complex plugins (not just “hello world”). A list of where to start looking for answers to common tasks would be useful. The sidebar for the API docs is a good example. At the moment, information is scattered over many different forum posts, and it’s difficult to find. Asking people who are new to Ruby, Rails, and Ember to “just read the code” creates a significant barrier to entry for many.

Example: I want to override the log out functionality on Discourse (to add a POST request to another URL on-logout) but don’t know where to look. I searched Github for Ruby files that handle log out and only found this, and it isn’t clear how I would override the functionality there. I’m too new to Ruby, Rails, and Ember to understand how it’s all wired together, so something that would only take a few hours with documentation ends up taking up days of time. It’s not just reading the information that takes time – it’s mostly figuring where to even find it among years of scattered forum posts for various different versions and configurations of the software.

10 Likes

Isn’t this already covered by the built in webhooks, in Admin, API, webhooks? We should have an on-user-logout webhook built in if we don’t already cc @tgxworld

4 Likes

Thanks, I didn’t see one for user logout, but that would be useful.

1 Like

Can you make sure this is somewhere on your list @tgxworld?

1 Like

Done in

https://github.com/discourse/discourse/commit/6c4ee9d5b52b55667264e2b39fe77f072306b9d1

4 Likes

Is there any indication of what action is performed? When I try it, it POSTs JSON to a URL. The JSON contains information about the entity, but I don’t see how to determine information like whether the user has logged in or out. Maybe it could be done with an extra key in the JSON?

    {
        "user": { // the type of event
            // the main payload
        },
        "action": "login" // or logout, create, update, delete
    }

(Feel free to move this post if it would fit better somewhere else in the forum.)