Full starting guide

You first need to install the requirements listed in Start a new website.

The Quick Start guide in Start a new website will do all this for you, but feel free to follow this instead if you want to understand how MagiCircles works in more details.

⚠️ Quick start is recommended over Full starting guide.

1. Pick a shortname for your website.

• Example: frgl for fr.gl.
• Everytime you see "sample" in the following instructions, replace it with this name.

2. Start a django project (the _project is important):

   django-admin startproject sample_project
   cd sample_project

3. Setup your local python working environment:

   virtualenv env
   source env/bin/activate

4. Create a file called requirements.txt and add MagiCircles as a requirement:

   git+https://github.com/SchoolIdolTomodachi/MagiCircles.git

5. Install the requirements:

   pip install -r requirements.txt

6. Create the app:

   python manage.py startapp sample

7. Edit sample_project/settings.py to specify your website name, add the following installed apps and middlewares, and some configuration:

   SITE = 'sample'
   
   INSTALLED_APPS = (
     ...
     'corsheaders',
     'bootstrapform',
     'bootstrap_form_horizontal',
     'rest_framework',
     'storages',
     'magi',
   )
   
   MIDDLEWARE_CLASSES = (
     ...
       'django.middleware.locale.LocaleMiddleware',
       'corsheaders.middleware.CorsMiddleware',
       'django.middleware.common.CommonMiddleware',
       'magi.middleware.languageFromPreferences.LanguageFromPreferenceMiddleWare',
       'magi.middleware.httpredirect.HttpRedirectMiddleware',
   )
   
   FAVORITE_CHARACTERS = []
   
   MAX_WIDTH = 1200
   MAX_HEIGHT = 1200
   MIN_WIDTH = 300
   MIN_HEIGHT = 300
   
   AUTHENTICATION_BACKENDS = ('magi.backends.AuthenticationBackend',)
   
   DEBUG_PORT = 8000
   
   from django.utils.translation import ugettext_lazy as _
   
   LANGUAGES = (
     ('en', _('English')),
     ('es', _('Spanish')),
     ('fr', _('French')),
     ('de', _('German')),
     ('it', _('Italian')),
     ('ru', _('Russian')),
   )
   
   LANGUAGE_CODE = 'en'
   
   LOCALE_PATHS = [
     os.path.join(BASE_DIR, 'magi/locale'),
   ]
   
   STATIC_UPLOADED_FILES_PREFIX = None
   
   CORS_ORIGIN_ALLOW_ALL = True
   CORS_URLS_REGEX = r'^/api/.*$'
   
   LOGIN_REDIRECT_URL = '/'
   LOG_EMAIL = 'emails-log@schoolido.lu'
   PASSWORD_EMAIL = 'password@schoolido.lu'
   AWS_SES_RETURN_PATH = 'contact@schoolido.lu'
   
   try:
       from generated_settings import *
   except ImportError, e:
       pass
   try:
       from local_settings import *
   except ImportError, e:
       pass
   
   INSTALLED_APPS = list(INSTALLED_APPS)
   INSTALLED_APPS.append(SITE)
   
   LOCALE_PATHS = list(LOCALE_PATHS)
   LOCALE_PATHS.append(os.path.join(BASE_DIR, SITE, 'locale'))
   
   if STATIC_UPLOADED_FILES_PREFIX is None:
       STATIC_UPLOADED_FILES_PREFIX = 'magi/static/uploaded/' if DEBUG else 'u/'

8. Include the URLs in sample_project/urls.py:

   urlpatterns = patterns('',
     url(r'^', include('magi.urls')),
     ...
   )

9. Create the file sample/settings.py that will describe how you want your website to look like:

   from django.conf import settings as django_settings
   from magi.default_settings import DEFAULT_ENABLED_COLLECTIONS, DEFAULT_ENABLED_PAGES
   from sample import models, forms
   
   SITE_NAME = 'Sample Website'
   SITE_URL = 'http://sample.com/'
   SITE_IMAGE = 'sample.png'
   DISQUS_SHORTNAME = 'sample'
   SITE_STATIC_URL = '//localhost:{}/'.format(django_settings.DEBUG_PORT) if django_settings.DEBUG else '//i.sample.com/'
   GAME_NAME = 'Sample Game'
   ACCOUNT_MODEL = models.Account
   COLOR = '#4a86e8'

10. Create a few images:

• Your logo in sample/static/img/sample.png
• The default avatar for your users in sample/static/img/avatar.png
• An illustration of the game in sample/static/img/game.png

11. Create a django model in sample/models.py that will contain the info about the users game accounts:

from django.contrib.auth.models import User
from django.utils.translation import ugettext_lazy as _
from django.db import models
from magi.item_model import MagiModel
from magi.abstract_models import BaseAccount

class Account(BaseAccount):
    class Meta:
        pass

Make this model available in your administration, edit sample/admin.py:

from django.contrib import admin
from sample import models

admin.site.register(models.Account)

15. Create the template to display an account in the leaderboard in sample/templates/items/accountItem.html (note: owner and owner.preferences in account item have been prefetched in the default queryset):

{% with account=item %}
<br>
<div class="well">
  <a href="{{ account.owner.item_url }}">
    <div class="row">
      <div class="col-md-2">{% include 'include/avatar.html' with av_user=account.owner av_size=30 av_image_size=100 %}</div>
      <div class="col-md-8"><h3>{{ account.owner.username }}</h3></div>
      <div class="col-md-2"><h3 class="text-right">{{ account.level }}</h3></div>
    </div>
  </a>
</div>
{% endwith %}

16. Create the template that will display the accounts under the users info in their profiles in sample/templates/accountsForProfile.html:

{% for item in profile_user.all_accounts %}
<div class="row"><div class="col-md-12">
  {% include 'items/defaultAccountItem.html' with without_link=True %}
</div></div>
{% endfor %}

In a real website, you would probably want to display the account differently in the context of the profile.

17. Create your LESS main file in sample/static/less/style.less:

 /* Uncomment these lines when you need to compile LESS -> CSS */
 // @import "../../../env/lib/python2.7/site-packages/magi/static/less/main.less";
 // @import "../../../env/lib/python2.7/site-packages/magi/static/less/mixins/magicircles.less";

 /* Comment these lines when you need to compile LESS -> CSS */
 @import "main.less";
 @import "mixins/magicircles.less";

 /******************************************/
 /* Variables */

 @mainColor: #4a86e8;
 @secondaryColor: #73c024;

 /******************************************/
 /* Tools */

 /******************************************/
 /* MagiCircles */

 html {
     .setup-sidebar(@mainColor);
     .magicircles(@mainColor, @secondaryColor);
 }

 @import "generated_colors.less";

 /******************************************/
 /* Single pages */

 /******************************************/
 /* MagiCollections */
 ```
You may customize the content depending on the page you're on using `.current-page` where page corresponds to the page name (example: `current-index`, `current-card_list`, ...).

18. Create your Javascript main file in `sample/static/js/main.js`:
```javascript
// Your functions or code that should load on all pages goes here.

19. Create your front-end dependencies file in bower.json:

{
  "name": "samplewebsite",
  "version": "0.0.0",
  "authors": [
    "db0company <db0company@gmail.com>"
  ],
  "description": "Database and community for Sample Game players.",
  "license": "Simple non code license (SNCL)",
  "dependencies": {
    "Autolinker.js": "0.15.2",
    "CuteForm": "~0.0.3",
    "bootstrap": "~3.3.5",
    "css-hexagon": "0.0.0",
    "github-wiki": "js-github-wiki#*",
    "jquery-visible": "1.2.0",
    "less": "~2.0.0",
    "navbar-variant": "~0.0.0",
    "jquery-easing": "*",
    "jquery-timeago": "timeago#^1.5.4"
  }
}

and the configuration file to specify the folder in .bowerrc:

{
    "directory": "sample/static/bower/"
}

20. Get the front-end dependencies:

npm install -g less bower
bower install
python manage.py generate_css

21. Initialize the models:

python manage.py makemigrations sample
python manage.py migrate

22. Set up your .gitignore:

env/
sample_project/local_settings.py
sample_project/generated_settings.py
sample/static/bower
sample/static/css/style.css
sample/templates/pages/map.html
sample/static/uploaded/
collected/
db.sqlite3

Those are in addition to usual python ignored files. You can get a basic .gitignore when you create a GitHub repository.

23. Test that the homepage works:

python manage.py runserver

Open http://localhost:8000/ in your browser

24. For next steps, follow the "Start coding!" section of Start a new website guide.