"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur"

Red Adair

Obix GitHub System Plugin

This system plugin allow the inclusion of GitHub asset contents, or download links to some of them, in webpages.

Raison d'être

Recently I decided to publish some of my extensions, initially were created for my own use, on my Obix website website. It seemed a waste of time having to maintain README and releases in two places, so I created this plugin.

Minimal requirements

  • Joomla! 4.0
  • PHP 8.0

BEWARE: Installing this plugin on a server runnning a PHP version that does not match the required minimum, will result in a fatal error and render the site unusable!

Installation

The installation package contains a plugin and a library:

  • System - Obix GitHub Plugin
  • Obix Library

Installation of the package is the same as for any other Joomla! extension. If it is installed for the first time, as opposed to upgraded, the plugin should be activated automatically. Doesn't do any harm to check though :)

Description

The plugin is of the System type. This means it is applicable in any context where Joomla! system plugins are supported. Technically this is achieved by responding to the onAfterRender plugin event. Before the rendered page is sent to the requesting browser, the body of the page is examined for any plugin tags. If it finds any, they are replaced with the intended GitHub asset content or applicable download link.

In practice this means the plugin can be used virtually anywhere in category descriptions, article texts, modules of type Custom etc. but also in article, category, module and menu item titles and the like.

Configuration

The plugin has several configuration settings that affect its behaviour:

GitHub user name
The user name used to access the GitHub repository with.
GitHub personal access token
The personal access token used to access the GitHub repository with. You can read here how to create such a token.
Error display
Allows setting how error messages should be handled:
  • Display regular Joomla! message (default)
  • Display message in content
  • Silently ignore
Message class
CSS class to be used when displaying message in content.

Usage

Syntax

After the plugin is installed and properly configured, one or more {github ...} tags can be included in any content for which Joomla! system plugins are supported. The general syntax of the plugin comes in two flavors, self closing and a non self closing version:

Self closing

The self closing version consists of an opening curly brace followed by the tag name, a whitespace separated list of parameters and a closing curly brace preceded with a slash.

`{github repo="..." content-type="..." [...="..."]/}`

Non self closing

The non self closing version actually consist of three parts:

  • The first part consists of an opening curly brace followed by the tag name, a whitespace separated list of parameters and a closing curly brace (no preceding slash here).

  • The second part depends on the intended purpose of the tag. Currently, it is only used to provide the text for download links.

  • The third part consists of an opening curly brace followed by a slash, the tag name and a closing curly brace.

    {github repo="..." content-type="..." [...="..."]}...{/github}

General information

  • In case of slashes preceding or following curly braces, there may not be any whitespace between them.
  • Parameters are specified as one or more name="value" constructs, separated by white space:
    • The name follows the general PHP variable naming conventions, except that they don't start with a dollar sign ($).
    • The value must be enclosed in double quotes.
  • The tag parsing logic does not take HTML into account. Any (unintended) HTML tags between opening and closing curly braces, results in the tag not being recognized.
  • If a tag is not recognised as such, it will be rendered in the content literally.

Parameters

repo
Required! The name of the GitHub repository.
content-type
Required! The kind of GitHub content to be included. It can be any of: readme, file, gist or release (see below).
path
The path of the folder where the requested GitHub asset resides, relative to the repository root (no leading slash).
id
Required for content type gist! The id of the GitHub asset to include.
ref
An identifier for the specific commit, branch or tag to retrieve the GitHub asset from.
output
The format in which the requested GitHub asset should be rendered and included in the page (see below).

Additional information

content-type

This parameter indicates the kind of GitHub asset for which the tag is intended:

readme
Renders a readme file, assumed to be in Markdown format (README.md), by converting it into HTML. If no path is specified, the default README will be rendered, i.e. the one in the root folder of the given repository.
file
Includes the content of the GitHub asset, based on the output setting (see below).
gist
Renders a Gist with the given id. The content of a gist is rendered in the same manner as a file (see above).
release-info
Renders the tag name of the latest release.
release
Unlike other applications of the tag, this type does not render the content of the associated GitHub asset, but a link that allows the asset to be downloaded. Unless an explicit tagname is provided, the latest release in the given repository is offered for download by default.
tag
To be used in combination with release to offer download of a specific release. If absent, the latest release is presented for download.

output

This parameter is used to explicitly specify how the contents of the GitHub asset should be rendered:

raw
Includes the content of the GitHub asset in the webpage unmodified.
default
Renders the content of the GitHub asset, based on its file extension.
md
Assumes the asset contains Markdown formatted text and converts it into HTML.
php
Assumes the asset iss PHP source code and converts it into highlighted HTML (see highlight_string).
default
Includes the content of the GitHub asset in the webpage unmodified.

Examples

Default README

{github repo="my_repo" content-type="readme"/}

Retrieves README.md from the root of the repository and converts its content from Markdown to HTML.

README in a specific folder

{github repo="my_repo" content-type="readme" path="foos/bar/baz"/}

Retrieves README.md from folder foo/bar/baz of the repository and converts its content from Markdown to HTML.

PHP file (in branch)

{github repo="my_repo" content-type="file" path="foo/bar/baz/foobar.php" ref="dev"/}

Retrieves foobar.php in branch dev from folder foo/bar/baz of the repository and converts its content from regular PHP code into highlighted HTML.

Gist

{github repo="my_repo" content-type="gist" id="8a5c7d0fd5527d72a607626a7ec683cd"/}

Retrieves the gist with the given id and renders it depending on its output (see above).

Download latest release

{github repo="my_repo" content-type="release"}Download latest release{/github}

Renders a link, with which a release can be downloaded.

Download specific release

{github repo="my_repo" content-type="release" tag="v1.2.3"}Download release v1.2.3{/github}

Renders a link, with which a release can be downloaded.

Raw content

{github repo="my_repo" content-type="file" path="foo/bar/baz/foobar.txt" output="raw" ref="dev"/}

Retrieves foobar.txt in branch dev from folder foo/bar/baz of the repository and outputs its content unmodified.

Joomla! Extensies