src/doc/doc_templates.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 # http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # HTML templates used by Nitdoc to generate API documentation
  16 # Pages are assembled using `Template`
  17 module doc_templates
  18
  19 import template
  20
  21 # A documentation page
  22 class TplPage
  23         super Template
  24
  25         # Page title in HTML header
  26         var title: String writable
  27
  28         # Directory where css, js and other assets can be found
  29         var shareurl: String writable
  30
  31         # Attributes of the body tag element
  32         var body_attrs = new Array[TagAttribute]
  33
  34         # Top menu template if any
  35         var topmenu: TplTopMenu writable
  36
  37         # Sidebar template if any
  38         var sidebar: nullable TplSidebar writable
  39
  40         # Content of the page in form a TplSection
  41         var sections = new Array[TplSection]
  42
  43         # Footer content if any
  44         var footer: nullable Streamable writable
  45
  46         # JS scripts to append at the end of the body
  47         var scripts = new Array[TplScript]
  48
  49         init do end
  50
  51         # Add a section to this page
  52         fun add_section(section: TplSection) do
  53                 sections.add section
  54         end
  55
  56         # Render the html header
  57         private fun render_head do
  58                 add "<!DOCTYPE html>"
  59                 add "<head>"
  60                 add " <meta charset='utf-8'/>"
  61                 add " <!--link rel='stylesheet' href='{shareurl}/css/Nitdoc.UI.css' type='text/css'/-->"
  62                 add " <link rel='stylesheet' href='{shareurl}/vendors/bootstrap/css/bootstrap.min.css'/>"
  63                 add " <link rel='stylesheet' href='{shareurl}/css/nitdoc.bootstrap.css'/>"
  64                 add " <link rel='stylesheet' href='{shareurl}/css/nitdoc.css'/>"
  65                 add " <link rel='stylesheet' href='{shareurl}/css/Nitdoc.QuickSearch.css'/>"
  66                 add " <link rel='stylesheet' href='{shareurl}/css/Nitdoc.ModalBox.css'/>"
  67                 add " <link rel='stylesheet' href='{shareurl}/css/Nitdoc.GitHub.css'/>"
  68                 add " <title>{title}</title>"
  69                 add "</head>"
  70                 add "<body"
  71                 for attr in body_attrs do add attr
  72                 add ">"
  73         end
  74
  75         # Render the topmenu template
  76         private fun render_topmenu do
  77                 add " <div class='row'>"
  78                 add topmenu
  79                 add " </div>"
  80         end
  81
  82         # Render the sidebar
  83         # Sidebar is automatically populated with a summary of all sections
  84         fun render_sidebar do
  85                 if sidebar == null then return
  86                 var summary = new TplSummary.with_order(0)
  87                 for section in sections do
  88                         section.render_summary summary
  89                 end
  90                 sidebar.boxes.add summary
  91                 add sidebar.as(not null)
  92         end
  93         # Render the footer and content
  94         private fun render_content do
  95                 for section in sections do add section
  96                 if footer != null then
  97                         add "<div class='well footer'>"
  98                         add footer.as(not null)
  99                         add "</div>"
 100                 end
 101         end
 102
 103         # Render JS scripts
 104         private fun render_footer do
 105                 add "<script src='{shareurl}/vendors/jquery/jquery-1.11.1.min.js'></script>"
 106                 add "<script src='{shareurl}/vendors/jquery/jquery-ui-1.10.4.custom.min.js'></script>"
 107                 add "<script src='{shareurl}/vendors/bootstrap/js/bootstrap.min.js'></script>"
 108                 add "<script data-main='{shareurl}/js/nitdoc' src='{shareurl}/js/lib/require.js'</script>"
 109                 for script in scripts do add script
 110                 add """<script>
 111                         $(function () {
 112                                 $("[data-toggle='tooltip']").tooltip();
 113                                 $("[data-toggle='popover']").popover();
 114                         });
 115                 </script>"""
 116                 add "</body>"
 117                 add "</html>"
 118         end
 119
 120         # Render the whole page
 121         redef fun rendering do
 122                 render_head
 123                 add "<div class='container-fluid'>"
 124                 render_topmenu
 125                 add " <div class='row' id='content'>"
 126                 if sidebar != null then
 127                         add "<div class='col col-xs-3 col-lg-2'>"
 128                         render_sidebar
 129                         add "</div>"
 130                         add "<div class='col col-xs-9 col-lg-10' data-spy='scroll' data-target='.summary'>"
 131                         render_content
 132                         add "</div>"
 133                 else
 134                         add "<div class='col col-xs-12'>"
 135                         render_content
 136                         add "</div>"
 137                 end
 138                 add " </div>"
 139                 add "</div>"
 140                 render_footer
 141         end
 142 end
 143
 144 #########################
 145 # general layout elements
 146 #########################
 147
 148 # Top menu bar template
 149 class TplTopMenu
 150         super Template
 151
 152         # Elements of the topmenu
 153         private var elts = new Array[Streamable]
 154
 155         # Add a new link to the menu
 156         fun add_link(href, name: String, is_active: Bool) do
 157                 var tpl = new Template
 158                 tpl.add "<li"
 159                 if is_active then
 160                         tpl.add " class='active'"
 161                 end
 162                 tpl.add ">"
 163                 tpl.add new TplLink(href, name)
 164                 tpl.add "</li>"
 165                 add_raw(tpl)
 166         end
 167
 168         # Add a raw content to the menu
 169         fun add_raw(content: Streamable) do
 170                 elts.add content
 171         end
 172
 173         redef fun rendering do
 174                 add "<nav id='topmenu' class='navbar navbar-default navbar-fixed-top' role='navigation'>"
 175                 add " <div class='container-fluid'>"
 176                 if not elts.is_empty then
 177                         add "<ul class='nav navbar-nav'>"
 178                         for elt in elts do add(elt)
 179                         add "</ul>"
 180                 end
 181                 add " </div>"
 182                 add "</nav>"
 183         end
 184 end
 185
 186 # A sidebar template
 187 class TplSidebar
 188         super Template
 189
 190         # Sidebar contains sidebar element templates called boxes
 191         var boxes = new Array[TplSidebarElt]
 192
 193         # Sort boxes by order priority
 194         private fun order_boxes do
 195                 var sorter = new OrderComparator
 196                 sorter.sort(boxes)
 197         end
 198
 199         redef fun rendering do
 200                 if boxes.is_empty then return
 201                 order_boxes
 202                 add "<div id='sidebar'>"
 203                 for box in boxes do add box
 204                 add "</div>"
 205         end
 206 end
 207
 208 # Comparator used to sort boxes by order
 209 private class OrderComparator
 210         super Comparator[TplSidebarElt]
 211
 212         redef fun compare(a, b) do
 213                 if a.order < b.order then return -1
 214                 if a.order > b.order then return 1
 215                 return 0
 216         end
 217 end
 218
 219 # Something that can be put in the sidebar
 220 class TplSidebarElt
 221         super Template
 222
 223         # Order of the box in the sidebar
 224         var order: Int = 1
 225
 226         init with_order(order: Int) do self.order = order
 227 end
 228
 229 # Agenericbox that can be added to sidebar
 230 class TplSideBox
 231         super TplSidebarElt
 232
 233         # Title of the box to display
 234         # Title is also a placeholder for the collapse link
 235         var title: String
 236
 237         # Box HTML id
 238         # equals to `title.to_cmangle` by default
 239         # Used for collapsing
 240         var id: String
 241
 242         # Content to display in the box
 243         # box will not be rendered if the content is null
 244         var content: nullable Streamable writable
 245
 246         # Is the box opened by default
 247         # otherwise, the user will have to clic on the title to display the content
 248         var is_open writable = false
 249
 250         init(title: String) do
 251                 self.title = title
 252                 self.id = title.to_cmangle
 253         end
 254
 255         init with_content(title: String, content: Streamable) do
 256                 init(title)
 257                 self.content = content
 258         end
 259
 260         redef fun rendering do
 261                 if content == null then return
 262                 var open = ""
 263                 if is_open then open = "in"
 264                 add "<div class='panel'>"
 265                 add " <div class='panel-heading'>"
 266                 add "  <a data-toggle='collapse' data-parent='#sidebar' data-target='#box_{id}' href='#'>"
 267                 add title
 268                 add "  </a>"
 269                 add " </div>"
 270                 add " <div id='box_{id}' class='panel-body collapse {open}'>"
 271                 add content.as(not null)
 272                 add " </div>"
 273                 add "</div>"
 274         end
 275 end
 276
 277 # Something that can go on a summary template
 278 class TplSummaryElt
 279         super Template
 280
 281         # Add an element to the summary
 282         fun add_child(child: TplSummaryElt) is abstract
 283 end
 284
 285 # A summary that can go on the sidebar
 286 # If the page contains a sidebar, the summary is automatically placed
 287 # on top of the sidebarauto-generated
 288 # summary contains anchors to all sections displayed in the page
 289 class TplSummary
 290         super TplSidebarElt
 291         super TplSummaryElt
 292
 293         # Summary elements to display
 294         var children = new Array[TplSummaryElt]
 295
 296         redef fun add_child(child) do children.add child
 297
 298         redef fun rendering do
 299                 if children.is_empty then return
 300                 add "<div class='panel'>"
 301                 add " <div class='panel-heading'>"
 302                 add "  <a data-toggle='collapse' data-parent='#sidebar' data-target='#box-sum' href='#'>"
 303                 add "Summary"
 304                 add "  </a>"
 305                 add " </div>"
 306                 add " <div id='box-sum' class='summary collapse in'>"
 307                 add " <ul class='nav'>"
 308                 for entry in children do add entry
 309                 add " </ul>"
 310                 add " </div>"
 311                 add "</div>"
 312         end
 313 end
 314
 315 # A summary entry
 316 class TplSummaryEntry
 317         super TplSummaryElt
 318
 319         # Text to display
 320         var text: Streamable
 321
 322         # Children of this entry
 323         # Will be displayed as a tree
 324         var children = new Array[TplSummaryElt]
 325
 326         init(text: Streamable) do self.text = text
 327
 328         redef fun add_child(child) do children.add child
 329
 330         redef fun rendering do
 331                 add "<li>"
 332                 add text
 333                 if not children.is_empty then
 334                         add "<ul class='nav'>"
 335                         for entry in children do add entry
 336                         add "</ul>"
 337                 end
 338                 add "</li>"
 339         end
 340 end
 341
 342 # Something that can go in a section
 343 # Sections are automatically collected to populate the menu
 344 class TplSectionElt
 345         super Template
 346
 347         # HTML anchor id
 348         var id: String
 349
 350         # Title to display if any
 351         # if both `title` and `summary_title` are null then
 352         # the section will not appear in the summary
 353         var title: nullable Streamable writable
 354
 355         # Subtitle to display if any
 356         var subtitle: nullable Streamable writable
 357
 358         # Title that appear in the summary
 359         # if null use `title` instead
 360         var summary_title: nullable String writable
 361
 362         # Parent section of this section if any
 363         var parent: nullable TplSection
 364
 365         init(id: String) do self.id = id
 366
 367         init with_title(id: String, title: Streamable) do
 368                 init(id)
 369                 self.title = title
 370         end
 371
 372         # Level <hX> for HTML heading
 373         protected fun hlvl: Int do
 374                 if parent == null then return 1
 375                 return parent.hlvl + 1
 376         end
 377
 378         # Render this section in the summary
 379         protected fun render_summary(parent: TplSummaryElt) is abstract
 380
 381         # Is the section empty (no content at all)
 382         fun is_empty: Bool is abstract
 383 end
 384
 385 # A HTML <section> element
 386 class TplSection
 387         super TplSectionElt
 388
 389         # Elements contained by this section
 390         var children = new Array[TplSectionElt]
 391
 392         # Add an element in this section
 393         fun add_child(child: TplSectionElt) do
 394                 child.parent = self
 395                 children.add child
 396         end
 397
 398         redef fun is_empty: Bool do return children.is_empty
 399
 400         redef fun render_summary(parent) do
 401                 if is_empty then return
 402                 var title = summary_title
 403                 if title == null and self.title != null then title = self.title.write_to_string
 404                 if title == null then return
 405                 var lnk = new TplLink("#{id}", title)
 406                 var entry = new TplSummaryEntry(lnk)
 407                 for child in children do
 408                         child.render_summary(entry)
 409                 end
 410                 parent.add_child entry
 411         end
 412
 413         redef fun rendering do
 414                 if is_empty then return
 415                 add "<section id='{id}'>"
 416                 if title != null then
 417                         var lvl = hlvl
 418                         add "<h{lvl}>"
 419                         add title.as(not null)
 420                         add "</h{lvl}>"
 421                 end
 422                 if subtitle != null then
 423                         add "<div class='info subtitle'>"
 424                         add subtitle.as(not null)
 425                         add "</div>"
 426                 end
 427                 for child in children do
 428                         add child
 429                 end
 430                 add "</section>"
 431         end
 432 end
 433
 434 # A page article that can go in a section
 435 class TplArticle
 436         super TplSectionElt
 437
 438         # Content for this article
 439         var content: nullable Streamable writable = null
 440
 441         # CSS classes to apply on the article title heading element
 442         var title_classes = new Array[String]
 443
 444         redef fun render_summary(parent) do
 445                 if is_empty then return
 446                 var title = summary_title
 447                 if title == null and self.title != null then title = self.title.write_to_string
 448                 if title == null then return
 449                 var lnk = new TplLink("#{id}", title)
 450                 parent.add_child new TplSummaryEntry(lnk)
 451         end
 452
 453         redef fun rendering do
 454                 add "<article id='{id}'>"
 455                 if title != null then
 456                         var lvl = hlvl
 457                         add "<h{lvl} class='{title_classes.join(" ")}'>"
 458                         add title.as(not null)
 459                         add "</h{lvl}>"
 460                 end
 461                 if subtitle != null then
 462                         add "<div class='info subtitle'>"
 463                         add subtitle.as(not null)
 464                         add "</div>"
 465                 end
 466                 if content != null then
 467                         add content.as(not null)
 468                 end
 469                 add """</article>"""
 470         end
 471
 472         redef fun is_empty: Bool do return content == null
 473 end
 474
 475 # A module / class / prop definition
 476 class TplDefinition
 477         super Template
 478
 479         # Comment to display
 480         var comment: nullable Streamable writable
 481
 482         # Namespace for this definition
 483         var namespace: Streamable writable
 484
 485         # Location link to display
 486         var location: nullable Streamable writable
 487
 488         init do end
 489
 490         private fun render_info do
 491                 add "<div class='info text-right'>"
 492                 if comment == null then
 493                         add "<span class=\"noComment\">no comment for </span>"
 494                 end
 495                 add namespace
 496                 if location != null then
 497                         add " "
 498                         add location.as(not null)
 499                 end
 500                 add "</div>"
 501         end
 502
 503         private fun render_comment do
 504                 if comment != null then add comment.as(not null)
 505         end
 506
 507         redef fun rendering do
 508                 add "<div class='definition'>"
 509                 render_comment
 510                 render_info
 511                 add "</div>"
 512         end
 513 end
 514
 515 # Class definition
 516 class TplClassDefinition
 517         super TplDefinition
 518
 519         var intros = new Array[TplListElt]
 520         var redefs = new Array[TplListElt]
 521
 522         init do end
 523
 524         redef fun rendering do
 525                 add "<div class='definition'>"
 526                 render_comment
 527                 render_info
 528                 render_list("Introduces", intros)
 529                 render_list("Redefines", redefs)
 530                 add "</div>"
 531         end
 532
 533         private fun render_list(name: String, elts: Array[TplListElt]) do
 534                 if elts.is_empty then return
 535                 add "<h5>{name}</h5>"
 536                 add "<ul class='list-unstyled list-definition'>"
 537                 for elt in elts do add elt
 538                 add "</ul>"
 539         end
 540 end
 541
 542 # Layout for Search page
 543 class TplSearchPage
 544         super TplSectionElt
 545
 546         var modules = new Array[Streamable]
 547         var classes = new Array[Streamable]
 548         var props = new Array[Streamable]
 549
 550         redef fun rendering do
 551                 if title != null then add "<h1>{title}</h1>"
 552                 add "<div class='container-fluid'>"
 553                 add " <div class='row'>"
 554                 if not modules.is_empty then
 555                         add "<div class='col-xs-4'>"
 556                         add "<h3>Modules</h3>"
 557                         add "<ul>"
 558                         for m in modules do
 559                                 add "<li>"
 560                                 add m
 561                                 add "</li>"
 562                         end
 563                         add "</ul>"
 564                         add "</div>"
 565                 end
 566                 if not classes.is_empty then
 567                         add "<div class='col-xs-4'>"
 568                         add "<h3>Classes</h3>"
 569                         add "<ul>"
 570                         for c in classes do
 571                                 add "<li>"
 572                                 add c
 573                                 add "</li>"
 574                         end
 575                         add "</ul>"
 576                         add "</div>"
 577                 end
 578                 if not props.is_empty then
 579                         add "<div class='col-xs-4'>"
 580                         add "<h3>Properties</h3>"
 581                         add "<ul>"
 582                         for p in props do
 583                                 add "<li>"
 584                                 add p
 585                                 add "</li>"
 586                         end
 587                         add "</ul>"
 588                         add "</div>"
 589                 end
 590                 add " </div>"
 591                 add "</div>"
 592         end
 593 end
 594
 595 #####################
 596 # Basiv HTML elements
 597 #####################
 598
 599 # A html link <a>
 600 class TplLink
 601         super Template
 602
 603         # Link href
 604         var href: String writable
 605
 606         # Text to display in the link
 607         var text: String writable
 608
 609         # Optional title
 610         var title: nullable String writable
 611
 612         init(href, text: String) do
 613                 self.href = href
 614                 self.text = text
 615         end
 616
 617         init with_title(href, text, title: String) do
 618                 init(href, text)
 619                 self.title = title
 620         end
 621
 622         redef fun rendering do
 623                 add "<a href=\""
 624                 add href
 625                 add "\""
 626                 if title != null then
 627                         add " title=\""
 628                         add title.as(not null)
 629                         add "\""
 630                 end
 631                 add ">"
 632                 add text
 633                 add "</a>"
 634         end
 635 end
 636
 637 # A <ul> list
 638 class TplList
 639         super TplListElt
 640
 641         # Elements contained in this list
 642         # can be <li> or <ul> elements
 643         var elts = new Array[TplListElt]
 644
 645         # CSS classes of the <ul> element
 646         var css_classes = new Array[String]
 647
 648         # Add content wrapped in a <li> element
 649         fun add_li(content: Streamable) do elts.add new TplListItem.with_content(content)
 650
 651         init do end
 652
 653         init with_classes(classes: Array[String]) do self.css_classes = classes
 654
 655         redef fun rendering do
 656                 if elts.is_empty then return
 657                 add "<ul class='{css_classes.join(" ")}'>"
 658                 for elt in elts do add elt
 659                 add "</ul>"
 660         end
 661 end
 662
 663 # Something that can be added to a TplList
 664 class TplListElt
 665         super Template
 666 end
 667
 668 # A list item <li>
 669 class TplListItem
 670         super TplListElt
 671
 672         # Content of the list item
 673         var content = new Template
 674
 675         # CSS classes of the <li> element
 676         var css_classes = new Array[String]
 677
 678         init do end
 679
 680         init with_content(content: Streamable) do append(content)
 681
 682         init with_classes(content: Streamable, classes: Array[String]) do
 683                 with_content(content)
 684                 css_classes = classes
 685         end
 686
 687         # Append `content` to the item
 688         # similar to `self.content.add`
 689         fun append(content: Streamable) do self.content.add content
 690
 691         redef fun rendering do
 692                 add "<li class='"
 693                 for cls in css_classes do add " {cls}"
 694                 add "'>"
 695                 add content
 696                 add "</li>"
 697         end
 698 end
 699
 700 # A label with a text content
 701 class TplLabel
 702         super Template
 703
 704         # Content of the label if any
 705         var content: nullable Streamable
 706
 707         # CSS classes of the <span> element
 708         var css_classes = new Array[String]
 709
 710         init do end
 711         init with_content(content: Streamable) do self.content = content
 712         init with_classes(classes: Array[String]) do self.css_classes = classes
 713
 714         redef fun rendering do
 715                 add "<span class='label {css_classes.join(" ")}'>"
 716                 if content != null then add content.as(not null)
 717                 add "</span>"
 718         end
 719 end
 720
 721 # A label with an icon
 722 class TplIcon
 723         super TplLabel
 724
 725         # Bootsrap icon name
 726         # see: http://getbootstrap.com/components/#glyphicons
 727         var icon: String
 728
 729         init with_icon(icon: String) do self.icon = icon
 730
 731         redef fun rendering do
 732                 add "<span class='glyphicon glyphicon-{icon} {css_classes.join(" ")}'>"
 733                 if content != null then add content.as(not null)
 734                 add "</span>"
 735         end
 736 end
 737
 738 # A HTML tag attribute
 739 #  `<tag attr="value">`
 740 class TagAttribute
 741         super Template
 742
 743         var name: String
 744         var value: nullable String
 745
 746         init(name: String, value: nullable String) do
 747                 self.name = name
 748                 self.value = value
 749         end
 750
 751         redef fun rendering do
 752                 if value == null then
 753                         add(" {name}")
 754                 else
 755                         add(" {name}=\"{value}\"")
 756                 end
 757         end
 758 end
 759
 760 # Javacript template
 761 class TplScript
 762         super Template
 763
 764         var attrs = new Array[TagAttribute]
 765         var content: nullable Streamable writable
 766
 767         init do
 768                 attrs.add(new TagAttribute("type", "text/javascript"))
 769         end
 770
 771         protected fun render_content do
 772                 if content != null then add content.as(not null)
 773         end
 774
 775         redef fun rendering do
 776                 add "<script"
 777                 for attr in attrs do add attr
 778                 add ">"
 779                 render_content
 780                 add "</script>"
 781         end
 782 end
 783
 784 # JS script for Piwik Tracker
 785 class TplPiwikScript
 786         super TplScript
 787
 788         var tracker_url: String
 789         var site_id: String
 790
 791         init(tracker_url, site_id: String) do
 792                 super
 793                 self.tracker_url = tracker_url
 794                 self.site_id = site_id
 795         end
 796
 797         redef fun render_content do
 798                 add "<!-- Piwik -->"
 799                 add "var _paq = _paq || [];"
 800                 add " _paq.push([\"trackPageView\"]);"
 801                 add " _paq.push([\"enableLinkTracking\"]);"
 802                 add "(function() \{"
 803                 add " var u=((\"https:\" == document.location.protocol) ? \"https\" : \"http\") + \"://{tracker_url}\";"
 804                 add " _paq.push([\"setTrackerUrl\", u+\"piwik.php\"]);"
 805                 add " _paq.push([\"setSiteId\", \"{site_id}\"]);"
 806                 add " var d=document, g=d.createElement(\"script\"), s=d.getElementsByTagName(\"script\")[0]; g.type=\"text/javascript\";"
 807                 add " g.defer=true; g.async=true; g.src=u+\"piwik.js\"; s.parentNode.insertBefore(g,s);"
 808                 add "\})();"
 809         end
 810 end
 811