<include> and <snippets> vs. <embed>

At first glance, <include> and <snippets> provides functionality rather similar to embedding: It allows to reuse some portions of code across plugins. So what is the difference between these approaches, and when should you use which?

The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete GUI, code to generate R code from this, and a help page. In contrast, include and insert allow much more fine grained control, but at the price of less modularity.

That is, a plugin embedding another plugin will typically not need to know much about the internal details of the embedded plugin. A prime example is the plot_options plugin. Plugins wishing to embed this do not necessarily need to know about all the options provided, or how they are provided. This is a good thing, as otherwise a change in the plot_options plugin might make it necessary to adjust all plugins embedding this (a lot). In contrast, include and insert really exposes all the internal details, and plugins using this will -- for example -- need to know the exact ids and perhaps even the type of the elements used.

Hence the rule of thumb is this: include and insert are great if the relevant options are only needed for a clearly limited group of plugins. Embedded plugins are better, if the group of plugins it may be useful to is not clearly defined, and if the functionality can easily be modularized. Another rule of thumb: If you can put the common portions into a single “chunk”, then do so, and use embedding. If you need lots of small snippets to define the common portions -- well, use <snippets>. A final way to look at it: If all plugins provide highly similar functionality, includes and inserts are probably a good idea. If they merely share one or two common “modules”, embedding is likely better.