UPGRADING.md

# Upgrading

### Torch v4 to Torch v5

Torch v5 **IS NOT ** fully backwards compatible with Torch v4.  Due to Phoenix 1.7 dropping the inclusion
of `Phoenix.View` in the core SDK, the way the templates are created, and the content of the templates
generated by Torch have changed significantly.

There is no automatic upgrade path for existing files that were generated with previous versions of Torch.
If you encounter issues using Torch v5 with existing templates, you can either continue to use Torch v4,
or manually update your existing Torch templates to the new unified function component style
provided by `Torch.Component`.

Templates that were generated with Torch v4 _should_ still funtion, if you manaully included `:phoenix_view`
in your projects mix dependencies, but your results may vary.  For templates generated with Torch v4, you
would also need to make the manual updates described below in the "Torch v3 to Torch v4" section.

#### Slime support dropped

Torch v5 has dropped support for Slime templates.  Only heex templates
are now supported.

### Torch v3 to Torch v4

Torch v4 **IS NOT** fully backwards compatible with Torch v3.  In particular, the templates have changed
in a manner that affect the generated DOM and CSS rules used.

To manually update your existing templates to the new v4 DOM do the following:

#### show.html.*

* `<div class="header"></div>` becomes `<header class="header"></header>`
* `<ul><li>...</li></ul>` list for model properties becomes `<section class="torch-show-details"><div class="torch-show-attribute">...</div></section>`

#### form.html.*

Inside `<div class="torch-form-group>...</div>`, the `input` and `error` outputs are now wrapped in an additional div:

    <div class="torch-form-group">
      <%= label %>
      <%= input %>
      <%= error %>
    </div>

becomes:

    <div class="torch-form-group">
      <%= label %>
      <div class="torch-form-group-input">
        <%= input %>
        <%= error %>
      </div>
    </div>


Another option to "upgrade" is to just generate new templates again via the Torch v4 generators.  Run the same
generator commands as the first time and overwrite your existing files.  Then resolve any customization previously
made to your Torch v3 templates by re-applying those change to the newly generated Torch v4 templates.