Create Silex components

This document is a work in progress, we need your help, ask questions in the issues and add info here please

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

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 a simple component example. Below your will find more info about how to create components.

test.ejs:

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

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'

Add the components to Silex

Copy your component to Silex components folder: node_modules/silex-website-builder/src/prodotype/components/.

Rebuild components:

$ cd node_modules/silex-website-builder/
$ npm run build:components

This will add your component to node_modules/silex-website-builder/dist/prodotype/components/components.json and make it available in the "+" menu of Silex.

Now run npm start in your project (created from How To Add Silex To Your Node.js Project) and open http://localhost:6805/.

Make things right

Now that it works, you need to cleanup all this. You are not supposed to write in the node_modules folder. If you do, when you update Silex, you will loose all your changes.

Create a folder named components/ in your project. Move your component's 2 files to this folder. Add this to your package.json:

{
  "build": "cp components/* node_modules/silex-website-builder/src/prodotype/components/ && cd node_modules/silex-website-builder/ && npm run build:components"

Now you can do

$ npm run build
$ npm start

To build and add your component(s) to your Silex instance. Just open http://localhost:6805/ to test it/them.

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: