Beginner's Guide to Creating Discourse Plugins - Part 1

plugins

(Robin Ward) #1

Building a plugin in Discourse can be really simple, once you learn a couple of quirks. The goal of this post is to create a skeleton plugin and introduce you to the basics.

Your development environment

Make sure you have a development environment of Discourse running on your computer. I recommend you use the appropriate setup guide and come back when you’re done.

plugin.rb

:tada: Update August 2018, see Rails plugin generator to create a complete discourse plugin skeleton in your plugins directory :tada:

When Discourse starts up, it looks in the plugins directory for subdirectories containing a plugin.rb file. The plugin.rb file has two purposes: it is the manifest for your plugin with the required information about your plugin including: its name, contact information and a description. The second purpose is to initialize any ruby code necessary to run your plugin.

In our case, we won’t be adding any ruby code but we still need the plugin.rb. Let’s create the directory basic-plugin with the file plugin.rb inside it, with the following contents:

basic-plugin/plugin.rb

# name: basic-plugin
# about: A super simple plugin to demonstrate how plugins work
# version: 0.0.1
# authors: Awesome Plugin Developer

Once you’ve created this file, you should restart your rails server and the plugin should be loaded.

An important Gotcha!

If you’re used to regular rails development you might notice that plugins aren’t quite as nice when it comes to reloading. In general, when you make changes to your plugin, you should Ctrl+c the server to stop it running, then run it again using bundle exec rails server.

My changes weren’t picked up! :warning:

Sometimes the cache isn’t cleared fully, especially when you create new files or delete old files. To get around this issue, remove your tmp folder and start rails again. On a mac you can do it in one command: rm -rf tmp; bundle exec rails s.

Checking that your plugin was loaded

Once you’ve restarted your rails server, visit the url /admin/plugins (make sure you’re logged in as an admin account first, as only admins can see the plugin registry).

If everything worked, you should see your plugin in the list:

Congratulations, you just created your first plugin!

Let’s add some Javascript

Right now your plugin doesn’t do anything. Let’s add a javascript file that will pop up an alert box when discourse loads. This will be super annoying to any user and is not recommended as an actual plugin, but will show how to insert Javascript into our running application.

Create the following file:

plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js.es6

export default {
  name: 'alert',
  initialize() {
    alert('alert boxes are annoying!');
  }
};

Now if you restart your rails server, you should see “alert boxes are annoying!” appear on the screen. (If you did not, see the “My Changes weren’t picked up” heading above).

Let’s step through how this worked:

  1. Javascript files placed in assets/javascripts/discourse/initializers are executed automatically when the Discourse application loads up.

  2. This particular file exports one object, which has a name and an initialize function.

  3. The name has to be unique, so I just called it alert.

  4. The initialize() function is called when the application loads. In our case, all it does is execute our alert() code.

You’re now an official Discourse plugin developer!


More in the series

Part 1: This topic
Part 2: Plugin Outlets
Part 3: Site Settings
Part 4: git setup
Part 5: Admin interfaces
Part 6: Acceptance tests
Part 7: Publish your plugin


Beginner's Guide to Creating Discourse Plugins Part 2: Plugin Outlets
Beginner's Guide to Creating Discourse Plugins Part 3: Custom Settings
Beginner's Guide to Creating Discourse Plugins Part 4: Git Setup
Beginner's Guide to Creating Discourse Plugins Part 5: Admin Interfaces
Beginner’s Guide to Creating Discourse Plugins Part 6: Acceptance Tests
How to start building stuff for Discourse if you're newbie (like myself)
Manipulating search box
Connecting to database with a plugin
Plugin API documentations?
How to create a new plugins?
Where to see if discourse can do what I want?
Separating View from Data, Plugins, Modularity
Categories Topic Replies
Beginners Guide to Install Discourse on Ubuntu for Development
How to create a plugin, that overrides the landingpage
Create fully custom header
Javascript getElement methods doesn't work
Customization of discourse
Overwriting controllers in plugin
Beginner’s Guide to Creating Discourse Plugins Part 7: Publish your plugin
Minimal Topic List Design with Sidebar for Navigation
How do you learn how to build these plugins
Plugin Tutorial #1 - How to manipulate the text in the composer?
How do you learn how to build these plugins
Best guides for creating Discourse plugins?
Added custom initializer
Allow reply-to individual instead of topic/forum (mailing list feature)
Custom home page to discourse
Push to digital ocean from command line and rebuild
How can I add "dislike" button?
How to convince my university to use/install Discourse?
Send Email to User When Mentioned
Hack to enable invitations for Trust level 1 users
Customization of discourse
Dropcaps in Discourse - cannot override span tag
How to hide a DIV with javascript on Discourse? and then change as users navigate?
Plugin: add a menu icon (next to search)
Error When creating custom plugin
Error When creating custom plugin
Emails only to users with specific group?
Recompile discourse without pulling new version
Rails Girls 2015 SoC Banter
Hide features for non-admin users through plugin
How to properly display jalali dates for Persian language
IOTA as a currency for Discourse
Discourse Development Contribution Guidelines
How would updating effect custom overrides?
Any options for over-riding the username restrictions?
Plugin Documentation Style Guide
Custom Field not working
Modify the topic body of an answer
Reputation and level on member profile
Beginners Guide to Install Discourse on macOS for Development
How can I make my own Discourse plugins?
Specify user by external id
How to correct change the forum?
Customizing handlebars templates
Customizing handlebars templates
/about page add a new link and menu
Adapt github changes to my own site
Bootstrap fails when plugin file specifies gem version range
How to transfer data from plugin to app/views templates?
Few clarifications on Discourse
Help needed in creating plugin to redirects user to pass reCAPTCHA v2
Which files can you override from a plugin?
New columns in directory (/users)
Why do I need a block storage?
Topic Ratings Plugin
Customizing CSS via plugin
LDAP login into Discourse
About the Plugin category
About the Plugin category
Show "topic-excerpt" for all post on Latest Page
Visual diagraming to add visual dimension to Conversations?
Show "topic-excerpt" for all post on Latest Page
Custom Onebox engine
Custom Layouts Plugin
(Mittineague) #2

Robin,
Thanks for this plugin guide.
I appreciate it and hope to see many more soon.
I really do.
In fact, I tried it and it worked great!

So, no offense intended, … … …
but

I would like to suggest one small change for those not masochistically inclined :ambulance:

⋮
//    alert('alert boxes are annoying!');
    console.log('console logging is not annoying!');
⋮

(Robin Ward) #3

I considered console.log but I didn’t want to have to explain “open your dev console” too :smile:


(Ladydanger) #4

Great guide - we tried it today and worked perfectly :smile:


(Matt Jones) #5

Thanks for the guide. I expected it to be complicated, but it looks pretty simple! I’m looking forward to having a play around with plugin development! :smiley:

Is there anything more to the JS integration? Are there any other supported functions other than initialize?

You’ve whet my appetite! I’d love to see something more in depth.


(Michael Kitzman) #6

I followed the instructions to set up my development environment, and I now have my system ready to go.

I just don’t know how to log into this system now…

Any advice on getting set up with my first admin user would be much appreciated.


(Mittineague) #7

Try these


(Michael Kitzman) #8

That was absolutely it! Thank you very much for that!

Running rake admin:create was absolutely what I wanted.


#12

Thanks for the guideline


(Frank Piva) #13

I followed these instructions and was not able to get the alert box to show up on my site.

I can view the plugin from the Admin panel, but after restarting my container there is no alert box that shows up. I have also tried console approach instead of using an alert, but have not had any luck. I have double-checked for typos, but haven’t found any.

Is this tutorial outdated?


(Jeff Atwood) #14

Anything here we need to update @eviltrout?


(Robin Ward) #15

Are you trying to use this guide in production? Because it is meant to be used in a development environment as a way of creating plugins. The reason I ask is you said container which is how we host discourse in production mode.

In production, you have to have a plugin installed using git clone commands.


(Frank Piva) #16

This makes sense then. I am running Discourse in production mode, and have previously installed plugins by adding git clone commands to the .yml file. I’ll try to get a development environment going and see if I have success.


(Frank Piva) #17

Ok, so I FINALLY got a development instance of Discourse running, but I am still unable to see the alert box. Again, I have checked to make sure I didn’t make any typos in the path name or in the code itself. After creating alert.js.es6 I ran ‘bundle exec rails s -b 0.0.0.0’. The site is still accessible through the browser, but no alert box. I can see the plugin in the admin panel, but it is only in black text; unlike the rest of the plugins which are in blue.

I am a Discourse/Rails newbie so I apologize if I am making an obvious mistake.


(Alan Tan) #18

Can you push your code to Github and link it here? Otherwise, it’ll be hard to see what is going wrong :slightly_smiling:


(Robin Ward) #19

Did you try the impotrant gotcha referred to here?


(Frank Piva) #20

I thought I tried clearing out the /tmp directory, but when I tried it a second time it worked. For the record though, bundle exec rails s does not start the server on my instance. I have to run bundle exec rails server -b 0.0.0.0 in order to get the instance to serve pages.


(Tyler Thrailkill) #21

I also cannot get the alerts to load. Here’s a link to the repo with the plugin, nothing else has changed besides the plugins folder. GitHub - snowe2010/discourse_plugins: Writing some plugins


#22

Did you nuke the tmp directory and restart rails?

I got to page 5 before issue popped up.


(Tyler Thrailkill) #23

Yeah I’ve nuked it almost every single time. What do you mean you got to page 5 before the issue popped up?