Introduction
Welcome to the Empress guide on creating and managing Empress Apps. This guide will offer a deep dive into the technical functionalities, advantages, and the integration process of Empress Apps.
Introduction to Empress Apps
A Empress App is a Python package that uses the Empress framework. This app resides in a directory named apps inside the frappe-bench directory. The default app frappe acts as the framework for all the apps, and every Empress App must have an entry in apps.txt.
Creating a Empress App
Empress provides a boilerplate for creating a new app. To create a new app, you need to run the following command from the frappe-bench directory:
$ bench new-app custom_app
Upon execution, this command creates a new custom_app directory inside the apps directory. Additionally, it adds the app to the apps.txt file.
Understanding the App Directory Structure
The directory structure of a Empress App is as follows:
apps/custom_app
├── MANIFEST.in
├── README.md
├── custom_app
│ ├── __init__.py
│ ├── config
│ │ ├── __init__.py
│ │ ├── desktop.py
│ │ └── docs.py
│ ├── custom_app
│ │ └── __init__.py
│ ├── hooks.py
│ ├── modules.txt
│ ├── patches.txt
│ ├── public
│ │ ├── css
│ │ └── js
│ ├── templates
│ │ ├── __init__.py
│ │ └── includes
│ └── www
├── custom_app.egg-info
│ ├── PKG-INFO
│ ├── SOURCES.txt
│ ├── dependency_links.txt
│ ├── not-zip-safe
│ ├── requires.txt
│ └── top_level.txt
├── license.txt
├── requirements.txt
├── dev-requirements.txt
├── package.json
└── setup.py
Let’s delve into understanding what each file and directory does:
requirements.txt
This file stores the list of Python dependencies for the app. When you install the app, its dependencies are also installed.
dev-requirements.txt
This is an optional file that stores the list of Python development dependencies. If developer mode is enabled, installing the app will also install its development dependencies.
package.json
This file maintains the list of Node.js dependencies for the app.
custom_app
This directory stores the source files of the Empress app.
custom_app/hooks.py
This is the file where you can hook into Empress events and extend or override standard behavior.
custom_app/modules.txt
Every Empress app is organized into different modules. Every DocType is part of a module. These modules are listed in this file.
custom_app/patches.txt
This file stores references to patches that run in database migrations. These patches are run only once, and in the order they are listed.
custom_app/public
The public folder is a static folder. It is used to store static assets used directly in the client side like JS, CSS, and images.
custom_app/templates
The templates folder is used to write and manage Jinja templates.
custom_app/www
Files in this directory are directly mapped to portal pages and the URLs match the directory structure.
Installing a Empress App into a Site
To use a Empress App, you must install it on a site. Installing an app on a site means creating the models that are bundled with the app into the site, which in turn creates database tables in the site database.
To install an app onto a site, run the following command:
$ bench --site site_name install-app custom_app
After the installation, you can verify if the app was installed correctly by running:
$ bench --site site_name list-apps
You should see the name of your app in the list of installed apps.
Conclusion
The ability to create and manage Empress apps offers developers an avenue to create powerful, customized applications using the Empress framework. By understanding the structure, creation, and management of Empress Apps, developers can leverage this feature to develop and customize business solutions in Empress.