Development/Server Coding Style: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
((Imported from MoinMoin))
(How to access User Preferences (Imported from MoinMoin))
Line 48: Line 48:
[% END %]
[% END %]
</pre>
</pre>

===User Preferences===

To test for a setting being on: <pre>[% IF c.user.preferences.get('preference') %]
</pre>

To test for a setting being off: <pre>[% IF !(c.user.preferences.get('preference')) %]
</pre>

where preference is whatever the preference's variable is in the perl files below.

To add a preference setting, add it to:
<ul><li style="list-style-type:none">/root/user/preferences.tt /lib/[[User Preference|UserPreference]].pm /lib/[[MusicBrainz]]/Server/Form/User/Preferences.pm
</ul>


==CSS==
==CSS==

Revision as of 22:57, 9 February 2009

  • Alert.png Status: This page is work in progress and has very questionable content :)

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 %]

User Preferences

To test for a setting being on:

[% IF c.user.preferences.get('preference') %]

To test for a setting being off:

[% IF !(c.user.preferences.get('preference')) %]

where preference is whatever the preference's variable is in the perl files below.

To add a preference setting, add it to:

CSS

  • TODO

JavaScript

How to add Guess Case and the Edit Suite to any template:

Step 1

Template before:

[% extra_js = "switch.js switchcontrols.js " %]
[% WRAPPER 'layout.tt' title=l('Add Release') %]

Template after:

[% extra_js = "switch.js switchcontrols.js " %]
[% guessCase=1 undoRedo=1 searchReplace=1 trackParser=1 styleGuidelines=1 %]
[% PROCESS 'editsuite/suitereqs.tt' %]
[% WRAPPER 'layout.tt' title=l('Add Release') %]

Note that this order is important. You can add other lines in-between, if you would like, but the two Edit Suite lines must be after the extra_js line, and before the layout.tt line.

In the above options, the (implied) SET line determines which modules you want to have loaded within that form - leave any out, and the HTML and JS won't even be inicluded; == smaller page to load. (ie, no need for TP on the "add artist" form)

Example:

[% guessCase=1 undoRedo=1 searchReplace=1 styleGuidelines=1 %]

Will load those 4 modules, but not the track parser.

The Edit Suite Settings panel is always available, if the user has it turned on in User Preferences. It does not need to be turned on in the above manner within the template code.

Keep in mind that if you want Guess Case on a form, even if you leave out every other module, you still need to include the Guess Case module:

[% guessCase=1 %]

Step 2

Put

[% INCLUDE 'editsuite/suiteloader.tt' %]

whereever you want the Edit Suite to be inserted into the form.

Step 3

Now, add hooks to the form fields so the various Edit Suite modules know what fields to work on.

All you need to do in your form is add a class to the fields. There are three field types: Artist, Title, and Time.

For Track Artist or Release Artist, add class es-artist to the INCLUDE for the input field. For Track Title or Release Title, add class es-title to the INCLUDE for the input field. For Track Time, add class es-time to the INCLUDE for the input field.

If you want to have a Guess All button on the form, add es=1 to the INCLUDE for the form.

Caution on Step 3

For each of es-artist, es-title, and es-time, you *can* leave out one or more of the three. You can have the add artist form with just class es-artist and no es-title or es-time.

However, when you have more than one of these fields in your form, such as on the Add Release form, make sure that each is assigned to each field, ie, don't give class es-artist to the release artist and all track artists, but give class es-title only to the track titles, and not the release artist. Otherwise, you will break track parser functionality.

Step 4

There is no spoon, nor is there a step 4. It really is that easy now to add the Edit Suite and Guess Case functionality.  :)


ServerDevelopment