Updating Old School Plugins

Updating old-school Sal Plugins

Things change... It's not you, it's me.

Plugins have evolved, and you may need to update your plugin code. No doubt, the log file is barking at you constantly about plugins in-need of updating? Familiarize yourself with the new-school plugin documentation and then follow the steps below to update old plugins.

When in doubt, consult the builtin plugins' source, which have all been updated.

1. import sal.plugin
2. (Do not from sal.plugin import <anything>, as this will cause yapsy to have issues.
3. Replace plugin's base class from IPlugin to sal.plugin.Widget, sal.plugin.DetailPlugin, or sal.plugin.ReportPlugin.
4. Remove the yapsy import as well as any other imports that aren't actually being used.
5. The new plugin class will automatically use <pluginname>/templates/<pluginname>.html for its template. Unless there's no way to use a single template, you can remove the template selection and loading stanzas from the existing widget_content method. All builtin plugins now use a single template, so you probably can too.
6. widget_width and description are now class attributes. You should remove these methods unless you need to do some dynamic sizing or description configuration.
7. Set the plugin classes' description = 'whatever'
8. Regular and machine detail plugins have a default width of 4; reports are 12. There's no need to specify widget_width unless you want to change this.
9. Remove the plugin_type method. It's no longer used (the plugin's class can tell Sal this information).
10. Rename the widget_content method to get_context, and change the parameters. The signature should now look like this: def get_context(self, queryset, **kwargs):
11. Rename all uses of the previous parameter machines to queryset in the (now) get_context method.
12. Start a context dictionary by calling context = self.super_get_context(queryset, **kwargs). This puts the plugin, group_type, and group_id key/value pairs into the context for you.
13. Make get_context return the context dictionary, not a rendered template.
14. In a lot of existing plugin code, this means making sure you don't overwrite the context you started in the previous step; insure you're adding values to it, not recreating it.
15. Django no longer expects a Context object be passed to templates, so you can remove that invocation as well as the import of Context and loader, if present.
16. The machine queryset passed into get_context has already been filtered for Business Unit, Machine Group, or "All", so you can remove any code that does that.
17. Likewise, you cam remove any access handling code, as user permissions have already been checked before your plugin code executes.
18. DetailPlugin receives a single machine rather than a queryset. Keep that in mind when looking over code.
19. In most cases, the main body of the (now) get_context method does not have to be changed.
20. The filter_machines method should be renamed to just filter.
21. Check your templates and update the following
22. You no longer need to pass a title into the template via context; Use {{ plugin.title }} instead.
23. Likewise, plugins have a repr method now; so you can use {{ plugin }} instead of passing a plugin name. The repr method returns the name of the plugin class; for example MunkiInstalls. This is the name used in plugin loading / URL construction...
24. Update all URL constructions.
    1. Most reversed URLs are to list machines. The machine_list_id and machine_list_front names are deprecated; please update to simply machine_list. 2. The page parameter should be replaced with group_type (which is already in your context). 3. The theid parameter should be replaced with group_id (also in the context). 4. If your {% url %} calls use a passed plugin name, just use the plugin object itself. 5. Example
    2. Old: {% url 'machine_list_id' 'MunkiVersion' 'abc123' page theid %}".replace(/abc123/, row['label'].toString());
    3. New: {% url 'machine_list' plugin 'abc123' group_type group_id %}".replace(/abc123/, row['label'].toString());
25. If you were using different templates for "front" and "id" views, you can use a single template. Observe the auto-template naming rules from earlier, and you can probably use a very lightly modified version of your previous "id" template.