Wappler Extensibility - Build Custom Wappler Extensions

[George]

The next level of Wappler extensibility - App Connect for our front-end framework is here!

Building custom App Connect custom components with their own dynamic attributes, events and data sources is now possible. You can write your own custom components and also provide a UI definition of your extensions so they integrate directly visually in Wappler!

You also build custom Server Connect extensions now for the backend. Both type of extensions are described here.

Your extensions can be published on Github and NPM, so they can be easily installed in Wappler as versioned packages and also use their own dependencies.

Writing Wappler Extensions

Extension Folder Structure

You can choose fully your own folder structure for the extensions, with just a few requirements:

• it has to be a subfolder of your project, like for example /src/your-extension-name

• it has to have package.json as any other node module, declaring the package general name, version and dependencies

• for App Connect components, it has to have a folder with the UI definition file in it:
  /app_connect/components.hjson

• for Server Connect extensions, it has to have a folder with the UI definition file in it:
  /server_connect/modules/xxx.hjson

Creating New Extension

We have simplified greatly the initial setup of an extension folder, so just go to your project settings, choose Extensions and choose to Create New Extension. Then just pick a new folder to place your extension in and all the above requirements will be created automatically for you.

You can specify your own scope name (organization) if you will be creating multiple extensions. To do so create first a subfolder starting with @ and your organization name and then extension name as sub folder like src/@my_company/wappler-my-first-extension

It is also important to start your extension name with wappler- for more easier recognition

Writing Custom Server Connect modules and formatters

Wappler Extensibility - Writing Custom Modules and Formatters for Server Connect

Wappler opens up its extensibility powers! Now you can define your own custom modules and formatters for Server Connect. You can write your own custom code but also provide a UI definition of your extensions so they integrate directly visually in Wappler! Writing Extensions for Server Connect Folder Structure All extensions files are placed in your project folder under the following folders: for modules: extensions/server_connect/modules for formatters extensions/server_connect/forma…

Writing Custom App Connect components and formatters

Wappler Extensibility - Writing Custom App Connect Components and Formatters

Writing App Connect Components The app connect component can easily be written in JavaScript. Check: Writing a Component for App Connect Writing Custom Attributes for App Connect Writing Custom Formatters for App Connect App Connect Components UI Definition To define a UI for your App Connect components, you need to place a create special Hjson file in that describes your UI. Hjson is just a more readable json format that makes it easier to write. It describes the components, dyna…

Publishing your extension to NPM

You can decide to publish your extension to NPM, so that other people can use it directly.
Make sure you check your package.json in the extension folder so that all correct name, info and dependencies are in there.

First make sure you visit NPM, register for account there and read the contribution rules

Then you can easily publish to NPM by:

1. Open a terminal in Wappler

2. Change to the folder where your extension is like:

cd src/your-extension-name

3. Login to NPM by entering

npm login

4. test your package publishing by running

npm publish ./ --access=public --dry-run

5. if all ok, then publish the package

npm publish ./ --access=public

That is all! Your package is now officially available as Wappler extension!

Using a published extension in Wappler

Using an extension in your project that is already published to NPM is pretty easy.

Just open the project settings, go to Extensions, click on the [ + ] to add extension and enter the NPM name for your extension.

You can try to install our example extension:

@wappler/wappler-example-component

After saving the project settings, the extension will be installed directly and ready for use.

[JonL]

@george do you have to publish to npm and install your own extensions to test them?

I’m saying this because the extension is looking for my js file in /node_modules as root so I get an error in the console.

file .../node_modules/browser/jonl/browser/index.js does not exists!

When going through the wizard I selected src/extensions/jonl/browser as folder to create the extension

This is my relevant part of the hjson

copyFiles: [
            {src: 'jonl/browser/index.js', dst: 'js/jonl_browser.js'}
        ],
linkFiles: [
            {src: 'js/jonl_browser.js', type: 'js', defer: true}
        ],

And my folder structure:

It would seem that /node_modules/browser/is being prepended to the url added in src

As a workaround I added ../../ to skip the error and get the file copied.

{src: '../../src/extensions/jonl/browser/index.js', dst: 'js/jonl_browser.js'}

It’s unclear though what is the procedure to test locally.

[George]

@JonL

@george do you have to publish to npm and install your own extensions to test them?

No you don’t need to publish them when developing locally… That is the whole point when “creating new” extension in the src/my-extension for example it will create a new package.json and install the extension locally in node_modules and symlink it to the src

so actually it is pretty much running npm install ./src/my-extension

The paths in src in copyFiles are also relative to your extension root, so you shouldn’t add any ../src in there. And the dst are relative to your site root.

[JonL]

Ok. Got it.

[JonL]

@George

Your extensions can be published on Github and NPM, so they can be easily installed in Wappler as versioned packages and also use their own dependencies.

and also use their own dependencies.

How would this work? If I add a dependency in package.json how can my extension access it in the browser? AFAIK there is no bundler working with Wappler.

@George

outputType: 'object',

It’s undocumented.

[George]

@JonL

If I add a dependency in package.json how can my extension access it in the browser?

It is just installed in node_modules outside of web root and in your hjson with copyFiles and linkFiles you can specify which from its files need to be copied to your web root and linked.

[George]

@George

outputType: ‘object’,

All output is specified in the dataScheme and it defaults to array. With outputType you can make it object or other simple type of no dataScheme is specified

[George]

@JonL

AFAIK there is no bundler working with Wappler.

We are actually brainstorming about integrating different bundlers in the same process as the extension installations and also in the publishing process, so you can contribute some ideas in a new topic if you want.

[JonL]

@george what does dataPick do? I haven’t noticed any difference between true or false

[George]

@JonL

what does dataPick do?

dataPick means that even with no dataScheme, the user should be able to pick the component name as data. Otherwise it is not listed in the data picker at all.

[JonL]

Well then there is a bug because I can’t pick it
I mean, it’s available. But it doesn’t get added when clicking on it.

[George]

Well try adding also dataPickObject: true

[JonL]

Something sketchy is going on here

@George

Well try adding also dataPickObject: true

From App Connect:

From Server Connect:

From some random core component:

I think we are going to require further help on what they do and how they combine

dataPickObject does indeed allow to select the root. But I no idea what dataPick does. I see no difference at all when changing values.

[JonL]

Hi @george, what’s the workflow of an extension installation via UI? Asking to understand at what point in the UI installation npm lifecycle scripts will be called if I add them to package.json

[George]

Well it is explained in the last section of the above doc Wappler Extensibility - Build Custom App Connect Extensions

[JonL]

I meant what npm commands and arguments you are using when installing remotely and their order(if more than one). Also what files in the project are updated(like .wappler/project.json)

I might have the need to install from a private registry some stuff and run some lifecycle scripts. So I’m thinking on building a shell script to automate this and I want to make sure I follow the same steps so it registers correctly.

[George]

The above article has now being updated to reflect the availability to package Server Connect extensions now as well in Wappler 5.6.2

[JonL]

@George

• for App Connect components, it has to have a folder with the UI definition file in it:
  /app_connect/components.hjson
• for Server Connect extensions, it has to have a folder with the UI definition file in it:
  /server_connect/modules/xxx.hjson

Wasn’t it possible to refactor SC extensions to follow the same folder structure as for App Connect extensions? Even if it meant a breaking change for SC current extensions.

[George]

There was really no need to, all works fine as it is.