Configuring Paragraph

Now that we have installed Paragraph, it's time to get things moving. If you are already using the official localization option of your framework, there is little left to do - Paragraph will automatically hook into the process.

Let's imagine we have a Laravel project that was never localized or maybe doesn't even have to be localized, it's a single language application:

<p>
    Some text here
</p>

We have our texts spread all over our Blade templates directly in the HTML markup and that's fine – many applications don't need anything more sophisticated than this. Now, if we want to be able to control this text and all other texts from Paragraph, we should enclose it in a framework-provided directive, in this case it's Laravel's @lang directive:

<p>
    @lang('Some text here')
</p>

If we refresh this page, this has exactly zero impact on your application – since there is no replacement text found for "Some text here", Laravel will just display "Some text here". So it's a non-breaking code update.

Discovering texts in Blade templates

Now that we have some texts wrapped in the language directive, we have a few options of how to submit these texts to Paragraph so that they can be controlled from there in a more convenient way. One option is to scan the view folder(s) and find all instances of the directive:

$ php artisan paragraph:submit-texts
Where should we look for Blade templates? [/Users/laravel-empty/resources/views]:
 [0] /Users/laravel-empty/resources/views
 [1] All of the above
 [2] My template path is not in the list
> 0

Discovered 1 view template

Discovering texts in language files

Another option that's going to work well for people who already use the language directive and have application texts in framework's language files is to scan these language files and import all existing texts right away:

$ php artisan paragraph:submit-texts
Where should we look for language files? [/Users/laravel-empty/module/lang]:
  [0] /Users/laravel-empty/module/lang
  [1] /Users/laravel-empty/lang
  [2] All of the above
  [3] My template path is not in the list
 > 2

Discovered 7 language files with a total of 96 texts

Discovering texts during render – Best

While the two previous options are simple and convenient, they have one major drawback – there is no way to distinguish between current and stale texts. We could be importing views and language files that aren't used anywhere in your application anymore and you could be wasting time and effort working on them.

A more advanced and more solid option is to catch the texts during the render process. This way, we know that everything that's coming our way is actually being displayed somewhere.

After you wrapped some of the texts in the language directive and browsed some pages, if you look in the "storage" folder you might notice some magic "snapshot" files appearing:

$ ls storage/*snapshot*
storage/paragraph_view_snapshot_errors::404.html	storage/paragraph_view_snapshot_welcome.html

These are views rendered by your application's framework and they have some extra meta data embedded in the original layout. These snapshots serve multiple goals:

• We can find all active texts and see what context they are used in;
• We can display nice rendered pages and offer in-place editing

$ php artisan paragraph:submit-views
Submitting /Users/laravel-empty/storage/paragraph_view_snapshot_errors::404.html
Submitting /Users/laravel-empty/storage/paragraph_view_snapshot_welcome.html
Submitted a total of 2 snapshots

You will see these pages now in your Paragraph dashboard. We will even try to automatically guess the route and the corresponding controller.