README.md

# Ext: sg_news

<img src="https://www.sgalinski.de/typo3conf/ext/project_theme/Resources/Public/Images/logo.svg" />

License: [GNU GPL, Version 2](https://www.gnu.org/licenses/gpl-2.0.html)

Repository: https://gitlab.sgalinski.de/typo3/sg_news

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_news

## About

Integrates a powerful News system. News and Categories can be created like normal TYPO3 pages. Newspages have several
additional meta information.

## Integration

Before using sg_news, you need to supply your frontend some information on how the extension needs to be integrated into
your template.

As the extension itself provides two
new [doktypes](https://docs.typo3.org/typo3cms/CoreApiReference/PageTypes/Index.html), you can simply add a switch case
to your Fluid template to provide different rendering paths.

### Example

```TypoScript
lib.pageTemplate.default >
lib.pageTemplate.default = FLUIDTEMPLATE
lib.pageTemplate.default {
	# your default page template
	file = EXT:project_theme/Resources/Private/Templates/Default.html

	variables {
		INTRO = CASE
		INTRO {
			key.field = doktype

			# show nothing for the intro view as sg_news provides it's own default intro section
			116 = TEXT
			116.value =

			117 = COA
			117 {
				10 < tt_content.list.20.sgnews_latest
				20 < styles.content.col0
			}

			# just show the content
			default < styles.content.col0
		}

		CONTENT = CASE
		CONTENT {
			key.field = doktype

			# show the single view of a news article if the page type matches
			116 < tt_content.list.20.sgnews_singleview

			# show the category view of the news if the page type matches
			117 = COA
			117 {
				10 < tt_content.list.20.sgnews_listbycategory
				20 < styles.content.col1
			}

			# just show the content
			default < styles.content.col1
		}
	}
}
```

In this example we will load the first column for the intro section by default, and the second column in the backend for
the content below that.

The news category (doktype 117) will render by default not the content on the page alone, but also the default category
listing.

With our example we don't want the intro section (116) and the default content to be rendered because the extension
handles those parts.

The single news plugin also needs some additional information so it can get the base content. By default, it will
resolve to the following code if not provided by you:

```TypoScript
lib.mainContent < styles.content.col1
```

### Example integration into your page template

Finally, you need to output the `INTRO` and `CONTENT` variable in your page template:

```HTML

<main>
    <!--TYPO3SEARCH_begin-->
    <f:if condition="{INTRO}">
        <div class="intro-section">
            {INTRO -> f:format.raw()}
            {BREADCRUMB_MENU -> f:format.raw()}
        </div>
    </f:if>

    <div class="main-content">
        {CONTENT -> f:format.raw()}
    </div>
    <!--TYPO3SEARCH_end-->
</main>
```

### Implement author id mapping in TYPO3 9

To enable the author id mapping in TYPO3 9, you need to add this routeEnhancer configuration to your config.yaml.

```YAML
routeEnhancers:
    NewsByAuthor:
        type: Extbase
        extension: SgNews
        plugin: NewsByAuthor
        routes:
            -   routePath: '/{authorTitle}'
                _controller: 'NewsByAuthor::list'
                _arguments: { 'authorTitle': authorId }
        defaultController: 'NewsByAuthor::list'
        aspects:
            authorTitle:
                type: PersistedAliasMapper
                tableName: tx_sgnews_domain_model_author
                routeFieldName: path_segment
```

### Tags

In addition to categories, multiple tags can be created and specified for each news page.

Tags can be created by adding sys_category records to the root page of the news block (blog). In order to differentiate
each block's tags from the others, the PageTS value of `TCEFORM.pages.tx_sgnews_tags.PAGE_TSCONFIG_ID`
can be set for each of the blocks containing the pid value for the selectable tags.

To make sure that only the correct tags are displayed in the FE, the `plugin.tx_sgnews.settings.tagPid`
constant must be set to the same value.

### Creating a news blog

Add the plugin **News Overview** and optionally the plugin **Latest News** to a standard TYPO3 page.

After that you must create sites of type **Category** sites below the blog page level and name them accordingly.

On the next lower page level of each **Category** you can create pages of type **News**. On these pages you can use all
your usual content elements to visualize your news entries belonging to the specific category.

### Plugins

General settings for the plugins can be found in the **Frontend/setup.typoscript** and **Frontend/constants.typoscript**
files:

*setup.typoscript*

```TypoScript
settings {
    # Name of your site - required for the news.xml
    siteName =

    # Your rootpage id - required for the news.xml to retrieve the base path
    rootpageId = 1

    # News limit (can be usually set also inside the flexforms)
    newsLimitPerPage = {$plugin.tx_sgnews.settings.newsLimitPerPage}

    # Uid of the page containing sys_category records used as tags
    tagPid = {$plugin.tx_sgnews.settings.tagPid}

    # How to sort the news in general (date, positionInTree)
    sortBy = date
}
```

*constants.typoscript*

```TypoScript
settings {
    newsLimitPerPage = 12
    tagPid =
}
```

This extension comes with several plugins to display and categorize news:

###### News Overview

Provides an overview over all news. Additionally, there is a tab navigation for groups of news.

Plugin options:

- **Group By**:    By which aspect should your news be grouped in the tab navigation (none, category, tags)
- **News Limit**:    The maximum amount news to be displayed. Further news can be displayed after the user clicks a
  button.
- **Only news within this page section**:    Should only news from subpages be shown, or from all sites in this TYPO3
  instance?

---

###### List News by Category/Tag

Lists all news from subpages for the given Categories / Tags.

Plugin options:

- **News Limit per Page**: The maximum amount of news to be shown.
- **Categories**: Here you can select which categories you want to be included (If none are selected, all are shown).
- **Tags**: Here you can select which tags the news entries need to have to be shown here (If none are selected, all are
  shown).

---

###### News Single View

Provides a new page type **News** in the **Page Module**, that renders the content as a news element in the frontend.

---

###### News Feed

Provides an RSS Feed **news.xml** as a typenum. The typenum is defined in the **Frontend/setup.typoscript** and needs to
be included in your TypoScript template:

```Typoscript
# news feed as own page type
newsFeed = PAGE
newsFeed {
    typeNum = 78906523

    10 = USER
    10 {
        userFunc = TYPO3\CMS\Extbase\Core\Bootstrap->run
        extensionName = SgNews
        pluginName = NewsFeed
        vendorName = SGalinski
        controller = NewsFeed
        action = index
        view < plugin.tx_sgnews.view
        persistence < plugin.tx_sgnews.persistence
        features < plugin.tx_sgnews.features
        legacy < plugin.tx_sgnews.legacy
        settings {
            # PIDs of news category pages (page doktype, not to be confused with actual sys_category records!!!)
            # If not provided, news of all categories are shown
            # Please separate multiple PIDs with a comma.
            showCategories =
            # UIDs of sys_category records, assigned to a news record in `tx_sgnews_tags`
            # If not provided, news of all tags are shown
            # Please separate multiple UIDs with a comma.
            showTags =
        }
    }

    config {
        disableAllHeaderCode = 1
        disableCharsetHeader = 1
        no_cache = 1
        xhtml_cleaning = 0
        index_enable = 0
        additionalHeaders {
            10 {
                header = Content-Type:text/xml
                replace = 0
            }
        }
    }
}
```

If you need multiple news feeds with different content, you can duplicate the provided configuration and modify the
typenum & parameters like showCategories / showTags:

```Typoscript
myOtherNewsFeed < newsFeed
myOtherNewsFeed.typeNum = ENTER_YOUR_TYPENUM_HERE
myOtherNewsFeed.10.settings.showCategories =
myOtherNewsFeed.10.settings.showTags =
```

---

###### PageBrowser

Automatically adds a pagination to the **News Overview** and **List News** plugins. You find the settings in the **
Fontend/constants.typoscript** configuration file:

```Typoscript
pagebrowser.settings {
    # Number of page links to show before the current page
    pagesBefore = 1

    # Number of page links to show before the current page
    pagesAfter = 1

    # Enables section for "more" pages. This section is shown after links to next pages, normally like three dots (1 2 3 ...). Notice that you can also hide it by emptying corresponding template section.
    enableMorePages = 1

    # Enables section for "less" pages. This section is shown after links to next pages, normally like three dots (... 1 2 3) Notice that you can also hide it by emptying corresponding template section.
    enableLessPages = 1
}
```

Example route enhancers with a static range for the page number to be able to generate URLs without additional cHash parameter

```YAML
routeEnhancers:
  PageBrowserNews:
    type: Plugin
    namespace: tx_sgnews_pagebrowser
    routePath: '/{localizedSegment}/{currentPage}'
    defaults:
      currentPage: '0'
    aspects:
      currentPage:
        type: StaticRangeMapper
        start: '1'
        end: '1000'
      localizedSegment:
        type: LocaleModifier
        default: page
        localeMap:
          -
            locale: 'de_DE.*'
            value: page
```

---

###### addLike

Automatically adds an AJAX like button to each single news entry. Make sure that the extension **sg_ajax** is installed,
otherwise this feature will be disabled. If it should be like this, then make sure to remove this button from the
sg_news default templates.

## The Backend Module

After a successful Installation, you have a new module in the "WEB" section of your TYPO3 Backend.

Clicking on it loads the administration panel. Using the drop-down above you can switch between the different languages
set up in your TYPO3 installation. Once you have selected a language, the module will display the news records and tag
filter corresponding to that language.

If you have selected a root-page in the page-tree, the module will display a list of news pages corresponding to this
root page, with respect to the current user permissions. Here you can filter the results by Category, Tags or by a
search word.

Selecting a News Category Page in the page-tree, will display the list of news pages in this Category. The same
functionality as for the root page, but without the category filter.

***Note*** : The search-word filter is language-sensitive.

You can also use
the '<img height="20px" width="20px" src="https://camo.githubusercontent.com/cd0d2f12f28169acfbafd1c8bf8f291155f3d210/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d6e65772e737667">
Add News Record' and
the '<img height="20px" width="20px" src="https://camo.githubusercontent.com/cd0d2f12f28169acfbafd1c8bf8f291155f3d210/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d6e65772e737667">
Add News Category' buttons to add News/Cateogry pages under the currelty selected page where available.

### Options for your news list items

For each news item in the paginated result list you have multiple editing/administration options, depending on the
logged-in user's permissions.

You can click a list item's title to edit it (language sensitive) or use the menu buttons:

<img height="20px" width="20px" src="https://camo.githubusercontent.com/bcf1ba22efb779447495395e452154160e2b39ba/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d76657273696f6e2d776f726b73706163652d707265766965772e737667"> Preview the frontend page
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/cf8d1359b3a6ef79ca3731f6f0e0e01bcf992dcb/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d76657273696f6e2d706167652d6f70656e2e737667"> Edit
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/3c5e6daff1f31fd3c4bf0ac3e70520133d06441c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d686964652e737667"> Disable/Enable
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/7773a0fc11517dc70b81f9ba516991f3669493e1/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d64656c6574652e737667"> Delete
<br>
 .... Expand/Collapse the options menu
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/ee057cb37045beeccf8078f74e65e1774ec5e001/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d696e666f2e737667"> Show further information
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/b4980d61f65fdfca4853fbd240f88de2b6fcb893/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d706167652d6d6f76652e737667"> Change the page's position in the page-tree
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/91c383d7beded93dbe6a62e2a1ae94bf82d1d783/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d686973746f72792d6f70656e2e737667"> Show history
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/78584763b0c5d3c1908183719f3b37508bd54620/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d6c6f636b2e737667"> Change permissions
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/b51a6820d6b9322bc4ef419b827a423f9b7cc57c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d706167652d6e65772e737667"> Create new
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/1794befd17574f066d0b3513729d731c158b8b0a/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d636f70792e737667"> Copy
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/1fc865a03039be5039e6069f2f53d1db2a8e3896/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d6375742e737667"> Cut
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/4646af23ac205e052ac3addf238868e59c047111/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d70617374652d696e746f2e737667"> Paste into
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/7908ba1757d3b77ba3b9444c095bb0582e74a4af/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d70617374652d61667465722e737667"> Paste after
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/2ba239d52c48bbcdc9d059a8aeca2eb7eb41a07a/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d6f70656e2e737667"> Edit Page Content

You can also handle the localisation of news pages for all the languages in your TYPO3 installation by using the
localisation links under each record's title:

- **full-opacity flag icon** : Edit the existing localisation record
- **half-transparent flag icon
  with <img height="14px" width="14px" src="https://camo.githubusercontent.com/b10f4d50dc21b152cde15cef5983c139e77b1c34/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f6f7665726c61792f6f7665726c61792d6e65772e737667"/>
  overlay** : Create new localisation record

***Note*** : The extension also adds a News Module link in the Page Module of News/Category pages

## Migrating tx_news to sg_news

This extension comes with the command controller task **** to migirate tx_news entries to sg_news. The task comes with
the following parameters:

- **copyPageId** : You will need a template site, which will be the basis of each new news record. Create your content
  elements accordingly on this site.
- **categoryPid** : This needs to be the category page id, you want your news to be children of.
- **year** : Only news of this year will be migrated
- **languageMapAsJson** : a json string, mapping language ids (old => new). this is needed if the sys_language_uids have
  changed
- **categoryMapAsJson** : a json string, mapping sys_category ids (old => new).
- **pId** : only news from that pid will be migrated

### Migrating File References

To use your old file references, you need to import your sys_file and sys_file_reference_table as
sys_file_news_migration and sys_file_reference into your database. The Filepaths must not change!