Feature: Implement macros to be called from HTML / page contents

tammoterhark commented

2018-10-17 12:03:17 +00:00

(Migrated from github.com)

Use case: in De Stadsbron we now can not easily distinguish between public/non public and published/not published pages This may lead to pages that stay unpublished.

Possible direction:
[list] : shows all pages that are available for the current user (= equal to current index)
[list content-type=article published=no author=current-user] shows all my non-published articles
[list published=no] shows all unpublished pages, not regarding content type.

By placing these codes on a page, the list may be shown, like in Wordpress.

To be discussed & expanded.

Use case: in De Stadsbron we now can not easily distinguish between public/non public and published/not published pages This may lead to pages that stay unpublished. Possible direction: `[list]` : shows all pages that are available for the current user (= equal to current index) `[list content-type=article published=no author=current-user]` shows all my non-published articles `[list published=no]` shows all unpublished pages, not regarding content type. By placing these codes on a page, the list may be shown, like in Wordpress. To be discussed & expanded.

tammoterhark commented

2018-10-17 12:06:40 +00:00

(Migrated from github.com)

[listusers]
[listusers admin=yes]
[listusers active=no]

etc.

``` [listusers] [listusers admin=yes] [listusers active=no] ``` etc.

tammoterhark commented

2018-10-18 07:34:07 +00:00

(Migrated from github.com)

[list content-type=article tag="westtangent"]

`[list content-type=article tag="westtangent"]`

tammoterhark commented

2018-10-18 07:59:24 +00:00

(Migrated from github.com)

Other idea after brainstorm: make index more versatile

use columns and classes and filters. All addressable through URL.

Need mockup.

Other idea after brainstorm: make index more versatile use columns and classes and filters. All addressable through URL. Need mockup.

tammoterhark commented

2018-11-26 10:45:47 +00:00

(Migrated from github.com)

[list content-type= article after-date="2018-10-01" before-date=today]
[list content-type=article date="2018-10"] for articles in october

`[list content-type= article after-date="2018-10-01" before-date=today]` `[list content-type=article date="2018-10"]` for articles in october

tammoterhark commented

2018-11-26 10:50:00 +00:00

(Migrated from github.com)

[list show-filter=content-type include=[article, page]]
For an index with a filter that visitors can use for filtering per content-type, showing pages and articles.

`[list show-filter=content-type include=[article, page]]` For an index with a filter that visitors can use for filtering per content-type, showing pages and articles.

tammoterhark commented

2019-02-16 12:20:26 +00:00

(Migrated from github.com)

From the Wordpress universe:
https://wordpress.org/plugins/display-posts-shortcode/

From the Wordpress universe: https://wordpress.org/plugins/display-posts-shortcode/

matthijskooijman commented

2020-05-06 14:06:41 +00:00

(Migrated from github.com)

This seems like a good way to implement the ideas we had in #298. A "dossier" page can then be a normal text page where the "header" and "footer" would just be plain HTML and the main page list could be generated using such an escape tag. Similarly, the homepage could be a plain text page, with some of these tags that indicate "insert most recent three videos here", or "insert 10 most recent articles here", or maybe even "insert these pages here" (where pages would be identified by id or url maybe?). The latter might need a UI to easily select pages, so that might be more complex again...

The page selection for such a list would be more complex than the currently implemented tag index (which only shows pages with a single tags), since it could filter on datatype, tag, maybe date and have configurable sorting and pagination.

As for implementing this, I originally had the idea of making these lists a proper datatype that could be used by themselves as well, but with an "embeddable" view. Then, you could include these embeddable views in other pages by just referring to that defined page. This could happen either server-side, but maybe also client-side (by just matching special tags and replacing their contents with an AJAX-request).

Creating separate pages for these has the advantage of allowing a proper UI for selecting them (rather than just typing text or raw HTML directly), though I guess a wymeditor module for editing these special lines could also be added maybe. The downside of creating separate pages is that you get a bunch of extra pages, which makes things more heavy-handed.

An upside of interpreting these tags client-side could be that it is easier to preview the result of these tags while editing (probably not inside the wymeditor, but wymeditor does have a preview button as well I believe). The downside is more requests, latency and server load, probably.

So, I tend to make these not separate pages (just put the proper tags in a text page to generate a list) and then interpret them server-side.

As for interpreting these tags, this could be done when rendering a wymeditor-editable field specifically, but maybe it could also be done as a global post-processing hook over the generated DOM. This would allow these special tags to occur anywhere, including in the hypha.html, which might also be valuable. It does mean these tags are rendered with fewer context (e.g. they won't necessarily have access to the page they were rendered in, for example).

As for how these tags would look, there's a few thoughts:

Writing these as HTML/XML tags might be the most flexible in the backend, since all escaping etc. is handled automatically, you can search for and access data using DomDocument/XPath, etc. For users, this more tricky, since it requires going through the HTML source editor to change these (but maybe that is acceptable, since this is rather an advanced feature). E.g. something like:
```
 <hypha:page-list content-type="article" tag="westtangent">
```
Using XML also makes more complex, nested structures easier (on the backend, at least):
```
 <hypha:page-list content-type="article">
   <filter>
     <or>
       <tag label="westtangent">
       <tag label="video">
     </or>
   </filter>
 </hypha:page-list>
```
Writing these tags as text inside the normal editor could be an alternative. This makes it easier to edit these, but maybe also more fragile (easier to make a typo in the syntax). Depending on how unique the syntax is, it might be easier to accidentally trigger it as well, maybe even by unauthenticated visitors in comments.
e.g.:
```
!!!page-list content-type="article" tag="westtangent"!!!
```
Implementing something like this in text might require some good thought about the syntax and a proper, generic parser (to allow arbitrary attributes, maybe attributes with list values as well, etc.). One advantage of using HTML is that this part is builtin. An alternative could be to use some other existing syntax (e.g. JSON) that PHP can already parse.
e.g.:
```
!!!{"type": "page-list", "content-type": "article", "tag": "westtangent"}!!!
```
Or more complex:
```
!!!{"type": "page-list", "content-type": "article", "filter": {
     {"combine": or, elements=[
         {"tag": "westtangent"},
         {"tag": "video"},
     ]}
   }!!!
```

This seems like a good way to implement the ideas we had in #298. A "dossier" page can then be a normal text page where the "header" and "footer" would just be plain HTML and the main page list could be generated using such an escape tag. Similarly, the homepage could be a plain text page, with some of these tags that indicate "insert most recent three videos here", or "insert 10 most recent articles here", or maybe even "insert these pages here" (where pages would be identified by id or url maybe?). The latter might need a UI to easily select pages, so that might be more complex again... The page selection for such a list would be more complex than the currently implemented tag index (which only shows pages with a single tags), since it could filter on datatype, tag, maybe date and have configurable sorting and pagination. As for implementing this, I originally had the idea of making these lists a proper datatype that could be used by themselves as well, but with an "embeddable" view. Then, you could include these embeddable views in other pages by just referring to that defined page. This could happen either server-side, but maybe also client-side (by just matching special tags and replacing their contents with an AJAX-request). Creating separate pages for these has the advantage of allowing a proper UI for selecting them (rather than just typing text or raw HTML directly), though I guess a wymeditor module for editing these special lines could also be added maybe. The downside of creating separate pages is that you get a bunch of extra pages, which makes things more heavy-handed. An upside of interpreting these tags client-side *could* be that it is easier to preview the result of these tags while editing (probably not *inside* the wymeditor, but wymeditor does have a preview button as well I believe). The downside is more requests, latency and server load, probably. So, I tend to make these *not* separate pages (just put the proper tags in a text page to generate a list) and then interpret them server-side. As for interpreting these tags, this could be done when rendering a wymeditor-editable field specifically, but maybe it could also be done as a global post-processing hook over the generated DOM. This would allow these special tags to occur *anywhere*, including in the `hypha.html`, which might also be valuable. It does mean these tags are rendered with fewer context (e.g. they won't necessarily have access to the page they were rendered in, for example). As for how these tags would look, there's a few thoughts: - Writing these as HTML/XML tags might be the most flexible in the backend, since all escaping etc. is handled automatically, you can search for and access data using DomDocument/XPath, etc. For users, this more tricky, since it requires going through the HTML source editor to change these (but maybe that is acceptable, since this is rather an advanced feature). E.g. something like: ``` <hypha:page-list content-type="article" tag="westtangent"> ``` Using XML also makes more complex, nested structures easier (on the backend, at least): ``` <hypha:page-list content-type="article"> <filter> <or> <tag label="westtangent"> <tag label="video"> </or> </filter> </hypha:page-list> ``` - Writing these tags as text inside the normal editor could be an alternative. This makes it easier to edit these, but maybe also more fragile (easier to make a typo in the syntax). Depending on how unique the syntax is, it might be easier to accidentally trigger it as well, maybe even by unauthenticated visitors in comments. e.g.: ```` !!!page-list content-type="article" tag="westtangent"!!! - Implementing something like this in text might require some good thought about the syntax and a proper, generic parser (to allow arbitrary attributes, maybe attributes with list values as well, etc.). One advantage of using HTML is that this part is builtin. An alternative could be to use some other existing syntax (e.g. JSON) that PHP can already parse. e.g.: ``` !!!{"type": "page-list", "content-type": "article", "tag": "westtangent"}!!! ``` Or more complex: ``` !!!{"type": "page-list", "content-type": "article", "filter": { {"combine": or, elements=[ {"tag": "westtangent"}, {"tag": "video"}, ]} }!!! ```

matthijskooijman commented

2020-05-13 14:00:58 +00:00

(Migrated from github.com)

Today we discussed this a bit further.

For naming these "things that you can include on a page", we suggested: content generators, shortcodes (like Wordpress), element, block, section, macro, lookup, placeholder, blob. For now, we'll work with the term "Macro".

Some ideas on additional usecases for this

Showing a list of users
Showing or hiding content based on external data (logged in user, a cookie, current url, etc.)
Showing an agenda of items (e.g. after #131)
Embedding registration for a newsletter into another page
Donations
Showing article comments (e.g. most recent comments on the entire site)
Allowing comments in other places too (e.g. on a textpage)
Inserting a chatbox (might already be possible with some javascript now, though)
Inserting a poll
Inserting external content (e.g. Meetjestad sensor data)
Viewing site statistics
Showing related articles

Note that something like "Showing related articles" is not really a macro at first glance, since you wouldl likely want to put that on every article, not only the ones where you manually include this macro code. However, that suggests another use for macros: Maybe you could globally config something like "On all pages with type=peer_reviewed_article, append the related_articles macro to the #pagefooter element". This would certainly be a later addition, though.

Some additional thoughts:

These macros could live in separate PHP files and be included only when required (e.g. get the macro name, append .php and include that file), which increases performance when macros are not required. Alternatively, they could all be included and they could register themselves as available macros, or the macro name could refer to a class name (checking that they extend from some new HyphaMacro class for safety).
For now, we'll go for the first option shown above, where macros are invoked using a bit of special HTML with parameters in attributes.
I'll have a look at koppelbot to see if some inspiration or code could be taken from there.
On the longer term, it would be interesting if macros could describe themselves and their parameters, to facilitatie some GUI-assistance in invoking these macros. This might also be useful on a shorter term to maybe generate documentation about available macros and their available parameters, to be shown to users.

Today we discussed this a bit further. For naming these "things that you can include on a page", we suggested: content generators, shortcodes (like Wordpress), element, block, section, macro, lookup, placeholder, blob. For now, we'll work with the term "Macro". Some ideas on additional usecases for this - Showing a list of users - Showing or hiding content based on external data (logged in user, a cookie, current url, etc.) - Showing an agenda of items (e.g. after #131) - Embedding registration for a newsletter into another page - Donations - Showing article comments (e.g. most recent comments on the entire site) - Allowing comments in other places too (e.g. on a textpage) - Inserting a chatbox (might already be possible with some javascript now, though) - Inserting a poll - Inserting external content (e.g. Meetjestad sensor data) - Viewing site statistics - Showing related articles Note that something like "Showing related articles" is not really a macro at first glance, since you wouldl likely want to put that on *every* article, not only the ones where you manually include this macro code. However, that suggests another use for macros: Maybe you could globally config something like "On all pages with type=peer_reviewed_article, append the related_articles macro to the #pagefooter element". This would certainly be a later addition, though. Some additional thoughts: - These macros could live in separate PHP files and be included only when required (e.g. get the macro name, append `.php` and include that file), which increases performance when macros are not required. Alternatively, they could all be included and they could register themselves as available macros, or the macro name could refer to a class name (checking that they extend from some new `HyphaMacro` class for safety). - For now, we'll go for the first option shown above, where macros are invoked using a bit of special HTML with parameters in attributes. - I'll have a look at koppelbot to see if some inspiration or code could be taken from there. - On the longer term, it would be interesting if macros could describe themselves and their parameters, to facilitatie some GUI-assistance in invoking these macros. This might also be useful on a shorter term to maybe generate documentation about available macros and their available parameters, to be shown to users.

matthijskooijman commented

2020-12-24 14:25:01 +00:00

(Migrated from github.com)

The basic version of this is implemented in #329 which I just merged, so I'm closing this. I moved the remaining improvements discussed here to #367.

Rows
Columns

Feature: Implement macros to be called from HTML / page contents #87