Skip to content

Embed JS: fix incompatibilities with sphinx 6.x (jquery removal) #9359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 4, 2022
Merged

Embed JS: fix incompatibilities with sphinx 6.x (jquery removal) #9359

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4658602
Emebed JS: fix compatibility with sphinx 6.x (jquery removal)
stsewd Jun 21, 2022
74ac50a
Updates from review
stsewd Jun 28, 2022
059d2f9
Merge branch 'main' into sphinx-jquery
stsewd Jun 28, 2022
8868a46
Use just one function
stsewd Jun 28, 2022
2c14c6f
Update readthedocs/core/static-src/core/js/readthedocs-doc-embed.js
stsewd Jun 29, 2022
54c8ad3
Merge branch 'main' into sphinx-jquery
stsewd Aug 4, 2022
af3b86f
Don't inject JQuery
stsewd Aug 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 54 additions & 69 deletions readthedocs/core/static-src/core/js/doc-embed/search.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,6 @@ var xss = require('xss/lib/index');
var MAX_RESULT_PER_SECTION = 3;
var MAX_SUBSTRING_LIMIT = 100;

/**
* Use try...catch block to append html to contents
*
* @param {Object} contents html element on which additional html is be appended
* @param {String} template underscore.js template string
* @param {Object} data template vars and their values
*/
function append_html_to_contents(contents, template, data) {
// underscore.js throws variable not defined error
// because of change of syntax in new versions.
// See: https://stackoverflow.com/a/25881231/8601393
try {
// this is the pre-1.7 syntax from Underscore.js
contents.append(
$u.template(
template,
data
)
);
}
catch (error) {
// this is the new syntax
contents.append(
$u.template(template)(data)
);
}
}

/*
* Search query override for hitting our local API instead of the standard
Expand All @@ -50,7 +23,7 @@ function attach_elastic_search_query_sphinx(data) {
var search_url = document.createElement('a');

search_url.href = data.proxied_api_host + '/api/v2/search/';
search_url.search = '?q=' + $.urlencode(query) + '&project=' + project +
search_url.search = '?q=' + encodeURIComponent(query) + '&project=' + project +
'&version=' + version + '&language=' + language;

/*
Expand All @@ -64,6 +37,48 @@ function attach_elastic_search_query_sphinx(data) {
}
};

/**
* Build a section with its matching results.
*
* @param {String} title.
* @param {String} link.
* @param {Array} contents.
*/
var buildSection = function (title, link, contents) {
var div_title = document.createElement("div");
var a_element = document.createElement("a");
a_element.href = link;
a_element.innerHTML = title;
div_title.appendChild(a_element);
html = div_title.outerHTML;
for (var i = 0; i < contents.length; i += 1) {
var div_content = document.createElement("div");
div_content.innerHTML = contents[i];
html += div_content.outerHTML;
}
return html;
};

/**
* Build a domain section.
*
* @param {String} title.
* @param {String} link.
* @param {String} content.
*/
var buildDomain = function (title, link, content) {
var div_title = document.createElement("div");
var a_element = document.createElement("a");
a_element.href = link;
a_element.innerHTML = title;
div_title.appendChild(a_element);

var div_content = document.createElement("div");
div_content.innerHTML = content;

return div_title.outerHTML + div_content.outerHTML;
};

search_def
.then(function (data) {
var results = data.results || [];
Expand All @@ -80,7 +95,7 @@ function attach_elastic_search_query_sphinx(data) {
title = xss(result.highlights.title[0]);
}

var link = result.path + "?highlight=" + $.urlencode(query);
var link = result.path + "?highlight=" + encodeURIComponent(query);

var item = $('<a>', {'href': link});

Expand All @@ -100,28 +115,6 @@ function attach_elastic_search_query_sphinx(data) {

var contents = $('<div class="context">');

var section_template =
'<div>' +
'<a href="<%= section_subtitle_link %>">' +
'<%= section_subtitle %>' +
'</a>' +
'</div>' +
'<% for (var i = 0; i < section_content.length; ++i) { %>' +
'<div>' +
'<%= section_content[i] %>' +
'</div>' +
'<% } %>';

var domain_template =
'<div>' +
'<a href="<%= domain_subtitle_link %>">' +
'<%= domain_subtitle %>' +
'</a>' +
'</div>' +
'<div>' +
'<%= domain_content %>' +
'</div>';

// if the result is page section
if (current_block.type === "section") {
var section = current_block;
Expand All @@ -145,15 +138,11 @@ function attach_elastic_search_query_sphinx(data) {
}
}

append_html_to_contents(
contents,
section_template,
{
section_subtitle_link: section_subtitle_link,
section_subtitle: section_subtitle,
section_content: section_content
}
);
contents.append(buildSection(
section_subtitle,
section_subtitle_link,
section_content
));
}

// if the result is a sphinx domain object
Expand All @@ -178,15 +167,11 @@ function attach_elastic_search_query_sphinx(data) {

var domain_subtitle = "[" + domain_role_name + "]: " + domain_name;

append_html_to_contents(
contents,
domain_template,
{
domain_subtitle_link: domain_subtitle_link,
domain_subtitle: domain_subtitle,
domain_content: domain_content
}
);
contents.append(buildDomain(
domain_subtitle,
domain_subtitle_link,
domain_content
));
}

contents.find('span').addClass('highlighted');
Expand Down
16 changes: 14 additions & 2 deletions readthedocs/core/static-src/core/js/readthedocs-doc-embed.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,22 @@ var search = require('./doc-embed/search');
}
}

domReady(function () {
function init() {
footer.init();
sphinx.init();
search.init();
sponsorship.init();
});
}

// Inject JQuery if isn't present already.
if (!window.jQuery) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's up if this line is executed first and then jQuery is loaded by a different extension/theme/etc?

I'm thinking about this scenario;

  1. this code is run and we inject jQuery
  2. another .js file is loaded that includes jQuery
  3. once domReady is called, we will have 2 different jQuery versions/files loaded

Shouldn't we inject jQuery synchronously inside domReady so we wait for all the scripts to be loaded first and avoid this scenario?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is going to be a problem anywhere we try to inject jquery, since the code to be executed after jquery is done loading is inside an asynchronous callback (onload). I think the only difference would be that the page won't be blocked till jquery is done downloading.

console.log("JQuery not found. Injecting.");
var script = document.createElement("script");
script.type = 'text/javascript';
script.src = "https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js";
script.onload = function () { domReady(init); };
document.head.appendChild(script);
} else {
domReady(init);
}
}());
Loading