Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
144 lines (98 sloc) 6.44 KB

Developing on Bedrock

Writing URL Patterns

URL patterns should be as strict as possible. It should begin with a ^ and end with /$ to make sure it only matches what you specifiy. It also forces a trailing slash. You should also give the URL a name so that other pages can reference it instead of hardcoding the URL. Example:

url(r'^channel/$', channel, name='mozorg.channel')

Bedrock comes with a handy shortcut to automate all of this:

from bedrock.mozorg.util import page
page('channel', 'mozorg/channel.html')

You don't even need to create a view. It will serve up the specified template at the given URL (the first parameter). You can also pass template data as keyword arguments:

page('channel', 'mozorg/channel.html',
latest_version=product_details.firefox_versions['LATEST_FIREFOX_VERSION'])

The variable latest_version will be available in the template.

Embedding images

Images should be included on pages using helper functions.

static()

For a simple image, the static() function is used to generate the image URL. For example:

<img src="{{ static('img/firefox/new/firefox-logo.png') }}" alt="Firefox" />

will output an image:

<img src="/media/img/firefox/new/firefox-logo.png" alt="Firefox">

high_res_img()

For images that include a high-resolution alternative for displays with a high pixel density, use the high_res_img() function:

high_res_img('firefox/new/firefox-logo.png', {'alt': 'Firefox', 'width': '200', 'height': '100'})

The high_res_img() function will automatically look for the image in the URL parameter suffixed with '-high-res', e.g. firefox/new/firefox-logo-high-res.png and switch to it if the display has high pixel density.

high_res_img() supports localized images by setting the 'l10n' parameter to True:

high_res_img('firefox/new/firefox-logo.png', {'l10n': True, 'alt': 'Firefox', 'width': '200', 'height': '100'})

When using localization, high_res_img() will look for images in the appropriate locale folder. In the above example, for the de locale, both standard and high-res versions of the image should be located at media/img/l10n/de/firefox/new/.

l10n_img()

Images that have translatable text can be handled with l10n_img():

<img src="{{ l10n_img('firefox/os/have-it-all/messages.jpg') }}" />

The images referenced by l10n_img() must exist in media/img/l10n/, so for above example, the images could include media/img/l10n/en-US/firefox/os/have-it-all/messages.jpg and media/img/l10n/es-ES/firefox/os/have-it-all/messages.jpg.

platform_img()

Finally, for outputting an image that differs depending on the platform being used, the platform_img() function will automatically display the image for the user's browser:

platform_img('firefox/new/browser.png', {'alt': 'Firefox screenshot'})

platform_img() will automatically look for the images browser-mac.png, browser-win.png, browser-linux.png, etc. Platform image also supports hi-res images by adding 'high-res': True to the list of optional attributes.

platform_img() supports localized images by setting the 'l10n' parameter to True:

platform_img('firefox/new/firefox-logo.png', {'l10n': True, 'alt': 'Firefox screenshot'})

When using localization, platform_img() will look for images in the appropriate locale folder. In the above example, for the es-ES locale, all platform versions of the image should be located at media/img/l10n/es-ES/firefox/new/.

Writing Views

You should rarely need to write a view for mozilla.org. Most pages are static and you should use the page expression documented above.

If you need to write a view and the page has a newsletter signup form in the footer (most do), make sure to handle this in your view. Bedrock comes with a function for doing this automatically:

from bedrock.mozorg.util import handle_newsletter
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def view(request):
    ctx = handle_newsletter(request)
    return l10n_utils.render(request, 'app/template.html', ctx)

You'll notice a few other things in there. You should use the l10n_utils.render function to render templates because it handles special l10n work for us. Since we're handling the newsletter form post, you also need the csrf_exempt decorator.

Make sure to namespace your templates by putting them in a directory named after your app, so instead of templates/template.html they would be in templates/blog/template.html if blog was the name of your app.

Coding Style Guides

Use the .open-sans, .open-sans-light and .open-sans-extrabold mixins to specify font families to allow using international fonts. See the :ref: CSS<l10n> section in the l10n doc for details.

Use the .font-size() mixin to generate root-relative font sizes. You can declare a font size in pixels and the mixin will convert it to an equivalent rem (root em) unit while also including the pixel value as a fallback for older browsers that don't support rem. This is preferable to declaring font sizes in either fixed units (px, pt, etc) or element-relative units (em, %). See this post by Jonathan Snook for more info.

When including CSS blocks, use {% block page_css %} for page specific inclusion of CSS. {% block site_css %} should only be touched in rare cases where base styles need to be overwritten.

Configuring your code editor

Bedrock includes an .editorconfig file in the root directory that you can use with your code editor to help maintain consistent coding styles. Please see editorconfig.org. for a list of supported editors and available plugins.