1 # This file is part of NIT ( http://www.nitlanguage.org ).
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
7 # http://www.apache.org/licenses/LICENSE-2.0
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.
15 # HTML templates for Nit model MEntities.
20 import html_components
21 import html
::bootstrap
25 # ID used as a HTML unique ID and in file names.
27 # **Must** match the following (POSIX ERE) regular expression:
30 # ^[A-Za-z_][A-Za-z0-9._-]*$
33 # That way, the ID is always a valid URI component and a valid XML name.
34 fun nitdoc_id
: String is abstract
36 # URL of this entity’s Nitdoc page.
37 fun nitdoc_url
: String is abstract
39 # Returns the mentity name without short signature.
45 # * MClassDef: `Foo[E]`
46 # * MProperty: `foo(e)`
47 # * MPropdef: `foo(e)`
48 var html_name
: String is lazy
do return name
.html_escape
50 # Returns a Link to the mentity `html_url`.
52 # Example: `<a href="html_url" title="mdoc.short_comment">html_short_name</a>
53 var html_link
: Link is lazy
do
54 var tpl
= new Link(nitdoc_url
, html_name
)
55 var mdoc
= mdoc_or_fallback
57 tpl
.title
= mdoc
.short_comment
62 # Returns a Link to the mentity `nitdoc_id`.
64 # Example: `<a href="#nitdoc_id" title="mdoc.short_comment">html_short_name</a>
65 fun html_link_to_anchor
: Link do
66 var tpl
= new Link("#{nitdoc_id}", html_name
)
67 var mdoc
= mdoc_or_fallback
69 tpl
.title
= mdoc
.short_comment
74 # Returns the list of keyword used in `self` declaration.
75 fun html_modifiers
: Array[String] is abstract
77 # Returns the complete MEntity declaration decorated with HTML.
79 # * MProject: `project foo`
80 # * MGroup: `group foo`
81 # * MModule: `module foo`
82 # * MClass: `private abstract class Foo[E: Object]`
83 # * MClassDef: `redef class Foo[E]`
84 # * MProperty: `private fun foo(e: Object): Int`
85 # * MPropdef: `redef fun foo(e)`
86 fun html_declaration
: Template do
87 var tpl
= new Template
89 tpl
.add html_modifiers
.join
(" ")
96 # Returns `self` namespace decorated with HTML links.
98 # * MProject: `mproject`
99 # * MGroup: `mproject(::group)`
100 # * MModule: `mgroup::mmodule`
101 # * MClass: `mproject::mclass`
102 # * MClassDef: `mmodule::mclassdef`
103 # * MProperty: `mclass::mprop`
104 # * MPropdef: `mclassdef:mpropdef`
105 fun html_namespace
: Template is abstract
107 # Returns the comment of this MEntity formatted as HTML.
108 var html_comment
: nullable Writable is lazy
do
109 var mdoc
= mdoc_or_fallback
110 if mdoc
== null then return null
111 return mdoc
.tpl_comment
114 # Returns the comment of this MEntity formatted as HTML.
115 var html_short_comment
: nullable Writable is lazy
do
116 var mdoc
= mdoc_or_fallback
117 if mdoc
== null then return null
118 return mdoc
.tpl_short_comment
121 # Icon that will be displayed before the title
122 fun html_icon
: BSIcon do
123 var icon
= new BSIcon("tag")
124 icon
.css_classes
.add_all
(css_classes
)
128 # CSS classes used to decorate `self`.
130 # Mainly used for icons.
131 var css_classes
= new Array[String]
133 # A li element that can go in a `HTMLList`.
134 fun html_list_item
: ListItem do
135 var tpl
= new Template
136 tpl
.add
new DocHTMLLabel.with_classes
(css_classes
)
138 var comment
= html_short_comment
139 if comment
!= null then
143 return new ListItem(tpl
)
148 redef var nitdoc_id
= name
.to_cmangle
is lazy
149 redef fun nitdoc_url
do return root
.nitdoc_url
150 redef var html_modifiers
= ["project"]
151 redef fun html_namespace
do return html_link
152 redef var css_classes
= ["public"]
156 redef var nitdoc_id
is lazy
do
157 if parent
!= null then
158 return "{parent.nitdoc_id}__{name.to_cmangle}"
160 return name
.to_cmangle
163 redef fun nitdoc_url
do return "group_{nitdoc_id}.html"
164 redef var html_modifiers
= ["group"]
166 # Depends if `self` is root or not.
168 # * If root `mproject`.
169 # * Else `mproject::self`.
170 redef fun html_namespace
do
171 var tpl
= new Template
172 tpl
.add mproject
.html_namespace
173 if mproject
.root
!= self then
180 redef var css_classes
= ["public"]
184 redef var nitdoc_id
is lazy
do
185 if mgroup
!= null then
186 if mgroup
.mmodules
.length
== 1 then
187 return "{mgroup.nitdoc_id}-"
189 return "{mgroup.nitdoc_id}__{name.to_cmangle}"
192 return name
.to_cmangle
195 redef fun nitdoc_url
do return "module_{nitdoc_id}.html"
196 redef var html_modifiers
= ["module"]
198 # Depends if `self` belongs to a MGroup.
200 # * If mgroup `mgroup::self`.
202 redef fun html_namespace
do
203 var tpl
= new Template
204 if mgroup
!= null then
205 tpl
.add mgroup
.html_namespace
212 redef var css_classes
= ["public"]
216 redef var nitdoc_id
= "{intro_mmodule.nitdoc_id}__{name.to_cmangle}" is lazy
217 redef fun nitdoc_url
do return "class_{nitdoc_id}.html"
218 redef fun mdoc_or_fallback
do return intro
.mdoc
221 redef var html_name
is lazy
do
222 var tpl
= new Template
223 tpl
.add name
.html_escape
226 var parameter_names
= new Array[String]
227 for p
in mparameters
do
228 parameter_names
.add
(p
.html_name
)
230 tpl
.add parameter_names
.join
(", ")
233 return tpl
.write_to_string
236 redef fun html_modifiers
do return intro
.html_modifiers
237 redef fun html_declaration
do return intro
.html_declaration
239 # Returns `mproject::self`.
240 redef fun html_namespace
do
241 var tpl
= new Template
242 tpl
.add intro_mmodule
.mgroup
.mproject
.html_namespace
249 # Returns `intro.html_short_signature`.
250 fun html_short_signature
: Template do return intro
.html_short_signature
252 # Returns `intro.html_signature`.
253 fun html_signature
: Template do return intro
.html_signature
255 redef fun html_icon
do return intro
.html_icon
256 redef fun css_classes
do return intro
.css_classes
259 redef class MClassDef
260 redef var nitdoc_id
= "{mmodule.nitdoc_id}__{name.to_cmangle}" is lazy
261 redef fun nitdoc_url
do return "{mclass.nitdoc_url}#{nitdoc_id}"
262 redef fun mdoc_or_fallback
do return mdoc
or else mclass
.mdoc_or_fallback
264 # Depends if `self` is an intro or not.
266 # * If intro contains the visibility and kind.
267 # * If redef contains the `redef` keyword and kind.
268 redef fun html_modifiers
do
269 var res
= new Array[String]
273 if mclass
.visibility
!= public_visibility
then
274 res
.add mclass
.visibility
.to_s
277 res
.add mclass
.kind
.to_s
281 # Depends if `self` is an intro or not.
283 # For intro: `private abstract class Foo[E: Object]`
284 # For redef: `redef class Foo[E]`
285 redef fun html_declaration
do
286 var tpl
= new Template
288 tpl
.add html_modifiers
.join
(" ")
292 tpl
.add html_signature
294 tpl
.add html_short_signature
300 # Returns `mmodule::self`
301 redef fun html_namespace
do
302 var tpl
= new Template
303 tpl
.add mmodule
.html_namespace
305 tpl
.add mclass
.html_link
310 # Returns the MClassDef generic signature without static bounds.
311 fun html_short_signature
: Template do
312 var tpl
= new Template
313 var mparameters
= mclass
.mparameters
314 if not mparameters
.is_empty
then
316 for i
in [0..mparameters
.length
[ do
317 tpl
.add mparameters
[i
].html_name
318 if i
< mparameters
.length
- 1 then tpl
.add
", "
325 # Returns the MClassDef generic signature with static bounds.
326 fun html_signature
: Template do
327 var tpl
= new Template
328 var mparameters
= mclass
.mparameters
329 if not mparameters
.is_empty
then
331 for i
in [0..mparameters
.length
[ do
332 tpl
.add
"{mparameters[i].html_name}: "
333 tpl
.add bound_mtype
.arguments
[i
].html_signature
334 if i
< mparameters
.length
- 1 then tpl
.add
", "
341 redef fun css_classes
do
342 var set
= new HashSet[String]
343 if is_intro
then set
.add
"intro"
344 for m
in mclass
.intro
.modifiers
do set
.add m
.to_cmangle
345 for m
in modifiers
do set
.add m
.to_cmangle
350 redef class MProperty
351 redef var nitdoc_id
= "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}" is lazy
352 redef fun nitdoc_url
do return "property_{nitdoc_id}.html"
353 redef fun mdoc_or_fallback
do return intro
.mdoc
354 redef fun html_modifiers
do return intro
.html_modifiers
355 redef fun html_declaration
do return intro
.html_declaration
357 # Returns `mclass::self`.
358 redef fun html_namespace
do
359 var tpl
= new Template
360 tpl
.add intro_mclassdef
.mclass
.html_namespace
362 tpl
.add intro
.html_link
367 # Returns `intro.html_short_signature`.
368 fun html_short_signature
: Template do return intro
.html_short_signature
370 # Returns `intro.html_signature`.
371 fun html_signature
: Template do return intro
.html_signature
373 redef fun css_classes
do return intro
.css_classes
377 redef var nitdoc_id
= "{mclassdef.nitdoc_id}__{name.to_cmangle}" is lazy
378 redef fun nitdoc_url
do return "{mproperty.nitdoc_url}#{nitdoc_id}"
379 redef fun mdoc_or_fallback
do return mdoc
or else mproperty
.mdoc_or_fallback
381 # Depends if `self` is an intro or not.
383 # * If intro contains the visibility and kind.
384 # * If redef contains the `redef` keyword and kind.
385 redef fun html_modifiers
do
386 var res
= new Array[String]
390 if mproperty
.visibility
!= public_visibility
then
391 res
.add mproperty
.visibility
.to_s
397 # Depends if `self` is an intro or not.
399 # For intro: `private fun foo(e: Object): Bar is abstract`
400 # For redef: `redef fun foo(e) is cached`
401 redef fun html_declaration
do
402 var tpl
= new Template
404 tpl
.add html_modifiers
.join
(" ")
408 tpl
.add html_signature
410 tpl
.add mproperty
.intro
.html_link
411 tpl
.add html_short_signature
417 # Returns `mclassdef::self`
418 redef fun html_namespace
do
419 var tpl
= new Template
420 tpl
.add mclassdef
.html_namespace
426 # Returns the MPropdDef signature without static types.
427 fun html_short_signature
: Template is abstract
429 # Returns the MPropDef signature with static types.
430 fun html_signature
: Template is abstract
432 redef fun css_classes
do
433 var set
= new HashSet[String]
434 if is_intro
then set
.add
"intro"
435 for m
in mproperty
.intro
.modifiers
do set
.add m
.to_cmangle
436 for m
in modifiers
do set
.add m
.to_cmangle
441 redef class MAttributeDef
443 redef fun html_modifiers
do
449 redef fun html_short_signature
do return new Template
451 redef fun html_signature
do
452 var tpl
= new Template
453 if static_mtype
!= null then
455 tpl
.add static_mtype
.html_signature
461 redef class MMethodDef
463 # FIXME annotation should be handled in their own way
464 redef fun html_modifiers
do
468 else if is_intern
then
471 if mproperty
.is_init
then
479 redef fun html_short_signature
do return msignature
.html_short_signature
480 redef fun html_signature
do return msignature
.html_signature
483 redef class MVirtualTypeProp
484 redef fun html_link
do return mvirtualtype
.html_link
487 redef class MVirtualTypeDef
489 redef fun html_modifiers
do
495 redef fun html_short_signature
do return new Template
497 redef fun html_signature
do
498 var tpl
= new Template
499 if bound
== null then return tpl
501 tpl
.add bound
.html_signature
507 # Returns the signature of this type whithout bounds.
508 fun html_short_signature
: Template is abstract
510 # Returns the signature of this type.
511 fun html_signature
: Template is abstract
514 redef class MClassType
515 redef fun html_link
do return mclass
.html_link
516 redef fun html_short_signature
do return html_link
517 redef fun html_signature
do return html_link
520 redef class MNullableType
522 redef fun html_short_signature
do
523 var tpl
= new Template
525 tpl
.add mtype
.html_short_signature
529 redef fun html_signature
do
530 var tpl
= new Template
532 tpl
.add mtype
.html_signature
537 redef class MGenericType
538 redef fun html_short_signature
do
540 var tpl
= new Template
541 tpl
.add
new Link.with_title
(lnk
.href
, mclass
.name
.html_escape
, lnk
.title
)
543 for i
in [0..arguments
.length
[ do
544 tpl
.add arguments
[i
].html_short_signature
545 if i
< arguments
.length
- 1 then tpl
.add
", "
551 redef fun html_signature
do
553 var tpl
= new Template
554 tpl
.add
new Link.with_title
(lnk
.href
, mclass
.name
.html_escape
, lnk
.title
)
556 for i
in [0..arguments
.length
[ do
557 tpl
.add arguments
[i
].html_signature
558 if i
< arguments
.length
- 1 then tpl
.add
", "
565 redef class MParameterType
566 redef fun html_link
do
567 return new Link.with_title
("{mclass.nitdoc_url}#FT_{name.to_cmangle}", name
, "formal type")
570 redef fun html_short_signature
do return html_link
571 redef fun html_signature
do return html_link
574 redef class MVirtualType
575 redef fun html_link
do return mproperty
.intro
.html_link
576 redef fun html_signature
do return html_link
579 redef class MSignature
581 redef fun html_short_signature
do
582 var tpl
= new Template
583 if not mparameters
.is_empty
then
585 for i
in [0..mparameters
.length
[ do
586 tpl
.add mparameters
[i
].html_short_signature
587 if i
< mparameters
.length
- 1 then tpl
.add
", "
594 redef fun html_signature
do
595 var tpl
= new Template
596 if not mparameters
.is_empty
then
598 for i
in [0..mparameters
.length
[ do
599 tpl
.add mparameters
[i
].html_signature
600 if i
< mparameters
.length
- 1 then tpl
.add
", "
604 if return_mtype
!= null then
606 tpl
.add return_mtype
.html_signature
612 redef class MParameter
614 # Returns `self` name and ellipsys if any.
615 fun html_short_signature
: Template do
616 var tpl
= new Template
618 if is_vararg
then tpl
.add
"..."
622 # Returns `self` name with it's static type and ellipsys if any.
623 fun html_signature
: Template do
624 var tpl
= new Template
626 tpl
.add mtype
.html_signature
627 if is_vararg
then tpl
.add
"..."
632 redef class ConcernsTree
633 # Render `self` as a hierarchical UnorderedList.
634 fun html_list
: UnorderedList do
635 var lst
= new UnorderedList
636 lst
.css_classes
.add
"list-unstyled list-definition"
638 var li
= r
.html_concern_item
640 build_html_list
(r
, li
)
645 # Build the html list recursively.
646 private fun build_html_list
(e
: MConcern, li
: ListItem) do
647 if not sub
.has_key
(e
) then return
649 var lst
= new UnorderedList
650 lst
.css_classes
.add
"list-unstyled list-definition"
652 if e2
isa MGroup and e2
.is_root
then
653 build_html_list
(e2
, li
)
655 var sli
= e2
.html_concern_item
657 build_html_list
(e2
, sli
)
660 var text
= new Template
662 if not lst
.is_empty
then text
.add lst
668 # Return a li element for `self` that can be displayed in a concern list
669 private fun html_concern_item
: ListItem do
671 var tpl
= new Template
672 tpl
.add
new Link.with_title
("#concern:{nitdoc_id}", lnk
.text
, lnk
.title
)
673 var comment
= html_short_comment
674 if comment
!= null then
678 return new ListItem(tpl
)
682 ################################################################################
683 # Additions to `model_ext`.
686 redef fun html_signature
do
687 var tpl
= new Template
690 if part
.target
!= null then
691 tpl
.add part
.target
.as(not null).html_link
693 tpl
.add part
.text
.html_escape
700 redef class MInnerClass
701 redef fun nitdoc_url
do return inner
.nitdoc_url
702 redef fun html_signature
do return inner
.html_signature
705 redef class MInnerClassDef
706 redef fun nitdoc_url
do return inner
.nitdoc_url
708 redef fun html_link_to_anchor
do return inner
.html_link_to_anchor
709 redef fun html_link
do return inner
.html_link
710 redef fun html_signature
do return inner
.html_signature