I'm using sphinx to auto-generate html pages. The Table of Contents is really long so I'm trying to add a new html class (among other things) to the toctree's div so I can use a javascript library. Basically wanting to change how the toctree generates its HTML.
I've found the globaltoc.html file, put it in the _templates folder and uncommented the template_path in conf.py.
This is the file in the _templates directory.
{% extends '!globaltoc.html' %}
<div class="toctree-wrapper compound dhtmlxTree" id="toc", setImagePath="_static/imgs/csh_dhx_skyblue/">
{{ toctree() }}
</div>
If I'm doing this completely wrong please tell me another way to do this. I'd like to be able to this in pure reST, but it doesn't seem possible. I've looked at the limited examples on Sphinx templating and this is all I can find.
The overall goal of this is to use dhtmlxTree for use with a very large tree. I've already added the required .js files and .css files to layout.html. I just need the div that contains the toctree to have the class I need. I can get the results I need by editing it manually, now i need to automate it.
Thanks for your help.
I believe there are two possible solutions to my problem:
Using Jinja templates to write the javascript and the bulleted list. Currently, I'm not familiar with using the recursive Jinja flag. So this solution, while possible, may cause me more frustration than the second solution.
Simply reducing the :maxdepth: attribute for the toctree directive. It was set to 4. Reducing this number makes the Table of Contents smaller and therefore easier to read.
After thinking about the need to see all the layers, I realized it was just silly and it reduced the usefulness of the Table of Contents. So I just reduced the :maxdepth: to 2 and everything is back to the simplicity that reST and Sphinx offers.
Better design trumps the cool factor every time.
Related
I noticed on youtube that replies to each comment are inside a <div id="replies">. So the same id is used for every comment reply group.
When is it a good practice to give same ids to multiple similar elements?
I know ids should be unique, that's why I'm wondering about this.
To check it, go to a youtube video, inspect and select the reply area of a comment. Optionally, Ctrl+F in inspect and search replies.
YouTube uses web components which might be the reason there are multiple of the same IDs. Web components are encapsulated chunks of HTML, javascript, and CSS that you can drop into your pages. You can read more about them here: https://www.polymer-project.org/
So my thinking of why YouTube specifically has multiple of the same ID is that the replies component itself has an ID of replies and is being targeted on a component level rather than a global.
I hope this makes sense? Even if it doesn't, try to avoid ID's that aren't unique like the others mentioned.
One of the reason YouTube can have duplicate IDs, completely invalid looking html and still get away with it, it's because they are generating dynamic content. Remember, even though it is incorrect, the browser will render it just fine. They are not using the ID to mark a unique element, but more as metadata.
Note that Youtube uses custom html tags that I assume helps them reuse code for not just the website, but also for their app.
Read more about custom elements
Update: Just wanted to show an example on how generating content through an application can help you get away with things that could otherwise be a problem.
Writing Inline css is not recommended mainly because it becomes impossible to maintain the larger the css becomes. However, you can code it in an external file during development, then compile it to be inline using an application and have none of the headaches.
See example
newbie question.
I've read some of the W3Schools, I also read a lot from other sources on the internet, however I can't find what I need, and I'm sure it's quite simple to you.
I'm using ASP.Net, and I want to add to my website, multiple items, which every item hold a picture, and some other information, including links. I'm pretty sure I don't need to write the code for every item in the HTML source, and I don't know exactly how to implement my this.
The basic idea is that my items will be imported from a Database that I create in visual studio, and I want to style my webpage so they would appear in a certain formation, I thought I might need to use Javascript or CSS for this, hope I'm not mistaken.
Javascript isn't some sort of magician that will render all your stuff on its own. However, you can use it to attach a template to every of your items.
What you have to do is :
Create a base HTML template for 1 of your item that can be applied to all of them
Create a Javascript function that will attach thoses CSS classes and HTML attributes to every element out of your DB (or you could use a templating frameork .. since there's a lot of them I'll let you look for it on Google. It's pretty easy to use)
On page load or whatever event you want to bind on, you call your function which will attach the CSS and HTML to every element out of your DB and will render it on your page
Enjoy what you've done.
I hope this helps. Good luck ! ;)
I am working on a simple Cordova app with about 4 page types and I am trying to think through which is the better way to handle the inner HTML templates.
Hidden HTML hard coded into the HTML files that is hidden and populated/revealed by my JS.
Using a JS template system and appending and removing from the DOM.
I feel that appending all that to the DOM for a page is inefficient when I could just update the sections that change. But perhaps an append is lightweight enough where I shouldn't worry about it.
There are a number of ways you can do it. In terms of load on the browser. That is hard to say. From your question it is hard to know what is in these pages, what are you displaying, is it live data, static html etc.
When you first plot out an app, if you are from the old class of building multiple page websites, it can be a little concerning as to how well your app/page will run with all those pages crammed in to one, and all that data plus code.
The answer is, amazingly well. If done properly in modern browsers, and for example Ipads the app will run to near native performance.
The options you have are
Map all the pages into one HTML document. Hide each page content using css display:none, flip them into view using css animation, fading or just display:block.
Use a javascript routing library to map urls to blocks of code that deal with each page, this makes mapping out your app much easier, and means that buttons can just link to your pages, like a real website. see http://projects.jga.me/routie/
Building all the page templates into one page can make it hard to code, as the page becomes enormous, consider breaking the inner content of each page into separate files, you can then give each page holder a url and use a small xhr request to load the page on-the fly, once loaded you can cache it into memory or even local-storage, depending on whether you remove it when it is closed or keep it hidden.
In my experience you can put an enormous number or nodes into one page and have very little speed drop, bear in mind if you use something like jquery and do a lot of $(".page > .page1 > .items li") your going to have a slow app.
Tips
Use element ID's everywhere document.getElementById(..) is 100's of times faster in a loop that $(...)
cache elements when you find them, if you need them later store them in a memory cache.
keep for loop inner code to a minimum.
use a decent click touch libary like http://hammerjs.github.io/ and delegate all the events of the body tag or at least on each page.
If you need to touch the server, load data, think dom first, device second server later. A good app is a responsive app, that responds to the user instantly.
I know this has been posted a while ago, but for the sake of the users I am going to add my answer.
I completely agree with MartinWebb but my answer will shed some light on the results of his options. I am currently working on a similar project. Please note that this answer pertains to cordova (previously called phonegap) specifically. My app has about 5 pages with +-20 different components (input's, div's, h1's, p's, etc.). This is what i tried and the result of each:
jQuery was my first option, mainly because it is easy to use and reduces the amount of code required to accomplish a said goal. Result: First time I tried this approach I though I would spice it up with animations and transformations. The result of this was a very unresponsive app. I removed the animation and transformation, however due to the nature of my application I required multiple dynamically added components and jQuery just wasn't up for the task.
Css display:none and visible:hidden was my next option. I used javascript's dom to display certain div's. Result: This works if your not planning on switching many div shortly after one another eg. a simple menu. It quickly became apparent that this wasn't going to work. Also this does not eliminate my need for the dom. Remember document.getElementById('menu').style.display = "none"; is still part of the dom. This as a solution, for me, is poor. There is a reason that var menu= document.createElement('div'); is part of the language. Which brings me to my last option.
Building a page 90% on javascript's dom was my last option. Logically I could not see how 600 lines of code cold trump one .innerHTML or .style.display = "block"; but it did. Result: It was by far the most responsive of all the solutions.
I'm not saying that all webpages should be coded with dom appending, but as I stated previously, for a cordova app of a few pages (<6), with a few components a javascript dom appending approach would be best. It takes longer to code, but you will be rewarded with control and efficiency. I would suggest coding the backbone of your app in html and populating and controlling with javascript's dom.
Best of luck.
The first option, <div>s with display:none; would be more efficient by a small margin, but you can get the best of both worlds by compiling your JavaScript and templates together into a single file using something like browserify or require.js.
The most obvious example I can think of is for outputting nested comments. Let's say you have a tree of comments and you want to output it as nested html (let's say lists inside lists or divs inside divs) using your template.
The "comment" block/function/tag/helper/whatever would have to be able to call itself somehow for the comment's children.
Are there template engines that would support that sort of thing inside one template file?
I am aware that you can just pre-compute the "indent" or "depth-level" of each comment and send them to the template as one flat list in the correct order, but let's just say I don't want that. And let's say I don't want to stitch snippets together in code / outside the template - I want the whole page self contained in one template or theme file.
Update: I want to generate nested html. I want the comments to be nested, not appear nested. I know how to indent things with CSS. :) Whether it is done in the browser or on the server is irrelevant because the point is I want the template to be self-contained in one file.
As in:
var html = render(template, {comments: aTreeOfNestedComments});
(see? that could be node.js, a brower plugin, some "jQuery" as some people like to call javascript these days...) It looks like jade can do this using mixins. Any tag-based templating engines that can do something similar?
Template engines can solve generic, run-off-the-mill problems. While nesting templates seems like a common use case, I haven't encountered many template engines who can do that.
Since the market didn't offer a good solution, I'm building my applications from JavaScript objects that know how to render themselves. I never use templates; every block gets a reference to the DOM (like the parent element to which is should attach itself) or the renderers return the child container and the parent element can add that in a suitable place.
This allows me to use the full power of JS without the limitations of template engines.
[EDIT] Here is a workaround: If you need a recursive element, add a span (if the recursive element should be inline) or div (if it's a block element). Give it the class recursiveTemplate and a data attribute data-template-name="..."
Run the template with your standard template engine. Afterwards, use jQuery or the like to find all elements with the class recursiveTemplate and replace them yourself.
Distal templates has an example here of a nested tree:
http://code.google.com/p/distal/wiki/UseCaseExamples#Building_a_nested_tree
as #TJHeuvel said, you can use the server side script to produce the desired otput, this would be the best way to do what you require. However if you must use JavaScript, I would advise jQuery this will also allow you to product the desired result.
for example:
$("ul li").css("margin-left", "10px");
I have been tasked with improving the current mess that is our JavaScript "strategy"; we're an online shopping company and my boss has given me time to do this properly. He is very keen on keepin this modular and increase the reusability of the components.
Our HTML is being rendered with JSP and we have lots of custom tags writing out, for example, information about products without the web designers needing to worry about it.
Now, we want to do similar things with JavaScript. The web designers should be given a set of custom tags, like, say,
<foo:draggable>
... some HTML here ...
</foo:draggable>
that will wrap the HTML in a <div> with a drag bar at the top and a close button.
My idea is to mark the div with a unique namespaced CSS class name, like foo_draggable, and then put all my functions in a single JS file. That JS file then sees if there are elements with the CSS class foo_draggable in the DOM and if it finds any it will attach the required event handlers.
However, I am worried about scaling problems, and wondering whether it is a good idea to have lots of selector queries running when they quite often aren't going to be used.
The first alternative would be to initiate each draggable item explicitly but that would mean putting <script> tags all over the place. The second approach would be to not put all UI function in one file but rather just download the ones I need, but that would mean lots more HTTP requests and slower page load speed.
Has anyone got experience with this?
What about having two classnames?
<div class='foo fooDragable'></div>
<div class='foo fooSortable'></div>
You add the class 'foo' to all your elements that require javascript modification.
Your javascript has to check the dom only once for foo.
var $foo = $('.foo');
Afterwards you can search within this array which should be way smaller than the complete dom.
var $dragAble = $foo.filter('.fooDragable');
Have you considered or taken a look to JSF? I know it's a major change if you aren't using JSF yet. But there are lot of ready-to-use JSF component libaries with an ajaxical sauce, for example RichFaces, IceFaces, PrimeFaces, etc. It's almost a waste of time to create components/tags for it yourself.
Alternatively you can replace all Javascripts to use the great jQuery JS framework.
Depending on how many separate components you have, the extra overhead of running the selectors might not be a big deal. You can initialize all the components just the once, when the page is loaded. Anything that's not present on the page simply won't get initialized, and will incur no further overhead. In most JavaScript frameworks, selecting by classname (or tag name) is pretty fast. It's only the complex selectors, which aren't natively supported by the browser, that are slow.
If you have a few commonly used components, and then a set of less commonly used ones, it may be worth splitting those up. Keep the commonly used components in a single JavaScript file (minified, served with compression and aggressive caching), and load that in every page, regardless of whether it's needed or not. Caching will ensure it's only downloaded once, and it'll only be one small HTTP request. For the less common components, keep them in separate files (ideally, one per component), and add a script tag on pages that use them.
I'm not entirely familiar with how JSP works, but it might be possible to do this automatically - if a tag is included in the document, add a script tag for foo_widget.js in the document header, or something like that.