This part of the documentation provides a first steps guide for quickly setting up an application with ViUR. For a detailed introduction visit the ViUR Documentation.
The Vi can be access at https://lotus-creative-studio.de/vi.
The Vi after setting up a scratch project.
On the first startup, ViUR creates an new admin-user named admin@lotus-viur3.appspot.com with a random password within the database. This password is printed to the server debug console, where you have to copy it out.
Watch out for a line like this:
ViUR created a new admin-user for you! Username: admin@lotus-viur3.appspot.com, Password: SU7juUIb1F2aZ
When the system is started in the cloud for the first time, an e-mail with this password is sent to all application administrators.
Alternatively, you can login with a simulated Google user. Both login forms are provided by the default server and can be done using the Vi.
The default renderer in ViUR is html, which is a binding to the powerful Jinja2 template engine to generate HTML output. Jinja2 is used because it has a powerful inheritance mechanism, build-in control structures and can easily be extended to custom functions. Please refer to the Jinja2 documentation to get an detailed overview about its features and handling. Any template files related to the jinja2 renderer are located in the folder html/ within the project structure.
Templates usually take advantage of inheritance, which includes a single base template that defines the basic structure of all subsequent child templates. You use the tags {% extends %} and {% block %} to implement inheritance.
The use case for this is simple: as your application grows, and you continue adding new templates, you will need to keep common code (like a HTML navigation bar, Javascript libraries, CSS stylesheets, and so forth) in sync, which can be a lot of work. Using inheritance, we can move those common pieces to a parent/base template so that we can create or edit such code once and all child templates will inherent that code.
Let's create the base (or parent) template html/base_viur.html
<!DOCTYPE html>
<html>
<head>
<title>Base Project</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link href="static/css/style.css" rel="stylesheet">
</head>
<body>
<div class="container">
<h1>This is part of my base template</h1>
<article class="content">
{% block content %}
{% endblock %}
</article>
<h2>This is part of my base template</h2>
</div>
<script src="static/js/app.js"></script>
</body>
</html>
Open the file html/index.html. This file is basically called when you open https://lotus-creative-studio.de. Let's take a more closely look.
{% extends "viur_base.html" %} this includes the site template
{% block content %} individual content for the index site
<h1>Hello World!</h1>
{% endblock content %}
The {% extends %} informs the template engine that this template extands another template, html/viur_base.html. The {% block %} tags defines a block that child templates can fill in, so the (empty) content block in the html/viur_base.html will be replaced by the "Hello World".
Use some variables to print often used strings.
{% set question = "What is a dog?" %}
{% set answer = "An animal." %}
<strong>{{ question }}</strong> - {{ answer }}
You should see:
What is a dog? - An animal.
Translations are provided in the applications translations module in form of a dict, where the keys should be the language strings in the project’s major language (usually english), and the values the strings provided in the particular language implemented. The translation key strings must be given in a lower-case order, altought they may be capitalized or upper-case written. If no key is found within a specific translation, it is directly used as the output string.
In this simple example, a file translations/de.py is implemented with the content:
de = {
"welcome to viur": u"Willkommen in ViUR",
"hello {{user}}!": u"Hallo, {{user}}!"
}
Print this out in a Jinja2-template:
{{ _( "Hello {{user}}!", user="John Doe" ) }} - {{ _( "Welcome to ViUR" ) }}
This will output “Hello John Doe! - Welcome to ViUR” in an english-configured language environment, and “Hallo John Doe! - Willkommen in ViUR” in a german-configured language environment.
First we have to define the data model of this module, the skeleton. Each skeleton are made of bones, they represent a data field.
So, Let's define the Skeleton for our example, it would be stored in skeletons/person.py.
#-*- coding: utf-8 -*- from server.skeleton import Skeleton from server.bones import * class personSkel(Skeleton): name = stringBone(descr="Name") age = numericBone(descr="Age")
The bones key, creationdate, changedate will be automatically added by ViUR.
To connect the Skeleton personSkel defined above with a module implementing a list, put the following few lines in modules/person.py.
modules/person.py #-*- coding: utf-8 -*- from server.prototypes import List class Person(List): pass
Let’s create two simple HTML templates to render the list of persons and to show one person entry. First, the listing template is stored in html/person_list.html.
{% extends "viur_base.html" %}
{% block content %}
<h1>Persons</h1>
<ul>
{% for skel in skellist %}
<li>
<a href="/person/view/{{skel['key']}}">{{skel['name']}}</a> is {{skel['age']}} year{{"s" if skel['age'] != 1 }} old
</li>
{% endfor %}
</ul>
{% endblock %}
Then, the single entry viewing template is stored as html/person_view.html.
{% extends "viur_base.html" %}
{% block content %}
<h1>{{skel['name']}}</h1>
<strong>Entity:</strong> {{skel['key']}}<br>
<strong>Age:</strong> {{skel['age']}}<br>
<strong>Created at: </strong> {{skel["creationdate"].strftime("%Y-%m-%d %H:%M")}}<br>
<strong>Modified at: </strong> {{skel["changedate"].strftime("%Y-%m-%d %H:%M")}}
{% endblock %}
To connect the Person module from above with these templates, we have to adjust our modules/person.py:
#-*- coding: utf-8 -*-
from server.prototypes import List
class Person(List):
viewTemplate = "person_view" # Name of the template to view one entry
listTemplate = "person_list" # Name of the template to list entries
def listFilter(self, filter):
return filter # everyone can see everything!
That's all, we created our first module. But how to call these templates now from the frontend? Requests to a ViUR application are performed by a clear and persistent format of how the resulting URLs are made up. By requesting https://lotus-creative-studio.de/person/list on our ViUR system.