Editing Template:Easy CSS image crop/doc

{{Documentation subpage}}
{{lua|Module:ImageRatio}}
This is intended to be an easier way to prepare {{tlx|CSS image crop}} crops, making it more intuitive and easier to guess what you'll get. It also allows for more predictable scaling: Want to make the image bigger after setting up a crop? Just change <code>desired_width</code> and the rest will follow. 

==Usage==
<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|image                 = <!-- The name of the image file. 
                         Do not include File: at the start. Just the base page name. -->
|desired_width         = <!-- How wide the image should be after cropping. Defaults to 220. -->
|crop_left_perc        = <!-- Percent to crop from the left, leaving out percentage sign (so 10.3% becomes 10.3) -->
|crop_right_perc       = <!-- Percent to crop from the right. -->
|crop_top_perc         = <!-- Percent to crop from the top. -->
|crop_bottom_perc      = <!-- Percent to crop from the bottom. -->
|align                 = <!-- 'right', 'left', 'center' or 'none'. Determines placement of the image on the page
                         Defaults to 'right' when description is provided (as is default for thumb images)
                         When description is blank, it defaults to left (as is default for non-thumbs) 
                         |location = may be used instead of |align = for compatibility with the old template. -->
|caption               = <!-- Caption for the image (will render out using thumbnail class). 
                         |description = can be used instead of |caption = for compatibility. -->
|link                  = <!-- Name of an article to be linked by clicking on the image (omit unless there is a
                         good reason to link to an article instead of the image). -->
|alt                   = <!-- The alt text for the image. -->
|page                  = <!-- The page of the file, if there are multiple pages (such as pdf files). -->
|magnify-link          = <!-- The image to be linked by the magnify icon (Use if the image parameter is set to
                         {{Annotated image}} or the Link parameter leads to something other than the image). -->
}}
</syntaxhighlight>

===Basic parameters===

<syntaxhighlight lang="wikitext">

{{Easy CSS image crop
|image                 = The name of the image file, e.g. Foo.jpg
|desired_width         = How wide the image should be after cropping. Defaults to 220.
|crop_left_perc        = Percent to crop from the left, leaving out percentage sign (so 10.3% becomes 10.3)
|crop_right_perc       = Percent to crop from the right.
|crop_top_perc         = Percent to crop from the top.
|crop_bottom_perc      = Percent to crop from the bottom.
|alt                   = alternative text for the image (description for the blind)
}}
</syntaxhighlight>

<code>desired_width</code> can be left out if the default of 220 pixels wide is acceptable. Any of the crop percentage parameters can be left out if you don't want to crop from that side. (But if you're not using at least one of them, why are you using this template?)  All crop parameters default to 0, which means nothing is cropped from that side.  <code>alt</code> is optional, but best practice is to include it.

In infoboxes, add the line:

<syntaxhighlight lang="wikitext">
|align                = center
</syntaxhighlight>

This causes it to behave as expected in an infobox.

===For an image that renders as a thumbnail===

<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|image                 = The name of the image file
|desired_width         = How wide the image should be after cropping. Defaults to 220.
|crop_left_perc        = Percent to crop from the left, leaving out percentage sign (so 10.3% becomes 10.3)
|crop_right_perc       = Percent to crop from the right.
|crop_top_perc         = Percent to crop from the top.
|crop_bottom_perc      = Percent to crop from the bottom.
|caption               = The image caption
|alt                   = alternative text for the image (description for the blind)
}}
</syntaxhighlight>

<code>alt</code> is optional, but best practice.

==<code><nowiki>{{Annotated image}}</nowiki></code>==
{{tlx|Annotated image}} is not currently supported here, due to [[Module:ImageRatio]] only accepting the base filename. Please continue using {{tlx|CSS image crop}} if you want to use it with an annotated image.

==Examples==

'''Base image:'''

[[File:Theodore Roosevelt by the Pach Bros.jpg|220px]]

'''Cropped, but at the same width:'''

{{Easy CSS image crop
|image                 = Theodore Roosevelt by the Pach Bros.jpg
|desired_width         = 220
|crop_left_perc        = 10
|crop_right_perc       = 10
|crop_top_perc         = 5
|crop_bottom_perc      = 
}}

'''Code for the crop:'''

<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|image                 = Theodore Roosevelt by the Pach Bros.jpg
|desired_width         = 220
|crop_left_perc        = 10
|crop_right_perc       = 10
|crop_top_perc         = 5
|crop_bottom_perc      = 
}}
</syntaxhighlight>

This crops 10% from the left, 10% from the right, 5% from the top, and nothing from the bottom, and keeps the image 220 px wide. Since it's the same width, but bits have been cropped, this gives a "zoomed in" effect, which is generally what you want in articles. Note that, since it has no value, <code>crop_bottom_perc=</code> could have been left out. We left out <code>alt=</code>; it ''is'' optional, but, as it's good practice, we'll use it in other examples.

If we want to have this as a standard in-article thumbnail (with a description and the box around it), we can use:

{{Easy CSS image crop
|image                 = Theodore Roosevelt by the Pach Bros.jpg
|desired_width         = 220
|crop_left_perc        = 10
|crop_right_perc       = 10
|crop_top_perc         = 5
|crop_bottom_perc      = 
|caption               = [[Theodore Roosevelt]].
|alt                   = A man with a moustache wearing pince-nez eyeglasses
}}

<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|image                 = Theodore Roosevelt by the Pach Bros.jpg
|desired_width         = 220
|crop_left_perc        = 10
|crop_right_perc       = 10
|crop_top_perc         = 5
|crop_bottom_perc      = 
|caption               = [[Theodore Roosevelt]]
|alt                   = A man with a moustache wearing pince-nez eyeglasses
}}
</syntaxhighlight>

Which renders as seen to the right. We could also have used <code>|description =</code> instead of <code>|caption =</code> for the same effect:

<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|image                 = Theodore Roosevelt by the Pach Bros.jpg
|desired_width         = 220
|crop_left_perc        = 10
|crop_right_perc       = 10
|crop_top_perc         = 5
|crop_bottom_perc      = 
|description           = [[Theodore Roosevelt]]
|alt                   = A man with a moustache wearing pince-nez eyeglasses
}}
</syntaxhighlight>

This is because {{tl|CSS image crop}} was created with certain idiosyncratic names for the parameters that aren't standard, but it's also existed for over a decade. Also, for further backwards compatibility, note that the captitalised forms of the shared parameters ({{mono|Image, Location, Description, Link, Alt,}} and {{mono|Page}}) will all still work with this template.

===Comparison with <code><nowiki>{{CSS image crop}}</nowiki></code>===

One example used in the documentation for the old template (which is, in fact, called by this one after doing all the necessary calculations) is isolating a water drop from a photo. The original file:

[[File:Dew on grass Luc Viatour.jpg|400px]]

Is cropped to this: 
{{Easy CSS image crop
|Image = Dew on grass Luc Viatour.jpg
|desired_width    = 100
|crop_left_perc   = 15
|crop_right_perc  = 60
|crop_top_perc    = 62.7
|crop_bottom_perc = 2.4
}}


Easy CSS image crop can do this as well. Here's the code:
<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|Image = Dew on grass Luc Viatour.jpg
|desired_width    = 100
|crop_left_perc   = 15
|crop_right_perc  = 60
|crop_top_perc    = 62.7
|crop_bottom_perc = 2.4
}}
</syntaxhighlight>

In practice, you might not care about it being quite that precise. However, the big advantage of Easy CSS image crop is that once you're happy with your crop, simply changing <code>|desired_width =</code> can scale your crop however you want. 

{{Easy CSS image crop
|Image = Dew on grass Luc Viatour.jpg
|desired_width    = 150
|crop_left_perc   = 15
|crop_right_perc  = 60
|crop_top_perc    = 62.7
|crop_bottom_perc = 2.4
}}

<syntaxhighlight lang="wikitext">
{{Easy CSS image crop
|Image = Dew on grass Luc Viatour.jpg
|desired_width    = 150
|crop_left_perc   = 15
|crop_right_perc  = 60
|crop_top_perc    = 62.7
|crop_bottom_perc = 2.4
}}
</syntaxhighlight>

This is much, much harder with {{tlx|CSS image crop}}: You have to calculate a scaling ratio and apply it to every parameter. 

Admittedly, cropping a tiny bit out of a large image with any sort of CSS image crop is very inefficient: It still has to load a thumbnail big enough to crop that tiny bit from. In this case, it's loading a 400px wide image for the first, smaller example of the isolated water droplet, and a 900px wide image for the second. Not ideal, and probably a case where using [[Commons:Commons:Croptool|CropTool]] would be much more sensible! However, for more sensible crops, this can be a major boon, as it allows MediaViewer to pull up the missing context when the image is clicked on, showing the viewer the whole image, as well as linking to a file that's arguably more useful to reusers of our content (They can crop images themselves, for ''their'' specific usage.)
<includeonly>{{Sandbox other|
| <!-- CATEGORIES BELOW THIS LINE, PLEASE: -->
[[Category:Image formatting and function templates]]
}}</includeonly>