Mini Documentation


EmeraldBox documentation is currently on going along with the development process. What you find in this page should be enough to keep you going.

Setup

You can get EmeraldBox using two ways:

        git clone https://github.com/femmerling/EmeraldBox.git

To get started with EmeraldBox, use terminal and go to the EmeraldBox root folder and run:

        python setup.py

The setup will then automatically download packages and adjusted your settings.

If you clone from git and want to control your project using git do the followings:

Change to the cloned EmeraldBox root directory

        cd [project_name]

Replace the remote address:

        git remote rm origin
        git remote add origin [new_remote like git@github.com:your_name/project_name.git]
        git commit -am "initial setup"
        git push origin master

Framework Structure

A typical EmeraldBox application comes with the following structure:

Root
        app/
                controllers/
                models/
                static/
                templates/
                __init__.py
                main.py
        box/
        db/
        db_repository/
        box.py
        config.py
        greeny.py
        helpers.py
        ignite.py
        setup.py
        testrun.py
        virtualenv.py

Structure info:

Usage

Framework generators and tools available. To see all the available the functions on unix/linux run:

        ./box.py -h

Or on windows:

        box\Scripts\python box.py -h

Automated database creation and controller tool available.

Run the following on unix/linux:

        ./box.py -n [Model Name] [field name]:[field type]--[field length (optional)]

Or on windows:

        box\Scripts\python -n [Model Name] [field name]:[field type]--[field length (optional)]

This will create an automated data management tool for Create, Read, Update and Delete using REST principles. You can access the tool at server_root/model_name. You can access the json data by adding the ?json=true at the end of the url. Your database will then be migrated and EmeraldBox will automatically create the tables in the database. This also creates a controller in your controller file for handling the JSON output of your model. Check app/main.py to see the result.

If you have your code and want to deploy it elsewhere, you can get the same database scheme automatically in the new server by running the database creation and migration tool.

On unix/linux simply run:

        ./box.py -c

Or on windows:         box\Scripts\python box.py -c

And your database will be created. Afterwards, on unix/linux run:

        ./box.py -m

Or on windows:

        box\Scripts\python box.py -m

This will migrate your database to the latest version and making it ready for use with your code.

You can also initiate your own controller in the controller file. On unix/linux simply run the following

        ./box.py -i [controller name]

Or on windows:

        box\Scripts\python box.py -i [controller name]

this controller initiation will also automatically generate a view file in your app/templates/ folder with your controller name as the file name.

Server and Deployment

As all python frameworks, EmeraldBox is dependent on WSGI. Worry not! EmeraldBox comes with the not 1 but 2 WSGI standalone server.

As of version 1.3, EmeraldBox comes with Tornado and Gunicorn.

You EmeraldBox package is a ready to deploy package and your app is ready to be published since instalation.

To run tornado web server on unix/linux:

        ./box.py -s

Or on windows:

        box\Scripts\python box.py -s

To run gunicorn web server on unix/linux:

        ./box.py -g

Or on windows:

        box\Scripts\python box.py -g

For gunicorn, the standard -g option will run gunicorn on the standard port as a daemon utilizing 4 tornado workers. You can add your own gunicorn options after -g but to change the port you have to change the it in the config.py.

The app will run at port 5000. You can change the port in the config.py file to any port you wish for. Just make sure that the port is available and does not conflict with other services.

We also provide a development server with debugging tools inside. Use it during development time to improve your work.

Run the development server on unix/linux using:

        ./box.py -t

Or on windows:

        box\Scripts\python box.py -t