Breadcrumb navigation

[mackski]

Breadcrumbs would be good for deeper navigation without having to back in browser or start from spec homepage again.

[ndelangen]

Yes I agree, this would be usefull for my project as well!

I might want to try and develop this feature, should this be a plugin or can this be a core feature?

[ndelangen]

I've got it working: https://github.com/ndelangen/sourcejs-Source/tree/ndelangen/breadcrumb-in-header

But I need feedback from @operatino whether this is as he envisioned such a feature. I've added this via the wrap.js middleware in core.

[mackski]

It would be better to use the meta data in info.json file and display title rather than a friendly file name.
The styling doesn't work for me.

[ndelangen]

Good point! I'll give it some thought on how to display the info.json names.

Regarding styling not working, I think you need to run npm run build once for that to work, styling I provided is minimal, since I'm not even sure this is a feature supposed to be in core.

[robhrt7]

Hi,

I totally like the idea with having breadcrumbs in the core. We were discussing it before with our team, had same requests before. Looking forward to your contribution!

Will be glad to help with making this work. Some initial thoughts about the implementation:

1. It should be done server-side, as we try to move most of this kind of features to server, without messing the client side part.
2. wrap.js is not the place to do it, because of separation of concerns. There's a special folder for this kind of middleware - /core/middlewares, breadcrumbs should be in the separate file.
3. I think the most scalable way of adding the UI is to create a special tag for EJS template like <%- breadcrumbs %>. Middleware will fill the variable with rendered HTML, and then user can choose where to put it, similar to engine version number -

   Source/core/middlewares/read.js

   Line 85 in 866e45d

   engineVersion: global.engineVersion,

   ,

   Source/assets/templates/footer.inc.html

   Line 12 in 866e45d

   Copyright © 2013-2015 <a href="http://sourcejs.com" class="source_a_l">Sourcejs.com</a> <span class="source_footer_version">(v.<%- engineVersion %>)</span>

   .
4. Breadcrumps template should be done with EJS and configured same as other core templates -

   Source/options.js

   Line 91 in 866e45d

   views: {

   .

Regarding the note from Gitter:

I see some potential problem with this, but it existed before this:
header.inc.html isn't an ejs template right now, it's used and embedded clientside when the header is missing, as a static html file. I don’t know exactly when or why this would happen, maybe this functionality is redundant?
With this change that would render improperly, showing the newly added ejs templating. But header.inc.html IS already used as a ejs template in wrap.js middleware. So it would seem to be meant as a dynamic template. Which would seem totally sane to me. In my project I’ve created a custom header.inc.html just to add a header navigation. I think this would also be good to create from options or from routes?

We'll move all the templates to use EJS and render on server side mostly, in case where it really be require to render client side as well, it will be still EJS with same data sets. But anyway, header and footer that are in some cases injected on client side is a legacy thing, which will be removed from the core.

This problem will be also less relevant, when we'll prepare whole HTML on the server, and fill in <%- breadcrumbs %> with already rendered version.

[ndelangen]

I'll refactor and submit a PR. 👍

[ndelangen]

I've been refactoring, but I've not been able to make it work so far, I'll need some help @operatino .

I updated my feature-branch. It's broken at this stage.
https://github.com/ndelangen/sourcejs-Source/tree/ndelangen/breadcrumb-in-header

What I think is going on: the same EJS-template is attempted to be rendered, once with part A of the data (head, header, footer), and a second time with breadcrumbs. But the first time EJS exits with an error: It cannot resolve 'breadcrumb'.

breadcrumb is not defined
    at eval (eval at <anonymous> (/sourcejs/node_modules/ejs/lib/ejs.js:495:12), <anonymous>:32:16)
    at returnedFn (/sourcejs/node_modules/ejs/lib/ejs.js:524:17)
    at exports.render (/sourcejs/node_modules/ejs/lib/ejs.js:345:37)
    at Object.ejs.render (/sourcejs/core/ejsWithHelpers.js:147:12)
    at /sourcejs/core/middlewares/wrap.js:116:49
    at /sourcejs/node_modules/graceful-fs/graceful-fs.js:76:16
    at tryToString (fs.js:414:3)
    at FSReqWrap.readFileAfterClose [as oncomplete] (fs.js:401:12)

Is there some option for EJS to ignore parts that it cannot resolve? And have it render the output of the earlier render with new data? I doubt this is intended use of EJS.

If you see some way of making this work, that be awesome!

[robhrt7]

Hi, @ndelangen!

I'll check what's going on with your version, seems like some small bit is missing to make whole thing running.

Regarding checks in EJS for data that may not exist, you can just do typeof foo !== 'undefined', since it's possible to use regular JS in EJS templates.

[ndelangen]

Does, making the error go away like that, solve the problem though? Since the template has already been provided with data once and rendered, I'm assuming all the EJS tags are removed/replaced? Thus a second iteration would not template/change anything, and breadcrumbs would simple not be shown?

[ndelangen]

Ah I see, the ejs spec templating is still done in wrap.js, but wrap.js is provided with additional data from the breadcrumb middleware. I have it working, will work on styling a bit tomorrow, and update the PR.

Do you have a good idea how to retrieve a spec's title, based on URL @operatino ? As @mackski suggests here, I'd be nice to display the real title instead of just the url-fragment. Is there some sitemap already generated somewhere? If not, that could be useful to make?

[robhrt7]

@ndelangen The recommended way is to always set Spec Title in the info.json file, so it could be used for automatic templating, and things like breadcrumbs.

In your middleware, you can fetch Spec Info with https://github.com/sourcejs/Source/blob/0.6.0-dev/core/lib/specUtils.js#L56, and use human readable title instead of URL. Same goes for parent folders/catalogs.

[ndelangen]

It's in!, updated my PR.

[robhrt7]

Looks cool! I'll give it a review as fast as possible.

[robhrt7]

Done 1f3b006

[mspkom]

Thanks for including the breadcrumbs to the project. Is there an "getting started" or an example how to use it in the specs?

[robhrt7]

@mspkom, you need to update the spec.ejs template you got with the starting project, adding there <%- breadcrumb %> tag. Just the same as @ndelangen did in his PR with default templates 1f3b006#diff-57ec3415e65bb12f7c2a7fcefb87a91cR27.

[mspkom]

Thanks so far, but I think, I still have a problem with the version. Installing or updating it with yo, I still have the version 0.4.2 on my computer. I guess, that is the problem.

[robhrt7]

Yes, you should have 0.6.0-dev version to make it work. I highly recommend using NPM install path, the transition for the existing project should be almost seamless.

The old project structure, when user folder is a child of SourceJS will be deprecated in 0.6.0, and dropped with 0.7 release.

[mspkom]

Thanks a lot for the good and fast support. You guys do really great work.

[ndelangen]

Glad to hear the breadcrumbs are liked!