Ability to embed HTML / data using a shortcode

[thestepafter]

Describe the feature you'd like

Hello everyone!

I'm currently evaluating wiki's for the ability to add a "shortcode" (e.g., [embed src="$apiEndpoint" fields="productName, productPrice"] similar to WordPress.

Adding this shortcode would make a call to the API endpoint and display the response (raw text or HTML) in the BookStack document when it is viewed. It would be great if this could be done as a custom button in the WYSIWYG editor or by adding the shortcode when editing the document in text only mode.

I assume this would require writing the functionality for the API call and parsing the shortcode in Laravel, I'm just curious if it's already been attempted or how difficult it would be. You would have to hook into the rendering of the document and parse the shortcode accordingly.

Describe the benefits this would bring to existing BookStack users

This would allow BookStack users to embed data from databases, APIs, and other systems.

Can the goal of this request already be achieved via other means?

I'm not sure.

Have you searched for an existing open/closed issue?

• I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

Over 5 years

Additional context

No response

[ssddanbrown]

Hi @thestepafter,
Thanks for the request.

This generally wouldn't be the kind of thing Id' look to add specific support for, especially as the scope is fairly wide and there's little desire for it, but I can think of a couple of methods for this kind of thing using existing options in current versions of BookStack:

Page includes with the logical theme system

BookStack supports specific include tags to fetch in content from other pages:
https://www.bookstackapp.com/docs/user/reusing-page-content/#include-tags

We also have the logical theme system to run custom PHP code on certain events:
https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md

One of the events you can listen to is page include tag parsing/rendering:

BookStack/app/Theming/ThemeEvents.php

Lines 103 to 116 in 0838d5e

	/**
	* Page include parse event.
	* Runs when a page include tag is being parsed, typically when page content is being processed for viewing.
	* Provides the "include tag" reference string, the default BookStack replacement content for the tag,
	* the current page being processed, and the page that's being referenced by the include tag.
	* The referenced page may be null where the page does not exist or where permissions prevent visibility.
	* If the listener returns a non-null value, that will be used as the replacement HTML content instead.
	*
	* @param string $tagReference
	* @param string $replacementHTML
	* @param \BookStack\Entities\Models\Page $currentPage
	* @param ?\BookStack\Entities\Models\Page $referencedPage
	*/
	const PAGE_INCLUDE_PARSE = 'page_include_parse';

You could make use of this to listen to page includes with a certain syntax/code, then run your desired logic to run any custom action/code you want, and return whatever HTML you want to include.
You could even call external systems via PHP with this, although I'd advise at having some kind of caching logic to prevent each page load causing external requests and delays.

As an example, the following hack uses some of the above mentioned systems/events:
https://www.bookstackapp.com/hacks/page-include-tag-value/

REST API

You could update pages as required via scripts, potentially automated, using the BookStack REST API. You could look for certain syntax and then update stored pages with the content you which to include.
This may take a little more extra external parsing, and requires thought in how content is tracked/marked to the "tags"/configuration for future updates.