Flows allows three ways of working:

• CGI Scripts
• Flows Scripts
• Flows Applications

The first mode of operation has nothing to do with Flows at all but is very useful if you are porting code from a legacy site. It simply enables you to execute Python CGI scripts so we’ll look at that later in Porting Old Code.

Flows applications are a more sophisticated way of working with Flows so let’s start by look at flows scripts now.

Creating a New Site

Setting up the code

To create a new site you need to run two scripts which aren’t currently available online:

• make_repo.sh
• repo_make_site.sh

Then check out the code on your local machine.

If you want to build flows on top of this you need to add the following files and directories from the flow example, replacing anything generated by the scripts above, where necessary:

• dist
• code/cmd
• code/dynamic
• code/framework
• static/Templates
• static/favicon.ico
• static/index.html

Now get the virtualenv.py file and put it in deploy

Edit the setup.py file with the following dependencies:

"Flows",
"NestedRecord",
"RecordConvert",
"ConfigConvert",
"StringConvert",
"URLConvert",
"CommandTool",
"ConversionKit",
"BareNecessities",
"DreamweaverTemplate",
"HTTPKit",
"Mail",
"ErrorReport",
"ErrorDocument",
"CommandTool",

Alternatively take an existing project or the ExampleSite example.

However you’ve obtained your code, change the name in the setup() function to match the name of your package and rename the examplesite directory with the correct name.

Now run these commands and change any occurances as necessary:

grep -rl "ExampleSite" . | grep -v ".pyc"
grep -rl "examplesite" . | grep -v ".pyc"


grep -rl ExampleSite . | xargs perl -pi -w -e 's/ExampleSite/JimmygSite/g;'
grep -rl examplesite . | xargs perl -pi -w -e 's/examplesite/jimmygsite/g;'
find | grep "\.pyc$" | xargs rm

Finally, rename the folders in the deploy diretory to match your server and instance name.

Configuring your Instance

In the deploy directory:

• Copy the app.conf from the flows example
• Update the settings in the example app.conf file in particular: * app.package * mail.* * error_report.to
• Update the date in CHANGELOG.txt to accurately document the date the project was started

Now you are ready to create your environment. You’ll only have to jump through these hoops once.

cd deploy/ve3.fourier.3aims.com/example-staging
python ../../virtualenv.py env

Tip

A lot of the dependencies aren’t released yet so you’ll need.

hg clone https://hg.3aims.com/dolphin/Flows && \
hg clone https://hg.3aims.com/dolphin/Database && \
hg clone https://hg.3aims.com/dolphin/URLConvert && \
cd Flows/trunk && \
../../env/bin/python setup.py develop && \
cd ../../Database/trunk && \
../../env/bin/python setup.py develop && \
cd ../../URLConvert/trunk && \
../../env/bin/python setup.py develop && \
cd ../../

Now install your software:

cd ../../../code/trunk
mkdir ../../dist
../../deploy/ve3.fourier.3aims.com/example-staging/env/bin/python setup.py develop -f ../../dist/ # -zmaxd ../../dist/
cd ../../deploy/ve3.fourier.3aims.com/example-staging

This installs your application getting the .egg files it needs either from the dist directory or from the internet.

You can now always run your application from the isolated Python sandbox in deploy/ve3.fourier.3aims.com/example-staging/env/bin/python. Anytime you want to install extra software you should add it to the install_requires list in setup.py and then run the env/bin/python setup.py develop -f ../../dist/ command again.

You can now perform any setup tasks:

env/bin/python -m examplesite.cmd.run instance create app.conf

Start the server:

env/bin/python -m examplesite.cmd.run serve app.conf

WARNING:

• Make sure the path doesn’t contain any spaces, otherwise the virtual Python environment won’t work correctly.

Adding Database Support

See the Database package documentation.

Adding URLRouting Support

Just edit the dynamic/url.py file to add new rules. Then, using the area/hello directory as an example, add your new controllers and actions.

Adding FormBuild Support

Adding i18n

Create a i18n directory at the same level as cmd, dynamic, framework etc.

Install the Domain and Babel packages and add them to the list of requirements in setup.py.

First import DomainService in dynamic/service.py:

from domain import DomainService

Then add it to the list of available services:

available_services = dict(
    ...
    domain = DomainService
)
return available_services

If you want the service started for every request, add it in dyamic/dispatch.py to the end of the required_services list:

from flows.dispatch import make_dynamic_component

def on_load_component(flow):
    component = make_dynamic_component(
        flow,
        required_services = [
            'url',
            'http',
            'input',
            'domain',
        ]
    )
    return component

You can then follow the instructions associated with the DomainService class in the use of Babel.

Adding an API Extension

• Copy the ext directory to your app
• Add the api service to both dynamic/service.py and dynamic/dispatch.py
• Connect the api component by adding this to your config file:

app.auto_connect = api

api = APIService(config.app.package+’.api.data’),

Automatic Handling of Error Documents

Flows automatically replaces the response body with a custom page whenever any of the above status codes are used. To see an example error page, check the server is still running and then visit http://127.0.0.1:8000/this_does_not_exist and you will see the page for a 404 Not Found status.

You can also trigger error documents to be displayed by setting a status code in the application.

Let’s create a

Things not to do

• Change the working directory
• Execute print statements

Because If you visit

Since the

from flows.application import make_application

def on_load_application(flow):

#def app(envion, start_response): # start_response(‘200 OK’, [(‘Content-Type’, ‘text/plain’)]) # return str(flow)

#return app