Create Silex components

---

This wiki is obsolete, it concerns Silex v2

⚠️ WARNING: Support for Silex v2 has stopped.

Go to Silex v3 documentation instead,

Try Silex v3 here,

Read about it,

Subscribe to the newsletter (En francais ici

---

> Please read the page How to Host An Instance of Silex before trying to create your own components

About components

Silex components are elements you can add to a website through the "+" menu. They are created with a tool called "Prodotype" which compiles them for Silex and generates the UI.

Why components

• Empower your users with new tools
• The UI is generated, you just need to describe the parameters
• It is like a widget (simple HTML code you put in an HTML box) but your users can not view the code, and can edit parameters in a UI

Add components to your own instance

Here is the code which is explained in this section

Create a project

You can add components to your instance for your users. Start by creating a new nodejs project as explained in the page How To Add Silex To Your Node.js Project. In short, Silex is included in your project as an npm dependency.

Create a simple component

For now here is a simple component example. Below your will find more info about how to create components.

Create a folder components/ at the root of your project.

components/test.ejs:

<h1><%= title %></h1>
<p><%= paragraph %></p>

components/test.yml:

---
name: Test component
description: A simple component which displays a title and a paragraph.
doc: https://github.com/silexlabs/Silex/wiki/Create-Silex-components
category: Test
faIconClass: fa-square
props:
- name: title
  type: string
- name: paragraph
  type: string
  description: 'This is a help text for Silex UI'
  default: 'This is the default value'

Custom index.html to pass options to Silex client side app

Then you need to change the HTML which loads Silex, in order to pass options to Silex. There is a proper way to do this without altering the code of Silex, so that you can keep your changes when updating Silex for example.

Create a pug file called index.pug which will "extend" Silex index.html page:

extends ./node_modules/silex-website-builder/src/html/index.jade
append silex-options
  script.
    silex.config.componentFolders.push('components/')

In order to serve the new HTML page in place of Silex index.html, add this line before silex.start to your index.js (the file which creates the Silex server). It will also serve the dist/components folder

// serve modified html
const path = require('path');
const serveStatic = require('serve-static');
// this needs to be before silex.start
silex.app.use('/', serveStatic(path.resolve('./dist/')));

Build your project

Add necessary npm packages to your project with

$ npm install --save prodotype pug-cli serve-static

Add the pug build to your package.json in order to generate a new HTML page to serve Silex and the components

{
    "build": "npm run build:components && npm run build:html",
    "build:html": "pug index.pug -o dist/",
    "build:components": "prodotype components/ dist/components"
}

Note: if you need to build on windows, you will want to get rid of the && so either call both npm run build:html and then npm run build:components or read this article

Now you can do

$ npm run build

If you have any questions please get in touch with Silex issues

Now run npm start and open http://localhost:6805/, look for your component in the + menu

How to contribute components

Install Silex sources, see Silex Developer Guide

The components files live in src/prodotype/components/. Each component is made of an HTML template (.ejs file) and a description file in a markdown file (.md).

Components files are compiled with the command npm run build:prodotype

If you add components - thank you! Please make a pull request and after it is merged update the documentation wiki.

How to create components

Components are made of 2 files: a text file which describes its properties, and an HTML template which use the properties to render the component.

Links:

• The components included in Silex
• Prodotype, the tool used to "compile" the components

This is how it looks like when you add a component: