Development
Compatibility
Unless otherwise specified, all development for McGill Drupal-based Web Management System must be contained in Drupal modules. McGill's primary theme will be used with all sites and should not be overridden by a sub-theme without a compelling reason that aligns with McGill IT strategy.
Unless otherwise specified, all externally developed Drupal modules must be compatible with the following:
- Drupal version 7 (latest stable release)
- PHP 7.0
- MySQL 5.1
- jQuery version 1.5.1
- jQuery UI 1.8.11
- Apache web server
WorkFlow
Local development
You may want to use your own local environment for development; we suggest using Devel Generate to populate your application. Refer to the general guidelines when developing your application.
Test functionality with McGill content on the RAS
Promote your code to the RAS regularly to make sure your development is in sync with the McGill code base and Production content.
Be sure to create features on the RAS to avoid conflicts with other modules.
Testing Deployment
When features are finalized, test deployment.
Reset the RAS for the latest production content
Test drive your deployment.
McGill Modules
Be sure to check the admin/modules page for existing functionality you can leverage.
Note that some McGill features are in beta, third parties should not build into or use features in beta.
Note that we disable Google Analytics in all development environments including the RAS. However, Google Analytics is enabled on all live sites and is properly configured.
You must ensure that the xmlsitemap module is enabled for your site, and that it includes instances of any custom content types you may have created. Content types created by McGill will be included by default and once enabled, the sitemap will be regenerated nightly as needed via cron. You will have to set a variable xmlsitemap_settings_node_CONTENT_TYPE for each content type you have created which is intended to be viewed as a stand-alone page, plus use xmlsitemap_custom and/or xmlsitemap_menu to include views pages or other content if needed.
Emergency message displaying in themes
You will need to add the following to your html.tpl.php for emergency messages:
<?php // EMS module might not be enabled: load the file that contains mcgill_emergency_output(). module_load_include('inc', 'mcgill_emergency', 'mcgill_emergency.theme'); // Exit if an emergency is active. if (mcgill_emergency_output()) { exit; } ?>
Below is markup that is used for emergency messages:
<div class="mcgill-emergency-message 3">
<div>
<h3>emergency test</h3>
<span class="ems-updated">Updated: <em class="placeholder">Fri, 05/20/2016 - 11:57</em></span>
<div class="field field-name-body field-type-text-with-summary field-label-hidden"><div class="field-items"><div class="field-item even"><p>This is a test, please ignore.</p>
</div></div></div> </div>
</div>
The background color is #FFED00.
Module Development
- Modules must adhere to Drupal coding standards, security standards and best practices as outlined here.
- Modules must pass inspection by the most recent 7.x version of the Drupal coder module without any errors or warnings: https://www.drupal.org/project/coder.
- Modules and any libraries that they depend on should be releasable under a GPL2 or similar license: http://www.gnu.org/licenses/gpl-2.0.html.
- Modules should provide an extensible API where possible and applicable.
- Modules should override core functionality using Drupal's hook system. Core Drupal code must never be modified directly.
- Modules must be designed and tested to work with Drupal multisite.
- Modules must be thoroughly commented in conformity with Doxygen formatting conventions.
- Modules must not duplicate existing solutions already in use within McGill’s Drupal-based Web Management System.
- Modules that interact with content must ensure that content is run through appropriate Drupal filters. Custom text formats must ensure that runnable PHP and JavaScript code can not be added into content. CSS properties that might allow JavaScript injection or other malicious activities must also be filtered out.
- All developed features should be in a default state and should not be in conflict with existing and enabled WMS modules.
- Existing WMS roles should be used in place of custom roles whenever possible.
- All roles should authenticate via LDAP and the McGill Active Directory system. This is preconfigured for existing WMS roles.
- PHP, JavaScript and CSS used in a module should be namespaced to that specific module.
- Use of Drupal's core PHP module is not allowed.
- All modules should be deployed and tested against McGill's code base and configuration before delivery using the remote application server.
- All modules will be subject to review by McGill IT Services to ensure that they conform to the aforementioned standards.
- Unless otherwise specified, if any contributed modules are used that are not currently part of the McGill code base, they must meet all of the above guidelines and have a full (not dev, alpha, beta or rc) release.
Theme Development
- Themes must adhere to Drupal coding standards, security standards and best practices as outlined .
- Unless otherwise specified, all development must be done using the primary McGill Drupal theme.
- Wherever possible, PHP logic must be placed in modules and removed from the theme layer.
- Drupal UI best practices.
- XHTML 1.0 http://www.w3.org/TR/2002/REC-xhtml1-20020801/ with allowances made for backward compatible HTML 5 http://www.w3.org/TR/2010/WD-html5-20100304/
- CSS 2 http://www.w3.org/TR/2008/REC-CSS2-20080411/ with allowances made for backward compatible CSS 3 http://www.w3.org/TR/2001/WD-css3-roadmap-20010523/
- WAI https://www.w3.org/WAI/fundamentals/accessibility-intro/ WCAG2.0 http://www.w3.org/TR/WCAG20/ accessibility standards
- WAI https://www.w3.org/WAI/fundamentals/accessibility-intro/ ATAG1.0 http://www.w3.org/TR/ATAG10/ accessibility standards
- All tpl.php PHP should be limited to print functions and if/else statements. More complicated theme layer PHP should reside in template.php.
- jQuery or HTML5 solutions should be used in place of Adobe Flash wherever possible.
- JavaScript UI elements must degrade gracefully when JavaScript is disabled.
- Theme code must be thoroughly commented in confomity with Doxygen formatting conventions.
- Content must display properly in all supported web browsers.
- Themes must be properly responsive and intitively on IOS or Android devices.
- All custom themes must be tied to the central McGill localization server for interface translation.
Translations
Translations can be broadly divided into two categories and each category is handled differently:
- Content translation, for example nodes. This should be handled by the Site Manager through a mechanism provided either in the McGill toolset or through externally developed tools.
- Interface translation, for example field labels and help text. These translations should be provided in a .po file with the relevant modules.
Deployment
Testing your deployment is essential and is stated in your contract. Whenever possible, we expect no manual configuration by us, the external developer, or the site owner. Database level changes (such as enabling a new module) should happen in Drupal update hooks wherever possible. To test, reset the RAS environment for your site, which will copy the database from the live site to RAS and then run your deployment hooks, just as will happen when your code is pushed from RAS to production.
The script we use to push code to both RAS and the production environment will always run update hooks and clear all caches; it's not necessary to ask us to do those steps manually. If any other steps are required, please include those in your code review request, for example as a list of drush commands to run on the server.
Before deployment can happen, all code must be reviewed.
Code review
- Any content/data that is added to the RAS will not be brought over to our staging or Production environment. This includes node IDs; do not rely on them being the same
- Make sure mcgill_template is enabled on the RAS site — mcgill_template could even be a dependency of the vendor modules
- All configuration and functions must be featured in code
- Modules should not have conflicts with McGill modules
- No patching of Drupal Contrib modules
- Permissions should be featurized — as a general rule:
- RAS developer should have no perm
- Site Manager and WSG Support should be able to administer any content
- Contrib and custom modules should be in separate folders, e.g., modules/custom/ and modules/contrib/
- Libraries should be in library/
- Don't use CDN's; use local copies of the resource you require. External scripts are inherently insecure. For your local implementation, if possible, use libraries.
- Credentials to third-party APIs (Twitter keys, etc.) should not be hard-coded — can be strong-armed
- Request a code review by emailing itsupport [at] mcgill.ca. Ask that the request be assigned to the "Web Services Group."
Need Help?
- If you have a quick one-time question, just ask in our IRC chatroom at #mcgill_web_external on freenode. There is usually a developer available during normal business hours Mon-Fri.
- For other issues or requests, submit a ticket to the IT Service Desk by emailing itsupport [at] mcgill.ca. Ask that the ticket be assigned to the "Web Services Group."