{"id":21842566,"url":"https://github.com/brookinsconsulting/bcdocumentreaderbundle","last_synced_at":"2025-03-21T16:14:40.795Z","repository":{"id":56951361,"uuid":"78580588","full_name":"brookinsconsulting/BcDocumentReaderBundle","owner":"brookinsconsulting","description":"This bundle implements a solution to detect file download links within XMLBlock content object attribute content and display the document helper applications which the user can use to open the file documents","archived":false,"fork":false,"pushed_at":"2017-03-08T06:48:36.000Z","size":340,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-26T11:27:50.490Z","etag":null,"topics":["bundle","detection","document-reader","ez-platform","ezpublishplatform","filter","mime-types","php","scss","twig-filter"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brookinsconsulting.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-10T22:32:57.000Z","updated_at":"2017-03-07T19:46:34.000Z","dependencies_parsed_at":"2022-08-21T09:20:08.692Z","dependency_job_id":null,"html_url":"https://github.com/brookinsconsulting/BcDocumentReaderBundle","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookinsconsulting%2FBcDocumentReaderBundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookinsconsulting%2FBcDocumentReaderBundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookinsconsulting%2FBcDocumentReaderBundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookinsconsulting%2FBcDocumentReaderBundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brookinsconsulting","download_url":"https://codeload.github.com/brookinsconsulting/BcDocumentReaderBundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244825654,"owners_count":20516592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundle","detection","document-reader","ez-platform","ezpublishplatform","filter","mime-types","php","scss","twig-filter"],"created_at":"2024-11-27T22:12:30.261Z","updated_at":"2025-03-21T16:14:40.765Z","avatar_url":"https://github.com/brookinsconsulting.png","language":"PHP","readme":"BC Document Reader\n===================\n\nThis bundle implements a solution to detect file download links within XMLBlock content object attribute content and display the document helper applications which the user can use to open the file documents.\n\n\nVersion\n=======\n\n* The current version of BC Document Reader is 0.1.6\n\n* Last Major update: May 20, 2015\n\n\nCopyright\n=========\n\n* BC Document Reader is copyright 1999 - 2015 Brookins Consulting and 2013 - 2015 Think Creative\n\n* See: [COPYRIGHT.md](COPYRIGHT.md) for more information on the terms of the copyright and license\n\n\nLicense\n=======\n\nBC Document Reader is licensed under the GNU General Public License.\n\nThe complete license agreement is included in the [LICENSE](LICENSE) file.\n\nBC Document Reader is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 2 of the License or at your\noption a later version.\n\nBC Document Reader is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nThe GNU GPL gives you the right to use, modify and redistribute\nBC Document Reader under certain conditions. The GNU GPL license\nis distributed with the software, see the file doc/LICENSE.\n\nIt is also available at [http://www.gnu.org/licenses/gpl.txt](http://www.gnu.org/licenses/gpl.txt)\n\nYou should have received a copy of the GNU General Public License\nalong with BC Document Reader in doc/LICENSE.  If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).\n\nUsing BC Document Reader under the terms of the GNU GPL is free (as in freedom).\n\nFor more information or questions please contact: license@brookinsconsulting.com\n\n\nRequirements\n============\n\nThe following requirements exists for using BC Document Reader extension:\n\n\n### eZ Publish version\n\n* Make sure you use eZ Publish version 5.x (required) or higher.\n\n* Designed and tested with eZ Publish Community Project 2013.11\n\n\n### PHP version\n\n* Make sure you have PHP 5.x or higher.\n\n\nFeatures\n========\n\n### Twig operators\n\nThis solution provides the following twig filters and functions\n\n* Twig Filter: `bc_document_reader` - Used within template overrides to detect download file links configured to detect (via yaml options) and detected within the passed twig filter url parameter input.\n\n* Twig Function: `bc_document_readers` - Displays the list of document readers for the download file links configured to detect (via yaml options) and detected within the current page's content object XML BLock attribute(s) content.\n\n* Twig filter: `bc_file_size` - Used with the content/download file download embed template to display the embedded file size. This twig filter is based directly on `ez_file_size` provided by default within ezplatform6.0-alpha1. This duplication was required to introduce the same feature support within older versions of eZ Publish Platform 5.x.\n\n\n### Services\n\n* Services to assist in detection of file download file links within content and templates\n\n\n### Dependencies\n\n* This solution does not depend on eZ Publish Legacy in any way\n\n* Persistent storage of pagedata and document reader file link extensions\n\n* Underlying persistent storage of pagedata variables is provided by the [BcPageData](https://bitbucket.org/brookinsconsulting/bcpagedatabundle) bundle.\n\n    * If you install via composer this dependency will be installed automatically\n\n\nUse case requirements\n=====================\n\nThis solution was created to provide for a common set of customer website requirements regarding document accessibility.\n\nThere may not be specific standards requiring all or parts of this solution, but it is part of the best practices we should strongly consider following for making accessible document management based solutions on the web.\n\n\n## ADA / Section 508 Compliance\n\nThe standards describe more specifically about making linked documents themselves accessible (which is out of our hands and instead in the hands of the customer) the rest are best practices but not necessarily 'required'.\n\nSection 508 Standards / Compliance requirements focus heavily on standards for making the documents themselves accessible (which is often out of our hands and instead in the hands of the customer).\n\nWhile the Section 508 Standards / Compliance requirements do not specifically mention or require all of the below items, we find the following best practices (not necessarily 'required') help create a more accessible user-experience for document management / reading on the web.\n\n* Links to document direct-downloads should include the title of the document and/or be explicitly descriptive of the linked document.\n\n* All links including but not limited to document direct-download links are subject to all general 508 Standards.\n\n    * Links should be of a readable size depending on device.\n\n    * Links should comply with color contrast standards.\n\n* Document direct-download links should have the associated mime-type icon and filesize when and where appropriate.\n\n* Pages with links for direct download of documents should also display links to an appropriate download page of a corresponding document reader (ie Adobe acrobat) which can open the document at the bottom of the page where possible.\n\n* Any image (or any non-text element) associated with the document link (e.g. thumbnail of the document) must include 'alt' text that succinctly describes the content conveyed by the element.\n\n* Avoid having redundant links next to each other within the structure of the page (e.g. If a thumbnail image links to a document followed by a standard text link to the same document, both should be wrapped inside a single `\u003ca\u003e` element where possible).\n\nVisit [http://www.section508.gov](http://www.section508.gov) for more information on the 'Americans with Disabilities Act and Section 508 Compliance'.\n\n\nInstallation\n============\n\n### Bundle Installation via Composer\n\nRun the following command from your project root to install the bundle:\n\n    bash$ composer require brookinsconsulting/bcdocumentreaderbundle dev-master;\n\n\n### Bundle Activation\n\nWithin file `ezpublish/EzPublishKernel.php` at the bottom of the `use` statements, add the following lines.\n\n    use BrookinsConsulting\\BcPageDataBundle\\BcPageDataBundle;\n    use BrookinsConsulting\\BcDocumentReaderBundle\\BcDocumentReaderBundle;\n\n\nWithin file `ezpublish/EzPublishKernel.php` method `registerBundles` add the following into the `$bundles = array(` variable definition.\n\n    // Brookins Consulting : BcDocumentReaderBundle Requirements\n    new BrookinsConsulting\\BcPageDataBundle\\BcPageDataBundle(),\n    new BrookinsConsulting\\BcDocumentReaderBundle\\BcDocumentReaderBundle()\n\n\n### Bundle Assets Installation\n\nIt is recommended (for the built-in functionality to work) to install bundle assets after bundle installation and activation.\n\nHere is an example of how to install bundle assets:\n\n    php -d memory_limit=-1 ezpublish/console assets:install --relative --symlink web\n\n\n### Bundle Styles Installation\n\nIt is recommended (for the built-in functionality to work as designed) to install an include of the bundle's styles within your pagelayout template.\n\n\n### Bundle Styles Installation for sites which are already configured to serve scss\n\nThis solution uses scss by default for it's stylesheets instead of pure css and expects your installation's assetic config.yml to have enabled the assetic stylesheets filters \"compass,cssrewrite\".\n\nEdit your pagelayout twig template and add the bundle's styles.scss within your stylesheets include:\n\n    {% stylesheets filter=\"compass,cssrewrite\"\n        \"@YourCustomBundle/Resources/public/scss/styles.scss\"\n        \"@BcDocumentReaderBundle/Resources/public/scss/styles.scss\"\n    %}\n\nYou will also want to ensure both Ruby and Compass are installed and available as they are used by assetic to convert the scss into css.\n\nYou can install ruby and compass in various ways. Make sure that they are available via command line before running the assetic:dump command and then testing the website's use of them.\n\nIt is recommended (for the built-in functionality to work as designed) to dump bundle assets after installing the bundle styles include in the pagelayout template.\n\nHere is an example of how to dump bundle assets:\n\n    php -d memory_limit=-1 ezpublish/console assetic:dump --env=dev web\n\n\n### Bundle Styles Installation for sites which are -not- already configured to serve scss\n\nThis solution uses scss by default for it's stylesheets instead of pure css and expects your installation's assetic config.yml to have enabled the assetic stylesheets filters \"compass,cssrewrite\".\n\nIn a default installation of eZ Publish Platform / eZ Platform you can enable these requirements yourself by making the following changes.\n\n\n#### Enable assetic stylesheets filters compass and cssrewrite\n\nEdit your `ezpublish/config.yml` file and make the following changes:\n\n    # Assetic Configuration\n    assetic:\n        debug:          %kernel.debug%\n        use_controller: true\n    # snip (to avoid confusion)\n        filters:\n            cssrewrite: ~\n            compass: ~\n\nSpecifically you must add these lines to your assetic configuration, save all config changes and clear all caches:\n\n    # Assetic Configuration\n    # snip (to avoid confusion)\n        filters:\n            cssrewrite: ~\n            compass: ~\n\n\n#### Ensure Ruby and Compass are installed and available\n\nRuby and Compass are used by assetic to convert the scss into css. You can install ruby and compass in various ways. Make sure that they are available via command line before testing the website's use of them.\n\n\n#### Scss style template code installation for sites which are -not- already configured to serve scss\n\nEdit your `pagelayout.html.twig` template or `page_head_style.html.twig` template and add the bundle's styles.scss calls *after* your existing css only stylesheets include calls:\n\n    {% stylesheets\n        '@eZDemoBundle/Resources/public/css/bootstrap.css'\n        '@eZDemoBundle/Resources/public/css/responsive.css'\n        '@eZDemoBundle/Resources/public/css/video.css'\n        '@BCPageLayoutOverrideTestBundle/Resources/public/css/override.css'\n    %}\n        \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{ asset_url }}\"/\u003e\n    {% endstylesheets %}\n\n    {% stylesheets filter=\"compass,cssrewrite\"\n        '@BcDocumentReaderBundle/Resources/public/scss/styles.scss'\n    %}\n        \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"{{ asset_url }}\"/\u003e\n    {% endstylesheets %}\n\nThe above example is from a default installation of eZ Publish Platform Demo Bundle (2014.11).\n\nIt is recommended (for the built-in functionality to work as designed) to dump bundle assets after installing the bundle styles include in the pagelayout template.\n\nHere is an example of how to dump bundle assets:\n\n    php -d memory_limit=-1 ezpublish/console assetic:dump --env=dev web\n\n\n### Bundle Document Helper Twig Function Installation\n\nEdit your pagelayout twig template and add the following `bc_document_readers` twig function code:\n\n    {# START INSTALL THIS CODE: BC Document Reader : Display Document Reader Helper Application Download Links #}\n    {{ include('BcDocumentReaderBundle:parts:reader_links.html.twig', {}) }}\n    {# END INSTALL THIS CODE: BC Document Reader #}\n\nHere is a basic example usage:\n\n    \u003cdiv id=\"main-content\" class=\"{% if is_homepage is not defined %}panel-light-blue subpage{% endif %}\" \u003e\n        {% if is_homepage is not defined %}\n        \u003cdiv class=\"container\"\u003e\n        {% endif %}\n\n        {% block content %}\n            {% if module_result %}\n                {# we are in a legacy rendered module #}\n                {{ module_result.content|raw }}\n            {% endif %}\n        {% endblock %}\n\n        {# START INSTALL THIS CODE: BC Document Reader : Display Document Reader Helper Application Download Links #}\n        {{ include('BcDocumentReaderBundle:parts:reader_links.html.twig', {}) }}\n        {# END INSTALL THIS CODE: BC Document Reader #}\n\n        {% if is_homepage is not defined %}\n        \u003c/div\u003e\n        {% endif %}\n    \u003c/div\u003e\n\n\n### Clear the caches\n\nClear eZ Publish Platform / eZ platfrom caches (Required).\n\n    php ezpublish/console cache:clear;\n\n\nTemplate Customization\n===================================\n\n## Custom Template Override Twig Filter Installation\n\nIf you need to use the `bc_document_reader` twig filter within your own custom template overrides (possibly for custom content types) simply pass your template content's url string value into the filter and the file / document type will be detected.\n\n\nMimetype / File type Customization\n===================================\n\n## Supported File Extensions and Mimetypes\n\nPlease review `Resources/config/documentreader.yml` and `Resources/config/mimetypes.yml` for the default detected file extensions and mimetypes.\n\nIf you wish to support further file extensions and mimetypes simply add them to the yaml settings and clear all caches (required).\n\n\n### Warning to avoid duplicate mimetypes\n\nIt is important to only have one mimetype per document reader helper application group settings.\n\nIf a mimetype already exists within the settings do not add a duplicate as this will cause serious problems.\n\nInstead just add the additional file extension to the existing document reader helper application group settings.\n\n\n## Add a new file extension to an existing mimetype document reader helper application group settings.\n\n\n### Detecting additional custom file extension and mimetypes\n\n\n### Example\n\nFirst edit the bundle settings options file `Resources/config/mimeptypes.yml` and search for the mimetype you wish to add file extension support for.\n\nIn this example we are adding detection support for the `.zipx` files which are not supported by default.\n\nSince there is already a setting for `application/zip` mimetype, you only need to add the additional extension.\n\nHere is a clear example of the addition / change that needs to be made.\n\nBefore:\n\n    - { type: \"CompressedWin\", mimeType: \"application/zip\", extensions: [ zip ] }\n\nAfter:\n\n    - { type: \"CompressedWin\", mimeType: \"application/zip\", extensions: [ zip, zipx ] }\n\nSave your yaml settings additions and clear all caches (required).\n\n\n## Add a new file extension and mimetype not already within the default settings within an existing document reader helper application group mapping\n\n\n### Example\n\nFirst edit the bundle settings options file `Resources/config/mimeptypes.yml` and search for the mimetype you wish to add file extension suport for.\n\nIn this example we are adding detection support for the `.cab` files which are not supported by default.\n\nSince there is not already a setting for `application/vnd.ms-cab-compressed` mimetype, you only need to add the complete settings definition.\n\nHere is a clear example of the addition / change that needs to be made.\n\nAdd the following setting line:\n\n    helper_mime_map:\n    # Snip (Feel free to place the following line any position below the helper_mime_map: line\n    - { type: \"CompressedWin\", mimeType: \"application/vnd.ms-cab-compressed\", extensions: [ cab ] }\n\nSave your yaml settings additions and clear all caches (required).\n\nBy default with the above settings additions will display the CompressedWin document reader helper application, 'WinRar (for Windows)'.\n\n\n## Add a new file extension and mimetype not already within the default settings within a new document reader helper application group mapping\n\n\n### Example\n\nFirst edit the bundle settings options file `Resources/config/mimeptypes.yml` and search for the mimetype you wish to add file extension suport for.\n\nIn this example we are adding detection support for the `.ogg` audio files which are not supported by default.\n\nSince there is not already a setting for `audio/ogg` mimetype, you only need to add the complete settings definition.\n\nHere is a clear example of the addition / change that needs to be made.\n\nAdd the following setting line:\n\n    helper_mime_map:\n    # Snip (Feel free to place the following line any position below the helper_mime_map: line\n    - { type: \"WindowsVlc\", mimeType: \"audio/ogg\", extensions: [ ogg, opus, oga, spx ] }\n\nSave your yaml settings additions.\n\nSecond edit the bundle settings options file `Resources/config/documentreaders.yml` and add the following document reader helper settings:\n\nHere is a clear example of the addition / change that needs to be made.\n\nAdd the following setting line:\n\n    helpers:\n        WindowsVlc:\n            name: VLC Media File\n            viewer_name: VLC Media Player\n            viewer_url: http://get.videolan.org/vlc/2.2.1/win32/vlc-2.2.1-win32.exe\n            icon: audio\n            icon_image: mimetypes/sound.png\n\nSave your yaml settings additions and clear all caches (required).\n\nBy default with the above settings additions will display the WindowsVlc document reader helper application, 'Vlc (for Windows)'.\n\n\nUsage\n=====\n\nThe solution is configured to work virtually by default once properly installed.\n\nTesting\n=====\n\nThe solution is configured to work once properly installed and configured.\n\nSimply navigate to a content object node which contains one or more xmlblock attributes. If the xmlblock attribute content contains links to files like pdf, zip, rar, mp3, etc simply load this page in your user siteaccess. If not simply use the admin to add some links to filetypes supported by default and view the node in your user siteaccess.\n\n\nTroubleshooting\n===============\n\n### Read the FAQ\n\nSome problems are more common than others. The most common ones are listed in the the [doc/FAQ.md](doc/FAQ.md)\n\n\n### Support\n\nIf you have find any problems not handled by this document or the FAQ you can contact Brookins Consulting through the support system: [http://brookinsconsulting.com/contact](http://brookinsconsulting.com/contact)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrookinsconsulting%2Fbcdocumentreaderbundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrookinsconsulting%2Fbcdocumentreaderbundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrookinsconsulting%2Fbcdocumentreaderbundle/lists"}