Question: Vision and future

[FMCorz]

Hi,

While developing the "Stash" block, @abgreeve and I introduced a new filter "Stash" which introduces some shortcodes. It seemed to me that such shortcodes should ideally be part of a broader plugin rather than being implemented by each plugin individually.

Your plugin seems to be headed in that direction. So I've got a few questions:

• Why choosing the curly brackets over the more common square brackets à la Wordpress?
• Any plans on supporting arguments for the codes?
• If you do support arguments, any plans on supporting backups?
• Would you be open to opening the API for other plugins to build upon yours?

Fred

PS: Role IDs should not be hardcoded in constants.

[michael-milette]

Hi @FMCorz ,

Thank you very much for your feedback Fred. I always love hearing from people in the Moodle community, especially other plugin developers.

Why { } braces?

As you mentioned, [ ] are used consistently for most WordPress Shortcodes, the { } braces were chosen for this Moodle project in order to be consistent with other Moodle filters which use the same delimiters. For example:

• https://moodle.org/plugins/filter_multilang2
• https://moodle.org/plugins/filter_multilangsecond
• https://moodle.org/plugins/filter_generico
• https://moodle.org/plugins/filter_tabs
• https://moodle.org/plugins/filter_collapsible

Not only does the use of { } in this plugin further promote consistency and intuitiveness for content contributors who type these variables, is also far less likely to occur in day to day text than [ ] making it what I believe to be a better choice (less chance of conflict) for filters.

As I said, in the world of WordPress, [Shortcode] square brackets are the norm. Moodle's problem when it comes to filters is that it lacks a standard for filter variable delimiters. It would also be nice if there was an API so that plugins like yours could create filter codes that are limited to the scope of the plugin. Yet another option might be to have private plugin filter code delimiters be different than global filter code delimiters. Regardless, this is probably a discussion for a different thread.

Plans for supporting arguments

Absolutely. In fact, the {lang xx} tag enables you to specify the 2-letter language code.

Plans to support backups

Not sure what you mean here. Could you elaborate?

Opening the API

I am always open to new ideas and suggestions. However I am not sure what you mean here. Moodle already has a filter API which is used by FilterCodes. You can create new filters by simply creating a new filter plugin. In the case of Stash, since the plugin is only applicable to the Stash block, it doesn't make sense to create a filter that will affect all content throughout Moodle. My recommendation would be to integrate your code into the plugin and, in fact, have your plugin process its own tags before calling the format_text() and/or format_string() functions in order to avoid conflicts with other Moodle filters.

With that said, if you have any suggestions for new general interest filter tags, maybe with a code snippet, that you would like to see included in FilterCodes, I would be happy to consider integrating it into a future release of Filter Codes.

Role IDs should not be hard coded in constants

You are correct of course. That did occur to me during development. If you have a way to work around this, please feel free to share. I am and shall always will be open to learning. :-)

Hope I addressed all of your questions. Let me know if I missed anything. Thanks again for taking the time to write. Looking forward to hearing from you.

Best regards,

Michael

[FMCorz]

Hi Michael,

Thank you very much for this very detailed answer! Some additional information from my side here follow.

Supporting backups

In the case of Stash, we have two arguments in the shortcode, the item ID, and the item hash. The item hash is a way for us to prevent students from using the shortcode, it is tied to the item and never changes. The item ID however, is the database ID for that item. It will change after a backup & restore, causing the shortcode to be invalid upon restore as it points to the initial item ID, not the restored one.

In Stash, we found a workaround for supporting this, and it works. Though, we were caught off guard by a limitation which forced us to use 32 characters shortcodes else the backup would ignore them.

Now, there isn't any reason for you to be supporting backups if you do not open your API. Which leads me to...

Open API

In the case of Stash, since the plugin is only applicable to the Stash block, it doesn't make sense to create a filter that will affect all content throughout Moodle

That is not how it works. The Stash filter allows someone to convert a shortcode placed anywhere on the Moodle site, to be converted to an item to be picked up. It is not limited to the scope of the block, however it is tied to the block's API.

I know there already is a filter API, and I'm not suggesting that we try to outsmart it. However, Moodle does not have a shortcode API like you do, and that's what I'm suggesting to open. See, it's much more user friendly if your plugin is the only dependency needed for any plugin to have shortcodes. See, if instead of requiring my users to install filter_stash, I could require them to install your plugin. In turn, if other plugins are requiring yours there is a greater chance that the dependencies are already met.

I have had many people telling me that they could not install the plugins they wanted in their administrations. Some administrators are reluctant for adding any additional plugins. Partners also generally charge high fees for any additional plugin. My suggestion here is an attempt to reduce the number of plugins to be installed while increasing the features for a user.

Let me use another example. Some users of block_xp have reported to me that they would like to be able to inject the user's level, or badge, or progress bar, or perhaps even the ladder, anywhere in their content. It makes sense as they may want to organise the content the way that works best for them. Without your plugin being open I effectively have to create another plugin, which would parse for block_xp's shortcodes. It's more burden on me, more burden on the user, and more burden on the server as more filters need to be running.

So in short, what I would like to be possible is for another plugin to define their own shortcodes, and your plugin to defer the logic to them when they are found.

Role IDs should not be hard coded in constants

I suggest that you get the roles out the database based on their archetype. You may find more than one role with the archetype student, or editingteacher. If not, you could simply search them based on their shortnames: student, editingteacher, rather than their supposed IDs. The IDs will generally be the ones you have set, the same way the admin user ID is usually 2, and guest 1, but that's an assumption that should not be made.

Thanks again for your detailed answer.

Fred

[michael-milette]

Hi @FMCorz ,

I implemented your suggestion that Role IDs not be hard coded. The limitation is that the shortnames of the default Moodle roles including 'manager', 'coursecreator', 'editingteacher', 'teacher' and 'student' must exist. Thank you for your suggestion.

I think creating an Open API for a Moodle implementation similar to shortcodes that found in WordPress is a great idea. It would be nice to standardize how developers can create and make use of filter tags. There are several big advantage that I can think of off the top of my head including:

• Be able to create a generic Atto editor plugin could make it easy for people to insert these filter tags without having to memorize or print a list of them.
• Officially standardize the tag delimiters for public filter tags. No more debate as to whether they should be [ ] or [[ ]] or { } or {{ }} or ( ) or / / or \ \ or | |, etc. (you get the idea) - although I still think { } is a better choice than [ ]. :-)
• If integrated with Moodle core, an API would make it easier to implement context awareness so that these tags would be processed in some places and not others.
• Plugins and themes could ship with their own set of filter tags to enhance their functionality instead of having to publish a separate filter plugin.

On a side note, I have been avoiding using the term "shortcode" because I am not sure if the term is generic or specific to WordPress - which might have some copyright or trademark implications. After some initial searches in Google, I have yet to find very much on this. The most relevant information found to date includes:

• https://en.wikipedia.org/wiki/Short_Code_(computer_language)
• https://en.support.wordpress.com/shortcodes/

If it is generic or at least available, I think it would be good to use this term as it is a concept with which many people are already familiar making easier to understand. In that case, the plugin should also be called Shortcode for consistency with its purpose.

Michael

[FMCorz]

Hi Michael,

Yes, those are exactly the benefits I'm seeing in a more generic solution. I am not sure whether this should make it to core, but if it does it would probably be in the form a filter plugin anyway.

I probably used the term shortcode because of WP's influence. I remember the days of BBCode. To me what is important is that the plugin is discoverable. If the name/concept is too cryptic, it won't easily make its way to the users, and developers.

Regarding the format used, I don't think there is a need to change what you've started with, unless it badly conflicts with other formats out there. For example, I know that Mathjax works with several delimiters, but I don't know which one is the default. That being said, I think it's important that the delimiters are not customisable, too many options are rarely a good thing, they make documentation harder and do not always achieve the desired goals.

[michael-milette]

Sounds good to me. Since this is your idea, would you like to initiate the feature idea on moodle.org? There is little point in developing an API if there is no interest by the community.

Next step: https://docs.moodle.org/dev/New_feature_ideas

Thank you for sharing your thoughts @FMCorz . Our conversation helps me be a better developer. :-)

Michael

[abgreeve]

Sorry to interject into your conversation, but I think the idea of a generic filter system is an excellent idea and should definitely be included in core. Perhaps I could have a word with people around HQ to immediately gauge if this could be included into core.

[FMCorz]

Thanks Adrian. Let us know how it goes.