Writing templates for Comas::HTML ================================= Comas::HTML was written using the HTML::Template mechanism for separating logic (the Perl modules) and layout (the templates themselves). Please refer to HTML::Template's documentation for details on how variables, conditionals and loops can be used, as well as to Comas::HTML's documentation (specifically, to the new_template method of Comas::HTML) for further details on how are templates called by default from within Comas. The templates should be located in the directory specified by the 'tmpl_path' key in the configuration. You don't need to use each of the template variables, they are specified in order for you to be _able_ to use them ;-) We know this documentation might not be as clear as it should... Please, if you have an idea on how to improve it, don't hesitate on contacting us. In this document, you will find at the start of each section/paragraph a filename - that is the name of the template that must be created inside the template path defined in the configuration file. You should be able to find examples included together with this package - This document will be of most use if you refer to the provided example templates. General recomendations ---------------------- You can create a header and a footer to be applied to each of the template files by adding '' at the top and '' at the bottom of each of your templates (or either of them). In your header, you probably will want to include a .css (cascading style sheet) file. This will make your system look more consistent and provide a single point for managing the style. Conventions ----------- Most templates will carry some similar data, so instead of repeating them all over, we list them all together here. DIRECT DATABASE FIELDS: Some fields are just representations for what we have in the database. They will have the name of the fieldname, preceded by a hyphen (-fieldname - eg., -title). For the database fields that are indexed into a catalog, you will usually have -fieldname for the field's description (i.e. the corresponding string), -fieldname_id for the numerical ID and -fieldname_list for a the contents of a selectbox with all the possible id<->value pairings. Of course, you will not always use them all. LOOPS AND CONDITIONALS: Labaled as such inside the description for each template file. VALIDATION INFORMATION: Many templates can include the has_missing field as a conditional, showing there is one or more required fields which has not been filled up. When applicable, another conditional (has_invalid) can be used to report that one or more fields contains invalid data. Besides, for the required fields, you can use fieldname_missing as a conditional to report that a specific fieldname is missing, and fieldname_invalid to report that a specific fieldname has invalid data. IF THE FORM IS POSTED: To know if a formf has been posted (i.e. to validate it) we use a hidden field called 'validate' with a true value ('1' is a good candidate). General template files ---------------------- main_menu.tmpl: Main Comas menu for regular users. We suggest providing in it links to /comas/attendees/new, comas/attendees/account, comas/attendees/proposals, possibly comas/attendees/recover_password. Gets no template variables. Links to the different public parts of the system (just described) Information publicly available ------------------------------ general/proposals_general_list.tmpl: General proposal list. Shows all the proposals. Direct database fields: -prop_type_list, -prop_status_list, -track_list. Variables: -number_of_proposals: Number of proposals listed Loops: proposals: A loop for each of the proposals. Includes the Direct database fields -id, -prop_status_id, -prop_status, -prop_type_id, -prop_type, -title, -track_id, -track. Contains as well: Loops: authors: A loop for each of the authors for this proposal. Contains the direct database fields -famname and -firstname. Links to: comas/general/proposals (this same page) specifying some filters, in order to implement searching for specific criteria comas/general/proposals/ (being a number): shows the complete information for the proposal whose ID is . general/proposals_details.tmpl: Details for a specific proposal. Direct database fields: -abstract, -prop_status, -prop_type, -title, -track Loops: authors: We loop over here for each of the authors Direct database fields: -firstname, -famname, -org, -resume Links to: Nowhere Attendee's personal data ------------------------ attendees/login.tmpl: Ask for login/password in order to enter the system. Direct database fields: -login, -passwd Variables: unknown_user: Conditional. The system reported the specified user is unknown or the password is invalid. Links to: comas/attendees/account, posting login and password comas/attendees/recover_password, for help recovering lost passwords attendees/menu.tmpl: Main menu for managing attendee's information. The variables in this template are to inform the user of the result of the actions carried out in the previous step leading to this page. All the variables here are conditional. Direct database fields: -firstname, -famname Variables: passwd_changed: The user's password was successfully changed data_changed: The user's personal data was successfully changed author_data_changed: Author information (i.e. number/order of talks) has been successfully updated proposal_new: A new proposal has been registered proposal_too_late: It is too late to submit a new proposal, it was not registered. too_many_proposals_for_you: One author submitted too many proposals. can_submit_proposal: Conditional. True if the attendee can currently submit a proposal. days_for_submitting: The number of days left until new submissions are no longer accepted. This variable is only set if can_submit_proposal is true. Links to: comas/attendees/account/data: Edit the personal data comas/attendees/account/passwd: Modify the password comas/attendees/account/proposals/new: Register a new proposal comas/attendees/account/proposals/list: Manage the proposals sent by this person attendees/new.tmpl: Register a new person in the system. This template will usually show up blank, but in case there is a problem with any of the data, the user will be presented this same tempalate again, with the values he originally filled in. Direct database fields: -login, -passwd, -passwd2, -firstname, -famname, -nickname, -org, -postal_addr, -zip, -city, -state_id, -state_list, -country_id, -country_list, -phone, -fax, -dept, -title, -studies_id, -studies_list, -email, -person_type_id, -person_type_list Variables: -b_day, -b_day_list, -b_month, -b_month_list, -b_year and -b_year_list map to the database field 'birth'. diferent_password: Conditional. Supplied password does not match confirmation password login_used: The selected login has already been used Links to: comas/attendees/new attendees/data.tmpl: Check/modify your personal information Direct database fields: -city, -country_id, -country_list, -dept, -email, -fax, -firstname, -nickname, -org, -person_type, -person_type_list, -phone, -postal_addr, -state_id, -state_list, -studies_id, -studies_list, -title, -zip Variables: -b_day, -b_day_list, -b_month, -b_month_list, -b_year and -b_year_list map to the database field 'birth'. has_invalid: Conditional. Whether to show a message indicating a field has an invalid value. has_missing: Conditional. Whether to show a message indicating a required field is missing. Links to: comas/attendees/account - Back to the main attendee's main page (only suggested, no action taken here) comas/attendees/account/data - Back to this same page, with the values set by the user specified as parameters (form destination, not link target) attendees/passwd.tmpl: Allows a person to change their password. Variables: diferent_passwd: The supplied new password and the confirmation do not match bad_current_passwd: The supplied current password is incorrect -current_passwd: The current user password -new_passwd: The desired new password -new_passwd2: The confirmation for the new password Links to: comas/attendees/account/passwd comas/attendees/account attendees/recover_passwd.tmpl: Help the user recovering a lost/forgotten password. The user needs to fill in his login and email address. If we have that login/email relation registered, we send them the password by email. Direct database fields: -login, -email Variables: password_recovered: The password has been sent to the specified mail address unknown_user: The supplied login is unknown or does not match the mail address Links to: comas/attendees/account - Present the user login comas/attendees/recover_passwd - Link back to this same space, posting the user-supplied data Author tasks (including proposal managenent) -------------------------------------------- attendees/authors/data.tmpl: Asks for the person data specific to authors (currently, only the resume/curricular brief). Direct database fields: -resume Links to: comas/attendees/account/authors/data attendees/authors/authors_edit.tmpl: Add, manage or remove authors for a given proposal Direct database fields: -id (person.id), -login Variables: All of the following variables are conditionals. login_empty: No username was provided login_dont_exist: The requested user login does not exist author_already_added: The requested user was already marked as an author too_many_proposals: The specified user has reached the maximum number of contributions per person and cannot be added. too_many_authors: The proposal has reached the limit of authors, no new authors can be specified cant_add_author_proposal_accepted: The proposal's status is marked as accepted, no authors can be added once it is accepted. author_added: The specified person was successfully added cant_delete_author_proposal_accepted: The proposal's status is marked as accepted, no authors can be deleted once it is accepted. author_deleted: The specified person was deleted from the authors list cant_move_author_proposal_accepted: The proposal's status is marked as accepted, author order cannot be changed once it is accepted. bad_position: Incorrect position requested, must be a positive integer author_moved: The author was successfully moved to the requested position Loops: authors: Direct database fields: -mention_order, -firstname, -famname, -email, -prop_id, -author_id Links to: comas/attendees/account/proposals/authors//add: Add the specified person as an author comas/attendees/account/proposals/authors//move/: Move the specified person's mention order comas/attendees/account/proposals/authors/: Delete the specified person as an author for the proposal attendees/authors/proposals_delete.tmpl: Asks for confirmation before deleting a proposal Direct database fields: -id (proposal.id), -title Links to: comas/attendees/account/proposals/delete/: Confirm deletion attendees/authors/proposals_edit.tmpl: Modify the information for a proposal Direct database fields: -id (proposal.id), -title, -comments, -abstract, -prop_status_id, -prop_status_list, -track_id, -track_list, -prop_type_id, -prop_type_list Links to: comas/attendees/account/proposals/edit/: Modify the proposal, get back to this same page attendees/authors/proposals_file.tmpl: Send the full material for a proposal Direct database fields: -id (proposal.id) Loops: files - Once for each file belonging to this proposal. Direct database fields: -id (prop_material.id), -filename, -descr Variables: -size: The size of the file in question Variables: file_added: The file was successfully received file_deleted: The file was successfully deleted cant_modify_accepted_proposal: Cannot modify an accepted distribution cant_delete_file: Cannot delete a file Links to: comas/attendees/account/proposals/file//delete: Delete the file comas/attendees/account/proposals/file//put: Send a file attendees/authors/proposals_list.tmpl: Show the list of proposals submitted by this author Variables: proposal_data_changed: The information for a proposal was successfully modified proposal_deleted: The proposal was successfully deleted cant_delete_accepted_proposal: Cannot delete an accepted contribution cant_modify_accepted_proposal: Cannot modify an accepted contribution deleted_yourself: Successfully eleted yourself as an author from a proposal Loops: proposals - Once for each proposal submitted by this person Direct database fields: -id (proposal.id), -title, -prop_status Links to: comas/attendees/account/proposals/edit/ - Edit this proposal comas/attendees/account/proposals/authors/ - Modify the list of authors for this proposal comas/attendees/account/proposals/file/ - Manage the files for this proposal comas/attendees/account/proposals/delete/ - Delete this proposal attendees/authors/proposals_new.tmpl: Register a new proposal for this author Direct database fields: -title, -abstract, -track_id, -track_list, -prop_type_id, -prop_type_list Links to: comas/attendees/account/proposals/new - Register the specified proposal General administrative tasks ---------------------------- committee/login.tmpl: Request authentication to enter the administrative interface Direct database fields: -login, -passwd Links to: comas/committee committee/menu.tmpl: Main administrative menu Variables: All of the following variables are conditionals. not_authorized: You are not authorized to enter this area. cannot_delete_self: You are not authorized to delete yourself. error_getting_data: Requested data was not found or could not be retrieved error_deleting_person: Error deleting specified person person_deleted: The specified person was successfully deleted user_deletede: The user has been successfully deleted passwd_changed: Your password was successfully changed admin_mgr: User has access to manage administrators person_cat_adm: User has access to manage person catalogs (information in the catalogs relative to a person - Country, studies, person_type, etc.) proposal_cat_adm: User has access to manage proposal catalogs schedule_adm: User has access to manage rooms and schedule monetary_adm: User has access to monetary administration academic_committee: User has right to review the submitted proposals payment_reg: User has access to register payments payment_mod: User has access to look up or modify specific payments Links to: /comas/committee/admin_mgr: Administrative user administration /comas/committee/person_adm - Modify person-related catalogs /comas/committee/person_cat_adm - Modify proposal-related catalogs /comas/committee/schedule_adm - Rooms and talk scheduling /comas/committee/monetary_adm - Monetary administration /comas/committee/academic_committee - Review submitted proposals /comas/committee/payment_reg - Payment registration /comas/committee/payment_mod - Payment lookup and modification committee/passwd.tmpl: Change the administrative password for this user Variables: diferent_passwd: The new password does not match the confirmation bad_current_passwd: The supplied current password is not valid -current_passwd: Current password -new_passwd: New password -new_passwd2: New password confirmation Links to: /comas/committee/passwd - Carry out the password change Administrative user administration ---------------------------------- committee/admin_mgr/menu.tmpl: Administrative user administration Direct database fields: -login, -name, -passwd, -passwd2 (confirmation for -passwd) Variables: login_used: The supplied administrative username is already in use Loops: admins: Loop for each of the administrative users Direct database fields: -id, -name, -login Variables: -not_self: True if this admin is not the active user (used to show the links to delete a user - it is not allowed to delete yourself) Links to: comas/committee/admin_mgr/new - Create a new administrative user comas/committee/admin_mgr/ - Modify the data for the specified administrative user comas/committee/admin_mgr//delete - Delete the specified administrative user committee/admin_mgr/del.tmpl: Asks for confirmation to delete an administrative user Direct database fields: -id, -login, -name, -tasks Variables: not_confirmed: Conditional. If true, deletion has not yet been confirmed Links to: comas/committee/admin_mgr//delete - Confirm and carry out the deletion Academic committee ------------------ committee/academic_committee/proposals_list.tmpl: Review submitted proposals Direct database fields: -prop_type_list, -track_list, -prop_status_list, Variables: revised_proposal: The proposal has been successfully modified revised_proposal_with_mail: The proposal has been successfully modified, mail was sent to the author notifying of changes number_of_proposals: The number of proposals shown Loops: proposals: Each of the proposals shown matching the specified criteria Direct database fields: -id (proposal.id), -prop_type_id, -track_id, -prop_status, -prop_status_id, -title Loops: authors: Each of the authors for a proposal Direct database fields: -firstname, -famname Links to: Links to: comas/committee/academic_committee - To this same listing. By linking prop_type, track and prop_staus lists to form fields called -filter_prop_type_id, -filter_track_id and -filter_prop_status_id, the proposals shown will be adjusted to match that criteria. comas/committee/academic_commitee/ - shows complete information for the specified proposal committee/academic_committee/proposals_revision.tmpl: Show complete information for a proposal, allowing to change it Direct database fields: -id (proposal.id), -title, -abstract, -track_id, -track_list, -prop_type_id, -prop_type_list, -prop_status_list, -prop_status_id, -comments Loops: authors: Show the information for each of the proposal's authors Direct database fields: -firstname, -famname, -resume files: The information for each of the files that are accompanying material for this proposal. Direct database fields: -file_id, -filename, -size, -descr Links to: comas/committee/academic_committee/ - send the modifications to this address comas/committee/academic_committee//file - download this proposals' material Payments -------- committee/payment/confirm_payment.tmpl: Register a person's payment Direct database fields: Variables: -id (person.id), -firstname, -famname, -email, -person_type, -payment_type_id, -payment_type_list, Loops: proposals: Each proposal for which we charge Direct database fields: id (proposal.id), title, prop_type, Variables: amount: How much does this proposal cost for this person type people: How many people have already registered for this proposal max_people: How many people fit in the room Links to: comas/committee/payment_reg/register/ - Register a payment for specified proposal committee/payment/register_payment.tmpl: Confirmation for registering a new payment, printing nametags and recognitions Direct database fields: -firstname, -famname, -email, -person_type, -payment_type Variables: -total_amount: The total amount the attendee must pay for the talks he is registered to Loops: proposals: Each of the proposals the user is registered to attend Direct database fields: title, prop_type Variables: amount: How much the attendee will be charged for this proposal (from Comas::Payment->calculate_amount) Links to: comas/committee/payment_reg/print_diploma/ - Print the person's recognition (refreshes back to this same page) comas/committee/payment_reg/print_sticker/ - Print the person's nametag (refreshes back to this same page) committee/payment/select_payment.tmpl: Payment registration Direct database fields: -filename, -famname, -email, -person_type, -id (proposal.id) Loops: proposals: Once for each proposal with a registered price Direct database fields: title, prop_type, amount, max_people Variables: payed: Whether this proposal has been paid for by this user (this means, the user has a confirmed place in it) full: Whether this proposal is currently full (that is, it cannot take any new attendees) people: The amount of people currently registered for this proposal Links to: comas/committee/payment_reg/confirm/ - next step in the payment process, registering it. committee/payment/delete_payment.tmpl: Payment lookup and deletion Direct database fields: -firstname, -famname, -email, -person_type, -id (proposal.id), Variables: -total: The total amount the attendee has paid deleted: Conditional. Shows confirmation after deleting payments. Loops: Payments: One row for each payment received from this user Direct database fields: id (payment.id), title, prop_type, max_people Variables: amount: How much will has attendee been charged for this proposal people: How many people have registered to attend this proposal Links to: comas/committee/payment_mod/confirm/ - Confirm the deletion of the selected payments committee/payment/confirm_delete_payment.tmpl: Ask on confirmation on whether to delete payments Direct database fields: -firstname, -famname, -email, -person_type, -id (person.id) Variables: -total: The total amount the attendee should have paid for the selected payments Loops: payments: Once for each payment that will be deleted Direct database fields: id, title, prop_type, max_people Variables: amount: How much has the attendee been charged for this proposal people: How many people have registered to attend this proposal Links to: comas/committee/payment_mod/delete/ Administration of attendees --------------------------- committee/person_adm/person_list.tmpl: Lists the all of the registered persons or those meeting a specified criteria Direct database fields: -country_list, -person_type_list Variables: person_does_not_exist: Specified person does not exist error_modifying: An error occurred performing the requested modification modif_person: The specified person's data has been successfully modified -tot_person: Loops: person: Once for each person that meets the search criteria Direct database fields: -person_type_id, -id (person.id), -famname, -firstname, -email, -country, -person_type Variables: -num_props: The number of proposals for which this person is an author Links to: comas/committee/person_adm - Links back to self, posibly specifying a search criteria comas/committee/person_adm/ - Edit the person's data comas/committee/person_adm//delete - Delete this person committee/person_adm/person_data.tmpl: Shows and allows for modification of a person's data Direct database fields: -id (person.id), -login, -firstname, -famname, -org, -dept, -title, -studies_id, -studies_list, -email, -person_type_id, -person_type_list, -postal_addr, -zip, -city, -state_id, -state_list, -country_id, -country_list, -phone, -fax, -birth, -resume, -pers_status_id, -pers_status_list Loops: proposals: Once for each proposal for which this person is an author Direct database fields: -pr_id, -pr_title Links to: comas/committee/person_adm//modif - Modify the person's data comas/general/proposals/ - Show the proposal's data committee/person_adm/person_delete.tmpl: Handle the deletion of a person Direct database fields: -id (person.id), -login, -firstname, -famname, -org, -dept, -title, -studies, -email, -person_type, -postal_addr, -zip, -city, -state, -country, -phone, -fax, -birth, -resume, -pers_status Variables: Loops: proposals: Once for each proposal for which this person is an author Direct database fields: -pr_id, -pr_title Links to: comas/committee/person_adm/ - Confirms and performs the deletion of the specified person /comas/general/proposals/ - Shows the information for the specified proposal committee/select_person.tmpl: Allows for selecting a person to work with (given their login), or to search for it (given their personal data). Direct database fields: -login, -firstname, -famname, -nickname, -email Variables: -title: The title for this page view login_not_found: The specified username is not registered -section: Which section (module) of Comas is requesting this search Links to: comas/committee/
- Send the submitted user login to the requesting module (submits login as a form field) comas/committee/
/search - Gives some parameters to be searched (displays results in committee/search_person.tmpl) committee/search_person.tmpl: Search for a person given part of their personal data Direct database fields: Variables: -section: Which section (module) of Comas is requesting this search Loops: persons: Once for each matching person Direct database fields: -id (person.id), -login, -famname, -firstname, -email Variables: Links to: comas/committee/
/select/ - Select the specified person, give it back to the requesting module. Other (non-HTML) templates -------------------------- The templates mentioned in this section are _not_ managed by HTML::Template, and do _not_ follow its style (although probably they will soon be converted to using it, just for consistency sake). For the templates mentioned here, no loops/conditionals are available, and variables are just any string of text with no blanks in it, with two underscores before and after (__VARIABLE__). They always have the names in caps. mail/proposal_new.txt: Send a mail acknowledging a new proposal has been received FROM: The originator of the mail (email@address, from the configuration field proposal_new_mail_from) NAME: The name of the person for which the mail is sent MAIL: The e-mail of the person for which the mail is sent PROP_ID: The ID of the proposal this mail is about TITLE: The title of the new proposal TRACK: The chosen track for this proposal (description) PROP_TYPE: The proposal type (description) ABSTRACT: The full abstract received mail/proposal_modif.txt: Notifies the academic committee that a submitted proposal has been modified (note that this mail has fixed to/from addresses, they are included literally in the template) PROP_ID: The ID of the modified proposal TITLE: The original title of the proposal TRACK: The original track of the proposal PROP_TYPE: The original proposal type ABSTRACT: The original abstarct NEW_TITLE: The new title NEW_TRACK: The new track NEW_PROP_TYPE: The new proposal type NEW_ABSTRACT: The new abstract mail/proposal_revision.txt: Notifies the authors of a proposal it has been reviewed by the academic committee FROM: The originator of the mail (email@address, from the configuration field proposal_revision_mail_from) NAME: The name of the author for which this mail is sent MAIL: The e-mail of the author for which this mail is sent TITLE: The title for the proposal being reviewed STATUS: The acceptance status of this proposal COMMENTS: Any comments the committee might have for the author mail/recover_passwd.txt: Generate a random password and send it to a person who forgot it FROM: The originator of the mail (email@address, from the configuration field attendees_recover_passwd_from) NAME: The name of the person for which the mail is sent MAIL: The e-mail of the person for which the mail is sent PERSON_ID: The ID for the person this mail is from NEW_PASSWD: The new generated password other/gafete.txt: The commands sent to a Zebra printer (serial connection, specialized for this kind of work) to print the nametag NICK: The person's nickname FIRSTNAME: The person's first name FAMNAME: The person's family name EMAIL: The person's e-mail address PERSON_TYPE: The type of attendee this person is (description)