diff --git a/lib/jsduck/app.rb b/lib/jsduck/app.rb index 79d38aa28910a9347ec9d872ce5f59f6f51265a4..ed8a39c323a074b77b42857e217bd7bee4ecb35e 100644 --- a/lib/jsduck/app.rb +++ b/lib/jsduck/app.rb @@ -215,7 +215,7 @@ module JsDuck # Given all classes, generates namespace tree and writes it # in JSON form into a file. def write_tree(filename, relations) - tree = Tree.new.create(relations.classes) + tree = Tree.new.create(relations.classes, @guides) icons = TreeIcons.new.extract_icons(tree) js = "Docs.classData = " + JSON.generate( tree ) + ";" js += "Docs.icons = " + JSON.generate( icons ) + ";" diff --git a/lib/jsduck/guides.rb b/lib/jsduck/guides.rb index 62f66cf7344b3f0fc54bd8f8eadcb4b39d5b77de..a6cd3cfab32a8e813344048fa30a635a2d84b910 100644 --- a/lib/jsduck/guides.rb +++ b/lib/jsduck/guides.rb @@ -95,6 +95,16 @@ module JsDuck EOHTML end + # Iterates over each guide + def each(&block) + @guides.each &block + end + + # Returns number of guides + def length + @guides.length + end + end end diff --git a/lib/jsduck/tree.rb b/lib/jsduck/tree.rb index 19dfab5f5ea569ed672700d8bd0cf13c31f29be8..56fb895f2542360d1cd9dd6d6054dfea4112a492 100644 --- a/lib/jsduck/tree.rb +++ b/lib/jsduck/tree.rb @@ -20,9 +20,10 @@ module JsDuck # Given list of class documentation objects returns a # tree-structure that can be turned into JSON that's needed by # documentation browser interface. - def create(docs) + def create(docs, guides=[]) docs.each {|cls| add_class(cls) } sort_tree(@root) + add_guides(guides) @root end @@ -34,10 +35,10 @@ module JsDuck # Comparson method that sorts package nodes before class nodes. def compare(a, b) - if a[:isClass] == b[:isClass] + if a[:leaf] == b[:leaf] a[:text].casecmp(b[:text]) else - a[:isClass] ? 1 : -1 + a[:leaf] ? 1 : -1 end end @@ -64,12 +65,20 @@ module JsDuck package end + # When guides list not empty, add guides to tree + def add_guides(guides) + if guides.length > 0 + pkg = package_node("guides") + guides.each {|g| pkg[:children] << guide_node(g) } + @root[:children] << pkg + end + end + # Given full doc object for class creates class node def class_node(cls) return { :text => cls.short_name, - :clsName => cls.full_name, - :isClass => true, + :url => "/api/"+cls.full_name, :iconCls => class_icon(cls), :leaf => true } @@ -93,6 +102,16 @@ module JsDuck :children => [] } end + + # Given full guide object creates guide node + def guide_node(guide) + return { + :text => guide[:title], + :url => "/guide/"+guide[:name], + :iconCls => "icon-guide", + :leaf => true + } + end end end diff --git a/lib/jsduck/tree_icons.rb b/lib/jsduck/tree_icons.rb index 2aca51a70b784e3966b8a69d93bd5808d509343f..d5022368ea3153d65e20884d131cd7a61925f28f 100644 --- a/lib/jsduck/tree_icons.rb +++ b/lib/jsduck/tree_icons.rb @@ -10,7 +10,7 @@ module JsDuck icons.merge!(extract_icons(child)) end else - icons[node[:clsName]] = node[:iconCls] + icons[node[:url]] = node[:iconCls] end icons end diff --git a/spec/tree_icons_spec.rb b/spec/tree_icons_spec.rb index 0b6725eb2015e1b2a80edc662750171cc58b9a8e..d71fe54213d1b611df29023b0ea69a95a120a92a 100644 --- a/spec/tree_icons_spec.rb +++ b/spec/tree_icons_spec.rb @@ -4,50 +4,36 @@ describe JsDuck::TreeIcons do before do @icons = JsDuck::TreeIcons.new.extract_icons({ - :clsName => "apidocs", + :id => "apidocs", :iconCls => "icon-docs", :text => "API Documentation", - :singleClickExpand => true, :children => [ { :clsName => "pkg-SamplePackage", :text => "SamplePackage", :iconCls => "icon-pkg", :cls => "package", - :singleClickExpand => true, :children => [ { - :href => "output/SamplePackage.Component.html", :text => "Component", - :clsName => "SamplePackage.Component", - :isClass => true, + :url => "/api/SamplePackage.Component", :iconCls => "icon-cmp", - :cls => "cls", :leaf => true }, { - :href => "output/SamplePackage.Singleton.html", :text => "Singleton", - :clsName => "SamplePackage.Singleton", - :isClass => true, + :url => "/api/SamplePackage.Singleton", :iconCls => "icon-static", - :cls => "cls", :leaf => true }, { - :clsName => "pkg-SamplePackage", :text => "sub", :iconCls => "icon-pkg", - :cls => "package", - :singleClickExpand => true, :children => [ { - :href => "output/SamplePackage.sub.Foo.html", :text => "Foo", - :clsName => "SamplePackage.sub.Foo", - :isClass => true, + :url => "/api/SamplePackage.sub.Foo", :iconCls => "icon-cls", - :cls => "cls", :leaf => true }, ] @@ -63,12 +49,12 @@ describe JsDuck::TreeIcons do end it "extracts icons inside a package" do - @icons["SamplePackage.Component"].should == "icon-cmp" - @icons["SamplePackage.Singleton"].should == "icon-static" + @icons["/api/SamplePackage.Component"].should == "icon-cmp" + @icons["/api/SamplePackage.Singleton"].should == "icon-static" end it "extracts icons inside all subpackages too" do - @icons["SamplePackage.sub.Foo"].should == "icon-cls" + @icons["/api/SamplePackage.sub.Foo"].should == "icon-cls" end end diff --git a/spec/tree_spec.rb b/spec/tree_spec.rb index 484116b0d5e439b560ffbea12e17807825d8cfab..239d12ec63db6180d0b2e6759312c8b87daf0056 100644 --- a/spec/tree_spec.rb +++ b/spec/tree_spec.rb @@ -44,16 +44,8 @@ describe JsDuck::Tree do shared_examples_for "all class nodes" do - it "with isClass = true" do - @class[:isClass].should == true - end - - it "with cls = 'cls'" do - @class[:isClass].should == true - end - - it "with clsName being full class name" do - @class[:clsName].should == @full_class_name + it "with url being full class URL" do + @class[:url].should == @full_class_url end it "with text being short class name" do @@ -70,7 +62,7 @@ describe JsDuck::Tree do before do @class = @tree[:children][0][:children][0] @short_class_name = "SampleClass" - @full_class_name = "SamplePackage.SampleClass" + @full_class_url = "/api/SamplePackage.SampleClass" end it_should_behave_like "all class nodes" @@ -85,7 +77,7 @@ describe JsDuck::Tree do before do @class = @tree[:children][0][:children][1] @short_class_name = "Singleton" - @full_class_name = "SamplePackage.Singleton" + @full_class_url = "/api/SamplePackage.Singleton" end it_should_behave_like "all class nodes" @@ -109,15 +101,15 @@ describe JsDuck::Tree, "lowercase package name" do end it "gets root package node" do - @root[:isClass].should_not == true + @root[:leaf].should_not == true end it "gets middle package node" do - @middle[:isClass].should_not == true + @middle[:leaf].should_not == true end it "gets leaf class node" do - @leaf[:isClass].should == true + @leaf[:leaf].should == true end end @@ -133,11 +125,11 @@ describe JsDuck::Tree, "uppercase package name" do end it "gets root package node" do - @root[:isClass].should_not == true + @root[:leaf].should_not == true end it "gets middle class node" do - @middle[:isClass].should == true + @middle[:leaf].should == true end it "gets class name containing package name" do @@ -170,3 +162,33 @@ describe JsDuck::Tree do end end + +describe JsDuck::Tree do + + before do + @tree = JsDuck::Tree.new.create( + [JsDuck::Class.new({:tagname => :class, :name => "Foo"})], + [{:name => "g1", :title => "Guide 1"}, {:name => "g2", :title => "Guide 2"}] + ) + end + + it "places guides last" do + @tree[:children][1][:text].should == 'guides' + @tree[:children][1][:children].length.should == 2 + end + +end + +describe JsDuck::Tree do + + before do + @tree = JsDuck::Tree.new.create( + [JsDuck::Class.new({:tagname => :class, :name => "Foo"})] + ) + end + + it "doesn't add guides if there aren't any" do + @tree[:children].length.should == 1 + end + +end diff --git a/template/app/Favorites.js b/template/app/Favorites.js index 2008c04b122ac6640cec5bf2be7b14d3cf91a11f..622c38d72d1299e48482b5771ed52cc0381a315c 100644 --- a/template/app/Favorites.js +++ b/template/app/Favorites.js @@ -11,18 +11,21 @@ Ext.define("Docs.Favorites", { // Populate favorites with Top 10 classes if (this.store.data.items.length == 0) { - this.store.add([ - { cls: 'Ext.data.Store' }, - { cls: 'Ext' }, - { cls: 'Ext.grid.Panel' }, - { cls: 'Ext.panel.Panel' }, - { cls: 'Ext.form.field.ComboBox' }, - { cls: 'Ext.data.Model' }, - { cls: 'Ext.form.Panel' }, - { cls: 'Ext.button.Button' }, - { cls: 'Ext.tree.Panel' }, - { cls: 'Ext.Component' } - ]); + var top10 = [ + 'Ext.data.Store', + 'Ext', + 'Ext.grid.Panel', + 'Ext.panel.Panel', + 'Ext.form.field.ComboBox', + 'Ext.data.Model', + 'Ext.form.Panel', + 'Ext.button.Button', + 'Ext.tree.Panel', + 'Ext.Component' + ]; + this.store.add(Ext.Array.map(top10, function(clsName) { + return {url: "/api/"+clsName, title: clsName}; + })); this.syncStore(); } @@ -37,38 +40,39 @@ Ext.define("Docs.Favorites", { }, /** - * Adds class to favorites + * Adds page to favorites * - * @param {String} cls the class to add + * @param {String} url the page to add + * @param {String} title title for Favorites entry */ - add: function(cls) { - if (!this.has(cls)) { - this.store.add({cls: cls}); + add: function(url, title) { + if (!this.has(url)) { + this.store.add({url: url, title: title}); this.syncStore(); - this.tree.setFavorite(cls, true); + this.tree.setFavorite(url, true); } }, /** - * Removes class from favorites. + * Removes page from favorites. * - * @param {String} cls the class to remove + * @param {String} url the page URL to remove */ - remove: function(cls) { - if (this.has(cls)) { - this.store.removeAt(this.store.findExact('cls', cls)); + remove: function(url) { + if (this.has(url)) { + this.store.removeAt(this.store.findExact('url', url)); this.syncStore(); - this.tree.setFavorite(cls, false); + this.tree.setFavorite(url, false); } }, /** - * Checks if class is in favorites + * Checks if page exists in favorites * - * @param {String} cls the classname to check - * @return {Boolean} true when class exists in favorites. + * @param {String} url the URL to check + * @return {Boolean} true when present */ - has: function(cls) { - return this.store.findExact('cls', cls) > -1; + has: function(url) { + return this.store.findExact('url', url) > -1; } }); diff --git a/template/app/History.js b/template/app/History.js index fd0d8326c5a3ddf262a5121343799590da48692a..8f4cc36fd678076d95c1566527eb9d92730ae93e 100644 --- a/template/app/History.js +++ b/template/app/History.js @@ -18,10 +18,10 @@ Ext.define("Docs.History", { navigate: function(token) { var url = this.parseToken(token); if (url.type === "api") { - Docs.App.getController('Classes').loadClass(url.key, true); + Docs.App.getController('Classes').loadClass(url.url, true); } else if (url.type === "guide") { - Docs.App.getController('Classes').showGuide(url.key, true); + Docs.App.getController('Classes').showGuide(url.url, true); } else { Ext.getCmp('card-panel').layout.setActiveItem(0); @@ -31,7 +31,7 @@ Ext.define("Docs.History", { // Parses current browser location parseToken: function(token) { var matches = token && token.match(/\/(api|guide)\/(.*)/); - return matches ? {type: matches[1], key: matches[2]} : {}; + return matches ? {type: matches[1], url: matches[0]} : {}; }, /** diff --git a/template/app/controller/Classes.js b/template/app/controller/Classes.js index 929853886eb789c3b40d98dbac80334fc69b272a..47e787cc1331cb0b8fb26a5a80bd61bb3f2a958d 100644 --- a/template/app/controller/Classes.js +++ b/template/app/controller/Classes.js @@ -69,7 +69,7 @@ Ext.define('Docs.controller.Classes', { ); Ext.getBody().addListener('click', function(event, el) { - this.opensNewWindow(event) ? window.open(el.href) : this.loadClass(el.rel); + this.handleUrlClick(el.href, event); }, this, { preventDefault: true, delegate: '.docClass' @@ -77,20 +77,20 @@ Ext.define('Docs.controller.Classes', { this.control({ 'classtree': { - classclick: function(cls, event) { - this.handleClassClick(cls, event, this.getTree()); + urlclick: function(url, event) { + this.handleUrlClick(url, event, this.getTree()); } }, 'classgrid': { - classclick: function(cls, event) { - this.handleClassClick(cls, event, this.getFavoritesGrid()); + urlclick: function(url, event) { + this.handleUrlClick(url, event, this.getFavoritesGrid()); } }, 'indexcontainer': { afterrender: function(cmp) { cmp.el.addListener('click', function(event, el) { - this.opensNewWindow(event) ? window.open(el.href) : this.showGuide(el.rel); + this.handleUrlClick(el.href, event); }, this, { preventDefault: true, delegate: '.guide' @@ -120,13 +120,21 @@ Ext.define('Docs.controller.Classes', { // We don't want to select the class that was opened in another window, // so restore the previous selection. - handleClassClick: function(cls, event, view) { + handleUrlClick: function(url, event, view) { + // Remove everything up to # + url = url.replace(/.*#/, ""); + if (this.opensNewWindow(event)) { - window.open("#/api/" + cls); - view.selectClass(this.currentCls ? this.currentCls.name : ""); + window.open(url); + view && view.selectUrl(this.activeUrl ? this.activeUrl : ""); } else { - this.loadClass(cls); + if (/^\/api\//.test(url)) { + this.loadClass(url); + } + else { + this.showGuide(url); + } } }, @@ -144,32 +152,28 @@ Ext.define('Docs.controller.Classes', { /** * Loads class. * - * @param {String} clsUrl name of the class + optionally name of the method, separated with dash. + * @param {String} url name of the class + optionally name of the method, separated with dash. * @param {Boolean} noHistory true to disable adding entry to browser history */ - loadClass: function(clsUrl, noHistory) { - var cls = clsUrl; - var member; - - if (this.activeUrl == clsUrl) return; - this.activeUrl = clsUrl; + loadClass: function(url, noHistory) { + if (this.activeUrl === url) return; + this.activeUrl = url; if (!noHistory) { - Docs.History.push("/api/" + clsUrl); + Docs.History.push(url); } Ext.getCmp('card-panel').layout.setActiveItem(1); // separate class and member name - var matches = clsUrl.match(/^(.*?)(?:-(.*))?$/); - if (matches) { - cls = matches[1]; - member = matches[2]; - } + var matches = url.match(/^\/api\/(.*?)(?:-(.*))?$/); + var cls = matches[1]; + var member = matches[2]; if (this.cache[cls]) { this.showClass(this.cache[cls], member); - } else { + } + else { if (this.getOverview()) { this.getOverview().setLoading(true); } @@ -197,7 +201,7 @@ Ext.define('Docs.controller.Classes', { this.getOverview().setLoading(false); - this.getTree().selectClass(cls.name); + this.getTree().selectUrl("/api/"+cls.name); this.fireEvent('showClass', cls.name); } @@ -210,16 +214,16 @@ Ext.define('Docs.controller.Classes', { this.currentCls = cls; - this.getFavoritesGrid().selectClass(cls.name); + this.getFavoritesGrid().selectUrl("/api/"+cls.name); }, - showGuide: function(name, noHistory) { - - if (this.activeUrl == name) return; - this.activeUrl = name; + showGuide: function(url, noHistory) { + if (this.activeUrl === url) return; + this.activeUrl = url; - noHistory || Docs.History.push("/guide/" + name); + noHistory || Docs.History.push(url); + var name = url.match(/^\/guide\/(.*)$/)[1]; Ext.data.JsonP.request({ url: this.getBaseUrl() + "/guides/" + name + "/README.js", callbackName: name, @@ -229,6 +233,8 @@ Ext.define('Docs.controller.Classes', { Ext.getCmp('card-panel').layout.setActiveItem(2); Docs.Syntax.highlight(Ext.get("guide")); this.fireEvent('showGuide', name); + this.getTree().selectUrl(url); + this.getFavoritesGrid().selectUrl(url); }, scope: this }); diff --git a/template/app/controller/Search.js b/template/app/controller/Search.js index 4bb891870e226c313ad5085ffc2e56d5378cedbf..752635424b1701e84f02bf403113a43098fd019c 100644 --- a/template/app/controller/Search.js +++ b/template/app/controller/Search.js @@ -97,7 +97,7 @@ Ext.define('Docs.controller.Search', { if (record.get("type") !== 'cls') { name += '-' + record.get("type") + '-' + record.get("member"); } - Docs.App.getController('Classes').loadClass(name); + Docs.App.getController('Classes').loadClass("/api/"+name); this.getDropdown().hide(); }, diff --git a/template/app/model/Favorite.js b/template/app/model/Favorite.js index 14ab7f69a60b7098394060f026be26a86a9b11c3..b04bfc6344400b929ea5079a7f975acd9d1a79cd 100644 --- a/template/app/model/Favorite.js +++ b/template/app/model/Favorite.js @@ -2,7 +2,7 @@ * Favorite classes */ Ext.define('Docs.model.Favorite', { - fields: ['id', 'cls'], + fields: ['id', 'url', 'title'], extend: 'Ext.data.Model', proxy: { type: ('localStorage' in window && window['localStorage'] !== null) ? 'localstorage' : 'memory', diff --git a/template/app/view/ClassGrid.js b/template/app/view/ClassGrid.js index 7917dd80a8988c28c598fe2a9a228a6186a815fa..a8977f87bbc3140f67da7669ec5b5179999cfc47 100644 --- a/template/app/view/ClassGrid.js +++ b/template/app/view/ClassGrid.js @@ -23,16 +23,16 @@ Ext.define('Docs.view.ClassGrid', { initComponent: function() { this.addEvents( /** - * @event classclick + * @event * Fired when class in grid clicked. - * @param {String} name Name of the class that was selected. For example "Ext.Ajax". + * @param {String} url URL of the page that was selected. For example "/api/Ext.Ajax". * @param {Ext.EventObject} e */ - "classclick", + "urlclick", /** - * @event closeclick + * @event * Fired when close button in grid clicked. - * @param {String} name Name of the class that was closed. For example "Ext.Ajax". + * @param {String} url URL of the page that was closed. For example "/api/Ext.Ajax". */ "closeclick" ); @@ -40,14 +40,14 @@ Ext.define('Docs.view.ClassGrid', { this.columns = [ { width: 18, - dataIndex: 'cls', - renderer: function(cls, data) { - data.tdCls = this.icons[cls]; + dataIndex: 'url', + renderer: function(url, data) { + data.tdCls = this.icons[url]; }, scope: this }, { - dataIndex: 'cls', + dataIndex: 'title', flex: true } ]; @@ -60,7 +60,7 @@ Ext.define('Docs.view.ClassGrid', { icon: 'resources/images/x12.png', tooltip: 'Delete', handler: function(view, rowIndex) { - this.fireEvent("closeclick", this.getStore().getAt(rowIndex).get("cls")); + this.fireEvent("closeclick", this.getStore().getAt(rowIndex).get("url")); }, scope: this } @@ -70,28 +70,28 @@ Ext.define('Docs.view.ClassGrid', { this.callParent(arguments); this.on("itemclick", function(view, record, item, index, event) { - // Don't fire classclick when close button clicked + // Don't fire urlclick when close button clicked if (!event.getTarget("img")) { - this.fireEvent("classclick", record.get("cls"), event); + this.fireEvent("urlclick", record.get("url"), event); } }, this); // Initialize selection after rendering this.on("afterrender", function() { - this.selectClass(this.selectedClass); + this.selectUrl(this.selectedUrl); }, this); }, /** - * Selects class if grid contains such class. + * Selects page if grid contains such. * Fires no events while selecting. - * @param {String} cls class name. + * @param {String} url page URL. */ - selectClass: function(cls) { - this.selectedClass = cls; + selectUrl: function(url) { + this.selectedUrl = url; // when grid hasn't been rendered yet, trying to select will give us error. if (this.rendered) { - var index = this.getStore().findExact('cls', cls); + var index = this.getStore().findExact('url', url); this.selectIndex(index); } }, diff --git a/template/app/view/tree/Tree.js b/template/app/view/tree/Tree.js index 38abeebd2e8fb242be71885edc22dacfd4bf8b27..78be81f4b7e93f1c775661b6ceef2dd1cbac666f 100644 --- a/template/app/view/tree/Tree.js +++ b/template/app/view/tree/Tree.js @@ -9,7 +9,6 @@ Ext.define('Docs.view.tree.Tree', { ], cls: 'class-tree iScroll', - folderSort: true, useArrows: true, rootVisible: false, @@ -20,11 +19,11 @@ Ext.define('Docs.view.tree.Tree', { this.addEvents( /** * @event - * Fired when class in tree was clicked on and needs to be loaded. - * @param {String} cls name of the class. + * Fired when link in tree was clicked on and needs to be loaded. + * @param {String} url URL of the page to load * @param {Ext.EventObject} e */ - "classclick" + "urlclick" ); // Expand the main tree @@ -48,28 +47,28 @@ Ext.define('Docs.view.tree.Tree', { addFavIcons: function(node) { if (node.get("leaf")) { - var cls = node.raw.clsName; - var show = Docs.Favorites.has(cls) ? "show" : ""; - node.set("text", node.get("text") + Ext.String.format('', cls, show)); + var url = node.raw.url; + var show = Docs.Favorites.has(url) ? "show" : ""; + node.set("text", node.get("text") + Ext.String.format('', url, show)); node.commit(); } }, onItemClick: function(view, node, item, index, e) { - var clsName = node.raw ? node.raw.clsName : node.data.clsName; + var url = node.raw ? node.raw.url : node.data.url; - if (clsName) { + if (url) { if (e.getTarget(".fav")) { var favEl = Ext.get(e.getTarget(".fav")); if (favEl.hasCls('show')) { - Docs.Favorites.remove(clsName); + Docs.Favorites.remove(url); } else { - Docs.Favorites.add(clsName); + Docs.Favorites.add(url, this.getNodeTitle(node)); } } else { - this.fireEvent("classclick", clsName, e); + this.fireEvent("urlclick", url, e); } } else if (!node.isLeaf()) { @@ -83,12 +82,12 @@ Ext.define('Docs.view.tree.Tree', { }, /** - * Selects class node in tree by name. + * Selects link node in tree by URL. * - * @param {String} cls + * @param {String} url */ - selectClass: function(cls) { - var r = this.findRecordByClassName(cls); + selectUrl: function(url) { + var r = this.findRecordByUrl(url); if (r) { this.getSelectionModel().select(r); r.bubble(function(n) { @@ -101,13 +100,13 @@ Ext.define('Docs.view.tree.Tree', { }, /** - * Sets favorite status of class on or off. + * Sets favorite status of link on or off. * - * @param {String} cls name of the class + * @param {String} url URL of the link * @param {Boolean} enable true to mark class as favorite. */ - setFavorite: function(cls, enable) { - var r = this.findRecordByClassName(cls); + setFavorite: function(url, enable) { + var r = this.findRecordByUrl(url); if (r) { var show = enable ? "show" : ""; r.set("text", r.get("text").replace(/class="fav *(show)?"/, 'class="fav '+show+'"')); @@ -115,9 +114,20 @@ Ext.define('Docs.view.tree.Tree', { } }, - findRecordByClassName: function(cls) { + findRecordByUrl: function(url) { return this.getRootNode().findChildBy(function(n) { - return cls === n.raw.clsName; + return url === n.raw.url; }, this, true); + }, + + getNodeTitle: function(node) { + var m = node.raw.url.match(/^\/api\/(.*)$/); + if (m) { + return m[1]; + } + else { + return node.raw.text; + } } + });