craftcms / docs Goto Github PK
View Code? Open in Web Editor NEWDocumentation for Craft CMS, Craft Commerce, and other official products.
Home Page: https://craftcms.com/docs
Documentation for Craft CMS, Craft Commerce, and other official products.
Home Page: https://craftcms.com/docs
In converting a Craft 2 site, I got a stack trace on section.getUrlFormat(), which doesn't any longer exist. There isn't any upgrade doc apparent about replacing this, which from source looks likely to need to involve both getSiteSettings and Sites. It didn't just fall out how to do it.
Not having the time at the moment to debug the Twig, I'm instead going to just replace the area with a better overall method already created for what I'm building there, which is a kind of automated menu, but someone else is likely to want to find doc for this.
in perusing for the problem, I came across a like-named craft.request.getUrlFormat(),
in upgrade.md, which looks incorrect in referring to craft.app.config.usePathInfo
as a replacement, not so?
Hi,
I just tried to write my first plugin for craft3 but found it quite hard to bring all peaces together. Before I write a plugin I have to get pieces from three different places right now:
But there is still a example missing, how everything works together. I remember how I got into meteor.js which has now quite great tutorials to start by creating a app step by step.
So it would be great to have such a thing for plugins in craft 3 which does the following things:
Writing a plugin with a twig extension, settings in the config, some settings should be also changable in the CP, accessing a Service through craft.myplugin.*
, basic error handling/logging, getting input values from the website and writing the data to a custom database table and displaying it again on the website. So basic routing is also included.
Maybe the classical TODO app would be good to way to do by it or similar. But such a tutorial/guide mix is definitely missing but would dramatically improve the learning curve.
Hi ya'll!
Just noticed a little naming inconsistency. I stumbled upon the "Should we update to Craft 3" page (https://craftcms.com/guides/should-we-update-to-craft-3), where a little Update vs. Upgrade
section is dedicated to the fact that 'update' is the preferred term.
This 'Update v.s. Upgrade' terminology isn't really consistently applied to the actual update guide: https://docs.craftcms.com/v3/upgrade.html#performing-the-upgrade -- As "Upgrade" seems to be the word of choice there.
I know, nothing much to worry about -- And certainly not stopping me from doing my job.
Thought I'd point it out, for the sake of consistency! 🙃
I've had to make a few custom elements on a couple projects recently and the experience wasn't the best. The documentation points you in the right direction but basically stops and says copy one of Crafts existing elements.
It would be great if a simple element could be created more quickly either with better documentation e.g. actual examples or some kind of CLI tool.
Even if the docs are for a really simple element e.g. form submissions.
Love the new dark mode docs, but I can't see whether I've selected anything from the code examples. Could you please update that to something visible?
Example of text not selected:
Example of a highlighted selection:
Probably depends on the monitor settings slightly, but I can't see it at all on at least two of my screens, which makes it very difficult to select and copy code / variables. Thanks!
Sometimes the Knowledge Base goes into more detail or augments pages in the docs. It’d be nice to either auto-suggest or manually define (or both?) links for more crossover between the two resources.
https://craftcms.com/docs/3.x/relations.html#simple-relationships
Here's how and
usage is described in code example:
{% set relatedDrinks = craft.entries()
.section('drinks')
.relatedTo([ 'and', gin, lime ])
.all() %}
It turns out however that in order for it to work correctly, such syntax needs to be used - at least with php:
$query->relatedTo(['and', ['element' => gin], ['element' => lime]])
Using syntax below in php, causes array_merge(): Argument #2 is not an array
error:
$query->relatedTo(['and', gin, lime])
https://craftcms.com/docs/3.x/config/config-settings.html#omitscriptnameinurls
When I install craft, this setting is set to true
, yet docs say that default value is false
.
A seemingly very common bug is for devs to rely on request/response props and methods that are available in a web app context, but not in a console one.
Especially with the queue, devs may not realize that their code needs to be able to run as web OR console.
So, one generally needs to sprinkle a bunch of getIsConsoleRequest
conditionals around.
Is there a better solution here?
The bug is understandable, as things may work fine for the dev when testing if they are not running their queue from console.
Examples:
The docs for 3 are lacking in specific instructions and examples around creating new sections. For me it is mostly fine but for a new user it would be super confusing. Should step through each part in the process with screenshots.
Sometimes we want to upload an image without using input type="file"
. Base64 encoding is a reasonably common format and can be set as an input's value without much trouble.
Not sure if it's hidden somewhere, but it exists on Craft 2 and Craft Commerce 3.
Just looking for a list of events that plugins/modules can use.
Thanks!
Most people who use Craft/Yii's query builders are going to end up on Entry's doorstep -- perhaps beginning with Entry::find();
It would be very good to have a worked out example of how this works when wanting to sort, for currrent Slack question example, using orderBy() on a column. You can't use an alias for the table involved, so the tablename itself must be used, which I couldn't rapidly lay on hands for an example that this is correct, last night. But it is, except many won't have my foggy long memory of possibilities on such things.
This would be a great place also to explain just what the Entry structure is, so that the joins behind it are understood in principle, if not necessarily in detail -- hence the table names that would be used for various columns.
On this page
https://craftcms.com/docs/commerce/3.x/example-templates.html
the first link at the top
https://github.com/craftcms/commerce/tree/master/templates
is a 404
It should instead be
https://github.com/craftcms/commerce/tree/master/example-templates
Just a typo. 'sourcElement' should presumably be 'sourceElement'
Started: craftcms/cms#5300
I would like to see isFieldEmpty
(Element::isFieldEmpty
, entry.isFieldEmpty('myField')
, et. al.) documented as a valid way to check a field for empty regardless of the fieldtype.
It looks like Craft uses this internally for required validation, but can be useful in other contexts as well.
In my use-case, I'm mapping a set of element fields, but don't care about the actual field output data, only if it has any.
Seems like the right thing to use, but I'm wary of relying on it without anything in the docs.
The tutorial on how to build plugins is great, but on the page about creating a settings page you forgot to mention that the composer.json file has to set:
"hasCpSettings": true,
"hasCpSection": true,
to make the settings "link" show up in the cp.
The current page structure for plugin/module extension is confusing for someone who never worked with Craft2 and only cares about extending Craft3.
Referencing: https://docs.craftcms.com/v3/extend/updating-plugins.html
A lot of the important Craft3 extension information is under 'Updating Plugins for Craft 3' and the content references both v2 and v3. This assumes you know v2 and are migrating to v3. This made sense when v3 launched, but a new Craft3 dev today should be able to learn v3 without seeing anything about v2.
Recommendations:
Also replace the tip with command instruction just like the current database example.
The Craft 2 plugin development documentation included information about Models, Records and Controllers which is no longer contained at all in the Craft 3 docs.
The current upgrade guide only mentions a very vague reference back to the Yii documentation for all of these concepts, without any specific instruction on how to port plugins that used them in Craft 2:
See its comprehensive upgrade guide to learn about how things have changed under the hood.
Considering the big changes (e.g. using actual PHP attributes instead of defineAttributes()
on models), this really hinders efforts to migrate plugins to Craft 3. It also led me to believe that Models and Records were no longer supported classes for Craft 3 plugins, until I delved into official P&T plugins like Digital Products to notice that they are indeed still used! This has us piecing up classes from the Craft 2 docs, Yii 2 upgrade docs, and reverse engineering... Far from ideal.
Here's the current table of core classes that are documented, which I'm making partly for myself to keep navigate through the upgrade process...
Craft 2 | Craft 3 | Craft Update Notes | Yii Update Notes |
---|---|---|---|
Models | Missing | Missing | Models |
Records | Missing | DB Queries | Active Record |
Controllers | Missing | (Multiple) | Controllers |
Element Actions | Element Actions | Missing | N/A |
Dashboard Widgets | Widget Types | Missing | N/A |
Field Types | Field Types | Components | N/A |
Services | Services | Missing | N/A |
Template Variables | Extending Twig | Template Variables | N/A |
Is there an update planned for the core Models/Records/Controllers documentation, along with examples of how to create and use them in Craft 3?
When looking at something like the orderBy
element query parameter (here), it would be really convenient to know what the default is without digging into the source code.
The 'Getting Started' page for testing is a lot of creating folders, creating files, and copying code.
It'd be simpler and less room for error if you tell devs to run the CLI command ./craft tests/setup
and then call out specific files they need to manually update. You could then remove the manual steps completely and just give a high-level overview of the folder structure.
Referencing: https://docs.craftcms.com/v3/testing/testing-craft/getting-started.html
I know it's impossible to cover every stack/scenario — but some basic documentation on configuring the most typical server setups for Craft multisite would be hugely appreciated.
(I've just spent more than an entire day getting multisite working via Nginx on a Forge-provisioned VPS and have almost cracked it now, but am sure other people would welcome this too).
I'm just querying this for sanity reasons. From a Craft 2 to 3 migration, I don't seem to have the settings column on the craft_plugins
table.
The example for modifying a Craft 2 plugin handle reference the settings columns below, but it doesn't seem to exist:
https://docs.craftcms.com/v3/extend/updating-plugins.html#writing-an-upgrade-migration
For updating the handle, the settings column isn't needed anyway, but I'm just wanting to clarify this, if the craft_plugins
DB table should have a settings column anymore?
On this page here's a couple references to customerFieldHandle
. Isn't that not a feature in Commerce 3?
This page shows how to define nested permissions but doesn't have information on how to check for them.
https://docs.craftcms.com/v3/extend/user-permissions.html
eg. for this example
'permissionName' => [
'label' => 'Permission Label',
'nested' => [
'nestedPermissionName' => [
'label' => 'Nested Permission Label',
],
],
];
its not clear which of the following is correct (if any)
$user->can('nestedPermissionName');
$user->can('permissionName.nestedPermissionName');
$user->can('permissionName/nestedPermissionName');
CraftCMS introduced a new featured in 3.1 to enable the ability for live preview to work on multi site setups when previewing entries that reside on other domains (in addition to the CP domain). Other than the linked guide below (specifically mentioning config for multiple sub domains), there is no documentation to explain what needs to be setup to enable this new feature. The guide should be amended to include this information.
https://craftcms.com/guides/using-live-preview-across-multiple-subdomains
docs/extend/controllers.md
After an hour of debugging I figured out that accessing custom controllers in Craft seem to require the first slug to be /action/
.
I would be great if the documentation mentioned this.
When i do searches in google, the craft commerce 2 documents appear on top. Can those be blocked in the robots.txt so google will index and prioritize craft commerce 3 in searches?
Thanks!
Attempting to browse the site in Firefox (79.0 on Mac), and navigation hangs
I see javascript errors like
The resource from “https://craftcms.com/docs/assets/js/210.3cf6e775.js” was blocked due to MIME type (“text/html”) mismatch (X-Content-Type-Options: nosniff).
and
Uncaught (in promise) ChunkLoadError: Loading chunk 210 failed.
(error: https://craftcms.com/docs/assets/js/210.3cf6e775.js)
Works in Chrome
Currently Dash has Craft docsets as part of the main docset library, but they are not currently up to date (latest v2 is 2.6 and latest v3 is 3.1).
There's probably no blocker for getting 2.7 in there via the v2
branch considering it is only receiving security updates now, but there are no dedicated branches or tags for this repo that allow for delineation between 3.2/3.3/3.4. Is this something that could be considered?
@Kapeli Is there anything else that would be required for updated Craft docsets?
In the CP deprecation warnings I see this:
The
class
argument of the svg() Twig function has been deprecated. The |attr filter should be used instead.
However when visiting the docs for the svg function the example is this:
{{ svg('@webroot/icons/lemon.svg', class='lemon-icon') }}
with no reference of how to use the |attr
filter
There is currently no documentation on how PDFs are set up and used in the commerce system.
As a plugin developer I want to make sure my plugins match Crafts UI as closely as possible.
To make this a better UX it would be great if the docs included a UI style guide section which described markup and classes. Currently I'm reverse engineering components by looking at the twig source templates.
I fear that with craft3 and the plugin store everyone will start using custom UI's and we'll end up with inconsistent experiences.
The main customisation I've needed so far is nested fieldsets. Here's how I handled it in a plugin I'm currently working on. I had to customise the labels of the "sub" fields and create a container.
Right now the theme honors your browser/system setting for prefers-color-scheme
, but it’d be nice to allow the visitor to optionally override that with an on-page control.
Heads up: this might be a long one, and I may very well be wrong. So please use a healthy dose of scepticism :)
I'm working on upgrading a site from craft 2 to 3 and ran into an issue with currentUser.can(). According to this page, in order to check if the user can edit entries in a section (which is what I'm using as a means of checking if the current user should be able to access the current page) I should be using currentUser.can('editEntries:[SectionID]'). However this returns false to me eventhough the current user has that permission.
After some digging, including outputting this:
<pre>{{ dump(craft.app.userPermissions.getPermissionsByUserId(currentUser.id)) }}</pre>
I looked at the source code. The .can(string $permission) pretty much just passes it on to Craft::$app->getUserPermissions()->doesUserHavePermission($this->id, $permission). This function simply checks if the lowercase $permission is in the array of the above dump.
But here's the kicker, that function getPermissionsByUserId() has those permission with uid instead of id. Thus if I follow the documentation, I will never get the right response.
I think either the documentation is wrong or at some point the .can() function had a transform from id to uid removed (as I'm pretty sure it did work in craft 2). I do think it's waaay more convenient to use id, but if the .can() function is wrong it seems like a big deal and I imagine someone should have run into this issue long ago. (which is why I'm sceptical of my find)
I could give steps to get to a point that should be correct according to the doc, but isn't. But think my write-up above covers it?
It would be great to have documentation around the endpoints that accept AJAX requests and the information they accept and return.
This documentation could do a lot more to explain how to set up the routes – or at least link to a page that explains it.
https://github.com/craftcms/docs/blob/master/en/element-types.md#edit-page
I have a suggestion for https://craftcms.com/docs/3.x/entries.html
The feedback is actually for the overall documentation site. It would be great if the search bar can be fixed at the top so that even if I am reading something near the bottom of the page, I can press /
and search the site from there.
Doc is missing in the section for these conversions,, but it's easy to provide, thus allowing all Craft 3 sites to take advantage of the better security possible, and be consistent when addressed in future.
Think what would be useful in the initial Updating Craft CMS section of upgrade.md is:
insert an step after 4) and similar to it, with this instruction. At present it will result in a tag of ^2.40, which should provide for future.
compoaer require vlucas/phpdotenv
In the step which now becomes 6), replace the index.php code substitution with something like this. Note that the phpdotenv call has added protection, in case the composer step hadn't been done or succeeded, or was lost.
<?php
// Project root path
$root = dirname(__DIR__);
// Load and run Craft
define('CRAFT_BASE_PATH', $root.'/craft');
require_once $root.'/vendor/autoload.php';
// dotenv?
if (file_exists($root.'/.env')
&& file_exists($root.'/vendor/vlucas/phpdotenv')) {
$dotenv = new Dotenv\Dotenv($root);
$dotenv->load();
}
$app = require $root.'/vendor/craftcms/cms/bootstrap/web.php';
$app->run();
You could quite usefully add a further paragraph in this area, quite possibly a new step (now) 9) and after 'success and delete app', explaining how the converted site will continue to use the present db.php and general.php, while possibly needing some modifications, leading to the following Configuration section
In that Configuration section, then it's easy to say that you may want to move forward to putting security items like passwords into .env, because now you can.
similarly, it could be quite informative to flesh out the rather misssable Asset Volume Settings section (bigger heading type there?) with a note that you can use .env entries to fill in the per-deployment-site differing values for ASSET_BASE_PATH and ASSET_BASE_URL in volumes.php.
last point is that problems with old Redactor configs could usefully be a bit better explained in the Redactor configs section. I would follow your specifics with a short paragraph saying 1) in fact old Redator configs often don't follow these rules, by not quoting all values, and by using the wrong quote character otherwise, so you will have to edit them if Craft shows an on Rich Text fields, and 2) that http://jsonlint.com/
can be very useful in assuring you've made all the corrections.
well, one more. It's likely to be helpful to add a now 10) item to the initial Updating Craft CMS section, suggesting to Clear Caches all nder the new Utilities menu, before beginning to try out the converted site. I've had some very misleading problems occur on conversion, until doing this, something easily overlooked but obviously of need for sites that have run before, when you think about it.
https://docs.craftcms.com/v3/installation.html#step-1-download-craft has a link to a very old download. It should be removed (or replaced with what is considered to be the newest stable version)
In the installation instructions the DOM extension is listed as optional (https://docs.craftcms.com/v3/requirements.html#required-php-extensions), but it actually seems to be required.
Craft Commerce requires PHP 7.0
or greater (just like Craft CMS).
The default craft project composer.json sets the platform to 7.0
https://github.com/craftcms/craft/blob/master/composer.json#L36
This platform requirement in the project will favour dependancies that are compatible with 7.0
In Commerce we require dompdf/dompdf ^0.8.3
which runs fine on PHP 7.0
If you run your project on PHP 7.4
and have dompdf 0.8.3
installed, you will get errors.
dompdf 0.8.4+
requires PHP 7.1
but these versions will not be installed due to your projects composer.json platform requirement.
Bottom line, if you are running PHP 7.4
update your projects platform to 7.4
(or 7.1
or greater) and do a composer update and dompdf will be upgraded to 0.8.4+
and work again.
@mattstein please ask me questions if the above is not clear. Probably best in the upgrade & requirements docs pages.
product.defaultVariant.stock
Background: https://craftcms.zendesk.com/agent/tickets/7752 (private link)
Make all the documentation more accessible to everyone by targeting WCAG AA compliance.
Increase the suggestion limit and paginate beyond ten results.
Since the move to make Drafts and Revisions Elements, it has been increasingly confusing for the number of scenarios custom Elements and Field Types need to support (measured by bug reports, time spent on client Yii modules dealing with Elements/Field Types, and curse words). In most cases, I think the solution is easier than I'm making it but the lack of documentation on how to even think about the problem makes it challenging to even know if you're considering all the possible scenarios for Drafts, Revisions, and Multi-Site.
Using X-Debug to troubleshoot is a challenge too as even if you are trying to just watch a single method involved in the save behavior the code ends up hitting that method countless times for things like auto-save, SCENARIO_ESSENTIALS, SCENARIO_LIVE, drafts, revisions, multi-site propagation, and more. Throw in a few variations on the Element settings or different Translation Methods and you have even more scenarios to make sense of as you try to figure out a simple question such as what is a reliable condition I can use to make sure I only trigger something when an Element is saved in the Live Scenario for the first time?, which should not be a complicated question to answer. It is. Or at least feels like it.
To illustrate my confusion here's a spreadsheet I made while trying to figure out how to save a custom field type with a separate data table:
https://share.barrelstrength.co/YEu1nwBK
The spreadsheet is trying to make sense of the number of different times Elements were saving in 6 different scenarios, which each save Elements multiple times.
This doesn't even get into examples of Elements saving for Multi-site or scenarios where Element saves get triggered from the console, queue, migrations, or failed validation.
Ideal documentation would identify (and give us a checklist for) ALL of the different scenarios we need to plan for, give us a framework on how to think about the problem (at least for custom Elements and Field Types), and clearly show an example of how our code can identify each scenario.
I stumbled across this and it simplified alot I was doing with redirects: craftcms/cms#1003 (comment)
Would be great if docs reflected anywhere localizeValue()
allows you to pass a callable
.
Here's a description of what happens and what to do, from Slack posting. Would be nice if could be edited into coming doc...
a little tip for the unwary: if you're connecting to an external database such as mssql, don't use craft\db\Connection (or craft\db\Exception). You'll miss getting proper messages for a failed connection, even just server down.
I had the driver and connection fully working, save for server down, and thought it was a driver issue. But actually it's Craft's db code, and its handling if it doesn't recognize the database/driver type -- says simply unsupported connection type, and mentions the driver.
The real messages from the dblib driver are nicely enough detailed -- using yii\db\Connection (subclassed), and yii\db\Exception.
It’s currently hard to find info about very common API methods, things like
{% set segments = craft.app.request.getSegments() %}
I know it’s not practicable to duplicate all docs from the Class Reference into documentation articles, but I think there should be something in the Craft 3 Documentation to guide new Craft users. Maybe it would already help to have an intro article in the “Templating” section, with links pointing to the Class Reference pages for common service APIs? Maybe enrich it with some Twig example code?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.