Merge branch 'features/course-template' into 'master'

Open sourcing project

See merge request !7

README.md

@@ -1,94 +1,29 @@
 # Classroom Admin
 
-This application enables to create Google Classrooms in bulk from a CSV file.
+This application enables to create Google Classrooms in bulk from a CSV file when you are using the Google Apps suite for your organization.
 
-![Classroom Admin Screenshot](classroom_admin_screenshot.png)
-
-## Configuration
-
-Some setup is needed to allow you to create courses and to send emails according to your taste. This configuration allows you to choose values of your CSV file and to format some fields.
-
-Two configuration files templates are available in `conf/`. Simply copy and rename them without `.template` to enable them.
-
-Please see below for details about the configuration values:
-
-### Course
-
-Choose here the values needed among you CSV column names to create a classroom course.
-
-```
-ownerId: Owner's email or ID
-name: Course name
-section-format: Section template
-section-values: Values for section template
-teacher: Teacher email or ID
-member-email-domain: Email domain of only students
-```
-
-### Email
-
-Choose here the values to access in your CSV file and in the `course` object returned by the Google API: https://developers.google.com/classroom/reference/rest/v1/courses#Course
+The problem encountered by the [Web School Factory](https://www.webschoolfactory.fr/) Staff was that they had to create
+each Google Classroom and add each student to it manually. They had to do it every year for each class. This is quite a repetitive task.
 
-**Warning: You should not name your CSV columns with the same name as the keys of the `course` object. It will be overriden.**
+So, we developed Classroom Admin which allows the staff of a school to create all classrooms and affect to them students all in one stretch.
 
+In order to use the software, the Staff has to prepare CSV (or Excel) files with the list of all courses
+with for each of them the email of the teacher and the mailing list of the students.
+Then, they only need to upload it into the Classroom Admin interface and click on the "Create courses" button. And voilà! Each Google Classroom will be created with students automatically added to it and the teachers will receive an email with all the information they need to manage their classroom.
 
-```
-to: Email to send to
-subject-format: Subject template
-subject-value: Value to use in subject template
-content-value: Values to be used in content template
-content-format: Content template
-```
+In case some teacher tells you something like *"Where is my Google Classroom? I don't know where I have to put my classroom materials!"*, there is also a feature which allows you to resend the email with all the information for given courses. You just need to upload the right CSV file, select the courses for which you want to resend and click on "Resend manually emails".
 
-## Installation
+This feature has also been added for technical reasons because Gmail can't guarantee that all emails are sent accordingly and you may need to resend the emails in case Gmail has not been able to process everything.
 
-Software Requirements:
-  - Docker 1.11.2
-  - Docker Compose 1.7.1
-
-To install these on Ubuntu 16.04 follow [this tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-16-04) and execute [these two command-lines](https://github.com/docker/compose/releases/tag/1.7.1)
-
-API Requirements:
-  - Admin SDK API enabled
-  - Gmail API enabled
-  - Google Classroom API enabled
-  - Client ID for Web Server
-
-To get your client ID, go on [Google's Console API](https://console.developers.google.com/apis/) and follow the wizard.
-
-Once the requirements installed, simply clone this directory, add your Google API secret and launch docker-compose.
-
-Clone the repository:
-``` Server
-git clone https://github.com/KillianKemps/ClassroomAdmin
-```
-
-Copy your Google client ID from your computer to the server under the name `client_secret.json`
-``` Computer
-scp client_secret.json username@your-server-address:~/ClassroomAdmin
-```
-
-Launch the app in background
-```
-cd ClassroomAdmin
-docker-compose up -d
-```
-
-The app is then accessible either at `http://localhost` or at the hostname
+![Classroom Admin Screenshot](classroom_admin_screenshot.png)
 
-## Tests
+## Documentation
 
-If you want to run tests because you want to contribute do following:
+- [Installation](docs/INSTALLATION.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Developers](docs/DEVELOPERS.md)
+- [License](LICENSE.md)
 
-Install development environment
-```
-virtualenv venv
-source venv/bin/activate
-pip install -r requirements.txt
-pip install -r requirements-dev.txt
-```
+Made by a student of the [Web School Factory](https://www.webschoolfactory.fr/).
 
-Run tests
-```
-make test
-```
+[!["Web School Factory"](webschoolfactory_0.png)](https://www.webschoolfactory.fr/)

classroom_admin/conf/course.template.yaml

@@ -1,9 +1,10 @@
 ownerId: Owner
 name: Name
-section-format: '{0} - {1} - {2}'
 section-values:
   - Year
   - Domain
   - Promotion
+section-format: '{0} - {1} - {2}'
 teacher: Teacher Email
+students: Students email
 member-email-domain: '@my-school.com'

classroom_admin/conf/email.template.yaml

@@ -1,16 +1,23 @@
 to: to_email
-subject-format: 'Subject: {0}'
 subject-value: course
+subject-format: 'Subject: {0}'
 content-value:
   - Surname
   - Name
   - alternateLink
+  - enrollmentCode
+  - Teacher Email
 content-format:
   >
     <html>
     <p>Hello {0} {1},</p>
 
-    <p>You can access the created course at {2]</p>
+    <p>You can access the created course at {2}</p>
+
+    <p>You can also give access to the students by giving them the following enrollment code: {3}</p>
+
+    <p><span style="font-weight:bold; color:red">CAUTION,</span> this interface is only accessible through the email the school gave you: {4}</p>
 
+    <p>The School team</p>
     </html>
 

classroom_admin/templates/courses.html

@@ -42,13 +42,13 @@
     <thead>
       <tr>
         <th>Index</th>
-        <th>Cours</th>
-        <th>Mail wsf de l'intervenant</th>
-        <th>Liste de diffusion</th>
-        <th>Promotion</th>
-        <th>Année scolaire</th>
-        <th>Domaine</th>
-        <th>Sélectionner tout:
+        <th>{{ conf['name'] }}</th>
+        <th>{{ conf['teacher'] }}</th>
+        <th>{{ conf['students'] }}</th>
+        {% for section in conf['section-values'] %}
+          <th>{{ section }}</th>
+        {% endfor %}
+        <th>
           <label class="form-checkbox" v-on:change="setAllCheckboxes">
             <input type="checkbox"/>
             <i class="form-icon"></i>
@@ -60,12 +60,12 @@
       {% for course in courses %}
         <tr>
           <td>{{ loop.index - 1 }}.</td>
-          <td>{{ course['Cours'] }}</td>
-          <td>{{ course['Mail wsf de l\'intervenant'] }}</td>
-          <td>{{ course['Liste de diffusion'] }}</td>
-          <td>{{ course['Promotion'] }}</td>
-          <td>{{ course['Année scolaire'] }}</td>
-          <td>{{ course['Domaine'] }}</td>
+          <td>{{ course[conf['name']] }}</td>
+          <td>{{ course[conf['teacher']] }}</td>
+          <td>{{ course[conf['students']] }}</td>
+        {% for section in conf['section-values'] %}
+          <td>{{ course[section] }}</td>
+        {% endfor %}
           <td>
             <label class="form-checkbox" v-on:change="add">
               <input type="checkbox" class="course" data-index="{{loop.index}}"/>

classroom_admin/views/index.py

@@ -25,7 +25,9 @@ def index():
             with open(filename) as csvfile:
                 reader = csv.DictReader(csvfile)
                 try:
-                    return render_template('courses.html', courses=reader)
+                    return render_template('courses.html',
+                                           courses=reader,
+                                           conf=app.config['COURSE_CONF'])
                 except Exception:
                     error_message = "Some characters in the file are not in " \
                         "UTF-8. Please check your file and remove non-unicode " \

classroom_admin/views/upload.py

@@ -19,14 +19,14 @@ def upload():
         if not os.path.exists(app.config['UPLOAD_FOLDER']):
             os.makedirs(app.config['UPLOAD_FOLDER'])
 
-        # Move the file form the temporal folder to
-        # the upload folder we setup
+        # Move the file from the temporary folder to
+        # the upload folder we have setup
         file.save(os.path.join(app.config['UPLOAD_FOLDER'], 'courses_list.csv'))
 
         print('New file uploaded')
         app.logger.info('New file uploaded')
         # Redirect the user to the uploaded_file route, which
         # will basicaly show on the browser the uploaded file
         return flask.redirect(flask.url_for('index'))
-
-
+    else:
+        return flask.redirect(flask.url_for('index'))

docs/CONFIGURATION.md

@@ -0,0 +1,137 @@
+## Configuration
+
+Some setup is needed to allow you to create courses and to send emails according to your taste. This configuration allows you to choose values of your CSV file and to format some fields.
+
+**This is needed because the Classroom Admin application needs to know which fields to use from your CSV file and how to use them.**
+
+You can see an example of CSV file in the [example](example/courses.csv) folder.
+
+Two configuration files templates are available in `conf/`. Simply copy and rename them without `.template` to enable them.
+
+Please see below for details about the configuration values:
+
+### Course
+
+A Google Classroom needs the following fields to be created:
+1. OwnerId
+2. Name
+3. Section
+4. Teacher
+5. Students email
+
+You will need to **map** the following fields with your CSV file column names
+
+For the `section-values` field you will need to give a list of your CSV file column names.
+
+And you will need to format these values in the `section-format` field using
+them with the `{x}` syntax where `x` is the value position in the list.
+
+```
+ownerId: Owner's email or ID
+name: Course name
+section-values: Values for section template
+section-format: Section template
+teacher: Teacher email or ID
+member-email-domain: Email domain of only students
+```
+
+*Example of a course template:*
+```
+ownerId: Owner
+name: Name
+section-values:
+  - Year
+  - Domain
+  - Promotion
+section-format: '{0} - {1} - {2}'
+teacher: Teacher Email
+students: Students email
+member-email-domain: '@my-school.com'
+```
+
+*Which will create this kind of courses:*
+```
+Name: 'Math'
+Owner: '[email protected]'
+Section: '2017 - Science - Promotion 2018'
+Teacher: '[email protected]'
+Students: '[email protected]'
+```
+
+### Email
+
+To send a Gmail email, we need the following fields:
+1. To (address to send to)
+2. Subject (subject of the email)
+3. Content (content of the email)
+
+You will need to map the following fields with fields you have in your CSV file.
+
+You may also want to use fields given by Google in the `course` object returned by the Google API: https://developers.google.com/classroom/reference/rest/v1/courses#Course
+
+**Warning: You should not name your CSV columns with the same name as the keys of the `course` object. It will be overriden.**
+
+
+In the fields finishing with `-value` you will need to give a list of your CSV fields to be used and values given by Google's API.
+In the fields finishing with `-format` you will format the values given previously by naming them with `{x}` where `x` is the value position in the list.
+```
+to: Email to send to
+subject-value: Value to use in subject template
+subject-format: Subject template
+content-value: Values to be used in content template
+content-format: Content template
+```
+
+*Example of an email template:*
+```
+to: Teacher Email
+subject-value: Course Name
+subject-format: 'Subject: {0}'
+content-value:
+  - Surname
+  - Name
+  - alternateLink
+  - enrollmentCode
+  - Teacher Email
+content-format:
+  >
+    <html>
+    <p>Hello {0} {1},</p>
+
+    <p>You can access the created course at {2}</p>
+
+    <p>You can also give access to the students by giving them the following enrollment code: {3}</p>
+
+    <p><span style="font-weight:bold; color:red">CAUTION,</span> this interface is only accessible through the email the school gave you: {4}</p>
+
+    <p>The School team</p>
+    </html>
+```
+Where the following values may be given from your CSV file:
+  - Teacher Email
+  - Course Name
+  - Surname
+  - Name
+
+And where the following values are given by Google's API:
+  - alternateLink
+  - enrollmentCode
+
+*Which may send this kind of email:*
+```
+To: [email protected]
+Subject: Subject: Math
+Content:
+  >
+    <html>
+    <p>Hello John Doe,</p>
+
+    <p>You can access the created course at https://classroom.google.com/fake-classroom</p>
+
+    <p>You can also give access to the students by giving them the following enrollment code: 0123abc</p>
+
+    <p><span style="font-weight:bold; color:red">CAUTION,</span> this interface is only accessible through the email the school gave you: [email protected]</p>
+
+    <p>The School team</p>
+    </html>
+```

docs/DEVELOPERS.md

@@ -0,0 +1,17 @@
+## Tests
+
+You are a developer and want to contribute?
+If you want to run tests do the following:
+
+Install the development environment
+```
+virtualenv venv
+source venv/bin/activate
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+Run tests
+```
+make test
+```