Thursday, February 28, 2013

EmeraldBox: My New Boilerplate Python Framework And A Mini Tutorial

I believe that developing web apps should be done in the easiest and most efficient ways. Python offers that. However, most of the available frameworks required a deep learning curve for new users and most users have problems deploying the web app.
After using several python web frameworks as well as using other languages' frameworks like Rails, Django, CodeIgniter and Zend over the years, I came to a conclusion that python is the easiest and most efficient language.
However, it will require tools that may speed up development. It that sense, Rails has a very good approach and will be implemented for the helper tools. Integration with 3rd party packages should also comes easily without having the need to interfere with the main OS, hence comes virtualenv.
Thus, comes EmeraldBox, an easy-to-use, light-weight, and easy-to-deploy framework.
EmeraldBox comes in a localized environment and includes standard packages that are commonly used in web development. The tool includes framework management tools and is designed to give ease for developers in managing database and migrations.
I initially develop the boilerplate framework based on a challenge from my boss at work. Can python be as good and as easy as Rails? Challenge accepted! I started doing research on best practice for Flask structures. Then I started getting into sqlalchemy as well since I think it is not that tightly coupled with the framework. Then I think of things that might be helpful for new users and will speed things up for more advanced users.
To see how easy it is to use EmeraldBox, see the tutorial below.

EmeraldBox Tutorial
Part 1: Setup
To start using EmeraldBox, download the package from the github source.
Extract the package wherever you want and get inside the EmeraldBox folder.
The package comes with 5 basic components:
  • Flask
  • Flask-SQLAlchemy
  • SQLAlchemy
  • SQLAlchemy-Migrate
  • Tornado Web Server
You can add the basic package to install by opening the config.py file and add the ADDITIONAL_PACKAGE list, i.e:
ADDITIONAL_PACKAGE = ['PIL','nose']
If you don't want to add any additional package just leave it as it is.
That's that, now open your command line and run the setup file
python setup.py
The setup will now run and install the pack in your virtual environment. Once the setup is done, try out the development server by typing
./box.py -t
or on windows
box\Scripts\python box.py -t
You should now see:

 * Running on http://127.0.0.1:5000/
 * Restarting with reloader
Head to http://localhost:5000 and you should see EmeraldBox welcome note there.
Please remember that the testrun.py is a development server and should not be use for production usage. 

To run the production server under tornado, simply type:
./box.py -s
or on windows
box\Scripts\python box.py -s

To run the production server under gunicorn, simply type:
./box.py -g
or on windows
box\Scripts\python box.py -g


Congratulations, your framework is ready to use.


Part 2: Usage
The best thing about EmeraldBox is the helper tools available. The tools help you to skip basic stuffs a framework needs and just go ahead and focus at things that matter more.

For this tutorial we will build a simple personal site application with a sort of a contact module inside it.
We will need the following views:
  • Home
  • About
  • Contact
I put the contact in the last part because it will need some sort of database and we will generate it later with a different tool.
Now let's build your first view.
To initiate a new view all you need to to from the command line is:
linux/unix
./box.py -i
windows
box\Scripts\python box.py -i 
So to build the home view, all you need to do is:


linux/unix
./box.py -i home
windows
box\Scripts\python box.py -i home
and your home view is generated.

You should see the following messages:

Controller generated
view file generated and available at \path\to\app\templates\home.html

Now, run your server and go to http://localhost:5000/home and you should see the basic home view. You can edit this view to your hearts content :D

Do the same thing for about view. These two pages will be the static content.

Now, let's head to the contact view. In this view, you will need database access to store the data. By default, EmeraldBox is configured to run with SQLite database. However, you can configure the connection with other database engine in the config.py file.

Now, what would you normally need in a blog? I'd say you'd need the following information:
  • Contact Name
  • Contact Email
  • Message
Let's make them with our tools:
linux/unix
./box.py -n contact contact_name:string contact_email:string message:text
windows
box\Scripts\python box.py -n 
contact contact_name:string contact_email:string message:text
 Simply copy-paste the lines above to your command line and you will see the following results:



...........

Generating model controller for JSON data access
JSON data controller added
Entries view controller added
Single entries view and controller added
Entries add form controller added
Entries creation controller added
Entries edit and update form controller added
Entries deletion controller added

Database creation completed
New migration saved as /path/to/app-root/db_repository/versions/001_migration.py
Current database version: 1
Please run box.py -m to complete the migration process 
That shows that the model is generated already.

Now, you would want your contact page to display only the contact form, right? Let's edit the codes a little bit now. Open app/main.py and you will see the following codes automatically generated from the commands we used above.
Now, let's edit line the contact controllers from line 50 up to 136.
First thing, we would want the contact add page to show up when you open /contact. To do so, let's change line 50's routing into the following
then change the line 82 into the following.
Now you have the right view when accessing those views.
However, the topbar is still not displaying all the required information and the home page is still not showing the home page we created. We can do this in two ways.
First, let's open the templates/base.html and edit it into the following:
Second, let's edit main.py on lines 19-27 into the following to make it correct:

Part 3: Running
Now that we have all those stuffs sorted, just run:

./box.py -t
or on windows
box\Scripts\python box.py -t
And voila! Your website is ready!

To access it simply open http://localhost:5000/
To see the sent contacts go to http://localhost:5000/contact/view-all

You can get EmeraldBox at https://github.com/femmerling/EmeraldBox

This example can be downloaded from https://github.com/femmerling/EmeraldBox-Web-Example

Happy coding then!

regards

-E-


2 comments:

  1. manggut2x..... emncoba memahami apa yang dikatakan om emfeld



    by cogendut

    ReplyDelete
  2. Why do you cut the jinja2 tmplt out of the loop, m8?
    Try flask.views instances--MethodView--and collect all app routing (url rule) in one single manageable page.

    ReplyDelete