jsduck 0.6.1 → 2.0.pre

data/template/app/view/Viewport.js

@@ -0,0 +1,240 @@
+/**
+ * The main viewport, split in to a west and center region.
+ * The North region should also be shown by default in the packaged
+ * (non-live) version of the docs. TODO: close button on north region.
+ */
+Ext.define('Docs.view.Viewport', {
+    extend: 'Ext.container.Viewport',
+    requires: [
+        'Docs.view.cls.Header',
+        'Docs.view.cls.Overview',
+        'Docs.view.index.Container',
+        'Docs.view.tree.Tree',
+        'Docs.view.ClassGrid',
+        'Docs.Favorites',
+        'Docs.Settings',
+        'Docs.History'
+    ],
+
+    id: 'viewport',
+    layout: 'border',
+    defaults: { xtype: 'container' },
+
+    initComponent: function() {
+        this.items = [
+
+            {
+                region:'west',
+                width: 240,
+                id: 'west-region-container',
+                padding: '5 0 0 0',
+                layout: 'vbox',
+                defaults: {
+                    xtype: 'container',
+                    width: "100%"
+                },
+                items: [
+                    {
+                        xtype: 'button',
+                        cls: 'logo',
+                        height: 60,
+                        margin: '0 0 10 10',
+                        width: 220,
+                        border: 0,
+                        ui: 'hmm',
+                        listeners: {
+                            click: function() {
+                                Docs.App.getController('Classes').loadIndex();
+                            },
+                            scope: this
+                        }
+                    },
+                    {
+                        cls: 'search',
+                        id: 'search-container',
+                        margin: '0 0 0 5',
+                        height: 40,
+                        items: [
+                            {
+                                xtype: 'triggerfield',
+                                triggerCls: 'reset',
+                                emptyText: 'Search',
+                                id: 'search-field',
+                                enableKeyEvents: true,
+                                hideTrigger: true,
+                                onTriggerClick: function() {
+                                    this.reset();
+                                    this.focus();
+                                    this.setHideTrigger(true);
+                                    Ext.getCmp('search-dropdown').hide();
+                                }
+                            },
+                            {
+                                xtype: 'searchdropdown'
+                            }
+                        ]
+                    },
+                    {
+                        id: 'nested-west-region-container',
+                        flex: 1,
+                        layout: 'border',
+                        border: false,
+                        items: [
+                            {
+                                id: 'classes-tab-panel',
+                                xtype: 'tabpanel',
+                                region: 'north',
+                                height: Docs.Settings.get('favorites-height') || 150,
+                                padding: '2 4 0 0',
+                                bodyPadding: '3 15 0 12',
+                                split: true,
+                                listeners: {
+                                    afterRender: function() {
+                                        // Add 7px padding at left side of tab-bar
+                                        this.tabBar.insert(0, {width: 7, xtype: 'container'});
+                                    },
+                                    resize: function(cmp, w, h) {
+                                        Docs.Settings.set('favorites-height', h);
+                                    }
+                                },
+                                items: [
+                                    {
+                                        xtype: 'classgrid',
+                                        id: 'favorites-grid',
+                                        title: 'Favorites',
+                                        iconCls: 'icon-fav',
+                                        viewConfig: {
+                                            plugins: [{
+                                                pluginId: 'favGridDD',
+                                                ptype: 'gridviewdragdrop',
+                                                animate: true,
+                                                dragText: 'Drag and drop to reorganize'
+                                            }],
+                                            listeners: {
+                                                drop: function() {
+                                                    // Hack to fix a bug in localStorage which prevents the order of
+                                                    // items being saved when they're changed
+                                                    var store = Ext.getStore('Favorites');
+                                                    store.getProxy().setIds(Ext.Array.map(store.data.items, function(i) { return i.data.id; }));
+                                                }
+                                            }
+                                        },
+                                        store: Ext.getStore('Favorites'),
+                                        icons: Docs.icons,
+                                        listeners: {
+                                            closeclick: function(cls) {
+                                                Docs.Favorites.remove(cls);
+                                            },
+                                            // Prevent row highlighting when doing drag-drop
+                                            afterrender: function() {
+                                                var ddPlugin = this.getView().getPlugin('favGridDD');
+
+                                                ddPlugin.dragZone.onInitDrag = function() {
+                                                    Ext.getCmp('favorites-grid').addCls('drag');
+                                                    Ext.view.DragZone.prototype.onInitDrag.apply(this, arguments);
+                                                };
+                                                ddPlugin.dragZone.afterValidDrop = ddPlugin.dragZone.afterInvalidDrop = function() {
+                                                    Ext.getCmp('favorites-grid').removeCls('drag');
+                                                };
+                                            }
+                                        }
+                                    }
+                                ]
+                            },
+                            {
+                                region: 'center',
+                                xtype: 'classtree',
+                                padding: '5 10 0 10',
+                                margin: '0 5 2 0',
+                                root: Docs.classData
+                                // dockedItems: [{
+                                //     xtype: 'toolbar',
+                                //     baseCls: null,
+                                //     dock: 'top',
+                                //     padding: '0 0 5 0',
+                                //     items: [
+                                //         {
+                                //             xtype: 'button',
+                                //             text: 'Sort by Package',
+                                //             menu: [
+                                //                 { text: 'by Category' },
+                                //                 { text: 'by Hierarchy' },
+                                //                 { text: 'by Popularity' }
+                                //             ]
+                                //         },
+                                //         { xtype: 'tbfill'},
+                                //         {
+                                //             xtype: 'button',
+                                //             iconCls: 'expandAllMembers',
+                                //             tooltip: "Expand all"
+                                //         }
+                                //     ]
+                                // }]
+                            }
+                        ]
+                    }
+                ]
+            },
+            {
+                region: 'center',
+                id: 'center-container',
+                layout: 'fit',
+                minWidth: 800,
+                padding: '20 20 5 0',
+                items: {
+                    id: 'card-panel',
+                    cls: 'card-panel',
+                    xtype: 'container',
+                    layout: 'card',
+                    padding: '20',
+                    items: [
+                        {
+                            autoScroll: true,
+                            xtype: 'indexcontainer'
+                        },
+                        {
+                            xtype: 'container',
+                            layout: {
+                                type: 'vbox',
+                                align: 'stretch'
+                            },
+                            items: [
+                                {xtype: 'classheader'},
+                                {xtype: 'classoverview', flex: 1}
+                            ]
+                        },
+                        {
+                            autoScroll: true,
+                            xtype: 'container',
+                            id: 'guide'
+                        },
+                        {
+                            xtype: 'container',
+                            id: 'failure'
+                        }
+                    ]
+                }
+            },
+            {
+                region: 'south',
+                id: 'footer',
+                contentEl: 'footer-content',
+                height: 15
+            }
+        ];
+
+        this.callParent(arguments);
+    },
+
+    /**
+     * Sets the contents of `<title>` tag.
+     * @param {String} text
+     */
+    setPageTitle: function(text) {
+        text = Ext.util.Format.stripTags(text);
+        if (!this.origTitle) {
+            this.origTitle = document.title;
+        }
+        document.title = text ? (text + " - " + this.origTitle) : this.origTitle;
+    }
+});

data/template/app/view/cls/Header.js

@@ -0,0 +1,47 @@
+/**
+ * Renders class name and icon in page header.
+ */
+Ext.define('Docs.view.cls.Header', {
+    extend: 'Ext.container.Container',
+    padding: '5 0 17 0',
+    // Initially the component will be empty and so the initial height
+    // will not be correct if not set explicitly
+    height: 47,
+    alias: 'widget.classheader',
+
+    initComponent: function() {
+        this.tpl = Ext.create('Ext.XTemplate',
+            '<h1 class="{[this.getClass(values)]}">',
+                '<tpl if="private">',
+                    '<span class="private">Private</span>',
+                '</tpl>',
+                '<a href="source/{href}" target="_blank">{name}</a>',
+                '<tpl if="xtypes.length &gt; 0">',
+                    '<span>xtype: {[values.xtypes.join(", ")]}</span>',
+                '</tpl>',
+            '</h1>',
+            {
+                getClass: function(cls) {
+                    if (cls.component) {
+                        return "component";
+                    }
+                    else if (cls.singleton) {
+                        return "singleton";
+                    }
+                    else {
+                        return "class";
+                    }
+                }
+            }
+        );
+        this.callParent();
+    },
+
+    /**
+     * Loads class name and icon to header.
+     * @param {Object} cls  class config.
+     */
+    load: function(cls) {
+        this.update(this.tpl.apply(cls));
+    }
+});

data/template/app/view/cls/Overview.js

@@ -0,0 +1,415 @@
+/**
+ * Renders the whole class-documentation page.
+ */
+Ext.define('Docs.view.cls.Overview', {
+    extend: 'Ext.panel.Panel',
+    alias: 'widget.classoverview',
+    requires: [
+        'Docs.view.cls.Toolbar',
+        'Docs.Syntax',
+        'Docs.Settings'
+    ],
+
+    cls: 'class-overview iScroll',
+    autoScroll: true,
+    bodyPadding: '20',
+
+    /**
+     * Scrolls the specified element into view
+     *
+     * @param {String} query  DomQuery selector string.
+     */
+    scrollToEl: function(query) {
+        var el = Ext.get(Ext.query(query)[0]);
+        if (el) {
+            var isMember = el.hasCls("member");
+            var scrollOffset = el.getY() - (isMember ? 145 : 135);
+            var docContent = this.getEl().down('.x-panel-body');
+            var currentScroll = docContent.getScroll()['top'];
+            docContent.scrollTo('top', currentScroll + scrollOffset, true);
+
+            if (isMember && el.down(".expandable")) {
+                el.addCls('open');
+            }
+            el.highlight();
+        }
+    },
+
+    /**
+     * Renders class documentation in this panel.
+     *
+     * @param {Object} docClass
+     */
+    load: function(docClass) {
+        this.docClass = docClass;
+
+        if (this.toolbar) {
+            this.removeDocked(this.toolbar, true);
+        }
+        this.toolbar = Ext.create('Docs.view.cls.Toolbar', {
+            docClass: this.docClass,
+            listeners: {
+                hideInherited: function(hideInherited) {
+                    this.filterMembers(this.toolbar.getFilterValue(), hideInherited);
+                },
+                filter: function(search) {
+                    this.filterMembers(search, Docs.Settings.get("hideInherited"));
+                },
+                scope: this
+            }
+        });
+        this.addDocked(this.toolbar);
+
+        this.update(this.renderClass(docClass));
+        Docs.Syntax.highlight(this.getEl());
+
+        if (Docs.Settings.get("hideInherited")) {
+            this.filterMembers("", true);
+        }
+    },
+
+    /**
+     * Filters members by search string and inheritance.
+     * @param {String} search
+     * @param {Boolean} hideInherited
+     * @private
+     */
+    filterMembers: function(search, hideInherited) {
+        Docs.Settings.set("hideInherited", hideInherited);
+        var isSearch = search.length > 0;
+
+        // Hide the class documentation when filtering
+        Ext.Array.forEach(Ext.query('.doc-contents, .hierarchy'), function(el) {
+            Ext.get(el).setStyle({display: isSearch ? 'none' : 'block'});
+        });
+
+        // Hide members who's name doesn't match with the search string
+        // and hide inherited members if hideInherited=true
+        var re = new RegExp(Ext.String.escapeRegex(search), "i");
+        this.eachMember(function(m) {
+            var el = Ext.get(m.tagname + "-" + m.name);
+            var byInheritance = !hideInherited || (m.owner === this.docClass.name);
+            var byFilter = !isSearch || re.test(m.name);
+            if (byInheritance && byFilter) {
+                el.setStyle({display: 'block'});
+            }
+            else {
+                el.setStyle({display: 'none'});
+            }
+        }, this);
+
+        // Remove all first-child classes
+        Ext.Array.forEach(Ext.query('.member.first-child'), function(m) {
+            Ext.get(m).removeCls('first-child');
+        });
+
+        Ext.Array.forEach(['cfg', 'property', 'method', 'event'], function(type) {
+            var sectionId = '#m-' + type;
+
+            // Hide the section completely if all items in it are hidden
+            var visibleEls = this.getVisibleElements(sectionId + " .member");
+            var section = Ext.query(sectionId)[0];
+            section && Ext.get(section).setStyle({display: visibleEls.length > 0 ? 'block' : 'none'});
+
+            // Hide subsections completely if all items in them are hidden
+            Ext.Array.forEach(Ext.query(sectionId+" .subsection"), function(subsection) {
+                var visibleEls = this.getVisibleElements(".member", subsection);
+                if (visibleEls.length > 0) {
+                    // add first-child class to first member in subsection
+                    visibleEls[0].addCls('first-child');
+                    // make sure subsection is visible
+                    Ext.get(subsection).setStyle({display: 'block'});
+                }
+                else {
+                    // Hide subsection completely if empty
+                    Ext.get(subsection).setStyle({display: 'none'});
+                }
+            }, this);
+        }, this);
+
+        this.toolbar.hideInherited(hideInherited);
+    },
+
+    getVisibleElements: function(selector, root) {
+        var els = Ext.Array.map(Ext.query(selector, root), function(node) {
+            return Ext.get(node);
+        });
+        return Ext.Array.filter(els, function(el) {
+            return el.isVisible();
+        });
+    },
+
+    // Loops through each member of class
+    eachMember: function(callback, scope) {
+        Ext.Array.forEach(['members', 'statics'], function(group) {
+            Ext.Object.each(this.docClass[group], function(type, members) {
+                Ext.Array.forEach(members, callback, scope);
+            }, this);
+        }, this);
+    },
+
+    renderClass: function(cls) {
+        this.classTpl = this.classTpl || new Ext.XTemplate(
+            '<div>',
+                '{hierarchy}',
+                 '<div class="doc-contents">',
+                    '{doc}',
+                '</div>',
+                '<div class="members">',
+                    '{members}',
+                '</div>',
+            '</div>'
+        );
+
+        return this.classTpl.apply({
+            doc: cls.doc,
+            hierarchy: this.renderHierarchy(cls),
+            members: this.renderMembers(cls)
+        });
+    },
+
+    renderHierarchy: function(cls) {
+        if (cls.superclasses.length === 0 && cls.allMixins.length === 0 && cls.alternateClassNames.length === 0) {
+            return "";
+        }
+
+        this.hierarchyTpl = this.hierarchyTpl || new Ext.XTemplate(
+            '<pre class="hierarchy">',
+            '<tpl if="alternateClassNames.length &gt; 0">',
+                '<h4>Alternate names</h4>',
+                '<tpl for="alternateClassNames">',
+                    '<div class="alternate-class-name">{.}</div>',
+                '</tpl>',
+            '</tpl>',
+            '<tpl if="tree">',
+                '<h4>Hierarchy</h4>',
+                '{tree}',
+            '</tpl>',
+            '<tpl if="mixins.length &gt; 0">',
+                '<h4>Mixins</h4>',
+                '<tpl for="mixins">',
+                    '<div class="mixin">{.}</div>',
+                '</tpl>',
+            '</tpl>',
+            '</pre>'
+        );
+
+        return this.hierarchyTpl.apply({
+            tree: cls.superclasses.length ? this.renderClassTree(cls.superclasses.concat(cls.name), true) : "",
+            mixins: Ext.Array.map(cls.allMixins, this.renderLink, this),
+            alternateClassNames: cls.alternateClassNames
+        });
+    },
+
+    renderClassTree: function(superclasses, firstChild) {
+        if (superclasses.length === 0) {
+            return "";
+        }
+
+        this.classTreeTpl = this.classTreeTpl || new Ext.XTemplate(
+            '<div class="subclass {firstChild}">',
+              '{link}',
+              '{subtree}',
+            '</div>'
+        );
+
+        var name = superclasses[0];
+        return this.classTreeTpl.apply({
+            firstChild: firstChild ? 'first-child' : '',
+            link: superclasses.length > 1 ? this.renderLink(name) : '<strong>'+name+'</strong>',
+            subtree: this.renderClassTree(superclasses.slice(1))
+        });
+    },
+
+    renderLink: function(className) {
+        return Ext.String.format('<a href="#/api/{0}" rel="{0}" class="docClass">{0}</a>', className);
+    },
+
+    renderMembers: function(cls) {
+        var sections = [
+            {type: "cfg", title: "Config options"},
+            {type: "property", title: "Properties"},
+            {type: "method", title: "Methods"},
+            {type: "event", title: "Events"}
+        ];
+
+        // Skip rendering empty sections
+        return Ext.Array.map(sections, function(sec) {
+            var members = cls.members[sec.type];
+            var statics = cls.statics[sec.type];
+            return (members.length > 0 || statics.length > 0) ? this.renderSection(members, statics, sec) : "";
+        }, this).join("");
+    },
+
+    renderSection: function(members, statics, section) {
+        this.sectionTpl = this.sectionTpl || new Ext.XTemplate(
+            '<div id="m-{type}">',
+                '<tpl if="!statics.length">',
+                    '<div class="definedBy">Defined By</div>',
+                '</tpl>',
+                '<h3 class="members-title">{title}</h3>',
+                '<tpl if="members.length">',
+                    '<div class="subsection">',
+                        '<tpl if="statics.length">',
+                            '<div class="definedBy">Defined By</div>',
+                            '<h4 class="members-subtitle">Instance {title}</h3>',
+                        '</tpl>',
+                        '{members}',
+                    '</div>',
+                '</tpl>',
+                '<tpl if="statics.length">',
+                    '<div class="subsection">',
+                        '<div class="definedBy">Defined By</div>',
+                        '<h4 class="members-subtitle">Static {title}</h3>',
+                        '{statics}',
+                    '</div>',
+                '</tpl>',
+            '</div>'
+        );
+
+        return this.sectionTpl.apply({
+            type: section.type,
+            title: section.title,
+            members: Ext.Array.map(members, this.renderMemberDiv, this).join(""),
+            statics: Ext.Array.map(statics, this.renderMemberDiv, this).join("")
+        });
+    },
+
+    renderMemberDiv: function(member, index) {
+        this.memberTpl = this.memberTpl || new Ext.XTemplate(
+            '<div id="{tagname}-{name}" class="member {firstChild} {inherited}">',
+                // leftmost column: expand button
+                '<a href="#" class="side {expandable}">',
+                    '<span>&nbsp;</span>',
+                '</a>',
+                // member name and type + link to owner class and source
+                '<div class="title">',
+                    '<div class="meta">',
+                        '<a href="#/api/{owner}" rel="{owner}" class="definedIn docClass">{owner}</a><br/>',
+                        '<a href="source/{href}" target="_blank" class="viewSource">view source</a>',
+                    '</div>',
+                    '{signature}',
+                '</div>',
+                // short and long descriptions
+                '<div class="description">',
+                    '<div class="short">{[this.shortDoc(values)]}</div>',
+                    '<div class="long">{longDoc}</div>',
+                '</div>',
+            '</div>',
+            {
+                // Returns contents for short documentation
+                shortDoc: function(cfg) {
+                    return cfg.shortDoc ? cfg.shortDoc : cfg.doc;
+                }
+            }
+        );
+
+        return this.memberTpl.apply(Ext.apply({
+            // use classname "first-child" when it's first member in its category
+            firstChild: (index === 0) ? "first-child" : "",
+            // use classname "expandable" when member has shortened description
+            expandable: member.shortDoc ? "expandable" : "not-expandable",
+            // use classname "inherited" when member is not defined in this class
+            inherited: member.owner === this.docClass.name ? "not-inherited" : "inherited",
+            // method params signature or property type signature
+            signature: this.renderSignature(member),
+            // full documentation together with optional parameters and return value
+            longDoc: this.renderLongDoc(member)
+        }, member));
+    },
+
+    renderSignature: function(member) {
+        this.signatureTpl = this.signatureTpl || new Ext.XTemplate(
+            '{before}<a href="#/api/{member}-{tagname}-{name}" class="name {expandable}">{name}</a>{params}{after}'
+        );
+
+        var cfg = Ext.apply({}, member);
+        cfg.expandable = member.shortDoc ? "expandable" : "not-expandable";
+
+        if (member.tagname === "method" && member.name === "constructor") {
+            cfg.before = "<strong class='constructor-signature'>new</strong>";
+            cfg.name = this.docClass.name;
+        }
+
+        if (member.tagname === "cfg" || member.tagname === "property") {
+            cfg.params = "<span> : " + member.type + "</span>";
+        }
+        else {
+            var ps = Ext.Array.map(member.params, this.renderShortParam, this).join(", ");
+            cfg.params = '( <span class="pre">' + ps + "</span> )";
+            if (member.tagname === "method") {
+                cfg.params += " : " + member["return"].type;
+            }
+        }
+
+        if (member['protected']) {
+            cfg.after = "<strong class='protected-signature'>protected</strong>";
+        }
+        if (member['static']) {
+            cfg.after = "<strong class='static-signature'>static</strong>";
+        }
+        if (member.deprecated) {
+            cfg.after = "<strong class='deprecated-signature'>deprecated</strong>";
+        }
+
+        return this.signatureTpl.apply(cfg);
+    },
+
+    renderShortParam: function(param) {
+        var p = param.type + " " + param.name;
+        return param.optional ? "["+p+"]" : p;
+    },
+
+    renderLongDoc: function(member) {
+        var doc = member.doc;
+
+        if (member.deprecated) {
+            var v = member.deprecated.version ? "since " + member.deprecated.version : "";
+            doc += '<div class="deprecated">';
+            doc += Ext.String.format('<p>This {0} has been <strong>deprecated</strong> {1}</p>', member.tagname, v);
+            doc += member.deprecated.text;
+            doc += '</div>';
+        }
+
+        if (member.params && member.params.length > 0) {
+            doc += '<h3 class="pa">Parameters</h3>';
+            var ps = Ext.Array.map(member.params, this.renderLongParam, this).join("");
+            doc += "<ul>" + ps + "</ul>";
+        }
+
+        if (member["return"]) {
+            doc += this.renderReturn(member["return"]);
+        }
+
+        return doc;
+    },
+
+    renderLongParam: function(param) {
+        this.paramTpl = this.paramTpl || new Ext.XTemplate(
+            '<li>',
+                '<span class="pre">{name}</span> : {type}',
+                '<div class="sub-desc">',
+                    '{doc}',
+                '</div>',
+            '</li>'
+        );
+
+        return this.paramTpl.apply(param);
+    },
+
+    renderReturn: function(returnDoc) {
+        this.returnTpl = this.returnTpl || new Ext.XTemplate(
+            '<h3 class="pa">Returns</h3>',
+            '<ul>',
+                '<li>',
+                    '<span class="pre">{type}</span>',
+                    '<div class="sub-desc">',
+                        '{doc}',
+                    '</div>',
+                '</li>',
+            '</ul>'
+        );
+
+        return this.returnTpl.apply(returnDoc);
+    }
+});