eiffel-org/documentation/trunk/eiffelstudio/eiffelstudio-reference/eiffelstudio-editor/Code-Templates.wiki

[[Property:uuid|7CCF602E-0B79-49C2-93FE-39C90CBE4E35]]
[[Property:link_title|Code Templates]]
[[Property:title|Code Templates]]
[[Property:weight|7]]

<span id="what_are_code_templates"></span> 
= What are code templates and how do they help me? =

EiffelStudio offers Code Templates. Introduced in version 16.11, code templates facilitate the programmer’s task by proposing program schemes that correspond to typical situations. Code templates are contextual: based on some properties of your code, EiffelStudio  will offer a list of templates that could -- just could! -- do exactly what’s on your mind at the moment.


For example, if you are using an integer array, EiffelStudio will offer a code template for a common operation: computing computes the array’s maximum. If you select the template, EiffelStudio will insert its code into your program, giving you the option of specifying the starting and ending indices (which it sets by default to the array’s bounds). You just have to specify the information relevant to your particular case; the template takes care of the implementation.


EiffelStudio comes with a number of predefined templates; you can also contribute your own.
There are two kinds of template:

* Targeted, that is, applied to a certain target entity.  For example, if you have a variable of type <code>ARRAY [INTEGER]</code>, EiffelStudio will offer you templates that work on that array (the “target”).
* Targetless (or “global’): applicable in all contexts, without a target.


<span id="how_do_i_use_templates"></span> 
= How do I use templates in EiffelStudio? =

==Target Templates==
Code templates are part of EiffelStudio’s code completion mechanism. Code completion lets you choose a code template at the same place where it offers you features to call: when you type a dot character “.” after the name of an applicable local variable, attribute or function, a menu appears:

[[Image:target_template_1_0]]

Figure 1. Auto-completion with code template option

If there are any applicable targeted templates, the first entry says “Show templates (Ctrl+Space)” and you can click it to get a list of applicable templates:

[[Image:target_template_1_1]] 

Figure 2. Auto-completion with code templates option list

As suggested, you can also type Control-space to get the same effect. If you find a template that you like, just click it (or navigate to it in the list using the up and down arrow keys, then type Return).

== Targetless Templates ==
It's also possible to use code templates without a target after type Control-Space, if there are any applicable targetless templates, the first entry says “Show templates (Ctrl+Space)” and you can click it to get a list of applicable templates. Choose the desired one by clicking or navigating.

[[Image:targetless_template_1_3]]

Figure 3. Targetless Auto-completion with code template option 

When you insert a template into your code, it will often have some highlighted fields, corresponding to the template arguments, for example the lower and upper bounds of the array slice whose maximum you need:

[[Image:targetless_template_1_4|680px]] 

Figure 4. Targetless Auto-completion with code templates option list.

<span id="eiffel_studio_templates"></span> 
= Where does EiffelStudio find the templates? =

To offer the template menus seen above, EiffelStudio looks in two locations:
* Standard templates, found in: 
** Linux: <code>$ISE_EIFFEL/studio/templates/code</code>
** Eiffel:  <code>%ISE_EIFFEL%/studio/templates/code</code>
* User-defined templates, which you can add at:
** Linux: <code> ~/.es/eiffel_user_files/16.11/templates/code</code>
** Windows: <code>C:/Users/your_user_name/Documents/Eiffel User Files/16.11/templates/code</code>

<span id="template_definition"></span> 
=What does a template definition look like?=

It is very easy to define a template. It is all done in Eiffel, of course. You simply define a class that inherits from TEMPLATE, with any number of routines, each of which introduces one template, applicable to targets of the corresponding type. If the routine has arguments, those will be the arguments of the template. Basically, that’s it!
Here is how we defined the template used in the above targeted example:

<code>
class ARRAY_TEMPLATE [T -> COMPARABLE] inherit
    
    TEMPLATE [ARRAY [T]]

feature  -- Templates

   maximum: T
            -- Maximum of `target' array.  
        note
            tags: "Algorithm, Maximum, ARRAY"
        do
	    across target as element loop
                Result := Result.max (element.item)
            end
        end

   slice_maximum (low, high: INTEGER): T
             -- Maximum of an array, 
             -- where the interval is defined by default 
             -- by array.lower |..| array.upper.
         note
             tags: "Algorithm, Maximum, ARRAY"
             default: "target.lower, target.upper"
         do
             across low |..| high as i loop
                 Result := Result.max (target [i.item])
             end
         end  
end 
</code>

This class defines two templates: maximum for the maximum of an entire array, and slice_maximum for the maximum of some contiguous part (“slice”) of that array.
That was a targeted template: EiffelStudio will propose it whenever the user types a dot after a target of type ARRAY [T] where T is a “COMPARABLE”. Note how you specify the target: as the actual generic parameters of TEMPLATE; that’s why the definition starts here as

<span id="share_code_templates"></span> 
=Sharing code templates=
You can share your code templates using Github

<span id="githib_code_templates"></span> 
=Contributing Code Templates EiffelStudio=

  == Fork the project == 
Clone your fork, and configure the remotes.  EiffelStudio github location: https://github.com/EiffelSoftware/EiffelStudio 

# Clone your fork of the repo into the current directory: <code>git clone https://github.com/<your-username>/<repo-name></code>
# Navigate to the newly cloned directory: <code>cd <repo-name></code>
# Assign the original repo to a remote called "upstream": <code>git remote add upstream https://github.com/<upstream-owner>/<repo-name></code>

If you cloned a while ago, get the latest changes from upstream:

<code>
git checkout <dev-branch>
git pull upstream <dev-branch>
</code>

== New Branch ==
Create a new topic branch (off the main project development branch) to contain your new code template
<code>git checkout -b <topic-branch-name></code>
Commit your changes in logical chunks. Before to commit double check Tim Pope's A Note About Git Commit Messages (http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
Use Git's interactive rebase feature to tidy up your commits before making them public.

Locally merge (or rebase) the upstream development branch into your topic branch:

<code>git pull [--rebase] upstream <dev-branch></code>

Push your topic branch up to your fork:

<code>git push origin <topic-branch-name></code>

==Pull Request== 
Open a Pull Request with a clear title and description


== Code Template Review ==
For your work to be integrated into the project, the maintainers will review your work and either request changes or merge it.


<span id="gui_template"></span> 
=Associating GUI with Template definition=
The following image shows the relationship between the template definition and how they will look in the GUI.

[[Image:target_template_1_2|780px]] 
Figure 5. Gui and Template relationship.


* Feature name or metadata `title` if present will be used as the value in the list of completion possibilities.
* Feature comment will be used in the tooltip description of a selected template.
* Feature body will be used in the tooltip code preview.