joomlatools / joomlatools-pages Goto Github PK

Some sanity checks are missing to avoid notices.

Related PR's for documentation purposes

1. Http Caching: #22

Implement http caching support through cacheable dispatcher behavior.

2. Data support: #4

Data improvements:

• Filter method
• Combining data files from different locations
• Dynamic frontmatter properties

Additional improvements

• Added The ComPagesRouter::getPage() method to return the active page after routing

• Ability to configure by adding a config.php to /joomlatools-pages root for the moment only cache configuration supported. (see)

• Added slug()template method to easily generate a ASCII slug from a UTF-8 string.

Write a documentation for the Pages component aimed at developers. Description of features are detailed in the release logs:

• 0.1.0 #7
• 0.2.0 #20
• 0.3.0 #23
• 0.4.0 #42
• 0.5.0 #53
• 0.6.0 #57
• 0.7.0 #62
• 0.8.0 #77
• 0.9.0 #89
  • 0.9.2 #103
  • 0.9.3 #110
  • 0.9.4 #115
• 0.10.0 #121
  • 0.10.1 #136
• 0.11.0 #140
• 0.12.0 #148
  • 0.12.1 #156
• 0.13.0 #168
  • 0.13.1 #173
  • 0.13.2 #179
  • 0.13.3 #187
• 0.14.0 #181
  • 0.14.1 #196
  • 0.14.2 #206
• 0.15.0 #209
• 0.16.0 #219
  • 0.16.1 #225
  • 0.16.2 #240
  • 0.16.3 #266
• 0.17.0 #276
  • 0.17.1 #316
• 0.18.0 #384
• 0.19.0 #448
  • 0.19.1 #472
  • 0.19.2 #494
  • 0.19.3 #504
  • 0.19.4 #521
  • 0.19.5 #531
  • 0.19.6 #550
  • 0.19.7 #580
  • 0.19.8 #600
  • 0.19.9 #610
  • 0.19.10 #620
• 0.20.0 #660
  • 0.20.1 #665
• 0.21.0 #728
  • 0.21.1 #735
  • 0.21.2 #771
  • 0.21.3 #785
  • 0.21.4 #794
  • 0.21.5 #807
  • 0.21.6 #811
• 0.22.0 #823
  • 0.22.1 #830
  • 0.22.2 #837
  • 0.22.3 #842
  • 0.22.4 #880
• 0.23.0 #956
  • 0.23.1 #966
  • 0.23.3 #972
  • 0.23.3 #990
  • 0.23.4 #995

Allow to decorate an existing Joomla page.

Improve the content plugin implementation. Implement it as a page filter to give more flexibility and disable it by default.

Add theme:// asset scheme to resolve to the path of the of the active Joomla template.

Implement a page object adding support for following page properties

• title
• description
• content
• date
• published
• category
• tags
• redirect
• metadata
• access
  -- groups
  -- roles
• process
  -- plugins

Add support for triggering the content plugins, handle following events:

• onContentBeforeDisplay
• onContentAfterDisplay
• onContentPrepare

If the limit is set in a page collection prevent it from being reset by the limitable behavior in the dispatcher.

Related PR's for documentation purposes

1. Opengraph support #86

Implements automatic support for opengraph and additionally twitter cards. For twitter we making use of the opengraph properties supported by twitter. For info see: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/markup

2. Data JSON support #82

Add several improvements to the data objects. It's now possible to cast a data object to a string and it's now possible to create a new data object from an associative array of data.

3. Fix markdown partials are not rendered correctly #88

4. Fix Joomla router is exposing 'view' in canonical #84

Implement changes in joomlatools/joomlatools-framework#266

Implement a regex based bi-directional routing system.

• Implement support for url aliases
• Implement support for canonical url's

References:

• https://blog.hubspot.com/marketing/canonical-url
• http://www.thesempost.com/using-rel-canonical-on-all-pages-for-duplicate-content-protection/
• https://support.google.com/webmasters/answer/139066?hl=en

• Implement JsonSerializable
• Implement __toString() and encode to JSON
• Allow to create a data object by passing an associative array to the data() template function

Implement page ordering support

Related PR's for documentation purposes

1. Page collections: #14

Page collections allow you to render a list of pages, supporting pagination, ordering, sorting and recursing through the folder structure.

2. Data support: #4

Data improvements:

• Ordering of data
• Support for markdown data files
• Ability to shuffle and slice a data object

Additional improvements

• It's now possible to define additional page formats. Default templates to render RSS feeds and XML sitemaps have been included.

• Page data caching has been improved.

Make the template filters configurable on a per page

Related PR's for documentation purposes

1. Plugin filter #60

Content wrapped in <ktml:plugins> will now run through content plugins.

2. Table of contents #58

Anchor elements for <ktml:toc> will only be created from the <article> tag on the page

Additional improvements

We no longer automatically add model states to the query string when building URLs

Implement support for database collections.

Allow to load alternative layouts from a /layouts folder and add support for layout inheritance as is explained here: https://jekyllrb.com/tutorials/convert-site-to-jekyll/#how-layouts-work

Implement support for dynamic pages to allow rendering a collection of items.

Allow to specify a controller identifier and fetch entities through the controller.

Using a none root menu item doesn't work when the file is not in a folder. Eg /test => /joomlatools-pages/pages/test.html

Add support for dynamic collections and page types. Allow to define the collection source through the collection frontmatter, and provide for the ability to define default collections through the configuration.

Recognised pages types:

• page (default)
• collection

Note in a later step a third 'form' type will be added.

Implement support for filesystem collections

Allow loading data from YAML, JSON, and XML, PHP and INI files in page template.

Add an image:// scheme to point to make the images folder configurable, by default point to /images.

Related PR's for documentation purposes

1. Improve page and data registry cache #43

The page and data registries are now cached in an optimised way. The actual content of the file is no longer being cached

2. Add attributes() template function #45

Function to build a string with xml style attributes from an array of key/value pairs

3. Add flatten() data object method #52

Method to flatten an multi-dimensional array ComPagesDataObject::flatten() method, if defined the key of the array will be added to each object being flattened using the property name defined.

4. Pages not being properly sorted by date #48

5. Fix warnings and notices #46

Additional improvements

• This release also refactors the http cache to use a custom file cache and no longer make use of the Joomla JCache API. This offers additional performance benefits as http cache objects are now also automatically stored in opcode cache.

• This release also includes a change in the way data works. If a data file has the same name as the folder it's part of, the file will not result in an additional level in the data collection. If the file has a different name the key of the level will be the name of the file

Additional configuration options

page_cache: JDEBUG ? false : true
page_cache_time: 606024 //1d
page_cache_path: /joomlatools-pages/cache

data_cache: JDEBUG ? false : true
data_cache_time: 606024, //1d
data_cache_path: /joomlatools-pages/cache

template_cache: JDEBUG ? false : true
template_cache_path: JPATH_ADMINISTRATOR.'/cache/koowa.templates'

http_cache: false
http_cache_time: 7200
http_cache_path: /joomlatools-pages/cache

• Make it possible to include or render to markdown and then filter from markdown to html (see: #35)
• Add support to TOC (https://github.com/bryanbraun/anchorjs)
• Add support for code highlighting (https://github.com/scrivo/highlight.php)

References:

• https://github.com/trilbymedia/grav-plugin-page-toc
• https://github.com/Sommerregen/grav-plugin-toc

The way the dynamic page and data registry cache is working right now doesn't allow to build the cache programmatically, and the per file approach is also not the most performant.

Investigate a better way of storing the page and data cache that also allows for manually building the cache.

In some blog posts, there are anchor elements between the author and the date resulting to weird additional spaces. You could test the issue in this blog post.

Implement support for forms to allow data to be submitted to the site. This would allow to easily create all sorts of forms like a contact form, but also other submission type forms.

• Add a form page type?
• Allow to store form submissions in a CSV file (use https://csv.thephpleague.com)
• Refactor CSRF to use Origin or Referrer checks
• Allow to store form submissions in the database
• Allow to log form valid and invalid/spam submissions

Notes

The current CSRF protection approach doesn't allow for HTTP caching. A new CSRF technique will need to be implemented to be able to provide cachability and security. For more info on this issue:

• https://www.fastly.com/blog/caching-uncacheable-csrf-security
• https://blog.cloudflare.com/the-curious-case-of-caching-csrf-tokens/
• https://medium.com/@iaincollins/csrf-tokens-via-ajax-a885c7305d4a

Investigate csv libraries:

• https://github.com/box/spout and http://opensource.box.com/spout/
• https://github.com/portphp/csv

When using the <ktml:partial format="md"></ktml:partial>and if the element is not placed at column 0 in the code the output is rendered inside <pre><code></code></pre>tags due to the additional whitespace added when the markdown code is retrieved by the filter.

The Joomla router is exposing the view in routes it creates for the canonical.

Implement support for opengraph (and twitter cards)

• http://ogp.me
• https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards

• Finish testing and merging
• Update version info
• Register on packagist

Note: this release requires joomlatools/joomlatools-framework#152

Refactor the page() methods to return the active entity if no path parameter is passed.

Calling route('index') results in warning

Implement support for loading templates files relative to the pages root folder.

• file.html
• /file.html
• /folder/file.html
• folder/file.html
• ../file.html
• ../folder/file.html

Implement http response caching for pages with etag validation.

For more info see: joomlatools/joomlatools-framework#36

Pages that use a timestamp are not being sorted correctly.

• Implement support for remote collections.
• Implement a data client that can retrieve data from a url
• Improve collections to allow to pass configuration information to the collection. This will allow to create simple collections on the fly without needing to create a specialised model.

Related PR's for documentation purposes

1. Controller collections #76

Allows to use a controller a collection source by specifying the controller identifier.

2. Filesystem collections #74

Implements support for filesystem collections. A collection can now easily be retrieved from any filesystem path. The implementation offers support for URI templates to make creating dynamic path easy, and allows to easily turn data into a collection by using the data:// path prefix.

3. Database collections #72

Implements support for database collections. A collection can now easily be retrieved from any database table. A database collection is almost fully automatic. All the table columns are available in the state and can be filtered on.

4. Webservice collections #64

Implements support for webservice collections. A collection can now easily be retrieved from any URL. The implementation offers support for URI templates to make creating dynamic URL's easy.

5. http_cache_time_proxy setting #70

Added new http_cache_time_proxy setting to allows defining the s-maxage cache directive. The default cache time is set to 15min and the shared proxy cache time is set to 2h.

6. Fix route('index') #68

7. Fix limit issue #66

Additional improvements

• All collections can easily be customised by extending the ComPagesModel[Collection] class, by default each collection is sortable, paginatable and searchable.

• A remote data cache has been added and stores a file per remote url prefixed with 'remote_'. The file contains the data as a php array.

• The http_cache_timedefault has been changed to 15min.

Additional configuration options

remote_cache: JDEBUG ? false : true
remote_cache_time: 606024, //1d
remote_cache_path: /joomlatools-pages/cache

http_cache_time_proxy: 606102 //2h

Function to build a string with xml style attributes from an array of key/value pairs

Files

Implement collection support for Dropbox HTTP API.
See: https://www.sitepoint.com/build-your-own-dropbox-client-with-the-dropbox-api/

Paper

Export a dropbox paper document to html or markdown to include it in the site
See: https://www.dropbox.com/developers/documentation/http/documentation#paper-docs-download

Resources:

• https://github.com/spatie/dropbox-api
• https://github.com/spatie/flysystem-dropbox
• https://developers.dropbox.com/paper-migration-guide

Related PR's for documentation purposes

1. Joomla Pathway support: #26

Ensures the Joomla pathway reflects the page hierarchy.

2. Page decoration: #27

Ability to decorate an existing Joomla menu item or page. The Joomla rendering cycle is intercepted after the active component has been dispatched and the returned by the component is then injected in a page to be decorated.

3. Add theme:// asset path: #29

Allows to use theme:// in pages and templates. Will be rewritten to the base url of the active template.

4. Page ordering support: #33

Pages can be ordered per folder by adding a .order.[format] file to the folder that specifies the specific ordering of all the data files, both files and directories can be ordered.Typecan be any data format: YAML, JSON, INI, PHP, and XML.

5. Allow to define template filters per page #35

Added a process:filters page property which can contain an array of additional page filters.

6. Improve Markdown support: #37

Added additional filters to improve markdown rendering. New filters are: markdown, partial, toc and highlight.

7. Allow page() method to return active page: #38

Ensure access to the active page object at all times using the page() template method.

8. Improve http caching: #40

Implement framework changes in: joomlatools/joomlatools-framework#242 to ensure http page is working as expected.

Additional improvements

• The $page variable is now only injected if the page is a single page. In case of a collection the $page variable is not longer available.

• The active page object can be accessed everywhere by using the page() template function. If you don't define a page path it will return the active page. Eg page()->title

• The page object has an additional 'text' parameter that gives you access to the text of the page, if the page includes a <--more -!>it will return the text below the tag, the part above is accessible using $page->excerpt

• You can now access page properties in your layouts. Eg, $page->content or ktml:contentdoes the same thing

Allow to load files from the active theme.

Add a attribute() template method that makes is easier to generate html element attributes. The method should accept both string and array values and turn them into an attribute of notation name=[value]

If the value is empty no attribute should be generated, if the value is an array the values should be separated by a space.

Related PR's for documentation purposes

1. Routing #54

A complete new routing system using a route resolvers approach, implementing a prioritised queue and bi-directional regex based routing.

2. Dynamic collections #56

A dynamic approach for collections. A collection is no longer only retrieved from the filesystem, instead a collection can fetch data from any model and custom collections can easily be created.

Additional improvements

• The router supplies a redirect resolver to handle permanent redirects. Redirects can be configured using the new 'redirects' config option and use the format: array('/path' => '/target')

• Support for canonical url's is added. A canonical url is always set in the response headers (even if the canonical route is used). This ensure clean self-referential url's. See also: http://www.thesempost.com/using-rel-canonical-on-all-pages-for-duplicate-content-protection/

Additional configuration options

• redirects: [array]
• collections: [array]

The users_groups and users_roles tables do not exist in Joomla CMS, only in Joomlatools Platform. Provide compatibility between the two

When flattening data, the folders names (keys) containing the flattened data are completely lost.

The idea is to allow keeping this data on demand when flattening. An example:

$testimonials = data('testimonials')->flatten('extension');

this would grab testimonials, then flatten them while keeping the dirname on an extension property inside each data object allowing access to it through $testimonial->extension. This prevents us from having to include a redundant extension property inside each testimonial md file.