Installation¶

Arpegio can be installed using pip:

pip install [--user] arpegio

Dependencies¶

Arpegio works with the following packages:

Python 2.7, 3.3+
Django >= 1.8, <1.11
Pillow >= 3.3.0
pytz

This packages are installed when using pip.

Applications¶

All the applications provided with Arpegio are optional. The only exception is core. To install the applications just add them to the INSTALLED_APPS section of your project’s settings.

INSTALLED_APPS = (
   ...
   'arpegio.core',
   #'arpegio.blog',
   #'arpegio.pages',
   #'arpegio.categories',
   #'arpegio.tags',
)

Context processors¶

Add the settings template context processor. This context processor passes information about the settings of the project to the templates. The settings defined with Arpegio are usefull for extending and customizing themes.

TEMPLATES = [
   {
      'BACKEND': 'django.template.backends.django.DjangoTemplates',
      'DIRS': [],
      'APP_DIRS': True,
      'OPTIONS': {
            'context_processors': [
               ...
               'arpegio.core.context_processors.settings',
            ],
      },
   },
]

URLs¶

The urlpatterns defined in Arpegio for testing purposes are the following:

urlpatterns = [
   url(r'^blog/', include('arpegio.blog.urls')),
   url(r'^pages/', include('arpegio.pages.urls')),
   url(r'^category/', include('arpegio.categories.urls')),
   url(r'^tags/', include('arpegio.tags.urls')),
]

The above urlpatterns are not defined in Arpegio because all the apps are optional. You can copy and paste the above code or prefix the urls used in your project individually.

Note

When using Django 1.8 you need to define the app name and namespace of the urls with include('path.to.urls', namespace='app', app_name='app').

For example, to include the blog app you need to include it with include('arpegio.blog.urls', namespace='blog', app_name='blog').

If you don’t set a namespace the url resolution methods will break.

Syncing the database¶

Arpegio is in alpha state and doesn’t include migrations. To sync the database you will need to run:

python manage.py makemigrations
python manage.py migrate

The migrations are going to be provided when reaching the beta state.

Arpegio’s settings¶

Arpegio uses a custom system to manage settings. To use it you have to include the following dictionary in your settings file:

ARPEGIO_SETTINGS = {
   'CATEGORY': {
      'Variable': {
         'value': 'Some value'
         }
      }
   }

The settings are passed to templates using the context variable arpegio and can be used like {{ arpegio.category.variable.value }}. Note that the keys are lowercased when they are processed.

This dictionary structure allows passing custom settings to the templates in a flexible way. You can easily include metada with the variables and pass information like this:

ARPEGIO_SETTINGS = {
   'GENERAL': {
      'Site_name': {
         'value': 'My site'}
   },
   'SOCIAL_MEDIA': {
      'Github': {
         'value': 'http://www.github.com',
         'css-class': 'github-link'
      },
      'Twitter': {
         'value': 'http://www.twitter.com'
         'css-class': 'twitter-link',
      },
      'Facebook': {
         'value': 'http://www.facebook.com'
         'css-class': 'facebook-link',
      }
   }
}

The settings can also be defined in reusable apps. Just add a settings.py file in your app’s folder and include the following code:

from arpegio.core.settings import site

settings = {'GENERAL': {'SITE_NAME':{'VALUE': 'App defined'}}}

site.register(settings)

Project settings take precedence over App settings. Using this workflow you can make reusable apps and override specific settings in your configuration file without touching the templates. This makes template inheritance even easier to work with and the site’s configurations are keept in a central file that can be versioned and/or forked.