Welcome to Lighthouse!

Lighthouse is a Pharo and Seaside demo application using the Bootstrap wrapper project and should help you designing an own custom web based application. It should give you some ideas how an application could be implemented and how you can adopt the dynamic development environment to suit your needs.

Download and Installation

Install into Pharo image

To install the application a Pharo 3.0 image is required. Just evaluate the following code in a workspace:

(Gofer new
    smalltalkhubUser: 'TorstenBergmann' project: 'Lighthouse';
    configurationOf: 'Lighthouse') load.

(Smalltalk at: #ConfigurationOfLighthouse) project development load.

This will install the application with all prerequisites (Seaside, Bootstrap, ...). After loading you can start the webserver either from the lighthouse menu "Webserver" -> "Start server" or by evaluating:

NUCServer start.

On Windows systems you alternatively evaluate

NUCServer browse

to open a browser.

Using a premade image

You can also download a demo image from the CI server at https://ci.inria.fr/pharo-contribution/job/Lighthouse Another option is to download the image from the Pharo launcher.

Demo

For now the primary focus is on providing a basic framework for own source code experiments. If you want to login on the application use the user admin and password as the password.

Introduction

Overall Architecture

The application consists of several code packages:

| Package name | Description | ---------------------- | -------------------------------------- | Lighthouse-Core | Core package with basic functionality | Lighthouse-Web | Web package for the web application | Lighthouse-Tools | Additional tools for Pharo

and test packages:

| Package name | Description | ---------------------- | -------------------------------------- | Lighthouse-Tests-Core | Test package for the basic functionality | Lighthouse-Tests-Web | Test package for the web application

Lighthouse as a Seaside application

First of all: Lighthouse is a regular web application using the Seaside web framework. The main entry point for the application is the class LHHome. This class is the regular Seaside root component and is registered programmatically in the LHServer(class)>>register method.

You can access lighthouse at http://localhost/lighthouse

Application parts

Server management

Lighthouse includes a class LHServer to take care of the webserver. You can start and stop the server either from the menu or by evaluating

NUCServer start

and

NUCServer stop

By default the port 80 is used making the application available at http://localhost/lighthouse If you need another port just run:

NUCServer stop.
NUCServer port: 9096.
NUCServer start.

which would run it on port 9096. http://localhost:9096/lighthouse

Usermanagement

The application includes an implementation of a simple user management that is used to maintain access to the application. You can use it as a template for own experiments. To get access to the usermanagement just have a look into category Lighthouse-Core-Model-Usermanagement within package Lighthouse-Core. There you will find a class LHUserManagement.

To get access to the default user management right from a workspace just inspect the following expression:

LHUserManagement default

Within the web application you can access this right from the session object:

self session usermanagement

Central part of a user management is a User identified by a user name which is also used as a login name. A user can login to the system.

A user is represented in the class LHUser.

Typically a user belongs to a specific user group, maybe he is a guest on the system or an administrator.

Secure password

As we have to deal with credentials for authentication and a password should stay as secure as possible all the passwords are hashed with a salt.

To convert a clear password into a secured one you should use:

LHUserManagement default securePassword: 'mysecurePassword'

which would return a hashed string ('A7BA1B952FACBF55EA06E9C84A026579835809A0' in this case)

Security Advice: If you want to use Lighthouse as a template for own applications you should change the method LHUserManagement(class)>>defaultSalt to return an own predefined salt. Also consider using HTTPS transfer protocol in deployment scenarios instead of HTTP communication. If not passwords will be sent in clear form over the wire and communication can be intercepted by a third party.

Internationalization (I18N)

If you want to provide an application that can be used in other countries you will have to think about internationalization. Depending on your requirements this can mean to deal with translations, different number formats, currencies, etc.

Browse translations

At a minimum an internationlized application includes a translated user interface where the output of message texts is dependent on the current language. Within Lighthouse there is a small tool window that displays all available translations of the application. Just go to the lighthouse menu and select "I18N Translations"

Providing translations

Lighthouse includes an own implementation purely in Smalltalk to do just that - have a look into category Lighthouse-Core-I18N within package Lighthouse-Core. There you will find a class LHTranslator.

It is important to look at the class comment of LHTranslator of this class as the class comment includes all the translations available and you can adopt and add your own.

LHTranslator defaultTranslator

Accessing translations

If you have access to a translator you can ask him to translate a specific term identified by a key:

LHTranslator defaultTranslator translationFor: #createAccount

which will return the string: 'Create an account'

As the LHTranslator class overrides the #doesNotUnderstand: message it is possible to send the translation keys as a usual unary message even when there is no appropriate method:

LHTranslator defaultTranslator createAccount

As you can guess the translator internally manages the translation keys and values within a dictionary:

LHTranslator defaultTranslator translationMap

Accessing different languages

If you need access to a particular translator you just access it using the ISO symbol:

"Return a german welcome message"
(LHTranslator forLanguage: 'DE') welcome

To see which languages are already included just evaluate:

LHTranslator languages

Accessing translations within the webapp

The lighthouse application already includes the translations as part of the framework and one can access the current translator directly from the session object using the #translator method.

renderWelcomeOn: html
    html heading: self translator welcome , '!'.

Testing with Devices

The Twitter Bootstrap library that is used for the Lighthouse project allows to develop for several device sizes - so you application should be usable on a desktop screen, a tablet device and a mobile device like a smartphone.

As part of the web package there is an utility class called LHDeviceCheckerHome which is registered as a seaside component and accessible on:

http://localhost/devicecheck

Here the Lighthouse application is shown in an iFrame and you have three buttons at the top: Desktop, Tablet and Mobile that you can use to change the width of the frame to simulate either a full width of 100% (Desktop), a width of 767px (Tablet) or a width of 480px for a mobile smartphone.

The Lighthouse Pharo project

Project repository

The project repository can be found on Smalltalkhub at http://smalltalkhub.com/#!/~TorstenBergmann/Lighthouse There you will also find the documentation and install instructions.

Code Contributions

The project is MIT licensed and accepts contributions. If you want to contribute just check that your contributed code is covered by automatic tests and keeps the projects test suite green.

Documentation

Documentation is done using Markup language. The documentation is a single document editet with http://stackedit.io and stored as a class comment on the Metacello configuration class ConfigurationOfLighthouse.

Some of the images withing the documentation are created using yuml.me

CI

To check periodic integration of code and assure that all unit tests stay green the project is watched by the Pharo contributions CI server.

Just visit the projects CI section on the Pharo contributions CI server.