Virginia Tech® home

How Do I ... Modify Provided Site Themes

Note that all local repositories were moved to GitLab (code.vt.edu) as of August 2021.

Web designers and developers may run into a situation that the web team never considered or may encounter edge cases where the design of the provided site templates need to be modified while still within the university branding guidelines. Advanced users have a few advanced tools to customize their components, pages, and sites. Essentially, users can layer their own CSS and Javascript over the bootstrap and university provided templates.

 

HTML Components

Some simple changes can be affected by putting a <style> tag into an HTML element. While non-compliant to have a <style> outside of the <head>, modern browsers will apply the CSS styles in these tags. By placing the <style> tag on the /en redirect page, that style can be inherited onto the entire site.  

 

Local Assets

Local assets allow web designers and web developers to customize the look and feel of their site.  Setting the local assets property on the site configuration tab adds additional files on every HTML page. By changing the contents of these files, web designers have access to change how content is displayed.  The two files referenced in the HTML <head> (that will be added when the local assets url field is filled) are:
      [local assets url]/modifyGlobalTemplate.css
      [local assets url]/modifyGlobalJS.js
An additional file is loaded as the last item in the body:
      [local assets url]/modifyGlobalJS_body.js

 

Requesting local assets

Please request local assets by Clicking on “Help” > “Request Support” in the content management system (CMS). In the form, please indicate that you would like local assets and also the site URL. A git repo will be created to host the local_assets files. Also an Enterprise Directory Group called cms.sitename_vt_edu.web_designer will be created to control write access to the repository. Group membership can be managed by web_admins at https://webapps.es.vt.edu/group-manager/. After local assets groups and repos are created and linked, you will need to add yourself to the correct group before proceeding.

 

Local assets hosted traditionally

While waiting for your local assets repository to be set up, you may begin modifying the style and functionality of your site if you have a traditional hosting site that allows you to directly add and edit text files. You should have modifyGlobalTemplate.css, modifyGlobalJS.js, and modifyGlobalJS_body.js although they can be empty. Note that there is no official support for this technique and it may be deprecated in the future. We recommend hosted local assets only as a temporary solution because a git repo offers version control (infinite server undo) and uses VT Enterprise Directory Group Management via a cms.sitename_vt_edu.web_designer group.

  1. Go to https://author.ensemble.vt.edu/mysites.html
  2. Check the box to the left of your website and "View Properties"
  3. Click "Edit"
  4. Choose "Site Configuration"
  5. Enter a Local Assets Path: https://site.domain.tld/folder/local_assets/
  6. Publish out the site root (/)
  7. Publish out the redirect level (/en/)
  8. Publish out the index (/en/index)

 

Setting up local assets using a git repo

Once created, local assets are managed in a git repository in a Stash / Bitbucket server. People that have access to the repository will need to be members of the group cms.[siteurl].web_designer. Web-admins can add members to this group using http://webapps.es.vt.edu/group-manager.

  1. Go to https://author.ensemble.vt.edu/mysites.html
  2. Check the box to the left of your website and "View Properties"
  3. Click "Edit"
  4. Choose "Site Configuration"
  5. Enter a Local Assets Path: /local_assets/[site_url]
    (replace [siteurl] with the url of your site. For example, www.mysite.vt.edu and note that the www. at the beginning of the site name is required to match the site name in the git repository.)
  6. Publish out the site root (/)
  7. Publish out the redirect level (/en/)
  8. Publish out the index (/en/index)

 

Configure and Clone local assets

A web designer for the site has full permissions to their local assets repo (so they can delete the branches, but doing so will break the hooks in place that update assets on the respective environments)

  1. Install or update SourceTree from https://www.sourcetreeapp.com/ unless you intend to use git entirely through a command line interface.
  2. If you intend to modify local_assets from off-campus, download, install, and activate the Remote Access VPN service.
  3. Go to SourceTree > Preferences > General to set your Full Name and Email address and allow SourceTree to modify global configuration files.
  4. The setting Check default remotes for update every __ minutes will generate Duo requests for older archives that do not use SSH keys. Please deny any Duo requests that you do not explicitly and immediately create.
  5. Go to SourceTree
    For macOS
    1. Preferences > Accounts
    2. Click <Add...>
    3. Host: Bitbucket Server
    4. Enter server name: https://webapps.es.vt.edu/stash/
    5. Enter your PID as the username
    6. Set Protocol to SSH
    7. If no key found, <Generate Key>, Allow SourceTree to Create an SSH key, enter a secure passphrase twice, <Create>, Copy to Clipboard, <OK>.
    8. If password requested, click Cancel.
    9. Close the Preferences window
    10. Window menu > Show Repository Browser
    11. Delete any existing local repositories that link to webapps.es.vt.edu/stash/. Local repos that you cloned before converting to an SSH authentication key will continue to use HTTPS and require a large number of verifications and may lock out your Stash and Duo accounts. Back up uncommitted or unpushed files elsewhere in your file system.
    For Windows
    1. SourceTree > Tools > Create or Import SSH Keys
    2. Choose Generate
    3. Copy the public key for use on Stash webpage
    4. Create a passphrase and enter it twice
    5. Save public key to file pubkey.ppk
    6. Save private key to file called privkey.ppk
    7. Open Pagent application in task manager
    8. Click <Add Key> and load the privkey.ppk
    9. Use passphrase from  above
    10. Delete any existing local repositories that link to webapps.es.vt.edu/stash/. Local repos that you cloned before converting to an SSH authentication key will continue to use HTTPS and require a large number of verifications and may lock out your Stash and Duo accounts. Back up uncommitted or unpushed files elsewhere in your file system.

  6. Log into the Stash / BitBucket server at http://webapps.es.vt.edu/stash/ with your pid and password then accept the Duo request from ED LDAP Proxy/Virginia Tech.

    If this is your first time logging in, you may get a message saying that you do not have access to any repos. If this is the case, wait 30 minutes before trying to login again. If you still have problems, please send us a Help Ticket using “Request CMS Support” in the lower right-hand corner of this window).

    If you have been locked out of the Stash / BitBucket server, you will have to complete a captcha on login. Completing the captcha will unlock your account. If you are locked out later, please log into the web interface to clear the lockout.

    It is also possible to be locked out of Duo due to too many requests. To unlock Duo, you will need to contact 4-Help. 

    Note that Duo verifications are not cached for services that do not use Login Single Sign On (SSO). You will get a duo verification every time you or one of your services validates against any VT 2-factor service.

    1. Go to Accounts in the upper right and choose Manage Account
    2. Click on SSH keys on the left
    3. <Add key>
    4. Paste in key copied from SourceTree (step 4-6 above)
    5. <Add key>

  7. Navigate to your Repository or enter the direct URL for your repository: https://webapps.es.vt.edu/stash/projects/CMSASSETS/repos/[siteurl]
    (For example, https://webapps.es.vt.edu/stash/projects/CMSASSETS/repos/www.assets.cms.vt.edu). 

  8. Select Clone (an arrow pointing down into a tray), verify SSH as the protocol, and clone in SourceTree. You will need to edit at least the "prod" branch locally.

 

Simplified work process for local assets

If only one developer is making changes to local_assets and they do not want to test in the preproduction environment and do not need approval from others, they can use this simplified process for manipulating assets: 

  1. Pull the prod branch from origin/prod into your local repo to confirm that your local repo is up to date.
  2. Make changes to your local assets file(s) using your file system and whatever text editor you prefer.
  3. Add the changed files to staging. In SourceTree, you choose History > uncommitted changes and then check the box next to the file(s) in the lower left-hand part of the window.
  4. Commit the files. Type a commit message that explains why this change was implemented.
  5. Push the prod branch to origin/prod.
  6. Test against the live site.
  7. Repeat work process as needed.

Recommended work process for local assets

The recommended work process for local assets supports multiple users in the same repository, supports testing in the preproduction environment, and approvals: 

  1. Pull the master branch from origin/master into your local repo to confirm that your local repo is up to date. (If multiple people are working in the repo, you may want to name branches after the people working in the repo or features being developed and then consolidate work into master.)
  2. Make changes to your local assets file(s) using your file system and whatever text editor you prefer.
  3. Add the changed files to staging. In SourceTree, you choose History > uncommitted changes and then check the box next to the file(s) in the lower left-hand part of the window.
  4. Commit the files. Type a commit message that explains why this change was implemented.
  5. Push the master branch to origin/master.
  6. Login to Stash / Bitbucket with your pid / password: https://webapps.es.vt.edu/stash/projects/CMSASSETS and click on your site url.
  7. Type [ on your keyboard if you do not see the Bitbucket left menu
  8. Click on “Create pull request” from the left side menu
  9. Select master as the source branch (top branch/base of arrow)
  10. Select pprd as the destination branch (bottom branch/tip of arrow)
  11. Continue
  12. Review changes with Diff; add reviewers as needed; <Create>.
  13. <Merge> to approve the request or ask other reviewers to review and have them <Merge>
  14. If the merge fails, fetch the repo locally, check out the pprd branch; pull from origin/master; resolve conflicts; commit; push pprd branch to origin.
  15. Test against https://cmsa-pprd-01.db.vt.edu/
  16. Click on “Create pull request” from the left side menu
  17. Select pprd as the source branch (top branch/base of arrow)
  18. Select prod as the destination branch (bottom branch/tip of arrow)
  19. Continue
  20. Review changes with Diff; add reviewers as needed; <Create>.
  21. <Merge> to approve the request or ask other reviewers to review and have them <Merge>
  22. If the merge fails, fetch the repo locally, check out the prod branch; pull from the origin/pprd; resolve conflicts; commit; push pprd to origin.
  23. Test against your live site.
  24. Repeat work process as needed.

 

Branches

Commits pushed to origin/master automatically update the DVLP environment: our development server for Ensemble websites.

Commits pushed to origin/pprd automatically update the PPRD environment: our test server for Ensemble websites.

Commits pushed to origin/prod automatically update the PROD environment: the live Ensemble websites.

We recommend that you make changes at least to pprd and test in pprd before rolling changes out to your live site.

 

Learning about and using git repos

After authenticating against LinkedInLearning.vt.edu, you can learn more about git at https://www.linkedin.com/learning/learning-git-and-github/working-with-the-staging-environment?u=57888345 and with other videos on LinkedIn Learning.

You can reverse a commit by right clicking on a particular commit in SourceTree or you can use git terminal commands while in the current projects directory:

git reset --soft HEAD^ deletes the last commit while leaving files (working directory) alone. Only use if you haven't pushed changes to origin.

git reset --hard 0d1d7fc32 deletes all changes since a particular commit. Only use if you haven't pushed changes to origin.

git reset --soft 0d1d7fc32 deletes all git changes since a particular commit but leaves files as is so that you can commit immediately. Only use if you haven't pushed changed to origin.

"Discard local changes" means that the git command that you are about to execute will overwrite existing states. If you are trying to undo something, you want to discard local changes.

A "detached head" means that you've gone backwards in time  to an older commit. This is useful to briefly review a past commit but you usually do not want to commit with a detached head.