Uncategorised
- Details
- Written by: Cliff
- Category: Uncategorised
- Hits: 316
Joomla documentation is plentiful and easy for anyone to contribute to. Over the years the Joomla Documentation Wiki has grown considerably, which in itself is good, but also brings challenges. It lacks structure, it's hard to search, it contains a lot of outdated articles, and translating the documentation is not as straightforward as it should be. So it's time to reconsider our documentation tools. What if we could have a Joomla based solution for our documentation?
Jdocmanual is a custom component designed as a Proof of Concept for ease of use, ease of contribution, ease of translation and ease of management. It brings together Joomla articles in Manual format as seen in many other software documentation projects: Index of Articles to the left, Article text in the centre and Article Contents to the right. That presentation is the easy part! This article mostly covers how the other easy requirements are met in Jdocmanual. It is intended to contribute to a discussion on the future of Joomla documentation.
You can try the public view yourself: https://jdocmanual.org. This is what it looks like in the Administrator view:
The Site view is similar but without the left menu. A user may choose any of the available manuals and display the Index and/or Content in any of the available languages.
Source Data
The articles for Jdocmanual have been selected from docs.joomla.org, which is the MediaWiki installation used for Joomla documentation. Only articles relevant for Joomla 4 have been included and each has been converted to GitHub Flavoured Markdown. The articles have been organised into separate Manuals for different user groups: User, Developer, Documenter and Help. Others can be added, for example Tutorials selected from the Joomla Community Magazine may come later.
Updating data
Jdocmanual can have multiple contributors in two User Groups: a JDM Author may create a personal copy of an article for editing purposes; a JDM Publisher may commit changes created by a JDM Author (JDM is used here to indicate separate user groups from Joomla default Author and Publisher). A Publisher also has Author permissions. The list of articles available is always based on the source English list. This is a screenshot of the article list with a language other than English selected:
The ticks in the Translated column indicate that this particular article has been translated into the selected language. Those without a tick have yet to be translated. If English is selected this column is not displayed. In the Status column, Stashes: 1 indicates that a user has created a personal stash of that article to work on. The yellow New Stash buttons indicate that I can make my own personal stash of that article to work on. The green Edit Stash button indicates that I have already created a personal stash of that article.
New Pages must be created in English so a New button only appears in the Toolbar when English is selected. Also, new pages cannot appear in the Pages list because they only exist as stashes until committed. So the New Pages tab shows a list of any new pages in preparation.
My Stashes is a tab used to display a list of any stashes I have created to work on.
Pull Requests is a tab seen only by users in the JDM Publisher group. The list includes all pull requests by all users. The links in this list opens the same Stash Edit form used by Authors but it has an extra Toolbar button labelled Commit.
Editing Content
The following screenshots show selected tabs from the stash edit form. The fields in the Details tab are mostly prefilled from data on the page being edited. The Display Title is the only field that can be changed, except for a completely new English article where more fields must be filled before saving.
The Stash tab is where editing of content occurs. If the page is a translation the English version is displayed in a read-only text area to the left. If the page is an English version the edit area fills the whole page. Editing requires familiarity with Markdown syntax.
If you need to know what has changed in the original English version since the last update you can look at the English Diff tab:
The Source tab shows the current source of the Stash you are working on. The Diff tab shows the difference between your Stash and the Source. Before making any changes this will be empty because there are no differences to show.
The Preview tab shows a HTML rendering of your Stash. The Comments tab is for entry of a Commit message and feedback on any Pull Request.
Pull Requests
When a Stash is ready to replace the original content a click on the Pull Request button makes it visible to all the JDM Publishers. Anyone in that group can inspect the Stash using exactly the same form. If it is acceptable, a click on the Commit button, which appears in the Toolbar when a Pull Request is made, is enough to stage and merge the changes into the original article. The result is visible immediately.
Ease of Use
Is it easy to maintain? The answer is probably Yes and No. If I am editing the data myself with a few trusted friends then I guess the answer is yes. If there are dozens or hundreds of contributors in the Author Group, processing all the pull requests could become a challenge for a small team.
Help Proxy
The Joomla Help Pages are delivered by a proxy server. The url is in your Joomla installtion configuration.php file:
public $helpurl = 'https://help.joomla.org/proxy?keyref=Help{major}{minor}:{keyref}&lang={langcode}';
Where {major} and {minor} are replaced by your Joomla installation values, the {keyref} value is set in the Administrator page invoking a Help page and {langcode} is the two-letter code for whatever language your Administrator template is using, for example en or de.
In practice, we do not maintain different Help pages for different minor versions of Joomla. And updating Help pages when migrating from one major version of Joomla to the next is a significant problem. About 200 original English pages have to be copied and re-translated even though any changes may be minor.
All of this is much easier to do with Jdocmanual. If you are testing Joomla 5 you can change the domain in your configuration.php file to https://jdocmanual.org/
and expect to see the Joomla 4 and Joomla 5 Help pages in English or your own language.
Menus
In Jdocmanual the order in which items appear in the article index to the left of the article content is independent of the order in which the items appear in the list of source files. That is achieved with a menu list - a text file containing the list of articles in the desired order. This is very easy to edit by cut and paste to move an item. This is much easier than the drag and drop method used for Joomla menus. The menu order is language independent so there is only one menu for each manual. Users can make their own stash copy of the menu, change it and then make a pull request to have it replace the existing menu. The menu stash edit form has tabs similar to the article stash edit form:
Utilities
The other items in the Jdocmanual Administrator menu are used to manage languages, to translate menu headings and to manage manuals.
Future Development
Development of Jdocmanual has focussed on functionality. Little effort has gone into appearance other than that offered by the default Cassiopeia and Atum templates. Suggestions and alternative style sheets would be welcome!
Coding
Jdocmanual was developed as a proof of concept. Under the hood some of the code needs to be improved: libraries for handling markdown to html conversion have been included within the component itself rather than within the Joomla libraries folder; there are probably better ways of implementing git commands, for example by using the Joomla GitHub library; and more. Comments and suggestions are welcome.
Content Revision
In processing and checking MediaWiki articles I came to the conclusion that there are too many unnecessary internal links. With a good index, as in Jdocmanual, many links can be left out without affecting the value of the article. This leads to a better user experience.So far precious little attention has been given to the actual content of the articles appearing in Jdocmanual.
I think the next important task is to update content, merge similar items and incorporate new content from other sources, such as the Community Magazine.
Conclusion
If you want to try it yourself you can get the code and data here:
Code: https://github.com/ceford/j4xdemos-com-jdocmanual-v2.git
Data: https://github.com/ceford/j4xdemos-data-jdocmanual.git
Pay heed to the README.md files. Setup requires more than simple installation of the component!
If you would like to participate in further development of the Jdocmanual code please feel free to make a pull request.
- Details
- Written by: Cliff
- Category: Uncategorised
- Hits: 924
Introduction
Much of the Joomla Documentation is handled by a MediaWiki installation. It does a good job of delivering the Help pages invoked with a Toolbar button on almost all Administrator pages. However, it has shortcomings that have led many in the community to look for an alternative. Some of the problems are mentioned at the end of this article.
- Details
- Written by: Cliff
- Category: Uncategorised
- Hits: 1529
Some content with bold and an image:
- Details
- Written by: Cliff
- Category: Uncategorised
- Hits: 526
Content of J3x namespace: 2022-07-25
- "Save as New" and "Save as Copy" removed from article manager after 3.3.4 Upgrade
- AJAX and Content History menu items are displaying in the components menu
- Access Control List
- Access Control List Tutorial
- Access Template Manager Customisation
- Add article title to read more link
- Adding JavaScript and CSS to the page
- Adding a custom CSS with Protostar
- Adding a new menu
- Adding custom fields
- Adding custom fields/Calendar Field
- Adding custom fields/Checkboxes Field
- Adding custom fields/Color Field
- Adding custom fields/Editor Field
- Adding custom fields/Example
- Adding custom fields/Gallery Field
- Adding custom fields/How̞ can you group custom fields
- Adding custom fields/Implement into your component
- Adding custom fields/Integer Field
- Adding custom fields/List Field
- Adding custom fields/List of Images Field
- Adding custom fields/Media Field
- Adding custom fields/Multilingual Sites
- Adding custom fields/Overrides
- Adding custom fields/Parameters for all Custom Fields
- Adding custom fields/Radio Field
- Adding custom fields/Repeatable Field
- Adding custom fields/Sql Field
- Adding custom fields/TOC
- Adding custom fields/Text Field
- Adding custom fields/Textarea Field
- Adding custom fields/Url Field
- Adding custom fields/User Field
- Adding custom fields/Usergroup Field
- Adding custom fields/What components are supporting custom fields
- After going to 4.1,1 or 3.10.7 some users can't login anymore
- Allow registering callback functions for the debug console
- Automatic Display need content events to be triggered
- Backend/Page Break PHP error after upgrade to Joomla 3.5.1
- Backend Login looks bad
- Backward Compatibility in Joomla 3.4.7
- CLI Applications Broken
- Caching Issues
- Call to a member function isBackend() on null
- Call to undefined method JAdminCssMenu::addChild in backend
- Can't edit modules after update to 3.6.3
- Cannot create new content 3.1.4
- Cannot log in to Joomla frontend
- Change of article category changes article publishing dates
- Change of parameters saving the Codemirror plugin
- Changes in language file loading
- Changes to the 2FA token generation recommendations for existing sites
- Class 'PDO' not found
- Class attributes are not included in mailcloak
- Codemirror editor fullscreen mode
- Configuring sqlserver
- Converting A Previous Joomla! Version Template
- Creating a Plugin for Joomla
- Creating a content plugin
- Creating a search plugin
- Creating a simple module
- Creating a simple module/Adding Auto Update
- Creating a simple module/Adding Form Fields
- Creating a simple module/Adding an install-uninstall-update script file
- Creating a simple module/Developing a Basic Module
- Creating a simple module/Introduction
- Creating a simple module/Menubar
- Creating a simple module/Using the Database
- Creating a submenu
- Creating an Authentication Plugin for Joomla
- Database schema version (3.2.3-2014-02-20) does not match CMS version (3.2.3)
- Date of birth shows everywhere on a single contact page
- Delete button on the media manager does not work anymore
- Detailed instructions for updating from 3.1.2 to 3.1.4
- Developing a component frontend update function
- Developing a component frontend update function/Excel xlsx export
- Developing a component frontend update function/First try at csv export
- Developing a component frontend update function/Import with summary screen
- Developing a component frontend update function/Improved export function
- Developing a component frontend update function/Initial version
- Developing a component frontend update function/Record item editing page
- Developing a component frontend update function/Record list view page
- Developing a component frontend update function/Rethink frontend permissions
- Developing a component frontend update function/Simple frontend data entry
- Developing a component frontend update function/csv and xlsx import
- Developing an MVC Component
- Developing an MVC Component/Adding ACL
- Developing an MVC Component/Adding AJAX
- Developing an MVC Component/Adding Access
- Developing an MVC Component/Adding Associations
- Developing an MVC Component/Adding Cache
- Developing an MVC Component/Adding Checkout
- Developing an MVC Component/Adding Custom Fields
- Developing an MVC Component/Adding Levels
- Developing an MVC Component/Adding Ordering
- Developing an MVC Component/Adding Tags
- Developing an MVC Component/Adding Versioning
- Developing an MVC Component/Adding a Feed
- Developing an MVC Component/Adding a Map
- Developing an MVC Component/Adding a Modal
- Developing an MVC Component/Adding a batch process
- Developing an MVC Component/Adding a front-end form
- Developing an MVC Component/Adding a menu type to the site part
- Developing an MVC Component/Adding a model to the site part
- Developing an MVC Component/Adding a variable request in the menu type
- Developing an MVC Component/Adding a view to the site part
- Developing an MVC Component/Adding an Image
- Developing an MVC Component/Adding an alias
- Developing an MVC Component/Adding an install-uninstall-update script file
- Developing an MVC Component/Adding an update server
- Developing an MVC Component/Adding backend actions
- Developing an MVC Component/Adding categories
- Developing an MVC Component/Adding configuration
- Developing an MVC Component/Adding decorations to the backend
- Developing an MVC Component/Adding language management
- Developing an MVC Component/Adding verifications
- Developing an MVC Component/Basic backend
- Developing an MVC Component/Developing a Basic Component
- Developing an MVC Component/Example of a frontend update function
- Developing an MVC Component/Introduction
- Developing an MVC Component/Navigate
- Developing an MVC Component/Using the database
- Developing an MVC Component/Using the language filter facility
- Disabling user registration
- Discover on which client your extension code is running
- Doc Pages
- Duplicate Maintenance Info
- Duplicate usernames cause update issue
- Editing a template with Template Manager
- Editing module shows module XML data not available
- Error in Mailing Extensions
- Errors in 2.5.26, 3.2.6, and 3.3.5
- Extension won't install
- Extensions Broken in 3.1.4
- Fatal Error in Input Filtering
- Fatal Error with PHP5.3 and Multilanguage enabled
- Fatal error Class JClassLoader
- File Structure and Naming Conventions
- Getting Started Modules
- Getting Started with Articles
- Getting Started with Categories
- Getting Started with Joomla!
- Getting Started with Menus
- Getting Started with Templates
- Getting a 500 when trying to sort users by User Group
- Global configuration
- Global editor setting overrides user editor setting
- Google ReCaptcha
- Hathor admin template has not been updated to work with the new features
- How To Use Content Tags in Joomla!
- How do you add a new module position?
- How to add breadcrumbs
- How to add tooltips to your Joomla! website
- How to turn off magic quotes gpc
- How to use the Template Manager
- Infinite error loop on multilanguage sites
- Information Request Workflow in Privacy Component
- Information about the Update to 3.6.3
- Information about the Update to 3.6.3 or 3.6.4
- Insert error in menu table of migrated data
- Install From Web (For Developers)
- Install From Web For Developers
- Install from web fails to load
- Installing Joomla
- Installing Weblinks
- Installing a template
- Integrate Extensions with the Privacy Component
- JLayout Improvements for Joomla!
- Javascript Frameworks
- Joomla 3.10 Backports
- Joomla 3.10 points to 4.0 while it claims to be on the Default update server
- Joomla 3.5 Imagery
- Joomla 3.6 Imagery
- Joomla 3.7 Imagery
- Joomla 3.8.13 Security Notes
- Joomla 3.8.4 Notes about the Security Patches
- Joomla 3.8.8 notes about the changed default settings
- Joomla 3.8 Imagery
- Joomla 3.9.3 Security Notes
- Joomla 3.9 Imagery
- Joomla Core Features
- Joomla Standard Icomoon Fonts
- Known issues with the new URL Routing parameter
- Known issues with the new plugin Editor - TinyMCE
- Known upgrading issues and solutions
- LDAP Client Missing Escape Method
- Language Overrides in Joomla
- Layout Overrides in Joomla
- Location of template language definition files
- Logging in or out of the Administrator back-end
- Login/Logout Redirections broken after upgrade to Joomla 3.4.6
- Make your own Action Log Plugin
- Making a Language Pack for Joomla
- Missing Installer Tabs
- Missing JBrowser class after upgrading
- Modifying a Joomla! Template
- Module article news ordering ascending
- Module random image PHP Error after 3.8.8
- Moving a menu to a different position
- Multilang-site override a option of JCategories that cause a SQL error
- Multilingual Associations
- Multilingual Associations&action/TOC
- Multilingual Associations/Developers
- Multilingual Associations/ListView
- Multilingual Associations/No Multilingual Associations̞
- Multilingual Associations/SidebySide
- Multilingual Associations/TOC
- Multilingual Associations
- Multilingual Template Styles are Broken
- Multilingual associations Copy not keep acl permission setting
- New Routing System
- No admin menu item for component
- No language support for Custom Fields
- Notice: Undefined variable $link com menus
- OnContentPrepare called with JCategoryNode
- Open basedir in effect in template manager
- Optional Technical Requirements
- PHP Warnings on PHP 7.0.9
- Plugin Joomla Update Notification
- Post installation message: Wrong PHP detection
- Privacy
- Problems for Sqlsrv
- Report Extension Capabilities in Privacy Component
- Secured procedure for installing Joomla with a remote database
- Select Type Field Missing in Extensions Manage
- Send test mail for smtp fails
- Server-side form validation
- Session Fatal Error in some CLI Scripts
- Setting proper default values for access level
- Setup a Multilingual Site
- Setup a Multilingual Site/Adding Multilingual Content
- Setup a Multilingual Site/Creating a Content Language
- Setup a Multilingual Site/Creating menus
- Setup a Multilingual Site/Duplicate your Template
- Setup a Multilingual Site/Enabling the Language Plugins
- Setup a Multilingual Site/Exploring the Site
- Setup a Multilingual Site/Installing New Language
- Setup a Multilingual Site/Language Switcher
- Setup a Multilingual Site/TOC
- Sharing layouts across views or extensions with JLayout
- Subcategories Not Showing
- Supporting SEF URLs in your component
- Switching templates
- Table xxx postinstall cpanels does not exist
- Tag view gives 404
- Taking the website temporarily offline
- Template Style field not shown in Menu Items
- Templates supplied with Joomla!
- The breadcrumbs module does not show the items not linked
- The reCaptcha function has been temporarily disabled for Joomla 3.2
- Timeout installing extensions
- To access the Template Manager
- Toolbar buttons missing after update to 3.1.4
- Toolbar buttons missing after upgrade
- Triggering content plugins in your extension
- Two Factor Authentication
- Unable To Edit Article 3.4.7
- Unable to delete modules after updating
- Unable to login with 2fa enabled after 3.6.3
- Unable to use a none alphabethic first character in folder name
- Understanding the Application classes
- Unuseable tab panels in user profile
- Update $explodedName with reversed array
- Update Package Install Failed
- Update fails with an error message
- Update from 3.6.x to 3.6.3 Timeout
- Update from 3.6.x to 3.6.5 Profile fields
- Update from 3.6.x to 3.6.5 Timeout
- Update from 3.7.x to 3.7.1 Timeout
- Update from 3.7.x to 3.7.2 Timeout
- Updating Joomla (Install Method)
- Updating Joomla (Update Method)
- Updating from an existing version
- Updating to Joomla 3.8.13 and 3.9.0 as non-superuser
- Upgrade from 2.5 to 3.6.0 fails
- Upgrades from 3.10.0 to 3.10.1 requires to tick an checkbox
- Upgrading from Joomla 3.4.x to 3.5
- Upgrading from Joomla 3.4.x to 3.5/de-formal
- Upgrading from Joomla 3.4.x to 3.5
- User Action Logs
- User custom field not display in the backend edit profile
- User custom field when admin activated the user all data in custom field deleted
- Using Composer with Joomla
- Using Tags in an Extension
- Using the JHtmlTabs class in a component
- Using the JToolbar class in the frontend
- Validation error on creating a menu entry
- What's new in Joomla!
- What does a simple Joomla! installation include?