You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
12 KiB
12 KiB
Minibase_Readme
Introduction
Minibase is a management tool for companies that need a high flexibility and manage interlaced projects.
In this Readme I will focus on the entry point and the structure of the main application. For more detailed information of each part you will find a separated Readme in each module template Static files etc...
Hope You enjow it
Knowledge required to deploy Minibase
The list can be scary for but if you don't want to make some changes, some basic python and web knowlegde would de sufficient.
The struture
The main overwiev how the file structure is organised. This Flask Application is using Blueprints for modularity purposes. In odrder to not overencoumber this docuemntation I will isolate each blueprint and the main app.
inibase/
├── docker-compose.yml "Docker compose file to start create an start the container"(optinal)
├── LICENSE
├── README.md
└── web
├── run.py "Entry point to the app ->" `python3 run.py`
├── Dockerfile "Docker file to containerize the application"(optinal)
├── requirments.txt "Python requirement."
└── minibase "Main App folder"
├── app.py "Main application called by" `../run.py`
├── config.py "Configurarion for Flask"
├── theme.py "My approach to make a semi interractive color sheme and navbar menus"
├── blueprints "Main Blueprint folder"
│ └── <Blueprint_Name> "Blueprint folder -> named as you like"
│ ├── forms.py "Definition of the forms to be used for the blueprint"
│ ├── models.py "Database models"
│ ├── routes.py "Routes for the html files and interractions for them"
│ ├── utils.py "Every Bluprint has it's functionalities coded here"
│ └── templates "Template folder for the current blueprint"
│ └── <Blueprint_Name> "Same as the blueprint name (this is a naming convention)"
│ └── <template>.html "Names of the HTML templates for this Blueprint"
├── static "Default location for Static files for the app"
│ ├── css "Here will be the CSS for Bootstrap and your own"
│ ├── img "Images as logos and icons"
│ ├── js "Here will be the JS for Bootstrap and your own"
│ └── pics "Pictures for users avatars etc.."
└── templates "Main Templates folder : for the entire app, Ex: base.html is here"
└── <template>.html "Names of the HTML templates for main app"
The Entry point and the main App
Building the virtual enviroment and running the app
I would make sense to start from the benninging! so we are int he minibase/web/ directory and working with run.py is our entry point and the one which will call minibase/app.py.
- To Sart you need to create a Python virtual envirement and activate it -> Instructions
- There is nothing special going on on the code, just creating and running the application -> Instructions
- PLease note that it still runs in debug
debug=Trueenviroment so please be careful if you are wiling to open it to the WWW.
from minibase.app import create_app
# Creation of the main app
flask_app = create_app()
# Running ht main app the flask app is configured at app.py with an external config.py file
if __name__ == '__main__':
flask_app.run(debug=True)
Main Application and initialisation
Here is where the magic starts, all the Blueprints and Modules comes together the form the main application. We will habve a look a app.py, config.py and theme.py. we Dont need any initial steps as they are taken care of from run.py
app.py
- Modules for the modules used here please refer to the links liusted at th beginning.
from flask import Flask
from flask_session import Session
from flask_sqlalchemy import SQLAlchemy
from flask_bcrypt import Bcrypt
from flask_login import LoginManager
from flask_mail import Mail
from flask_migrate import Migrate
from minibase.config import AppConfig
- Global declarations Code comments should suffice. In othe case write to me ;)
# (DATABASE) Definition
db = SQLAlchemy()
# (PASSWORD) Hashing Module to save paswords safely
bcrypt = Bcrypt()
# (LOGIN) Login manage plugin configuration
login_manager = LoginManager()
login_manager.login_view = 'users.login' # User management (current_user)
login_manager.login_message_category = 'info' # Boostrap Info Message
# (EMAIL AGENT) Definition
mail = Mail() # So that we can send mails
# (SESSION) Starts the curren flask session
session = Session()
- Definition and initialisation of the app.
def create_app():
# (APP) Definition
app = Flask(__name__)
# (APP) Configure configuration
app.config.from_object(AppConfig)
# (DATABASE) Initialisation
db.init_app(app)
# (PASSWORD) Initialisation
bcrypt.init_app(app)
# (LOGIN) Initialisation
login_manager.init_app(app)
# (EMAIL AGENT) Initialisation
mail.init_app(app)
# Session for variable manipulation on server side
# (DATABASE) Linking the app and the Database
Migrate(app, db)
- Blueprints being imported and registered. We will go deeper in Bluprints Afterward
NOTE: This is not an exaustive list of Blueprints just some exmaples to make it more understandable.
# (BLUEPRINTS) Importing the blueprints.
# Include are made here to awoid the Circular import issues
from minibase.blueprints.main.routes import main
from minibase.blueprints.user.routes import user
from minibase.blueprints.errors.routes import errors
# (BLUEPRINTS) Registering the blueprints.
# Giving them theie ulr_prefixes that will define their links on the webBrowser.
app.register_blueprint(main, url_prefix='/')
app.register_blueprint(user, url_prefix='/user')
app.register_blueprint(errors, url_prefix='/errors')
# (APP) Returning the initialised app
return app
Main Templates
Here you will find the what i call the Main templates, what do i mean by that ?
- Flask allows us to work with templates which are HTML files, in combination with Jinja2 template engine
- This means we can use some Python code in out HTML
- The most common practice is to define a Base template which defines the parts of our website that will stay the same. like the nav bar footer etc...
- have called it base.html Let's have a look and i guess you will understand it better
Base template
So as this is the base template which every other template will extend from, i have overly commented it.
{# #}are Jinja Comments and are not visible at the website source code<!-- --!>are HTML Comments and are visible at the website source code
base.html
- Here you can already see some interesting use of Jinja
- To add a Variable we use
{{ <varible> }} - To add a loop of a comparison we use :
{% <statement> %}
- To add a Variable we use
- The rest is Standart HTML
- So what is going on here :
<head>we define the HTML propoerties an reference our CSS stylesheets<title>{% block title %}Minibase{% endblock %}</title>We define the title with a default value | which will be overwritten if another html file has a<{% block title %}{% endblock %}block<body style="{{ theme.maineTheme.div_style }}">Here is a an example of how to use Varible in HTLM. Here I define the<body style=with a varibale tha is declared in theme.py.{% with messages = get_flashed_messages(with_categories=true) %}Here we do a check everytime that base.html is loaded to see if there is any messages to Flash. and show them dynamically wiht their appropriate categories. We will also see som examples in the future don't worry.{% block content %} {% endblock %}Same as for the title content there here will be inserted the content of each template
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no">
<!-- Referencing custom CSS stylesheet --!>
<link rel="stylesheet" type="text/css" href="/css/style.css"/>
<!-- Referencing Bootstrap CSS stylesheet --!>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
<!-- Referencing Favicon --!>
<link rel="shortcut icon" href="{{ url_for('static', filename='img/logo.png') }}">
{# Title Block : wit Minibase as defauls value : will be overwritten if anothe page has the same title block #}
<title>{% block title %}Minibase{% endblock %}</title>
</head>
{# Here You can see how we use variables in HTML code #}
<body style="{{ theme.maineTheme.div_style }}">
{# We can also include othe html files #}
{% include 'navbar.html' %}
<main>
{# This part will catch anny messages that we want to FLASH when something has been updated #}
{# Gets the messages with their respective categories #}
{% with messages = get_flashed_messages(with_categories=true) %}
{% if messages %} {# If there are messages present #}
{% for category, message in messages %} {# Get the message and his category #}
<div class="alert alert-{{ category }}">
{{ message }} {# Print it #}
</div>
{% endfor %}
{% endif %}
{% endwith %}
{% block content %}
{# Every extra template will be placed here for examplem login.htlm and so on #}
{% endblock %}
</main>
<!-- Incluting the scrips for bootstrap | Bootstrap 5 don't need jquery anymore -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
{% block scripts %}{% endblock %}
</body>
</html>
{# These are Jinja comments and will not be shown if someone was to look at the source code of this page contrary to the HTML comments#}