Support content insertion into <head> of a Page #361

Chng-Zhi-Xuan · 2018-07-23T08:23:12Z

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] New feature

Resolves #355

What is the rationale for this request?
User would like to easily insert their own script or css files into the <head> of a page.

What changes did you make? (Give an overview)

Have Site initialise a new head folder within the _markbind folder.
Insert logic for Page to process the specified head file in front-matter
Update page.ejs template to insert content from head file
Update Site unit tests
Add code and files to test content insertion within test_site
Add description to user guide

// Within customScript.js
console.log('custom script inserted into the head successfully!');

In console	In Page HTML

Is there anything you'd like reviewers to focus on?

Method / Variable naming
Whether is there a need to do nunjucks.renderString within collectHeadFiles
User Guide wording

Testing instructions:

Checkout this PR's branch and navigate to test_site folder.
Run markbind serve and check console for the success message from inserted script
Add new folders with CSS or JS files in the root
Use the appropriate syntax and add them inside myCustomHead.md
Run markbind serve and you should see the <head> having your newly authored content from myCustomHead.md along with the files in Sources tab (in Chrome).

Chng-Zhi-Xuan · 2018-07-24T02:04:37Z

Update

Add user guide section
Update PR title and description
Ready for review

yamgent · 2018-07-24T02:51:43Z

lib/Page.js

+  const userDefinedVariables = this.userDefinedVariablesMap[path.join(this.rootPath, newBaseUrl)];
+  const headFileMappedData = nunjucks.renderString(headFileContent, userDefinedVariables);
+  this.headFileReferences = headFileMappedData.trim();
+  return pageData;


Seems like the pageData is not used at all in this method, so it is not necessary.

Therefore, we can call this method before the line this.headFileReferences = nunjucks.renderString(this.headFileReferences, { baseUrl, hostBaseUrl }); instead of doing .then(result => this.collectHeadFiles(result)).

yamgent · 2018-07-24T03:03:46Z

lib/Page.js

+  // Map variables
+  const newBaseUrl = calculateNewBaseUrl(this.sourcePath, this.rootPath, this.baseUrlMap) || '';
+  const userDefinedVariables = this.userDefinedVariablesMap[path.join(this.rootPath, newBaseUrl)];
+  const headFileMappedData = nunjucks.renderString(headFileContent, userDefinedVariables);


Is this rendering necessary? Seems to still work for me when I commented it out. Also the render method seems to be called again below.

It is useful if the user predefined a <style> or <link> variable and used it in headFile.md.

The render method below is specifically for resolving {{baseUrl}}.

yamgent · 2018-07-24T03:04:08Z

docs/userGuide/contentAuthoring.md

@@ -375,6 +375,50 @@ Front matter can also be included from a separate file, just like how content ca

 This will result in `index.md` having the title `Binary Search Tree` and the specified keywords in order for it to be looked up through the search bar.

+### Inserting content into a page's head element
+
+While authoring your website, you may want to have your own CSS or Javascript file to be included in a page.


file -> files

yamgent · 2018-07-24T03:06:04Z

docs/userGuide/contentAuthoring.md

+    - More than one head file can be created for different pages.
+
+- Author your `<style>` elements for CSS files and `<link>` elements for Javascript files using HTML as shown below.
+    - Ensure that any url starts from the root directory <code>{<span></span>{baseUrl}}/</code> when you are referencing your files.


Ensure that any url starts... -> Ensure that your URLs start...
... from the root directory {{baseUrl}} ... -> ... from the root directory, by using {{baseUrl}} ...

yamgent · 2018-07-24T03:07:18Z

docs/userGuide/contentAuthoring.md

+<script src="{{baseUrl}}/yourScriptFolder/myCustomScript.js"></script>
+```
+
+- Specify the head file in pages that you want it, within the [front matter](#front-matter) `head` attribute.


...that you want it, within the... -> ...that uses it, by specifying the...

yamgent · 2018-07-24T03:08:58Z

docs/userGuide/contentAuthoring.md

+```
+
+The head file contents will be placed near the end of the page's head tag.
+It will override existing Bootstrap and MarkBind CSS styles if there is an overlap. 


It will... -> Your head file will...
there is an overlap -> there is an overlap of classes.

... overlap of ~~classes~~ -> ... overlap of selectors

Doc here

yamgent · 2018-07-24T03:11:40Z

Also by any chance, is it possible to support live preview for changes to the head files?

Chng-Zhi-Xuan · 2018-07-24T05:57:44Z

Update

Apply changes requested
Add support for page regeneration on head file change

yamgent · 2018-07-24T07:20:55Z

docs/userGuide/contentAuthoring.md

+
+```html
+<!-- In _markbind/head/compiledRef.md -->
+<link rel="stylesheet" href="{{baseUrl}}/yourCSSFolder/subfolder/myCustomStyle.css">


{{baseUrl}} is not getting rendered (see Netlify preview).

yamgent · 2018-07-25T02:15:55Z

@Chng-Zhi-Xuan the commits need to be squashed.

As discussed with Prof, we can live with the {{baseUrl}} documentation problem for now, and fix it in a separate PR (in fact, another section also have the {{baseUrl}} documentation problem, so might as well solve everything later).

Will merge it as soon as it is squashed.

Chng-Zhi-Xuan · 2018-07-25T02:40:56Z

Update

Squashed commits

damithc · 2018-07-25T06:23:27Z

@Chng-Zhi-Xuan I'm having trouble getting this to work in website-base. Can you try it out?
Attached files:

_/markbind/head/scheduleHead.md
schedule/index.md

head files.zip

I got the feature to work in other places. In fact I can include scheduleHead.md as the head in other files. But when I include it in schedule/index.md, it doesn't get inserted into the head.

damithc · 2018-07-25T06:27:43Z

To add to the above, full code available in the scheduleHead branch https://github.com/nus-cs2103/website-base/tree/scheduleHead

Chng-Zhi-Xuan · 2018-07-25T07:01:10Z

@damithc

Findings:

Clicking on "Schedule" in the main page's navbar directs to /website-base/index.html, which does not specify any head file in the front-matter.
Navigating to /website-base/schedule/index.html and it has the specified head file as shown below.

This is intended behaviour as <include> ignores the file's front-matter.

A quick fix is to specify scheduleHead.md in the main page's index.md 😄

damithc · 2018-07-25T07:16:18Z

Indeed that should be the problem. My bad. Sorry. Thanks for the help.

Chng-Zhi-Xuan changed the title ~~[WIP] Support content insertion into <head> of a Page~~ [WIP] Support content insertion into <head> of a Page Jul 23, 2018

Chng-Zhi-Xuan changed the title ~~[WIP] Support content insertion into <head> of a Page~~ Support content insertion into <head> of a Page Jul 24, 2018

Chng-Zhi-Xuan requested a review from yamgent July 24, 2018 02:04

Chng-Zhi-Xuan mentioned this pull request Jul 24, 2018

Support adding custom classes to any vue-strap component #363

Closed

yamgent reviewed Jul 24, 2018

View reviewed changes

yamgent mentioned this pull request Jul 25, 2018

User guide: Example code should render {{baseUrl}} verbatim #367

Closed

Chng-Zhi-Xuan added 6 commits July 25, 2018 10:35

Site: Initialise head folder

3bb1d1e

Page: Read and process specified head file

e99721e

Template: Add head file reference

0b3bf04

Test: Update Site unit tests

7d2fa1d

Test: Update test_site to insert head file

16f7f65

Docs: Add page head content insertion section

7c7600f

Chng-Zhi-Xuan force-pushed the 355-insert-head-files branch from d8830c8 to 7c7600f Compare July 25, 2018 02:40

yamgent added this to the v1.9.2 milestone Jul 25, 2018

yamgent merged commit 97711ef into MarkBind:master Jul 25, 2018

Chng-Zhi-Xuan deleted the 355-insert-head-files branch May 21, 2019 06:40

yamgent mentioned this pull request Jan 23, 2020

Content Insertion into <head> does not respect file types #993

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support content insertion into <head> of a Page #361

Support content insertion into <head> of a Page #361

Chng-Zhi-Xuan commented Jul 23, 2018 •

edited

Loading

Chng-Zhi-Xuan commented Jul 24, 2018 •

edited

Loading

yamgent Jul 24, 2018

yamgent Jul 24, 2018

Chng-Zhi-Xuan Jul 24, 2018

yamgent Jul 24, 2018

yamgent Jul 24, 2018

yamgent Jul 24, 2018

yamgent Jul 24, 2018

Chng-Zhi-Xuan Jul 24, 2018

yamgent commented Jul 24, 2018

Chng-Zhi-Xuan commented Jul 24, 2018

yamgent Jul 24, 2018

yamgent commented Jul 25, 2018

Chng-Zhi-Xuan commented Jul 25, 2018

damithc commented Jul 25, 2018

damithc commented Jul 25, 2018

Chng-Zhi-Xuan commented Jul 25, 2018

damithc commented Jul 25, 2018

Support content insertion into <head> of a Page #361

Support content insertion into <head> of a Page #361

Conversation

Chng-Zhi-Xuan commented Jul 23, 2018 • edited Loading

Chng-Zhi-Xuan commented Jul 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yamgent commented Jul 24, 2018

Chng-Zhi-Xuan commented Jul 24, 2018

Choose a reason for hiding this comment

yamgent commented Jul 25, 2018

Chng-Zhi-Xuan commented Jul 25, 2018

damithc commented Jul 25, 2018

damithc commented Jul 25, 2018

Chng-Zhi-Xuan commented Jul 25, 2018

damithc commented Jul 25, 2018

Chng-Zhi-Xuan commented Jul 23, 2018 •

edited

Loading

Chng-Zhi-Xuan commented Jul 24, 2018 •

edited

Loading