Welcome to petycja-norweskie’s documentation!¶
Contents:
Koncepcja aplikacji¶
Petycje są formą bezpośredniego uczestnictwa obywateli w procesie sprawowania władzy. Zostały przewidziane w art. 63 Konstytucji RP:
Każdy ma prawo składać petycje, wnioski i skargi w interesie publicznym, własnym lub innej osoby za jej zgodą do organów władzy publicznej oraz do organizacji i instytucji społecznych w związku z wykonywanymi przez nie zadaniami zleconymi z zakresu administracji publicznej. Tryb rozpatrywania petycji, wniosków i skarg określa ustawa.
Przedstawiony system został zrealizowany w celu zapewnienia możliwości gromadzenia podpisów pod takimi petycjami w postaci elektronicznej w sposób efektywny i atrakcyjny dla użytkownika, a tym samym skuteczny.
System został opracowany początkowo na potrzeby kampanii norweskie.org . Jednak opierał się na wcześniejszych doświadczeniach Stowarzyszenia Siec Obywatelska - Watchdog Polska między innymi z takimi kampaniami jak:
- NaszRzecznik.pl - kampania uruchomiona w 2015 roku celem wsparcia wyboru dr Adama Bodnara na funkcje Rzecznika Praw Obywatelskich - zakończona powodzeniem, w 2016 roku przekształcona w kampanie na rzecz obrony Rzecznika Praw Obywatelskich przed odwołaniem - zakończona powodzeniem,
Jawna kampania wyborcza
(wyłączona) - kampania uruchomiona w 2015 roku w związku z prezydencką kampanią wyborczą poświęcona presji na opublikowanie jeszcze przed wyborami prezydenckimi aktualizowanej informacji o otrzymanych przez partię w trakcie kampanii wyborczej darowiznach od osób fizycznych, która wywołała szeroką dyskusje o jawności kampanii wyborczej,Poprawka dla Fundacja Akademia Organizacji Obywatelskich
(wyłączona) - kampania przeprowadzona w 2015 roku na przeciwdziałaniu ustawowej poprawce o zakazie finansowania „promocji 1%” ze środków uzyskanych w ramach „mechanizmu 1%” - zakończona sukcesem,
Użycie i zasada działania¶
Korzystanie z aplikacji warto rozpocząć od stworzenia dedykowanego szablonu (zob. Dodawanie szablonu). Następnie dodania
kampanii (zob. Dodawanie kampanii), utworzenia petycji (zob. Petycje (petitions)). Zadaniem użytkowników strony będzie
utworzenie podpisów (zob. petycja_norweskie.petitions.models.Signature
).
Aplikacja została skonstruowana wokół kampanii (zob. Kampanie (campaigns)), która grupuje jedną lub więcej petycji (zob. Petycje (petitions)). Poszczególna petycja ma określony formularz, pola w nim, a także wymagane zgody. To w relacji z petycją znajduą się wszelkie składane podpisy.
Instalacja¶
Został opracowany playbook Ansible, który zapewnia uruchomienie aplikacji w środowisku developerskim. Przedstawia on także podstawowe kroki, które są konieczne do uruchomienia aplikacji. Dostępny jest on w pliku vagrant_provision_ansible.yaml
. Zalecane jest wykorzystanie przedstawionego playbooka wraz z środowiskiem wirtualizacyjnym Vagrant. Wówczas konfiguracja całego środowiska to:
$ vagrant up --provision
$ vagrant ssh -
vagrant@vagrant:/vagrant$ python manage.py runserver 0.0.0.0:8000
Następnie można przejśc w przeglądarce pod adres http://localhost:8000
.
Po zakończeniu pracy można wykonać w celu skasowania wirtualnej maszyny:
$ vagrant destroy
Alternatywnie w celu zaoszczędzenia pamięci RAM można ją wyłącznie uśpić:
$ vagrant suspend
Warto także zwrócić uwagę na polecenie zapewniające utworzenie użytkownika administracyjnego:
vagrant@vagrant:/vagrant$ python manage.py createsuperuser
Jeżeli zepsujesz sobie bazę danych wykonaj:
vagrant@vagrant:/vagrant$ sudo -H mysql 'drop database petycja_norweskie';
$ vagrant provision
Jeżeli chcesz skonfigurować maszynę od nowa wykonaj:
$ vagrant destroy -f && vagrant up --provision
Jeżeli chcesz upewnić się co do aktualności konfiguracji możesz wykonać:
$ vagrant provision
Wdrożenie¶
Wdrożenie aplikacji wymaga:
- dostępności Python>3.3 i menadżera pakietów
pip
, - skonfigurowania serwera baz danych MariaDB,
- wywołania serwera aplikacyjnego gunicorn,
- skonfigurowania serwera Nginx jako reverse-proxy w Gunicorn.
Ponadto konieczne jest ustawienie następujących zmiennych środowiskowych:
DJANGO_SECRET_KEY
- losowa i poufność wartość zgodnie z dokumentacją Django dla SECRET_KEY,DJANGO_SETTINGS_MODULE
o wartościconfig.settings.production
dla określenie pliku konfiguracyjnego wykorystanego po załadowaniu aplikacji,DJANGO_SENTRY_DSN
- adres Sentry DSN służacy do wskazania narzędzia monitoringu wyjątków,DJANGO_ADMIN_URL`
o wartości np. „admin/” dla określenia ścieżki panelu administracyjnego,CACHE_URL
o wartości zgodnej z django-environ dla ustawienia mechanizmu cache.
W środowisku Stowarzyszenie wdrożenie odbywa się z wykorzystaniem roli Ansible watchdogpolska.django
.
Testy¶
Testy automatyczne zostały oparte o wbudowane w Django mechanizmy. Dostał wykorzystany także domyślny „test runner”.
Automatyzacje testów różnych konfiguracji np. wersje zależności zapewnia tox
.
Aby wypisać dostępne środowiska należy wykonać:
tox -l
Wówczas możliwy jest wybór środowiska testów i wykonanie:
tox -e dj111-coveralls
Zostały wdrożone ciągłe testy integracyjne z wykorzystaniem TravisCI.
Kampanie (campaigns)¶
Założenia¶
Moduł zapewnia mechanizm budowania wielu kampanii w ramach indywidualnej instancji aplikacji. Pozwala to ograniczyć liczbę aplikacij, które będą uruchomione dla różnych kampanii. Dla uruchomienia dodatkowej instancji aplikacji konieczne jest zagwarantowanie, że
Każda kampania stanowi jedną lub więcej petycji (Petycje (petitions)).
Każda kampania może mieć skonfigurowany indywidualny wystrój, dzięki mechanizmowi szablonów (Szablony (themes)).
Mechanizm kampanii odpowiedzialny jest także za kontrolę dostępu. Umożliwia bowiem określenia użytkowników, którzy bez uprawnień administracyjnych mają możliwość zarządzania ankietami.
Dodawanie kampanii¶
Uruchomienie kampanii wymaga podjęcia następujących kroków:
- aktualizacja serwera WWW do obsługi nowej domeny
- aktualizacja dopuszczalnych adresów domenowych - zob. ALLOWED_HOSTS poprzez zmienną środowiskową
DJANGO_ALLOWED_HOSTS
- dodawania nowej strony - zob.
django.contrib.sites
- dodania kampanii w panelu administracyjnym - zob.
petycja_norweskie.campaigns.admin.CampaignAdmin
Architektura¶
Model¶
-
class
petycja_norweskie.campaigns.models.
Campaign
(id, created, modified, name, organizer, theme, site, site_title, site_subtitle, show_title)[źródło]¶ Parametry: - id (AutoField) – Id
- created (AutoCreatedField) – Utworzony
- modified (AutoLastModifiedField) – Zmodyfikowany
- name (CharField) – Nazwa
- organizer (CharField) – Osoba lub organizcja odpowiedzialna za organizacje kampanii
- theme_id (ForeignKey to
petycja_norweskie.themes.models.Theme
) – Theme - site_id (ForeignKey to
django.contrib.sites.models.Site
) – Strona użyta w kampanii - site_title (CharField) – Nazwa
- site_subtitle (CharField) – Podtytuł
- show_title (BooleanField) – Pokaż tytuł petycji
Panel administracyjny¶
Widoki¶
Fabryki¶
Petycje (petitions)¶
Założenia¶
Komponent zapewnia mechanizm petycji, a także gromadzenia pod nimi podpisów, co stanowi podstawowy cel funkcjonowania projektu. Każda petycja ma określoną kampanie (zob. Menu (menu) ).
Mechanizm petycji jest szeroko konfigurowalny zapewniając możliwość ukrycia każdego z pól formularzy, co umożliwia uwzględnienie specyfiki kampanii.
Ponadto jest przewidziana funkcjonalność pól zgód. W celu ich skorzystania należy pierw zdefiniować definicję zgody dla danej petycji. Można przy tym określić czy zgoda będzie wymagana, czy opcjonalna, a także wzajemną kolejność zgód w formularzu. Zapewnia to szerokie możliwości uzyskania zgód zgodnie z różnorodnymi potrzebami i wymogami prawa.
Zgromadzone podpisy możliwe są do wyeksportowania w szeregu formatach. Eksport obejmuje także informacje o udzielonych zgodach.
Architektura¶
Model¶
-
class
petycja_norweskie.petitions.models.
Permission
(id, definition, signature, value)[źródło]¶ Parametry: - id (AutoField) – Id
- definition_id (ForeignKey to
petycja_norweskie.petitions.models.PermissionDefinition
) – Definicja zgody - signature_id (ForeignKey to
petycja_norweskie.petitions.models.Signature
) – Podpis - value (BooleanField) – Wartość
-
class
petycja_norweskie.petitions.models.
PermissionDefinition
(id, petition, text, default, required, ordering)[źródło]¶ Parametry: - id (AutoField) – Id
- petition_id (ForeignKey to
petycja_norweskie.petitions.models.Petition
) – Petycja - text (TextField) – Text
- default (BooleanField) – Czy domyślnie zaznaczone?
- required (BooleanField) – Czy wymagane?
- ordering (PositiveSmallIntegerField) – Określ kolejność
-
class
petycja_norweskie.petitions.models.
Petition
(id, created, modified, campaign, name, slug, title, text, overview, finish_message, ask_first_name, ask_second_name, ask_organization, ask_city, ask_email, first_name_label, second_name_label, organization_label, city_label, email_label, sign_button_text, paginate_by, is_published, is_active, front, disabled_warning, disabled_message)[źródło]¶ Parametry: - id (AutoField) – Id
- created (AutoCreatedField) – Utworzony
- modified (AutoLastModifiedField) – Zmodyfikowany
- campaign_id (ForeignKey to
petycja_norweskie.campaigns.models.Campaign
) – Kampania - name (CharField) – Nazwa
- slug (CharField) – Zmodyfikuj, aby zmienić adres petycji
- title (CharField) – Tytuł
- text (TextField) – Treść
- overview (TextField) – Zwarte omówienie przedmiotu petycji zachęcające do podpisania petycji.
- finish_message (TextField) – Wiadomość pokazywana po podpisach
- ask_first_name (BooleanField) – Zapytaj o imię
- ask_second_name (BooleanField) – Zapytaj o nazwisko
- ask_organization (BooleanField) – Zapytaj o organizacje
- ask_city (BooleanField) – Zapytaj o miasto
- ask_email (BooleanField) – Zapytaj o e-mail
- first_name_label (CharField) – Etykieta pola imienia
- second_name_label (CharField) – Etykieta pola nazwiska
- organization_label (CharField) – Etykieta pola nazwy organizacji
- city_label (CharField) – Etykieta pola miejscowości
- email_label (CharField) – Etykieta pola adresu e-mail
- sign_button_text (CharField) – Etykieta przycisku zgłoszeniowego
- paginate_by (SmallIntegerField) – Określa liczbę podpisów na jednej podstronie z listą podpisów
- is_published (BooleanField) – Opublikowane na stronie?
- is_active (BooleanField) – Otwarte na nowe podpisy?
- front (BooleanField) – Tutaj powinna być jedna dostępna strona
- disabled_warning (TextField) – Wiadomość, gdy ktoś próbuje wprowadzić podpis, pomimo wyłączenia formularza.
- disabled_message (TextField) – Wiadomość zamieszczona na stronie, jeśli możliwość składania podpisów została wyłączona.
-
class
petycja_norweskie.petitions.models.
Signature
(id, created, modified, petition, first_name, second_name, organization, city, email, counter)[źródło]¶ Parametry: - id (AutoField) – Id
- created (AutoCreatedField) – Utworzony
- modified (AutoLastModifiedField) – Zmodyfikowany
- petition_id (ForeignKey to
petycja_norweskie.petitions.models.Petition
) – Petycja - first_name (CharField) – Imię
- second_name (CharField) – Nazwisko
- organization (CharField) – Organizacja
- city (CharField) – Miejscowość
- email (EmailField) – Adres e-mail
- counter (SmallIntegerField) – Numer
Formularze¶
Panel administracyjny¶
Widoki¶
Fabryki¶
Szablony (themes)¶
Założenia¶
Komponent określa szablony i ich parametry, które są możliwe podczas konfiguracji kampanii.
Szczególną rolę pełni pole Theme.prefix
, gdyż określa dopuszczalne wartości.
Każdy szablon winien zapewniać następujące pliki szablonów Django:
$ find $(find -type d -name 'norweskie') -type f
./petycja_norweskie/templates/norweskie/base.html
./petycja_norweskie/petitions/templates/petitions/norweskie/field_custom.html
./petycja_norweskie/petitions/templates/petitions/norweskie/signature_form.html
./petycja_norweskie/petitions/templates/petitions/norweskie/signature_list.html
./petycja_norweskie/petitions/templates/petitions/norweskie/petition_success.html
./petycja_norweskie/petitions/templates/petitions/norweskie/petition_detail.html
W wskazanym przykładzie «norweskie» stanowi odpowiedni prefix.
Dodawanie szablonu¶
W przypadku dodania nowego szablonu należy wykonać:
python manage.py makemigrations themes --empty --name "add theme {{prefix}}"
W nowoutworzonym pliku wstawić treść zgodnie z szablonem:
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
from django.db import migrations
def update_theme_forward(apps, schema_editor):
Theme = apps.get_model('themes', 'Theme')
Theme.objects.update_or_create(
prefix="norweskie",
defaults={
'name': 'Niezależne fundusze norweskie',
'description': '',
'authorship': 'Kamil Breguła (mik-laj)'
}
)
class Migration(migrations.Migration):
dependencies = [
('themes', '0001_initial'),
]
operations =
migrations.RunPython(update_theme_forward)
]
Warto także w niniejszej dokumentacji zamieścić podgląd.
Architektura¶
Model¶
-
class
petycja_norweskie.themes.models.
Theme
(id, created, modified, name, description, authorship, prefix)[źródło]¶ Parametry: - id (AutoField) – Id
- created (AutoCreatedField) – Utworzony
- modified (AutoLastModifiedField) – Zmodyfikowany
- name (CharField) – Nazwa
- description (TextField) – Nazwa
- authorship (CharField) – Autorstwo
- prefix (CharField) – Systemowa nazwa prefiksu szablonu