Development/Server Coding Style
MusicBrainz Server Coding Style
Perl Modules
- Use tabs, not spaces.
- Name references to the current object
$self
, not$this
. - In Catalyst controllers, the Catalyst context should be stored in
$c
. - Use words separated by underscores for function/method names. The server currently uses CamelCase, but I'd propose to change this to match perlstyle and most existing Perl modules.
Controllers
Authentication
If an action in your controller requires the user to be logged in, you should add this action to the list of private pages in musicbrainz.yml
(located in the root directory of your source code) - following the current format. The path like syntax can be found by looking at the controller listing in the Catalyst development server, but in general takes the form CONTROLLER/ACTION
(so MusicBrainz::Server::Controller::Foo::bar
would be entered as foo/bar
).
By taking this approach, you will not need to handle redirection. If you need more fine grained control (ie, you do not know whether the user should be logged in until you have data), here is a snippet which you can use to seamlessly implement login redirection:
if (!$c->user_exists) { $c->flash->{login_redirect} = $c->uri_for($c->action, $c->req->args); $c->response->redirect($c->uri_for('/user/login')); $c->detach }
TT2 Templates
When working with templates, in general try and be as concise as possible. If you find yourself doing a lot of logic, you should seek to abstract this out into a template component (more on these below) - or move the logic to the controller action; filing a bug on the bug tracker if you don't want to do this yourself.
Forms
I've tried to make working with forms as easy as possible, and there are 2 options. I have noticed we have 2 types of forms, which I'll call generic and custom. A generic form has labels on the left and inputs on the right (ie, login, artist edit, pretty much all of our forms). Custom forms impose no such restrictions, and allow you to layout the form however you want.
When working with any form, use the forms/form.tt
wrapper. This wrapper sets up the <form>
tags for you, along with providing the user information regarding any general errors and which fields are mandatory. By default the form is setup as a generic form, however if you pass the custom=1
option to the wrapper, no formatting will be done for you.
Once you have opened a form wrapper you are ready to begin your form. To add a widget to the form with a label (textbox, combo-box, etc) - you should INCLUDE
the forms/widget.tt
component. forms/widget.tt
requires the following options:
- widget: The field in the form that you wish to display. You will often fetch this by using
form.field('field-name')
. - label: The label of this field.
You should then finish your form with forms/submit.tt
, providing the text for the button with the label
parameter.
Below is a simple example form. For an example of a more complicated custom form, see the user preferences form
[% WRAPPER "forms/form.tt" %] [% INCLUDE "forms/widget.tt" widget=form.fields('name') label="Full Name:" %] [% INCLUDE "forms/submit.tt" label="Save Name" %] [% END %]
CSS
- TODO
JavaScript
- TODO
ServerDevelopment