What are we creating ¶

We will create a new Xlog extension that adds “Hello World!” before the page text.

Creating an extension ¶

Xlog extensions are Go modules (check extensions for more details). So make sure Go toolchain is installed on your system.

First create an empty directory and initialize a new go module in it

1mkdir helloworld
2cd helloworld
3go mod init github.com/emad-elsaid/helloworld
4go get github.com/emad-elsaid/xlog

Replace the URL to your github account or any other URL where your extension will be hosted. as per Go modules convention.

Create a custom installation ¶

To test our extension we need a main package that loads xlog and your own extension.

We’ll create cmd/xlog/xlog.go that acts as custom installation.

1mkdir -p cmd/xlog

Create a file under cmd/xlog/xlog.go that has the following content.

 1package main
 2
 3import (
 4	// Core
 5	"github.com/emad-elsaid/xlog"
 6
 7	// Extensions
 8	_ "github.com/emad-elsaid/helloworld"
 9)
10
11func main() {
12	xlog.Start()
13}

Create an extension ¶

Lets make sure Go finds a helloworld package in your module root. it’ll do nothing for now.

Create a file helloworld.go that contains the package name.

1package helloworld

Run your custom installation ¶

Now running cmd/xlog/xlog.go will start the xlog core with only your extension loaded. so it’s a clean environment that include only the xlog core and no other extensions.

1go run ./cmd/xlog/xlog.go

You should see output similar to the following. And navigating to http://localhost:3000 should drop you in the editor to create your index.md page.

2022/11/17 17:13:38  Template  (64.165µs) commands
2022/11/17 17:13:38  Template  (47.627µs) edit
2022/11/17 17:13:38  Template  (53.813µs) layout
2022/11/17 17:13:38  Template  (21.99µs) pages
2022/11/17 17:13:38  Template  (27.596µs) properties
2022/11/17 17:13:38  Template  (67.411µs) quick_commands
2022/11/17 17:13:38  Template  (116.689µs) sidebar
2022/11/17 17:13:38  Template  (80.292µs) view
2022/11/17 17:13:38 Starting server: 127.0.0.1:3000

From now on any change to any of the Go files will require restarting the xlog server

Create your first test page ¶

Try opening http://localhost:3000
Enter any text. for example: “We are creating a Hello world Xlog extension.”
Click “Save” or “Ctrl+S”
You should see your page rendered in HTML

Define a Preprocessor ¶

Packages add features to Xlog by calling Register* functions in the init function of the page. This allow registering a group of types for xlog to use in the appropriate time. Like:

Preprocessor
Autocomplete
Command

For our extension we want to add “Hello world!” before the actual page content. this is exactly what the Preprocessor is for. a function that processes the page text before rendering it to HTML.

We will create a function that implement the Preprocessor interface. helloworld.go should have the following content.

1package helloworld
2
3func addHelloWorld(input string) string {
4	return "Hello world!\n" + input
5}

This is a function that takes the page content as string and return the content after processing. You can manipulate the page content as you wish in this function. for us we added a line in the beginning of the page.

The Init function ¶

Now we’ll need to register this function as a preprocessor. we’ll do this by importing xlog core and use RegisterPreprocessor.

 1package helloworld
 2
 3import "github.com/emad-elsaid/xlog"
 4
 5func init() {
 6	xlog.RegisterPreprocessor(addHelloWorld)
 7}
 8
 9func addHelloWorld(input string) string {
10	return "Hello world!\n" + input
11}

Restarting the server and refreshing your web page will show the following:

Hello world!
We are creating a Hello world Xlog extension.

Success ¶

Congrates, You created a new xlog extension. Now you can publish this extension to github and import it in any custom installation of xlog.

Also you may try to explore Xlog package documentation to get familiar with other types and Register functions.

Backlinks

extensions Thursday 17 November 2022
📼 index Saturday 14 January 2023