django-editorial-staff 0.8.0

A simple app to manage newsroom staff and hierarchy.

django-editorial-staff

django-editorial-staff is a simple Django app to store and manage editorial staffers, and the organizational hierarchy they work in.

It includes a robust API that other apps can treat as a "single source of truth" for users in the organization.

It also includes a "data provider" feature that will quickly and automatically ingest users' data from third-party services (and ships with a "data provider" for Slack organizations).

Quick start

1. Install this app:

    pip install django-editorial-staff
   

2. Add four entries (three helper apps and "editorial_staff") to your INSTALLED_APPS setting (in settings.py) like this:

   INSTALLED_APPS = [
       ...
       'bootstrap3',
       'colorfield',
       'rest_framework',
       ...
       'editorial_staff',
   ]
   

3. Add the following lines to your settings.py file (to configure form rendering):

    BOOTSTRAP3 = {
        'field_renderers': {
            'default': 'bootstrap3.renderers.FieldRenderer',
            'inline': 'bootstrap3.renderers.InlineFieldRenderer',
            'immaterial': 'editorial_staff.field_renderers.ImmaterialFieldRenderer',
        },
    }
   

4. Include the editorial_staff URLconf in your project urls.py like this:

   url(r'^staff/', include('editorial_staff.urls')),
   

5. Run python manage.py migrate to create the staff models.

6. Start the development server and visit http://127.0.0.1:8000/staff/ to see a list of staffers and add others.

7. Visit http://127.0.0.1:8000/staff/api/ to explore the app's REST API.

Configuration

Several included settings allow you to customize most aspects of django-editorial-staff.

Settings related to the "data provider" feature are discussed in the following section. The other available settings are:

Setting name	Default value	Description
EDITORIAL_STAFF_BASE_URL	'' (empty str)	Optional. The full URL of the server on which this app/project will live. Used to generate links sent via Slack.
EDITORIAL_STAFF_LOGOUT_URL	None	Optional. Named URL pattern of a view that logs users out. If blank, there won't be a log-out link included in the app-wide navigation.
EDITORIAL_STAFF_EMAIL_DOMAIN	'example.com'	Optional. The domain name at which most of your staffers receive email. Used mainly to generate the [e-mail] placeholder text on the staffer-creation form.
EDITORIAL_STAFF_API_NAME	'Staff API'	Optional. The branded name for the API generated by this app. Only shown on Django REST framework-generated pages. This is not very important; it's just included here as it's easy to pass this option down to REST framework.

Data provider configuration

django-editorial-staff's data providers are configured in two parts:

• With the EDITORIAL_STAFF_DATA_PROVIDER setting, a string that can containe the path to the provider being used (or None to use the app without a data provider), and

• With the EDITORIAL_STAFF_DATA_PROVIDER_OPTIONS setting, a dictionary of additional options for the chosen provider.

The second of these settings is intended to be flexible, with its dictionary containing attributes that are fairly unique to the active provider.

Currently the app only includes one provider ('editorial_staff.data_providers.SlackProvider'), which enables users to retrieve staffer data from a connected Slack workspace. This provider has two possible values that can be defined in EDITORIAL_STAFF_DATA_PROVIDER_OPTIONS:

• notification_channel, the name of the Slack channel where "new staffer created" announcements are posted, and
• excluded_email_domains, which prevents Slack user data from being imported into new staffer objects if a Slack user's email address domain is in this list.

NOTE: If EDITORIAL_STAFF_DATA_PROVIDER is set to None (or omitted from the settings.py file entirely), no provider will be connected.

Integrating with Slack

To start using the Slack data provider, follow the installation steps above, then do the following.

1. Install the following Slack-provider-specific dependencies:

   pip install probablepeople~=0.5.4
   pip install slacker~=0.9.0
   

2. Add the data-provider settings mentioned above to your settings.py file:

   ...
   EDITORIAL_STAFF_DATA_PROVIDER = 'editorial_staff.data_providers.SlackProvider'
   
   EDITORIAL_STAFF_DATA_PROVIDER_OPTIONS = {
       'notification_channel': 'staffer-announcements',  # Can also be omitted
   }
   ...
   

   (where staffer-announcements is the name of the channel you want to receive messages whenever a staffer is added).

3. Create an API token in your Slack workspace and add it to your settings.py file under the SLACK_TOKEN name.

Front-end development

django-editorial-staff front-end pages are built using ES6 and SCSS, and this app includes a Gulp installation that converts files written in these dialects to plain JavaScript and CSS, respectively.

When developing on the front-end, you'll need to run this Gulp installation yourself. Follow these steps to get started.

1. Open a terminal window and navigate to the root of this app.

2. Within the app, navigate to ./editorial_staff/staticapp.

3. If this is your first time running Gulp on this project, run npm install to install JS dependencies. This may take several minutes.

4. Once your dependencies are installed, run gulp to begin local development.

5. When your Gulp server says it's up and running, visit http://127.0.0.1:3000/staff/ for a live preview of your front-end files.

6. Proceed to modify your front-end interface by changing files in ./editorial_staff/staticapp/scss/ and ./editorial_staff/staticapp/js/. Your changes will be applied to the Gulp server URL without the need for to reload the page manually.