Branding

Overview

If you are installing your own instance of DMPRoadmap it is likely that you will want to add your own branding. Following these basic guidelines will help ensure that your codebase is able to be kept up to date with the latest DMPRoadmap codebase:

• Create a new branch for your own branding/customizations git checkout -b my-dmp-app
• Make your changes (see below for specific recommendations for different file types)
• Use this new branch when deploying your application to your server
• Keep your branch up to date as new releases of DMPRoadmap come out. git checkout master and git pull origin master followed by git checkout my-dmp-app and git merge master.
• Git will tell you if there are any conflicts. If so resolve them and do a git add path/to/file.extension and git merge --continue to finalize the merge.

Configuration

• Update any sensitive credentials EDITOR=vi rails credentials:edit.
• Be sure to update the default URL defined in config/environments/production.rb. This is used by the ActionMailer system to construct URLLs embedded within emails sent out from the system
• Update the values in config/initializers/_dmproadmap.rb. These values are referenced throughout the code.

Stylesheets

Stylesheet customizations can be broken down into two areas:

• Changing variables
  • Due to the nature of cascading stylesheets you must define variables before using them (e.g. $color: red; p { background-color: $color; } $color: green; would result in paragraphs with a red background in the browser). If you would like to override the standard DMPRoadmap colors we recommend:
    • Creating your own variable overrides file app/assets/stylesheets/variables/_my_app.scss and importing it in app/assets/stylesheets/application.scss immediately after the @import "variables/*"; line
• Other style changes
  • Rather than modifying the core DMPRoadmap stylesheets we recommend that you create a subdirectory in app/assets/stylesheets/ and store your customizations there. For example if I wanted to change the color of a table row when the user hovers over it you would:
    • Create a folder for your customizations app/assets/stylsheets/[my_app]/
    • Create a file called app/assets/stylsheets/[my_app]/_tables.scss that contained the appropriate SCSS (e.g. .table-hover tbody tr:hover td { background-color: $color-light-grey; })
    • Add a line to the main app/assets/stylsheets/application.scss to make sure your customization gets loaded (e.g. @import "[my_app]";). Be sure to place this line at the end of application.scss so that it overrides the previous styling in the cascade.

For more information on stylesheets and how they are structured within the DMPRoadmap codebase please see the README sections for CSS Variables, CSS Utils and CSS Blocks

Images

• If you just want to use your own logo instead of the DMPRoadmap logo, we recommend simply replacing app/assets/images/logo.png. Be sure that your replacement is a PNG format and its dimensions are similar to the original file.

Views

The codebase contains logic that will look for a particular view/partial in the app/views/branded directory first before looking in the standard app/views directories. To customise a view simply create a branded directory under app/views, then take a copy of the view you wish to customize and place it into the appropriate directory under app/views/branded (follow the same subdirectory patterns). For example: app/views/branded/home/index.html.erb or app/views/branded/paginable/plans/_privately_visible.html.erb

Pros: The custom code is isolated and would not be accidentally broken by a change in the core codebase. It makes it a bit easier to share your customization with other members of the community since the code is isolated.

Cons: When the underlying DMPRoadmap code changes you need to pay closer attention to the release notes to see if a change was made to one of the files you copied and if so you would need to manually update your customized copy.

Controllers, models and other non-CSS or non-View files

If you need to add/remove functionality from any other files in the codebase we recommend that you try to place them into mixins that can be pulled into the core codebase. This gives you the benefit of only having to worry about a single include statement than having your changes overwritten when doing a git merge. For example if you wanted to add a new public facing page for your users, you could add the appropriate route to config.routes.rb and then add the new endpoint directly to the app/controllers/public_pages_controller.rb.

It would be better though to add them to a separate app/controllers/[my_app]/public_pages.rb file that could then be used as a mixin:

  # contents of app/controllers/[my_app]/public_pages.rb
  module MyApp
      module PublicPages

        # The sign in/account creation options page accessed via the 'Get Started' button
        # on the home page
        def get_started
          skip_authorization
          render "/shared/_get_started"
        end

      end
    end
  end

  # contents of app/controllers/public_pages_controller.rb
  class PublicPagesController < ApplicationController
    after_action :verify_authorized, except: [:template_index, :plan_index]

    include MyApp::PublicPages

    ...
  end

With this approach we only need to ensure that our include statement is in the controller during future merges of the latest DMPRoadmap codebase.

The mixin approach though doesn't always work. Sometimes you may need to update the existing files directly. If you do need to do this, we recommend commenting out the original line of code and adding your changed version below it. We also recommend placing comments around the change to help highlight it during future merges.