e_components

Overview

The e_components main purpose is to provide the possibility of widening the scope of Erlang Web functionalities without modification of the 3 (or, in case of scalable EW 4 (eptic_fe)) core applications. Each of the e_components is a separate Erlang application, which has the following attributes:

the source code - since Erlang Web is the Open Source project, we should accept only open solutions
the documentation - e_component should contain the clear documentation which covers the basic usability, all the features, API (edoc?) and the examples

Adding the e_components to the project

User attach the e_component into the existing project built on top of Erlang Web by specifying its name and configuration in the project.conf file.

If you are building target systems with systools, you should add the e_components as included_applications in the .app file of one of your ordinary applications, and also add them to the .rel file.

Example

User wants to add two e_components to his environment. First one is wpart_rss with no configuration parameters and the latter is the ew_backup with the parameters describing the backup frequency and the backups destination directory.

The part of the project.conf dealing with e_components registration should look like:

...
{ecomponents, [{wpart_rss, []},
               {ew_backup, [{frequency, {12, hour}},
                            {output_directory, "backups"}]}}.
...

Implementing the e_component

As it was mentioned before, the e_component must be an Erlang application. Since the other than OTP dependency and configuration manager is used, it is strongly recommended not to provide the mod clause in the .app file. Instead of doing that, all the actions which should be performed during the e_component start should be moved to the install/1 function.

e_component behavior

The following functions are mandatory for the e_component implementation:

install(Configuration) - does all the necessary actions to set up the environment for the new e_component (like registering itself to the wpart supervisor (or other one), creating the ets tables and so on). The argument it takes - Configuration - is the list of the parameters specified in the project.conf file.
uninstall(Configuration) - called during the e_component removal process. The configuration is the same as in the install/1 function case.
dependecies() - returns a list of the dependencies - the e_components which are required for this e_component to run. The list should be in format:
```
 [{EcomponentName, {MinVersion, MaxVersion}}]
```
where MinVersion and MaxVersion could be either a number or an undefined atom (to indicate the given version does not matter).

Example

The example of the e_mnesia_auth e_component, which requires the e_auth e_component at least in version 1.2:

...
install(Config) ->
  TblName = proplists:get_value(table_name, Config),

  Spec = {?MODULE, {?MODULE, start_link, [TblName]}, 
          permanent, 2000, worker, [?MODULE]},
  supervisor:start_child(wpart, Spec).

uninstall(_Config) ->
   case supervisor:terminate_child(wpart, ?MODULE) of
    ok ->
        supervisor:delete_child(wpart, ?MODULE);
    Else ->
        Else
   end.

dependencies() ->
   [{e_auth, {1.2, undefined}}].
...

e_components repository

In order to make the e_components usage easier there is an e_component repository set up and the installation script attached. Each of the e_component stored in the repository is described by the following parameters:

name
version
author
description
category

The installation script usage:

bin/e_component.erl list - lists all the e_components stored in the repository
bin/e_component.erl search Keyword - searches for the e_component containing Keyword in its name or description
bin/e_component.erl details Name - writes out the details about the given e_component
bin/e_component.erl install Name - installs the e_component in the current directory
bin/e_component.erl path Path install Name - installs the e_component in the selected Path

The possible extensions of the script are:

installing the e_component globally
uninstalling the e_component

The repository address is http://ecomponents.erlang-web.org

The second script is named e_component_uploader.erl and will be available only for contributors. Its only duty is to login to submit new components on the server so they will be available for download. Of course, there is a basic authentication implemented, so it will not be possible for anonymous people to mess up in the repository.

The usage is as follows:

bin/e_component_uploader.erl add Path - creates a tar.gz file and uploads it to the server. User is prompted for its credentials during the phase. The mandatory information is read from the .app file of the application.

Available e_components

So far, the following e_components have been implemented:

e_auth - basic authentication interface
e_auth_dets - e_auth DETS authentication implementation
ew_backup - mnesia backup utility
wpart_erlsyntax - wpart responsible for Erlang code highlighting
wpart_rss - generic RSS feed generator