Tutorials

← Previous: Introduction

Welcome!

... And thanks for joining Circles as a developer. The goal of this tutorial is to help you get started on a MagiCircles-powered website, wether it just started or you're joining an existing site as a developer.

Here are a few things you need to know before you get started:

• MagiCircles sites aim to be both databases and communities

  • Database:
    • Pages that provide details about what the site covers. Example: idols, cards Those are made using what's called Collections, and they're likely the main thing you'll be working on, which is why most of the tutorial is about them!
    • Wiki pages allow to more freely talk about a subject, with things like game guides and stories.
  • Communities:
    • Sites come shipped with a full-featured social network feed where users can post photos and tag their adventures!
    • To keep the community active, staff members regularly organize community events where users are challenged to post something they created, and can sometimes even win prizes.
  • Staff:
    • To manage, run and grow these sites, we need humans! That's why all sites have their own staff teams, and each staff member have a role that fits into what MagiCircles wants to provide. Check the list of staff & contributors roles!
  • And more!
    • A lot of features come pre-made with the framework, saving you a ton of time. Once you set up your site, make sure you click everywhere to discover all the features and pages.

• MagiCircles sites are available in many languages!

  We're proud to make our sites accessible by providing translations in many languages.

  Translations fall into 2 categories:

  • Ⓐ Translations of all the websites' interfaces (ex: "Home", "Search", "Profile", ...)

    Whenever you write text in English that's meant to be visible by users, it can't be a simple "string" in your code. It needs to be a "translated string". Translated strings use a special _ shortcut, like this:

    # Don't ❌
    title = 'Cards'
    # Do ✅
    from magi.utils import _
    title = _('Cards')

    Whenever you're about to "introduce" a new term, keep in mind that hundreds of translators will be involved in translating it, so you shouldn't take it lightly. Some things to consider:

    • Check if the word already exists in the existing translated terms (see translators guide to access our translation tool). If it doesn't, consider using another word that's already there.
    • Consider using variables inside your translations to reduce the number of sentences. For example:

      # Don't ❌
      message5m  = _('You were 5 minutes late.')
      message10m = _('You were 10 minutes late.')
      # Do ✅
      message5m = __(_('You were {total} minutes late'), total=5)
      message10m = __(_('You were {total} minutes late'), total=10)

    • Check Translations utils to see what else is available

  • Ⓑ Translations of content in the database for a specific website (ex: Card names, Idols hobbies, ...)

    Those are saved directly in the database! When you design your MagiModel, make sure you make all relevant fields translatable. See Translate fields values in multiple languages to learn more.

• Coding style and readability

  You'll likely be working with other developers, so make sure that before you submit your first pull request, you read the Coding style!

Ready? 💪 Let's dive in! 🚀

ℹ️ To use this tutorial, make sure you always read what's in "Content" before moving on to the "Next" section.

↓ Content

1. Collections
2. Single pages
3. Configuring the navbar

→ Next: References