blog@clarkwinkelmann

A look behind my FLL scoreboard

Wed, 30 Aug 2017 23:00:00 +0000

It’s the fourth year in a row that I develop a web scoreboard for the FLL RobotGame competition.

It’s starting to get routine, but each year has hat its lot of changes. I could have taken the same code base each year and simply update some variable, tweak logos and fix the calculation, but it evolved a bit more than that.

First, what is it ? The Robot Game is one of four challenges of FIRST LEGO League competition. Two teams compete on a mat with LEGO robots. Robots have 2min30 to score a maximum of points in different missions on the mat, in complete autonomy. Each year a new mat is released with missions around the season theme.

These missions are described in the challenge rules, and calculating your total of points is sometimes complicated, and often a bit ambiguous.

It’s never been clear to me if there is or isn’t an official scoreboard. The FLL has a platform to manage the competition that seems to handle score calculation, but it’s not publicly accessible. They also release the paper forms used by judges during the tournaments, but you have to calculate scores by hand !

That’s why in 2014 I created my first FLL scoreboard, and did so the following years as well.

Oh, and I should mention I’m a coach and “IT guy” in the Robots-JU robotics association, which is why I’m dealing with this competition. We also organized our own competition, as you will see below and probably read in future posts as well.

Let’s go back in history and explore the different iterations of my scoreboard.

2014

If I remember correctly it’s the first year I joined as a coach, and also the time where we officially founded the association. I participated in the FLL the previous two years as a member, but I was now too old to take part. So I joined as a coach and took care to setup our website and such.

I also decided to create a scoreboard. I knew from experience it would be really useful during the training, even if it was far from perfect. 2014 had a some very complicated rules where you had to calculate fractions of points for some missions to get the final result, making it very hard to do by hand.

The 2014 scoreboard was a simple vanilla javascript application, with most of the calculation and texts hard-coded in the page. The page also featured a print stylesheet, which was never really used, and a sharable url, which also wasn’t particularly useful to my knowledge, given it was mostly used internally.

Right from the start I decided to publish the scoreboards on our website for everyone to use, and also published the source code under the MIT license on GitHub

2015

The 2015 scoreboard re-used the 2014 style, but everything else was rewritten.

I dropped the print stylesheet and also removed the shareable url feature.

Since 2014 I started using React and thought it was a perfect fit for the job, with plenty of inputs to sync and a single state management logic.

A regular complaint about the previous scoreboard was that it only contained English mission descriptions (We’re in the French part of Switzerland). So this year I added both French and English variations.

A big issue with the 2014 scoreboard was its fixed width. It was highly impractical on mobile devices. The 2015 version partly fixes it by aligning missions more regularly on the screen and allowing them to resize as the screen gets smaller.

Another big issue with the 2014 scoreboard was its unreliability. It contained no unit tests, and each fix was threatening the whole calculator.

To solve this, I extracted the calculator part of the scoreboard into a separate package, which would include a complete test suite checking every single mission based on the official rules.

At the start of 2016 we organized our first robotics competition, the Coupe Robots-JU. The competition re-use the Robot Game mat and rules of the FLL so teams who prepared for the FLL can easily take part in our competition as well.

During a typical FLL tournament, the Robot Game is divided into 3 rounds, in with each team plays once again another team. Matches usually start on alternate table every 5 minutes. The large breaks between rounds usually get overflowed by the matches schedule falling behind, and a lot of time seems to be lost calculating the ranks (thought it improved in the last years, probably because it’s now done on the platform I mentioned above).

During our Coupe, we pushed the concept further by making each team play multiple times per round, with a match starting every 5 minute and nearly no break. At the same time, the rankings were shown live on screen. This was made possible by judges using the scoreboard to quickly validate and send scores.

Integrating the web scoreboard into the scoring application wasn’t too difficult, given the ease to re-use React components.

The biggest issue we noticed was that it was hard to make sure you covered every single mission in the scoreboard before sending it. It’s also an issue we noticed when we wanted to quickly check we entered the correct data in the scoreboard just by looking at the mat.

It was useless to make changes to the scoreboard at that time, given the FLL season ended and the Coupe was a one-time event. It would be improved the next year.

2016

The 2016 scoreboard aimed to solve the remaining issues.

At the association we used the scoreboard on PCs, but it was clear that anybody from outside or simply on the go would prefer to use the app on a mobile device. The 2015 resizable layout was simply making things smaller on small screens. It was time to introduce a mobile-first layout.

The interface was rewritten to just show small badges on the mat, and let the user browse mission details in a separate, paginated panel. The new layout also made place for longer mission descriptions and mission pictures.

The new interface also solved the coverage issue encountered the last year. By adding a paginated list of missions, it was now a lot easier to review all missions in order and not miss one. It was still possible to directly click on a mission on the mat to access it, just like before.

Social buttons to share the score on Twitter and connect with our association were added, but it looks like there were as much used as the print layout of the 2014 version.

Once again we organized the Coupe Robots-JU and used the scoreboard as part of the technology stack involved. The new layout proved a lot more efficient. Recording the scores and getting the team validation was now one of the shortest part of the organization (we’ve not managed to automate setting the mat back in start position yet !). We even managed to finish matches ahead of schedule at the end of the day !

A big advantage of using that scoreboard to calculate the scores is that you not only store the final score, but also the details of accomplished missions. This is useful for statistics and providing a complete detailed list of the results for each team and match. I suspect the official FLL platform also keeps track of the individual missions, but these are not shown in the interface.

2017

And here we are. This year challenge rules were released on the 28th of August, and I decided to try to break my personal (and maybe worldwide ?) record of time taken to publish an unofficial scoreboard.

It usually took me a few months before starting the work on the scoreboard so I don’t have to rewrite everything in case of a rule change. But this year the rules looked pretty straightforward so I started right away. In less than 12 hours the 2017 scoreboard was online.

Never finished coding the season scoreboard so quickly. Less than 12 hours since challenge release #FLL #HYDRODYNAMICS https://t.co/cFffxWQ4tl
— Clark Winkelmann (@clarkwinkelmann) 30 août 2017

I could probably have done it even faster, but I took the opportunity to make a few changes.

Since 2015 I went from React to Mithril as my main framework, and it already caused a few integration issues during the last Coupe to integrate the React scoreboard into the Mithril app. The React code of 2016 was also a big mess because everything was fit into a single file, meaning it required some major rewrite anyway.

I decided to re-create the exact same logic from React in Mithril. This went without issues, given the large similarities between the frameworks. The CSS style stayed mostly the same, with updated colors to reflect this year’s theme.

I also switched from a custom Gulp file to a Laravel Mix setup, which basically did the same things with nearly no code, better performance and better out of the box optimizations for the production files. I also dumped Bower completely and now use Yarn to install all dependencies. This removes a lot of complexity.

The most time-consuming tasks are copying texts from official websites and PDFs into the test suite and the scoreboard missions list. Since 2016 the layout is built from a JSON file, which allows for easy changes to the list of missions.

You can use the scoreboard on the Robots-JU website at https://fll-scoreboard-2017.robots-ju.ch/ and also check out the scoreboard source and the unit-tested score calculator source.

Future

In 2018 we will organize the third Coupe Robots-JU, which will most likely rely on the 2017 scoreboard. With the improvements of the past years, it has now become a robust part of our scoring stack.

As long as I will be an FLL coach and FIRST does not release an official and better tool I will probably keep coding new scoreboards. And I’m certainly not finished switching javascript frameworks either…

Given its early release it’s highly probable the 2017 scoreboard still has issues to address. Feel free to drop by the issues section on GitHub to report problems, make suggestions or directly contribute code.

If your team uses the scoreboard, we would be happy to hear about it. Please tweet us comments or pictures at @RobotsJU !

Written with StackEdit.

Step-by-step creation of my Flarum Emoji extension

Thu, 02 Feb 2017 01:00:00 +0000

This is a step-by-step guide on how I created my EmojiOne Area Picker extension for Flarum. For more info about my research, trial&error and sources or information, see my other article.

Before we start

This was done with Flarum beta 6 on an Ubuntu 16.04 system. I cannot guarantee it will apply to future versions of Flarum.

I have a local Flarum install in /var/www/flarum. This is referred as the Flarum root.

In code snippets, [...] indicates that nothing changed from the last snippet of the same file.

Workbench setup

Based on this discussion.

Create a new workbench folder under the Flarum install and register it as a repository in Flarum’s composer.json:

    "repositories": {
        "workbench": {
            "type": "path",
            "url": "workbench/*/"
        }
    },

Extension setup

Create new new folder with the name of the extension inside the workbench folder, in my case workbench/flarum-ext-emojionearea. That’s where my extension will be placed and I will refer to it as the Extension folder.

Next create a composer.json file inside the extension folder with your details:

{
    "name": "clarkwinkelmann/flarum-ext-emojionearea",
    "description": "Add EmojiOne Area emoji picker to Flarum",
    "type": "flarum-extension",
    "require": {
        "flarum/core": "^0.1.0-beta.6"
    },
    "extra": {
        "flarum-extension": {
            "title": "EmojiOne Area"
        }
    }
}

Then require the extension in Flarum’s composer.json file with the following line:

"clarkwinkelmann/flarum-ext-emojionearea": "*@dev"

Running composer update will add a symlink from the vendor directory to the extension folder, so we don’t need to run a Composer command every time we change our extension in the workbench.

Javascript setup

All following paths are relative to the extension path.

Javscript code will be placed in js/forum in the extension folder. In this folder we will need two files:

js/forum/package.json:

{
    "private": true,
    "devDependencies": {
        "gulp": "^3.8.11",
        "flarum-gulp": "^0.2.0"
    },
}

js/forum/Gulpfile.js:

var flarum = require('flarum-gulp');

flarum({
    modules: {
        'clarkwinkelmann/emojionearea': [
            'src/**/*.js'
        ]
    }
});

We also create the javascript bootstrap file that will setup our extension.

js/forum/src/main.js:

app.initializers.add('clarkwinkelmann-emojionearea', () => {
    // Nothing yet
});

When running gulp or gulp watch this will create an extension.js file in the js/forum/dist folder.

LESS setup

This is easy, create a less/forum/extension.less file.

PHP setup

We only need PHP to register our assets, this is done in bootstrap.php at the root of the extension folder:

<?php

use Flarum\Event\ConfigureClientView;
use Illuminate\Contracts\Events\Dispatcher;

return function (Dispatcher $events) {
    $events->listen(ConfigureClientView::class, function (ConfigureClientView $event) {
        if ($event->isForum()) {
            $event->addAssets([
                __DIR__ . '/js/forum/dist/extension.js',
                __DIR__ . '/less/forum/extension.less',
            ]);
            $event->addBootstrapper('clarkwinkelmann/emojionearea/main');
        }
    });
};

Coding javascript

Inspired by the flagrow/upload extension.

We will use the mervick/emojionearea jQuery plugin, so we first need to add it as a dependency:

js/forum/package.json:

{
    "private": true,
    "devDependencies": {
        "gulp": "^3.8.11",
        "flarum-gulp": "^0.2.0",
        "emojionearea": "^3.1.5"
    }
}

We need to create our own button. For that, we create a new file for our EmojiAreaButton that is based on the base flarum/Component:

js/forum/src/components/EmojiAreaButton.js:

import Component from "flarum/Component";
import icon from "flarum/helpers/icon";

export default class EmojiAreaButton extends Component {

    view() {
        return m('div', {className: 'Button Button-emojionearea hasIcon Button--icon'}, [
            icon('smile-o', {className: 'Button-icon'}),
            m('span', {className: 'Button-label'}, 'Emojis'),
            m('span', {className: 'Button-emojioneareaContainer'})
        ]);
    }

}

The .Button-emojionearea class allows us to target the button with CSS and the .Button-emojioneareaContainer element will contain the picker that we will load with jQuery.

We need to run the $.emojioneArea() method after this component has been loaded. For that we make use of Mithril’s config attribute. This allows you to supply a method that will be called each time a DOM item is redrawn. The isInitialized parameter informs us the method has already been called.

    view() {
        return m('div', {config: this.configArea.bind(this), className: '[...]'}, [
            // [...]
        ]);
    }

    configArea(element, isInitialized) {
        if (isInitialized) return;

        var $container = $(element).find('.Button-emojioneareaContainer');
    }

We can then load our javascript plugin in the configArea() method. We load emojiOneArea on a new jQuery <div/> so it does not try to find a textarea and we put the picker inside our $container:

    configArea(element, isInitialized) {
        // [...]

        $('<div />').emojioneArea({
            container: $container,
            standalone: true,
            hideSource: false,
            events: {
                emojibtn_click: function (button, event) {
                    // emoji clicked
                }
            }
        });
    }

We can then add our button to the post editor.

js/forum/src/main.js:

import {extend} from "flarum/extend";
import TextEditor from "flarum/components/TextEditor";
import EmojiAreaButton from 'clarkwinkelmann/emojionearea/components/EmojiAreaButton';

app.initializers.add('clarkwinkelmann-emojionearea', () => {
    extend(TextEditor.prototype, 'controlItems', function (items) {
        var emojiButton = new EmojiAreaButton;
        items.add('clarkwinkelmann-emojionearea', emojiButton, 0);
    });
});

In order for the jQuery plugin to load, we need to add it to our Gulpfile as a file.

js/forum/Gulpfile.js:

var flarum = require('flarum-gulp');

flarum({
    files: [
        'node_modules/emojionearea/dist/emojionearea.js'
    ],
    modules: {
        'clarkwinkelmann/emojionearea': [
            'src/**/*.js'
        ]
    }
});

After running npm install and gulp (or gulp watch) in js/forum, the extension can be enabled in the Flarum install and the Emoji picker is loaded inside the button. Clicking on an emoji does not do anything yet.

To add text to the post, we need to call the insertAtCursor() method on the TextEditor instance. This is not accessible from our button by default, we need to save a pointer when we extend the editor.

We add the attribute to our button:

js/forum/src/components/EmojiAreaButton.js:

// [...]

export default class EmojiAreaButton extends Component {

    init() {
        this.textEditor = null;
    }

    // [...]

}

And fill it at extend time:

js/forum/src/main.js:

// [...]

app.initializers.add('clarkwinkelmann-emojionearea', () => {
    extend(TextEditor.prototype, 'controlItems', function (items) {
        var emojiButton = new EmojiAreaButton;
        emojiButton.textEditor = this;
        items.add('clarkwinkelmann-emojionearea', emojiButton, 0);
    });
});

Now we can access it when an emoji is clicked:

js/forum/src/components/EmojiAreaButton.js:

    configArea(element, isInitialized) {
        // [...]

        var editor = this.textEditor;

        $('<div />').emojioneArea({
            // [...]
            events: {
                emojibtn_click: function (button, event) {
                    var shortcode = button.data('name');
                    editor.insertAtCursor(shortcode);
                }
            }
        });
    }

And it works ! Some optimisations were not shown here, have a look at the source code.

Coding CSS/LESS

The less/forum/extension.less file contains a few rules to hide the parts of the picker we do not need. Have a look at it here on GitHub for the details.

This CSS part is my own invention because I did not find any other extension doing it

To include the CSS of the picker, I use another (normal) Gulp file to copy the CSS needed to a dist folder, much like the javascript part:

css/forum/package.json:

{
    "private": true,
    "devDependencies": {
        "gulp": "^3.8.11",
        "emojionearea": "^3.1.5"
    }
}

css/forum/Gulpfile.js:

var gulp = require('gulp');

gulp.task('default', function() {
    gulp.src([
        'node_modules/emojionearea/dist/emojionearea.css'
    ]).pipe(gulp.dest('dist'));
});

Running npm install and gulp in css/forum produces a css/forum/dist/emojionearea.css file that will be included in version control. We also add this file to the bootstrap.php file:

<?php

use Flarum\Event\ConfigureClientView;
use Illuminate\Contracts\Events\Dispatcher;

return function (Dispatcher $events) {
    $events->listen(ConfigureClientView::class, function (ConfigureClientView $event) {
        if ($event->isForum()) {
            $event->addAssets([
                __DIR__ . '/js/forum/dist/extension.js',
                __DIR__ . '/less/forum/extension.less',
                __DIR__ . '/css/forum/dist/emojionearea.css',
            ]);
            $event->addBootstrapper('clarkwinkelmann/emojionearea/main');
        }
    });
};

To finish properly, add a README.md, LICENSE.txt and .gitignore file. Here’s what I used in the .gitignore file:

**/node_modules
/vendor

In my case I did not even had to run composer install in the extension folder, but if I had unit tests (for example) I would have to run composer. That’s where the /vendor rule in the gitignore would be useful.

Now your extension is ready for git init and git commit !

Have a look at:

Written with StackEdit.

My first Flarum extension

Thu, 02 Feb 2017 01:00:00 +0000

This is a diary on the creation of my first Flarum extension. For the step-by-step tutorial (without all the trial and error rambling) have a look at this other article.

Starting point

I just replaced the manually crafted ZetaMode Forum with Flarum.

Both ZetaMode and Flarum being in beta, this seemed like a good idea. I’m already expecting things to break anyway, so I prefer to help debug and improve Flarum over building custom in-house stuff.

Of course, new forum means new user suggestions. The first thing reported was it was hard for new users to guess the emoji shortcodes.

In the previous forum, I added a link to emoji.codes at the bottom of the autocomplete popup. But there is no such link in the Flarum emoji popup, nor is an emoji picker included.

I did a quick search to find if anybody had already made one. I found this thread. A few people were looking for the same thing as me. Also, there was a link to a jQuery plugin named emojionearea.

Since it looked like nobody had created an extension for that before, I decided to give it a try. I tried to find other existing emoji picker libraries on the web. I found this one by @tommoor and this one by @OneSignal. The first was written for React, which is probably hard to integrate with Mythril, and the second one used a hell lot of files.

I hesitated. The OneSignal one had more stars on GitHub, but the meverick one had more options. Also, I’ve seen other Flarum extensions use jQuery plugins so I was more confident to success with it.

Coding the extension

I went back to have a look at the official doc. The start of this page is a bit fishy because I’ve read somewhere there is no more extensions directory.

I remembered seeing a composer dev tutorial on the forum, which I quickly found again. That tutorial is really straightforward and it was easy to setup the project.

I then proceeded to the javascript part of the extension. There, the official doc is really easy to follow. I created a js/forum folder inside my extension folder with a package.json and Gulpfile.js.

In addition to my own javascript code for UI integration, I needed to import the jQuery plugin. Adding the file path inside the modules section was not working. I found this geotags plugin that also used a jQuery plugin and found that I could use a files section to add raw JS imports (the code snippet above is the final version)

Then, I had to find out which components I had to extend. Again the official doc is great to explain how it works, but I had to look inside other’s extensions source code to find out which was the right component and how it worked.

I first had a look at the flarum/flarum-ext-emoji, which does something similar to what I want to do (it implements the emoji autocomplete, but not a real picker). But it turned out it was not necessary to hack into the ComposerBody component like they had to do with the autocomplete.

The flagrow/upload extension is actually more similar to what I want to do. It adds a button to the post composer, and this button alters the content of the post.

First I tried to use the emojionearea plugin the way it was meant to be: by just running $textarea.emojioneArea(). But I quickly found out it was destroying the whole post composer. Indeed, this plugin creates its own contenteditable area and hides the original textarea, which breaks the editor. By adjusting the plugin settings, I can change which divs get replaced / used, but there was no way to make it keep the original textarea untouched.

Hopefully, this plugin also had a “standalone” mode. I was able to embed this box under the post editor. I was then able to use the plugin events to detect an emoji selection and use the Flarum TextEditor functions to insert the emoji in the post. Great !

Last part, I needed to put this selector inside a Flarum button and hide its own button style (the standalone version displays the current selected emoji and a button with an icon - but it does not fit nicely with Flarum). Some custom CSS in less/forum/extension.less did the trick, hiding what’s not required. opacity: 0 on the original button allows the user to click on the original button through the Flarum button.

The tricky part was to include the original CSS file of EmojiOne Area into the extension as well.

Even after desperately asking for help on the forum, I still have not found any example of extension doing that. Let’s consider I am the first ever person to do it and have to decide myself how to do it.

The easy option would have been to use the Gulpfile inside the js/forum folder to copy the CSS to a dist folder. Unfortunately, the Flarum gulp helper does not seem to have an option to copy files. Plus, doing this in the js folder didn’t seem right.

So I created a new css/forum folder in my project folder, with another package.json and Gulpfile.js. There I load the same emojionearea library, as well as a standard Gulp. With a simple gulp task, I copy the CSS file I need to a dist folder that is included in my version control.

var gulp = require('gulp');

gulp.task('default', function() {
    gulp.src([
        'node_modules/emojionearea/dist/emojionearea.css'
    ]).pipe(gulp.dest('dist'));
});

There is no real back-end code for this extension, the only thing to do is to register the assets. I decided to put everything in bootstrap.php, but if I had more files I should probably store events listener in an src folder and only list these in the bootstrapping file like most extensions do.

I then commited the extension folder to my GitHub account, created a new release tagged v0.1.0 and registered it on Packagist. That was my first time adding a package to Composer. That was really easy and straightforward.

In conclusion, creating front-end extensions is not as scary as it looked like for me. I will now try to create more complex ones. Please tell me if you want other articles from me on the subject !

Links:

Written with StackEdit.

Bypassing broken Joomla! permissions

Tue, 18 Oct 2016 19:00:00 +0000

I just retired an (already) old Joomla! website to replace it with a new Concrete5 one.

I backed up the whole Joomla! database and files. I still needed to access some archive items so I set up the Joomla website on my local machine.

I am not familiar with Joomla! at all, but it’s certainly not the first time that I try to launch an “old” website on localhost.

I was afraid that the PHP version would mess everything. I run 7.0 on my dev machine and the old server hosting the website was still on 5.2.

I imported the database on my local MySQL instance, edited the config file and fired the PHP dev server in the root directory. Incredibly, it worked !

For reference, here was the Joomla version (does not seem too old - again, I don’t know anything about Joomla!):

Joomla! Version Joomla! 2.5.24 Stable [ Ember ] 25-July-2014 13:00 GMT

Joomla! Platform Version Joomla Platform 11.4.0 Stable [ Brian Kernighan ] 03-Jan-2012 00:00 GMT

I had access to the administration panel, but what I wanted was to see the old website as it was previously online (I need to access specific known URLs and it’s just a mess in the admin panel). Here, things were not OK: the home page was displayed, but there was no menu. Every other page returned an error:

You are not authorised to view this resource.

A few minutes on DuckDuckGo, or Google, or whatever reveals there could be A TON of reasons behind this message. And even the StackOverflow answers are not very helpful, because each case is very specific.

I tried a few of the suggested actions. Cleared cache, but it seems it was disabled; check permissions, everything is public; empty trash - wait, I still have no idea where is this damn Joomla! trash. Nothing helped. Still same error.

I didn’t want to lose time into debugging this, I just wanted to see the website. Looking for ways to disable the permissions all together didn’t yield interesting results either.

So before spending a day on the internet to troubleshoot this I decided to just go into the PHP files and edit whatever needed to be able to see the website.

Fortunately, enabling debug mode is as simple as:

configuration.php:

class JConfig {
    // [...]
    public $debug = '1';
    // [...]
}

This enables a nice little console at the bottom of each page.

On a problematic page I can see in Joomla! Debug Console > Errors:

You are not authorised to view this resource.

Call stack

# Function Location

1 JSite->dispatch() JROOT/index.php:42

2 JComponentHelper::renderComponent() JROOT/includes/application.php:194

3 JComponentHelper::executeComponent() JROOT/libraries/joomla/application/component/helper.php:348

4 require_once() JROOT/libraries/joomla/application/component/helper.php:380

5 JController->execute() JROOT/components/com_content/content.php:16

6 ContentController->display() JROOT/libraries/joomla/application/component/controller.php:761

7 JController->display() JROOT/components/com_content/controller.php:74

8 ContentViewArticle->display() JROOT/libraries/joomla/application/component/controller.php:722

9 JError::raiseWarning() JROOT/components/com_content/views/article/view.html.php:104

10 JError::raise() JROOT/libraries/joomla/error/error.php:276

The error (raiseWarning() does not seem a really good name here) comes from the view.html.php file.

You can disable it by removing the whole if block checking if user has access.

components/com_content/views/article/view.html.php:101:

// remove:
if ($item->params->get('access-view') != true && (($item->params->get('show_noauth') != true &&  $user->get('guest') ))) {
    JError::raiseWarning(403, JText::_('JERROR_ALERTNOAUTHOR'));
    return;
}

This removes the error but the page is still blank. On pages with “paged” navigation, the navigation now appears, but not the content. A quick look in the subdirectories of this article/view module reveals a template file tmpl/default.php where additional checks occur. By hard-coding true into the normal display case the content shows up.

In components/com_content/views/article/tmpl/default.php:161 change:

<?php if ($params->get('access-view')):?>

to:

<?php if (true):?>

And voilà.

This does not solve the problem of the menu, but it was not important for me. It may be a little harder to fix because there are no errors indicating where to look, but I expect a similar menu controller and template somewhere.

I hope this article will be useful to somebody else facing the same issue. I also put some bold text saying again that this is a hack to access every page on a local Joomla! instance, do not try this in production !

Javascript redirect and Piwik tracking

Fri, 02 Sep 2016 23:20:00 +0000

Today I set up a custom shortlink: https://zetamode.com/questionnaire pointing to a Google Form (Click it if you speak french and are interested in online fashiown game, we’re doing a survey !)

The zetamode.com website is hosted with GitHub Pages, so I cannot go with an HTTP redirect. And I want to track the origin of the shortlink users through my Piwik instance.

[Of course] I did not find anybody who had the same use-case on Google. But I found two interesting articles: Here someone explains how to replicate the behavior of the jekyll-redirect-from plugin (without tracking) and here there are a few interesting ways to do a javascript redirect while tracking it with Google Analytics. I find this one particularly interesting. It involves turning the async tracking code into a sync one, and put the redirect after the tracking code. This prevents the redirect from happening before the tracking, and we don’t need hard-coded waiting times.

You can have a look at the actual file here, but below is a more generic version you are welcome to edit to fit your needs:

And to use it:

Note: The SO answer I based my code on states that you should not use page.redirect_to as the parameter name, as it will conflict with the jekyll-redirect-to plugin, which I believe is enabled on GitHub Pages (didn’t test myself).

So far it seems this method works !

Sources:

Flarum templating

Mon, 22 Aug 2016 16:20:00 +0000

Note by Clark from the future (November 2018): this was written a long time ago and while still accurate, the new Flarum docs now cover this a lot better than I did here :)

An interesting discussion was taking place on the Flarum Gitter today. I figured I should better write an article instead of writing thousands of words in a small text input.

I’m new to Flarum, I didn’t even have time to write my first extension. But I read all the docs, looked at the source code of most core extensions, and I must say this is some very impressive technology.

So impressive, that some devs get confused very quickly.

Why use composer, why do I have to write JavaScript to edit the templates, why can’t I just paste my HTML there ?

I will try to explain this the best as I can. Hopefully, I will be able to re-use this post everytime someone gets confused.

The old way of doing things

In very old web application, you just didn’t have Views.

For example, in osCommerce (until v2 at least, I don’t know if v3 will ever be released) you had to edit the core files to change how things look. Want to add a link to the user settings ? Better edit that account.php file in the root folder.

Of course, everything breaks when:

There is an update to the software (which requires to overwrite the files you edited)
You want to share your amazing feature with somebody else which has a base installation
or worse, someone who already has another extension installed

I’d like to say nobody does it anymore but guess that ? I’m actually maintaining a 2005 shop which cannot easily be migrated.

Anyway, most websites now use another technique:

The current way of doing things

If you come from a WordPress background for example, this is the way things work:

You get your own special directory somewhere like wp-content/themes/myamazingtheme. There, you create php template files, which get used for a given request. If you don’t create a file, a default one kicks in and everything works.

In this file, you get access to a few variables, so you know what to display. You can include other files to prevent duplication.

Important note: Views can not only return HTML. You may also format your data as XML or JSON for example.

Congratulations, you are using Views ! MVC frameworks takes this to a higher level, by using them to separate the visual interface from the data. I won’t go into that, there are loads of good MVC tutorials out there.

In modern frameworks like Laravel, there are other components which glue everything together. The only one that you should know to understand my article is the Router, which maps URLs to Controllers. A Controller then returns a View.

A typical request to a web application could be drawn like this:

User > Request (GET) > Router > Controller > Fetch data > View (HTML) > Page

The modern way of doing things

The new trend is JavaScript applications.

How it works: The first time you load the page, the application loads, without worrying of what the current page is. When it is ready or when you change page, an AJAX request is issued to get the new content, and the interface is updated through JavaScript.

It now works like this:

User > Request (GET) > Controller > View (HTML) > Empty page (JavaScript App)
JS App > Request (AJAX) > Controller > Fetch data > View (JSON) > Page update

This changes everything.

We still have a Controller which returns HTML, but there is no data here, just the application bootstrap code.

When the JavaScript application is started, it fetches the data based on the current URL. No fancy HTML there, the data is returned in JSON format, and the JavaScript takes care of placing this data at the correct place.

Now you think you’ve seen everything ? Nope.

MVC on client side

Flarum uses Mithril, which is itself an MVC Framework, but on the client side !

This means there is also a Router, some Controllers and of course Views written in JavaScript !

Let’s draw a new schema taking that into account. Here’s what happens on a typical page load:

(Server) User > Request (GET) > Router > Controller > View (HTML) > Page (Mithril App)
(Client) Mithril App > Router > Controller > Data request [...]
(Server) Mithril > Request (AJAX) > Router > Controller > Fetch data > View (JSON) > Response
(Client) [...] > Parse response > Controller > View (Virtual DOM) > HTML update

Now, how do Mithril Views work ? Pretty much the same as the PHP ones. The view consists of an HTML structure, which is written inside the page and takes the whole place.

To make things easier and prevent code duplication, Mithril uses Components, which can be “included” from a parent Component. You can find some example Components in the Flarum documentation, like DiscussionPage, PostStream, Post, etc…

How to extend the interface ? You just need to change the HTML output of the JavaScript Component of the item you want to change on the page. You can add new Components inside existing ones, too ! From now on the official Flarum doc will tell you where to change things: http://flarum.org/docs/extend/start/

One last thing: Mithril, like React, uses Virtual DOM. This is a way to make things faster by computing the “HTML” in memory, and updating only the bits of the page that changed across requests.

The difference for you is that you don’t return a “string of HTML” but a “representation of the HTML”, which is made of JavaScript objects. The good news is that you can write HTML almost normally and it will be turned into cryptic objects at compilation time. Have a look at how it looks on Mithril’s home page or the Flarum Extensions documentation.

Recap

So what did we learn here (I hope you learned something lol).

The visual interface of Flarum is a JavaScript MVC application powered by Mithril
It talks to a PHP application which just sends data as JSON, not as HTML
The PHP application does uses Views, but only to render the JavaScript application
The JavaScript Views are organised as Components, which are placed in a hierarchical way on the page
To change how something looks like, you have to edit the Component responsible for it
You can add new Components as child of existing ones

I won’t go into further details on the development of Extensions for now. I think the official one is pretty good once you know how the technologies used work together.

This is my first tutorial, please give me feedback on Twitter or anywhere else that you can find me =)

Additional notes

There are in fact a few HTML templates in the views folder of Flarum. They are used to display a simple alternative interface to users with JavaScript disabled.

Davis Custom Header extension does manipulate the DOM directly with a jQuery selector. That’s a special case. Why ? If you look at views/forum.blade.php you can see several things: #content will hold the main application Component. #header-primary and #header-secondary will hold the navigation Components. The tags that are accessed directly (#header and head) are outside the JS application. They are not Components and therefore must be accessed in the “old” way. You can’t do that with Components, because the DOM is managed by Mithril. Maybe in the future the #header tag will be merged into the main application, which would allow to change all its content via Components.

I only cover the problems that newcomers may face when editing Flarum interface. Adding functionality is another topic that includes things like Providers and Events (as opposed with WP Hooks). I’ll write another article if there is interest in the matter !

The blog deadline

Thu, 18 Aug 2016 10:40:00 +0000

I’m lazy.

So lazy that launching a blog was on my TODO list for a long time now. There was only one way to finally do it. I set a deadline. The deadline is today. So here is the blog.

In fact making a blog is easy. Making it open-source is just as well.

What’s taking a lot of time is writing (wow it’s already been an hour to write the first 2 posts, hope I get better at it). But the simple fact of having a blog will force me to write more content.

Here are the easy-to-use tools I used

I use Jekyll because I already use it for my other websites. It’s actually the first time I will be using it for a blog.

I write text in Markdown because that’s just so easy. And I don’t need any special editor. Visual Studio Code is actually pretty good at it. Sucks for PHP, though.

I host the code on GitHub, because I thing it is logical to share the source and allow contributions.

I use GitHub Pages to host the website because, well, it’s free, and you can’t choose anything easier when your code is already on GitHub. They even launched an update yesterday that makes things easier. Hello master branch.

I put CloudFlare in front of it just. GitHub Pages already uses a CDN but I would not look serious if my blog wasn’t HTTPS secured.

By the way, maybe you noticed I use the default Jekyll Theme. If I had decided to create a theme before launching the blog, it would have taken ages ! So I stay with default for the moment. But guess what, it even looks good.

And I started a blog

Thu, 18 Aug 2016 10:00:00 +0000

Hi there ! My name is Clark Winkelmann and I’m a webdesigner freelancer.

I will keep this short. I will use this blog to share my experiences with open-source software as well as share insights about projects I’m working on.

Why ? I’ve been contributing to the open-source community for some time already, but generally don’t share all the knowledge I gained while working on a project. I merely share the code (and sometimes the doc) without going further.

This was a way to get things done quicker so I could work on something else. Now that I do more serious stuff and that I’m more confident in doing things sort of right, it’s time to share more !

Let’s keep this simple, with a list. Things-I-often-face-and-others-will-too:

Trouble setting up dev environment
Getting the minimum required knowledge of a software to fix things like URLs or typos
Old and great software whose installation documentation is just totally outdated Anybody still on Ubuntu 8.04 ?

In the end, I find a way to work around and make things work. But this knowledge is lost. It would be much more useful if I put it online so others can find it.

What to expect on this blog

Open-source related things
Web development stuff
Linux & Ubuntu stuff
Command line stuff
Installation of web applications in the cloud
How-to’s about old projects that are still great

I’ve seen that all devs have a “goto” language to try out logic and quickly connect things between them. Mine is PHP. Expect to see a lot of PHP here =)

Immediate projects: I will start by retroactively talking about important projects I’ve developed. My biggest projects can be found at https://clarkwinkelmann.com/ (French) and https://github.com/clarkwinkelmann, but they lack a proper description from a programmer point of view.

A last few things about me

I live in Switzerland and my native language is French. Most articles here will be written in English. If I write something in French I’ll try to provide the English translation as well.

Note that I may share progress about projects that use the French language. When I work with other people in my area I may comment the code in French. Otherwise, all my code is named and commented in English.

I’m open to all suggestions about this blog. Feel free to contact me on Twitter @clarkwinkelmann or by email at clark.winkelmann@gmail.com

If like me you want things fixed quickly (horrible typos or non-https-but-compatible links for example) you are welcome to send me PRs on the GitHub repo of the blog.

Joomla! Version	Joomla! 2.5.24 Stable [ Ember ] 25-July-2014 13:00 GMT
Joomla! Platform Version	Joomla Platform 11.4.0 Stable [ Brian Kernighan ] 03-Jan-2012 00:00 GMT

#	Function	Location
1	JSite->dispatch()	JROOT/index.php:42
2	JComponentHelper::renderComponent()	JROOT/includes/application.php:194
3	JComponentHelper::executeComponent()	JROOT/libraries/joomla/application/component/helper.php:348
4	require_once()	JROOT/libraries/joomla/application/component/helper.php:380
5	JController->execute()	JROOT/components/com_content/content.php:16
6	ContentController->display()	JROOT/libraries/joomla/application/component/controller.php:761
7	JController->display()	JROOT/components/com_content/controller.php:74
8	ContentViewArticle->display()	JROOT/libraries/joomla/application/component/controller.php:722
9	JError::raiseWarning()	JROOT/components/com_content/views/article/view.html.php:104
10	JError::raise()	JROOT/libraries/joomla/error/error.php:276