Local assets allows web designers and web developers to customize the look and feel of their site.  Setting the local assets property on the site configuration tab calls 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

Stash / Bitbucket Configuration

Requesting local assets

Please request local assets by Clicking on “Help” > “Request Support” in the CMS. In the form, please indicate that you would like local assets and also the site URL.

Setting up local assets

Once created, local assets are managed in a git repository in a Stash / Bitbucket server. People that have access to the repository will need 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 index (/en/index)

 

Work process for local assets

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

  1. Login to Stash / BitBucket with your pid / password: https://webapps.es.vt.edu/stash/projects/CMSASSETS/repos/[siteurl]
    (replace [siteurl] with the url of your site. For example, www.assets.cms.vt.edu)

    1. If this is the first time logging in, you may get an message saying that you do not have access to any repos.  If this is the case, wait before trying to login again.  The first login creates an account on the repository and there is a sync process that runs every half hour to update group memberships).

    2. If you still have problems accessing your local assets repository, please send us a Help Ticket: in the CMS click on “Help” > “Request Support”).

  2. Clone Repo.  The clone URL is available under "Clone" in the "Actions" menu entry. You may need to click on the elipses (...) to see this menu entry.

    1. You can use a git client like SourceTree (https://www.sourcetreeapp.com/). Once SourceTree  is installed, you can click on the "Clone in SourceTree" after selecting the "Clone" entry and this should open up the application with the correct clone parameters.

  3. Make local commits to individual branches (if wanted) and push when necessary to origin/master.

    1. Commits to master automatically update the DVLP environment (our development server for AEM Ensemble websites).

  4. Create a pull request from master to pprd and merge to pprd.

    1. The action of merging to pprd will update the assets in PPRD (our preproduction/test version of AEM Ensemble websites).

    2. Verify changes in PPRD:  https://cmsa-pprd-01.db.vt.edu/

  5. Create a pull request from pprd to prod and then merge to prod.

    1. The action of merging to prod will update the assets in PROD (the live versions of our AEM websites).

    2. Verify changes.

 

Creating and managing Pull Requests via a browser

  1. Login to Stash / Bitbucket with your pid / password: https://webapps.es.vt.edu/stash/projects/CMSASSETS and click on your site url.

  2. Click on “Create pull request” from the left side menu

    1. If you do not see this menu, type [ on your keyboard which should expand out the left menu

    2. You can also click on the the Pull Request Icon, then click on “Create Pull Request”

  3. The arrow indicates which branch is pull request is coming from and going to (The top is the originating branch and the bottom is the branch that the pull request will be merged into.

    1. Select the desired branches (ie. master -> pprd)

    2. Click continue

  4. You can review the changes by clicking on the “Diff” tab. You can also add additional reviewers at this step.

    1. Click on “Create” to create the pull request.

  5. Once the pull request has been created, you can approve it and “Merge” it.

    1. Click on the “Diff” to see the changes in the pull request

    2. Click on “Merge” to approve the pull request and merge it.

  6. If the automatic merge fails, this means that there is a conflict in the file which cannot be resolved automatically.

    1. Download the repo in your computer using a git client

    2. Check out the branch that is being merged into

    3. Pull from the origin branch that the pull request is coming from

    4. Resolve conflicts

    5. Push the branch to the origin

Alternatives

Yes, currently you can add your own server in the local assets url and as long as you have the correct names of the files, it should work. This can be great for rapid testing of code pre-launch. However, this technique is not supported and may not be available in the future. You may also run into cross-site scripting issues hosting your own local asset links.

We recommend using the Stash / Bitbucket configuration because of all the benefits of a git repository (revisions) as well as control over access (via the web_designer group).